|
Project: stp | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface StpProperty<T>
A property is a named collection of metadata associated with a resource. The collection is named by its PropertyName.
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.
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.
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), );
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.
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. |
|
|
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 |
---|
static final StpProperty.MetaPropertyName<Boolean> IS_EMPTY
static final StpProperty.MetaPropertyName<PropertyNameList> META_PROPERTY_NAMES
static final StpProperty.MetaPropertyName<String> NAME
static final StpProperty.MetaPropertyName<String> NAMESPACE
static final StpProperty.MetaPropertyName<PropertyNameList.PropertyName<?>> PROPERTY_NAME
static final StpProperty.MetaPropertyName<Resource> RESOURCE
static final StpProperty.MetaPropertyName<Long> SIZE
static final StpProperty.MetaPropertyName<StpProperty.Type> TYPE
static final StpProperty.MetaPropertyName<?> VALUE
Method Detail |
---|
boolean getIsEmpty() throws WvcmException
IS_EMPTY
meta-property as
defined by this StpProperty instance.
WvcmException
- if this StpProperty instance does not define a
value for the IS_EMPTY
meta-property
component.<U> U getMetaProperty(StpProperty.MetaPropertyName<U> name) throws WvcmException
name
- A MetaPropertyName object identifying the meta-property
desired.
WvcmException
- if this StpProperty instance does not define a
value for the named meta-property.PropertyNameList getMetaPropertyNames() throws WvcmException
META_PROPERTY_NAMES
meta-property as defined by this StpProperty instance.
WvcmException
- if this StpProperty instance does not define a value
for the META_PROPERTY_NAMES
meta-property.String getName()
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.
String getNamespace()
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.
PropertyNameList.PropertyName<T> getPropertyName()
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.
Resource getResource() throws WvcmException
RESOURCE
meta-property as
defined by this StpProperty instance.
WvcmException
- if this StpProperty instance does not define a
value for the RESOURCE
meta-property
component.long getSize() throws WvcmException
SIZE
meta-property as defined by
this StpProperty instance.
WvcmException
- if this StpProperty instance does not define a
value for the SIZE
meta-property component.StpProperty.Type getType() throws WvcmException
TYPE
meta-property as defined by
this StpProperty instance.
WvcmException
- if this StpProperty instance does not define a value
for the TYPE
meta-property.T getValue() throws WvcmException
VALUE
meta-property as defined by
this StpProperty instance.
WvcmException
- if this StpProperty instance does not define a
value for the VALUE
meta-property.StpPropertyException metaPropertyException(StpProperty.MetaPropertyName<?> name)
name
- The name of the meta-property whose retrieval status is being
interrogated.
StpPropertyException[] metaPropertyExceptions()
StpProperty.MetaPropertyName<?>[] metaPropertyNames()
Resource.propertyNameList()
|
Generated Mon 17-Nov-2014 07:03 AM | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |