Nested properties

The value of many properties is a reference to another resource.

If the value of a property is a reference to a resource, the PropertyRequest might contain a NestedPropertyName object instead of the PropertyName object for the property. The NestedPropertyName object has a root property name and a nested PropertyRequest. It requests properties from the resource referenced by the value of the property named as the root.

In addition to specifying the name of the property, a NestedPropertyName also includes its own PropertyRequest. This nested PropertyRequest specifies the properties of the resource referenced by the property of the original resource whose values are to be obtained from the referenced resource.

For example, the following code fragment creates a property name list that identifies the CREATOR_DISPLAY_NAME, CHECKED_IN, and LAST_MODIFIED properties, as well as the VERSION_NAME and CREATION_DATE of the value of the CHECKED_IN property. In this example the nest method constructs and returns a NestedPropertyName.

PropertyRequest my_prop_request = new PropertyRequest(ControllableResource.CREATOR_DISPLAY_NAME,
     ControllableResource.CHECKED_IN.nest(
            Version.VERSION_NAME,
            Version.CREATION_DATE).
     ControllableResource.LAST_MODIFIED);

After specifying the nested properties, you can call the doReadProperties method and access the nested properties. For example:

resource = 
   (ControllableResource) resource.doReadProperties(my_prop_request);
String versionName = resource.getCheckIn().getVersionName();
// work with the properties ...

The PropertyRequest nested within a NestedPropertyName can itself contain additional NestedPropertyName objects. So, in one interaction with the server, it is possible to retrieve an arbitrary number of related resources and their properties.