6 Attribute Requests

Attribute requests are a commonly used feature when developing for Oracle Content Services. Attribute requests tell Oracle Content Services to return a set of attributes about a specific Item in the repository. The request is given when performing an action on that Item, and is returned in an array of AttributeRequest objects. The examples in this book have all used basic attribute requests to retrieve simple piece of data. Attributes, however, can be nested, allowing the creation of more complex data structures for attribute requests. The following example shows how to request and retrieve a nested attribute structure.

Chaining Attribute Requests

In the case where attributes are composed of multiple values, attribute requests must be nested or chained. Chaining attribute requests allows retrieval of an entire tree of related objects in one call. Consider the following example, which sets version numbers on a folder:

/**
 * Set manual and auto version on folder
 */
public static void setVersion(Item folder)
    throws FdkException, RemoteException
{
    // get the Manager instances
    CommonManager cm = s_WsCon.getCommonManager();
    VersionManager vm = s_WsCon.getVersionManager();
 
    // create auto version configuration definition
    NamedValue[] autoVerDef = WsUtility.newNamedValueArray(new Object[][] {
        { Attributes.VERSIONING_CONFIGURATION_AUTO_LABEL, Boolean.TRUE },
        { Attributes.VERSIONING_CONFIGURATION_AUTO_VERSION, Boolean.TRUE },
        { Attributes.VERSIONING_CONFIGURATION_MAX_VERSIONS, new Integer(1000) },
        { Attributes.CONFIGURATION_FINAL, Boolean.FALSE },
        { Attributes.CONFIGURATION_ENABLED, Boolean.TRUE } });
 
    // set auto version configuration on the folder
    vm.setVersioningConfiguration(folder.getId(), autoVerDef);
 
    // The version attributes request
    // This requests the attributes of the folder, and nests
    // the attributes to be retrieved from the versioning configuration 
    // of the folder
    AttributeRequest[] fdr_ver_attr = new AttributeRequest[] {
        WsUtility.newAttributeRequest(Attributes.PATH),
        WsUtility.newAttributeRequest(Attributes.DESCRIPTION),
        // nest the attributes of the versioning configuration
        WsUtility.newAttributeRequest(Attributes.VERSIONING_CONFIGURATION,
            WsUtility.newAttributeRequestArray(new String[] {
                Attributes.VERSIONING_CONFIGURATION_AUTO_LABEL,
                Attributes.VERSIONING_CONFIGURATION_AUTO_VERSION,
                Attributes.VERSIONING_CONFIGURATION_MAX_VERSIONS,
                Attributes.CONFIGURATION_ENABLED })) };
 
    // requesting folder version attributes
    // use the CommonManager to get the attributes of an Item
    folder = cm.getItem(folder.getId(), fdr_ver_attr);
 
    // returned item has the requested attributes in a NamedValue[]
    // convert it to a map for easy lookup and access to attributes
    NamedValue[] attrs = folder.getRequestedAttributes();
    Map attrMap = ClientUtils.namedValuesToMap(attrs);
    WsUtility.log("");
    
    // attributes name and value
    WsUtility.log(Attributes.PATH);
    // PATH attribute
    WsUtility.log(WsUtility.INDENT + (String) attrMap.get(Attributes.PATH));
    
    WsUtility.log(Attributes.DESCRIPTION);
    WsUtility.log(WsUtility.INDENT
        + (String) attrMap.get(Attributes.DESCRIPTION));
    
    WsUtility.log(Attributes.VERSIONING_CONFIGURATION);
    // VERSIONING_CONFIGURATION is again an Item which will have the nested
       attributes 
    // that we requested for
    Item verItem = (Item) attrMap.get(Attributes.VERSIONING_CONFIGURATION);
    
    // again we get these as NamedValue[]
    // convert it to a map for easy lookup
    attrs = verItem.getRequestedAttributes();
    attrMap = ClientUtils.namedValuesToMap(attrs);
    
    WsUtility.log(WsUtility.INDENT
        + Attributes.VERSIONING_CONFIGURATION_AUTO_LABEL);
    WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
        + (Boolean) attrMap.get(Attributes.VERSIONING_CONFIGURATION_AUTO_LABEL));
    
    WsUtility.log(WsUtility.INDENT
        + Attributes.VERSIONING_CONFIGURATION_AUTO_VERSION);
    WsUtility.log(WsUtility.INDENT
        + WsUtility.INDENT
        + (Boolean) attrMap.get(
            Attributes.VERSIONING_CONFIGURATION_AUTO_VERSION));
    
    WsUtility.log(WsUtility.INDENT
        + Attributes.VERSIONING_CONFIGURATION_MAX_VERSIONS);
    WsUtility.log(WsUtility.INDENT
        + WsUtility.INDENT
        + (Integer) attrMap.get(
            Attributes.VERSIONING_CONFIGURATION_MAX_VERSIONS));
    
    WsUtility.log(WsUtility.INDENT + Attributes.CONFIGURATION_ENABLED);
    WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
        + (Boolean) attrMap.get(Attributes.CONFIGURATION_ENABLED));
}

The attribute request stored in the array fdr_ver_attr is an example of a nested attribute request. The attribute VERSIONING_CONFIGURATION contains multiple sub-attributes, all of which are stored in a subarray of the original request. Oracle Content Services can produce attributes for any level of nesting.

Reading nested attributes follows the same process as regular attributes. Since each nested attribute is itself a fully formed attribute request, you can use the getRequestedAttributes method on its Item object.

Note that the examples use the WsUtility class, which is included with the samples. This class contains many convenient wrappers for simple operations such as object instantiation and logging. These wrappers are used primarily for the sake of readability, and are not necessary.

Below is a second example, featuring two levels of nesting. The nested attribute request extracts attributes for a document, one of which is the nested VERSIONS attribute. For each version, the request fetches information about that versioned document, as well as the nested VERSIONED_DOCUMENT attribute. This attribute contains information about the versioned document itself. The entire structure is returned in the docs variable, converted to a Map, and extracted.

/**
 * Checks in a Document.
 */
public static void checkinDocument(Item workingCopy)
    throws FdkException, RemoteException
{
    // get the Manager instances
    CommonManager cm = s_WsCon.getCommonManager();
    VersionManager vm = s_WsCon.getVersionManager();
 
    // create checkin document definition
    // set a label and comment while checking in
    NamedValue[] checkInDef = WsUtility.newNamedValueArray(new Object[][] {
        { Attributes.VERSION_COMMENT, "a new version" },
        { Attributes.VERSION_LABEL, "2.0" } });
 
    NamedValueSet[] checkInDefs = new NamedValueSet[] { 
        WsUtility.newNamedValueSet(checkInDef) };
 
    // check in the document 
    vm.checkin(new long[] { workingCopy.getId() }, null, checkInDefs, null);
 
    // request for the attributes of the document
    // we look for the document's attributes,
    // attributes for different versions of this document
    // and for each version we get the details of the version
    AttributeRequest[] doc_ver_attr = new AttributeRequest[] {
        WsUtility.newAttributeRequest(Attributes.PATH),
        WsUtility.newAttributeRequest(Attributes.DESCRIPTION),
        // request for the version details
        WsUtility.newAttributeRequest(Attributes.VERSIONS,
            new AttributeRequest[] {
                WsUtility.newAttributeRequest(Attributes.VERSION_LABEL),
                WsUtility.newAttributeRequest(Attributes.VERSION_COMMENT),
                WsUtility.newAttributeRequest(Attributes.VERSIONED_DOCUMENT,
                    // request for attributes of each version
                    new AttributeRequest[] {
                    WsUtility.newAttributeRequest(Attributes.DESCRIPTION),
                    WsUtility.newAttributeRequest(Attributes.DOCUMENT_LANGUAGE),
                    WsUtility.newAttributeRequest(Attributes.CHARACTER_SET) }) 
    }) };
 
    // fetch the attributes via the CommonManager
    Item docs = cm.getItem(workingCopy.getId(), doc_ver_attr);
 
    // the returned item has the requested attributes in a NamedValue[]
    // convert it to a map for easy lookup and access to attributes
    NamedValue[] attrs = docs.getRequestedAttributes();
    Map attrMap = ClientUtils.namedValuesToMap(attrs);
    WsUtility.log("");
    
    // the document's attributes
    WsUtility.log(Attributes.PATH);
    WsUtility.log(WsUtility.INDENT + (String) attrMap.get(Attributes.PATH));
    
    WsUtility.log(Attributes.DESCRIPTION);
    WsUtility.log(WsUtility.INDENT
        + (String) attrMap.get(Attributes.DESCRIPTION));
    
    WsUtility.log(Attributes.VERSIONS);
    // these are the different versions of the document
    Item[] verItem = (Item[]) attrMap.get(Attributes.VERSIONS);
    for (int i = 0; i < verItem.length; i++)
    {
        // get second level of attributes
        attrs = verItem[i].getRequestedAttributes();
        attrMap = ClientUtils.namedValuesToMap(attrs);
    
        WsUtility.log(WsUtility.INDENT + Attributes.VERSION_LABEL);
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
            + (String) attrMap.get(Attributes.VERSION_LABEL));
      
        WsUtility.log(WsUtility.INDENT + Attributes.VERSION_COMMENT);
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
            + (String) attrMap.get(Attributes.VERSION_COMMENT));
      
        WsUtility.log(WsUtility.INDENT + Attributes.VERSIONED_DOCUMENT);
        // for each version the attributes of those documents that were versioned 
        Item docItem = (Item) attrMap.get(Attributes.VERSIONED_DOCUMENT);
      
        // get third level of attributes
        attrs = docItem.getRequestedAttributes();
        attrMap = ClientUtils.namedValuesToMap(attrs);
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
            + Attributes.DESCRIPTION);
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT + WsUtility.INDENT
            + (String) attrMap.get(Attributes.DESCRIPTION));
      
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
            + Attributes.DOCUMENT_LANGUAGE);
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT + WsUtility.INDENT
            + (String) attrMap.get(Attributes.DOCUMENT_LANGUAGE));
      
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT
            + Attributes.CHARACTER_SET);
        WsUtility.log(WsUtility.INDENT + WsUtility.INDENT + WsUtility.INDENT
            + (String) attrMap.get(Attributes.CHARACTER_SET));
    }
}

NamedValue and NamedValueSet

Every Item object has a getRequested Attributes method returns the attribute set in an array of NamedValue objects. The NamedValue class represents a name/value pair. In Oracle Content Services this class is used to represent attributes, options, and preferences. When working with a returned NamedValue array, it is often easier to convert it to a Map to allow lookups by attribute name. The preceding examples use the namedValuesToMap method (found in the included ClientUtils class), which returns a Map object comprising all the elements of the NamedValue array, with the name elements as key. Another option is to use the NamedValueSet class, which stores arrays of NamedValue objects. This class is used primarily to avoid the need to manage multi-dimensional arrays of attributes.