Project: stp

com.ibm.rational.wvcm.stp
Interface StpProperty<T>

All Known Subinterfaces:
CqFieldValue<T>, CqHistoryFieldValue

public interface StpProperty<T>

A property is a named collection of metadata associated with a resource. The collection is named by its PropertyName.

Meta-Properties

Each metadata component is called a meta-property and is a (name, value) pair. That is, a property is a named collection of meta-properties. The name of a meta-property is denoted by a MetaPropertyName object. The value is an arbitrary Object.

The term "meta-property" is used here rather loosely. Meta-properties specify more than just static attributes of a property (such as its type or name), but often define very dynamic aspects of the property (e.g., what resource it came from) or its value (e.g. whether or not the value is null). There is even a VALUE meta-property, whose value is the value of the property.

Just like a PropertyName, a MetaPropertyName is composed from a namespace and a simple name. (In fact, to simplify this API, MetaPropertyName is a subclass of javax.wvcm.PropertyNameList.PropertyName.) The PropertyName and MetaPropertyName namespaces cannot overlap.

Every property has the meta-properties defined in this class; namely NAME, NAMESPACE, PROPERTY_NAME, RESOURCE and VALUE. Each property may have additional meta-properties of its own as well.

When we speak of the "value of a property", we are actually referring to the value of the VALUE meta-property of the property.

Requesting Meta-properties

An StpProperty object is a client-side proxy for a property; just as a Resource object is a client-side proxy for a resource. Like a resource proxy, each StpProperty instance defines only those meta-properties that have been explicitly requested from the server. (The NAME, NAMESPACE, and PROPERTY_NAME meta-properties are an exception since they are required to construct a StpProperty instance and are always present.)

An StpProperty instance does not provide an interface for changing the value of a meta-property. Clients can change only property values, which may have the side-effect of changing other meta-properties for that property or meta-properties for other properties.

Property meta-properties are available only in the context of a specific resource and the request for property meta-properties is tied directly to that resource using the same mechanism used to request properties from that resource.

MetaPropertyName Objects in a NestedPropertyName

To request a meta-property of a property, a MetaPropertyName object for the meta-property is included in the PropertyRequest argument to PropertyName.nest(). MetaPropertyName objects and PropertyName objects can coexist in the same nested PropertyRequest; the nested MetaPropertyName objects request meta-properties of the property, while the nested ProperyName objects request properties of the resource named by the value of the property.

To request the meta-properties of a property-valued property, the MetaPropertyNames must be nested within a NestedPropertyName. The root meta-property of this request will be StpProperty.VALUE and the desired meta-properties of the value will be nested in the PropertyRequest of the NestedPropertyName.

Examples

  PropertyRequest wanted=new PropertyRequest(
    // The value of the DISPLAY_NAME property
    Resource.DISPLAY_NAME,
    Resource.WORKSPACE_FOLDER_LIST.nest(
        // The type of the WORKSPACE_FOLDER_LIST property
        StpProperty.TYPE,
        // The value of the CHILD_LIST property for each folder
        // named by the WORKSPACE_FOLDER_LIST
        Folder.CHILD_LIST),  
    Resource.INVALID_PROPERTIES.nest(
           // The type of the INVALID_PROPERTIES property
           StpProperty.TYPE,
           StpProperty.VALUE.nest(
               // The type of each property named by the value of the 
               // INVALID_PROPERTIES property.
               StpProperty.TYPE,
               // The value of each property named by the value of the 
               // INVALID_PROPERTIES property.
               StpProperty.VALUE),
  );
 

The VALUE Meta-Property

Every property has a VALUE meta-property. The use of a PropertyName by itself implicitly requests this meta-property. A NestedPropertyName containing nested ProperyNames also implicitly requests the VALUE meta-property (since it would be impossible to request properties of the value without also requesting the value itself).

On the other hand, a NestedPropertyName that contains only nested MetaPropertyNames must include StpProperty.VALUE if the value of the property is desired. This makes it possible for a client to request information about a property (such as is size) without actually retrieving the value itself.

Accessing Meta-Properties

Like property values, meta-properties retrieved from the server are stored in the resource proxy and accessed via methods defined in the StpResource class. The principal method is Resource.getMetaProperties(PropertyName), which returns an StpProperty object containing all of the meta-properties for a given property retrieved from the server and diagnostic information for those meta-properties that couldn't be retrieved.

As long as the PropertyName was mentioned in the request and that property is defined by the resource, getMetaProperties will return a StpProperty object for that PropertyName. An exception is thrown only if the property is not defined by the resource or no meta-property of the property was requested.

Resource.getProperty(PropertyName) returns the value of the VALUE meta-property of the property and will throw an exception if that meta-property was not requested or the server reported an error in attempting to retrieve the value. If the value of a property is, itself, a property, getProperty will return an StpProperty object.

From the StpProperty object, the client can access the retrieved meta-properties, either generically using the getMetaProperty() method and an explicit MetaPropertyName or using the specialized methods, such as getName and getValue, where the MetaPropertyName is implicit. Subclasses of Resource may define subclasses of StpProperty and provide typed accessors for them. The subclasses of StpProperty may, in turn, define more typed accessors for meta-properties they know about. (See, for example Record and CqFieldValue.)

The type parameter of an StpProperty instance specifies the type of the property's VALUE meta-property.


Nested Class Summary
static class StpProperty.List<S extends StpProperty>
          A List of Properties.
static class StpProperty.MetaPropertyName<V>
          An object representing the name of a meta-property.
static class StpProperty.Type
          An enumeration of the possible property types.
 
Field Summary
static StpProperty.MetaPropertyName<Boolean> IS_EMPTY
          Whether or not the value of this property is empty/null.
static StpProperty.MetaPropertyName<PropertyNameList> META_PROPERTY_NAMES
          A list of all the meta-property names defined for this property.
static StpProperty.MetaPropertyName<String> NAME
          The simple name for this property.
static StpProperty.MetaPropertyName<String> NAMESPACE
          The namespace for this property.
static StpProperty.MetaPropertyName<PropertyNameList.PropertyName<?>> PROPERTY_NAME
          A PropertyName object for this property.
static StpProperty.MetaPropertyName<Resource> RESOURCE
          The resource of which this is a property.
static StpProperty.MetaPropertyName<Long> SIZE
          A metric relating to the size of the property value, such as the number of characters in a string, or the number of items in a list.
static StpProperty.MetaPropertyName<StpProperty.Type> TYPE
          An enumerator denoting the type of this property's VALUE meta-property value.
static StpProperty.MetaPropertyName<?> VALUE
          The meta-property whose value is the value of the property.
 
Method Summary
 boolean getIsEmpty()
          Returns the value of the IS_EMPTY meta-property as defined by this StpProperty instance.
<U> U
getMetaProperty(StpProperty.MetaPropertyName<U> name)
          Returns the value of the given meta-property defined by this StpProperty instance.
 PropertyNameList getMetaPropertyNames()
          Returns the value of the META_PROPERTY_NAMES meta-property as defined by this StpProperty instance.
 String getName()
          Returns the value of the NAME meta-property as defined by this StpProperty instance.
 String getNamespace()
          Returns the value of the NAMESPACE meta-property as defined by this StpProperty instance.
 PropertyNameList.PropertyName<T> getPropertyName()
          Returns the value of the PROPERTY_NAME meta-property as defined by this StpProperty instance.
 Resource getResource()
          Returns the value of the RESOURCE meta-property as defined by this StpProperty instance.
 long getSize()
          Returns the value of the SIZE meta-property as defined by this StpProperty instance.
 StpProperty.Type getType()
          Returns the value of the TYPE meta-property as defined by this StpProperty instance.
 T getValue()
          Returns the value of the VALUE meta-property as defined by this StpProperty instance.
 StpPropertyException metaPropertyException(StpProperty.MetaPropertyName<?> name)
          Returns the StpPropertyException that would be thrown if getMetaProperty were invoked on a specified meta-property.
 StpPropertyException[] metaPropertyExceptions()
          Returns an array of StpPropertyException objects, each of which represents a meta-property whose value was requested but could not be successfully retrieved.
 StpProperty.MetaPropertyName<?>[] metaPropertyNames()
          Returns the names of meta-properties available on this client StpProperty proxy.
 

Field Detail

IS_EMPTY

static final StpProperty.MetaPropertyName<Boolean> IS_EMPTY
Whether or not the value of this property is empty/null. Not all properties define this meta-property; see the property documentation.


META_PROPERTY_NAMES

static final StpProperty.MetaPropertyName<PropertyNameList> META_PROPERTY_NAMES
A list of all the meta-property names defined for this property. This is the analog of Resource.doGetPropertyNameList. Since properties may not be addressed directly, this analogous capability is expressed as a meta-property.


NAME

static final StpProperty.MetaPropertyName<String> NAME
The simple name for this property.


NAMESPACE

static final StpProperty.MetaPropertyName<String> NAMESPACE
The namespace for this property.


PROPERTY_NAME

static final StpProperty.MetaPropertyName<PropertyNameList.PropertyName<?>> PROPERTY_NAME
A PropertyName object for this property.


RESOURCE

static final StpProperty.MetaPropertyName<Resource> RESOURCE
The resource of which this is a property.


SIZE

static final StpProperty.MetaPropertyName<Long> SIZE
A metric relating to the size of the property value, such as the number of characters in a string, or the number of items in a list. Not all properties define this meta-property; see the property documentation.


TYPE

static final StpProperty.MetaPropertyName<StpProperty.Type> TYPE
An enumerator denoting the type of this property's VALUE meta-property value.


VALUE

static final StpProperty.MetaPropertyName<?> VALUE
The meta-property whose value is the value of the property. (The type of the value is specified by the TYPE meta-property.) This meta-property is defined for all properties.

Method Detail

getIsEmpty

boolean getIsEmpty()
                   throws WvcmException
Returns the value of the IS_EMPTY meta-property as defined by this StpProperty instance.

Returns:
true if the value of this StpProperty is empty or null; false otherwise.
Throws:
WvcmException - if this StpProperty instance does not define a value for the IS_EMPTY meta-property component.

getMetaProperty

<U> U getMetaProperty(StpProperty.MetaPropertyName<U> name)
                  throws WvcmException
Returns the value of the given meta-property defined by this StpProperty instance.

Parameters:
name - A MetaPropertyName object identifying the meta-property desired.
Returns:
An Object representing the value of the meta-property requested.
Throws:
WvcmException - if this StpProperty instance does not define a value for the named meta-property.

getMetaPropertyNames

PropertyNameList getMetaPropertyNames()
                                      throws WvcmException
Returns the value of the META_PROPERTY_NAMES meta-property as defined by this StpProperty instance.

Returns:
A PropertyRequest containing a MetaPropertyName for each meta- property defined by this StpProperty.
Throws:
WvcmException - if this StpProperty instance does not define a value for the META_PROPERTY_NAMES meta-property.

getName

String getName()
Returns the value of the NAME meta-property as defined by this StpProperty instance. Note that this meta-property is always defined by a property and does not need to be requested.

Returns:
A string representing the simple name of this property's PropertyName

getNamespace

String getNamespace()
Returns the value of the NAMESPACE meta-property as defined by this StpProperty instance. Note that this meta-property is always defined by a property and does not need to be requested.

Returns:
A String representing the namespace in which this property is defined.

getPropertyName

PropertyNameList.PropertyName<T> getPropertyName()
Returns the value of the PROPERTY_NAME meta-property as defined by this StpProperty instance. Note that this meta-property is always defined by a property and does not need to be requested.

Returns:
This object as a PropertyName.

getResource

Resource getResource()
                     throws WvcmException
Returns the value of the RESOURCE meta-property as defined by this StpProperty instance.

Returns:
A Resource proxy for the resource this property belongs to.
Throws:
WvcmException - if this StpProperty instance does not define a value for the RESOURCE meta-property component.

getSize

long getSize()
             throws WvcmException
Returns the value of the SIZE meta-property as defined by this StpProperty instance.

Returns:
An non-negative integer.
Throws:
WvcmException - if this StpProperty instance does not define a value for the SIZE meta-property component.

getType

StpProperty.Type getType()
                         throws WvcmException
Returns the value of the TYPE meta-property as defined by this StpProperty instance.

Returns:
A Type enumeration representing the type of this property's VALUE meta-property.
Throws:
WvcmException - if this StpProperty instance does not define a value for the TYPE meta-property.

getValue

T getValue()
           throws WvcmException
Returns the value of the VALUE meta-property as defined by this StpProperty instance.

Returns:
An Object representing the value of the property represented by this StpProperty instance.
Throws:
WvcmException - if this StpProperty instance does not define a value for the VALUE meta-property.

metaPropertyException

StpPropertyException metaPropertyException(StpProperty.MetaPropertyName<?> name)
Returns the StpPropertyException that would be thrown if getMetaProperty were invoked on a specified meta-property.

Parameters:
name - The name of the meta-property whose retrieval status is being interrogated.
Returns:
an StpPropertyException is returned if the named meta-property could not be retrieved or if it's retrieval was not requested; otherwise null.

metaPropertyExceptions

StpPropertyException[] metaPropertyExceptions()
Returns an array of StpPropertyException objects, each of which represents a meta-property whose value was requested but could not be successfully retrieved.

Returns:
An array containing an StpPropertyException object for each meta-property that could not be retrieved. The PropertyName field of the PropertyException identifies the meta-property that could not be retrieved.

metaPropertyNames

StpProperty.MetaPropertyName<?>[] metaPropertyNames()
Returns the names of meta-properties available on this client StpProperty proxy. This is the analog of Resource.propertyNameList. A meta-property is available if it would not throw an exception if retrieved from this StpProperty. Failing to retrieve a meta-property would cause a meta-property name to not appear in the metaPropertyNames result and forgetting or removing a meta-property would remove that property from the metaPropertyNames result.

Returns:
the list of MetaPropertyName objects identifying the meta-properties available on this client StpProperty proxy.
See Also:
Resource.propertyNameList()

Generated Wed 18-May-2011 12:24 PM

Copyright © IBM 2011. All rights reserved.