Revised on 9/30/08:

There are two basic use cases for the PropertySpecifier class. In one case, you receive a PropertySpecifier in assembler methods such as getItem(). In this case, the PropertySpecifier provides a hint so that your code can optimize the fetching of the properties. For the Assembler.getItem() method you only need to return the properties specified in the PropertySpecifier.

There are a couple of ways to determine which properties are specified in the PropertySpecifier. You can use the PropertySpecifier.includeProperty(String name) method to test if a specific property is included by a given PropertySpecifier. You also can look at how the PropertySpecifier is defined.

A PropertySpecifier can have a default mode, which means that all properties should be returned unless they are listed as exceptions in the configuration. For example, if you define an association with the load-on-demand or page-size attributes, it is not included in the default PropertySpecifier. You can also define a PropertySpecifier for the all mode, in which case, it returns all properties. PropertySpecifiers can also be defined to contain an explicit list of property names, or you can define one that includes the default properties plus an explicit list of property names.

default 

All properties other than load on demand or paged association properties.

all 

All properties.

default plus list 

Default properties plus an extra set of properties retrievable by the getExtraProperties() method.

just list 

A set of properties retrievable by the getExtraProperties() method.

A typical reason you might use the PropertySpecifier is if you define master and detail views of the properties in your value objects. All properties in the detail view would be marked as load-on-demand or with page-size so that they are not put into the default set of properties. The only properties you can mark load-on-demand are associations. When the initial fill() or getItem() call is made for that item, it does not need to return any of these load-on-demand or paged properties. The default fill() method must only return properties defined in as default properties for that item. When the client tries to access these properties, a separate request is made to the server to fetch them. In that case, if you set load-on-demand to true, your getItem() method is called with a PropertySpecifier that only includes the property accessed on the client. If you set the page-size attribute on your association property, the getPagedCollectionProperty() method is used instead to fetch a range of items from that association property. 

The second use case for a PropertySpecifier is when you must specify one for a Data Management Service API such as the DataServiceTransaction class. The PropertySpecifier provides a way to specify a list of properties for a given operation. For example, the refreshFill() method takes a PropertySpecifier that specifies which properties from the adapter layer should be refreshed. The DataServiceTransaction.getItem() method can also take a PropertySpecifier to indicate which properties should be fetched from the assembler. Whenever you call a Data Management Service API function that takes a PropertySpecifier argument, null can be used instead of providing a PropertySpecifier instance. For the refreshFill() method, supplying null means to not refresh any properties of items. In that case, items are only added to or removed from the collection as necessary; no properties of updated items are refreshed. For the getItem() method, passing null means to use the default property descriptor.   

To create a new PropertySpecifier on the server, you first need to get the DataDestination for the type of object you are dealing with. You do this with the static method DataDestination.getDataDestination(String destName). Once you have the DataDestination, you can use the getDefaultPropertySpecifier() and getAllPropertySpecifier() methods to retrieve predefined PropertySpecifiers that refer to the default set or all properties, respectively.

You also can use the PropertySpecifier.getPropertySpecifier(DataDestination dest, List props, boolean includeDefault) to create a PropertySpecifier that refers to a specific set of properties you specify in the props parameter. You use this method in general when you want to create a PropertySpecifier from an explicit list of properties. In that case, you have two choices: you can include just the list of properties you specify, or you can include use the includeDefault parameter to include all default properties in addition to the list of properties specified in the props parameter.

Suppose you have a Person type with a load-on-demand addresses property and you want to call to the getItem() method to retrieve a given user’s addresses property. You could write the following code to get a PropertySpecifier that retrieves just the addresses property:

ArrayList props = new ArrayList();
props.add(“addresses”);
PropertySpecifier.getPropertySpecifier(DataDestination.getDataDestination
  (“Person”), props, false);

You could write the following code to get a PropertySpecifier that includes all of the non-load-on-demand properties (firstName, lastName, and so forth) in addition to the addresses property:

ArrayList props = new ArrayList();
props.add(“addresses”);
PropertySpecifier.getPropertySpecifier(DataDestination.getDataDestination
  (“Person”),props, true);