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 ...

In a NestedPropertyName, the PropertyRequest that designates the properties to retrieve from the server can be augmented with MetaPropertyName elements, which allow the client to request specific meta-properties of a property (instead of, or in addition to, its VALUE meta-property).

The value of a property that references another resource is a proxy, and that proxy contains the properties requested in the NestedPropertyName. Additionally, NestedPropertyName elements can be included in a PropertyRequest to request a property of a resource referenced by a meta-property, or a meta-property of a property referenced by a meta-property. For example:

CqRecord r = p.buildProxy(CqRecord.class, "...");
FieldName<CqRecord> OWNER = new FieldName<CqRecord>("Owner");
FieldName<String> NAME = new FieldName<String>("login_name");
PropertyRequest request =
   new PropertyRequest(OWNER.nest(StpProperty.TYPE,
                                  CqFieldValue.REQUIREDNESS,
                                  StpProperty.VALUE.nest(NAME)));
CqRecord rec = (CqRecord)r.doReadProperties(request);
CqFieldValue<CqRecord> v = rec.getFieldInfo(OWNER);
String name = v.getValue().getProperty(NAME);

PropertyRequest pnl =
   new PropertyRequest(
     CqRecord.FIELDS.nest(
         StpProperty.VALUE.nest(
               StpProperty.NAME,
               StpProperty.TYPE,
               StpProperty.VALUE)));
List<CqFieldValue<?>> fields = ((CqRecord)r.doReadProperties(pnl)).getFields();
for(CqFieldValue<?> field: fields)
    System.out.println("field " + field.getName()
                       ": " + field.getType()
                       " = " + field.getValue());

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.