Working with Properties

The following topics describes tasks and provides Java™ and C# code examples that use property-related objects.

Retrieving a PropertyDescription Object

The following code example demonstrates how to find a specific PropertyDescription object in an object store:

Java Example


System.out.println ("Type the symbolic name of the class description in which the property description is located:");
InputStreamReader converter = new InputStreamReader(System.in);
BufferedReader in = new BufferedReader(converter);
String strClassDescSymbolicName = in.readLine();

// Construct property filter to ensure PropertyDescriptions property of CD is returned as evaluated
PropertyFilter pf = new PropertyFilter();
pf.addIncludeType(0, null, Boolean.TRUE, FilteredPropertyType.ANY, null); 
 
// Fetch selected class description from the server
ClassDescription objClassDesc = Factory.ClassDescription.fetchInstance(objObjectStore, strClassDescSymbolicName, pf);

String strPropDescSymbolicName;   
System.out.println("Type the symbolic name of the property description you want to retrieve:");
String strSearchName = in.readLine();
                 
// Get PropertyDescriptions property from the property cache
PropertyDescriptionList objPropDescs = objClassDesc.get_PropertyDescriptions(); 
                                        
Iterator iter = objPropDescs.iterator();
PropertyDescription objPropDesc = null;
          
// Loop until property description found
while (iter.hasNext())
{                                               
   objPropDesc = (PropertyDescription) iter.next();                      
                        
   // Get SymbolicName property from the property cache
   strPropDescSymbolicName = objPropDesc.get_SymbolicName();

   if (strPropDescSymbolicName.equalsIgnoreCase(strSearchName))
   {
      // PropertyDescription object found
      System.out.println("Property description selected: " + strPropDescSymbolicName);
      System.out.println(objPropDesc);
      break;
   }
}

C# Example


Console.WriteLine("Type the symbolic name of the class description in which the property description is located:");
String strClassDescSymbolicName = Console.ReadLine();

// Construct property filter to ensure PropertyDescriptions property of CD is returned as evaluated
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeType(0, null, true, FilteredPropertyType.ANY, null); 
                
// Fetch selected class description from the server
IClassDescription objClassDesc = Factory.ClassDescription.FetchInstance(objObjectStore, strClassDescSymbolicName, pf);                  
 
String strPropDescSymbolicName;    
Console.WriteLine("Type the symbolic name of the property description you want to retrieve:");
String strSearchName = Console.ReadLine();
                 
// Get PropertyDescription property from the property cache                     
IPropertyDescriptionList objPropDescs = objClassDesc.PropertyDescriptions;                                      
          
// Loop until property description found
foreach (IPropertyDescription objPropDesc in objPropDescs)
{
   strPropDescSymbolicName = objPropDesc.SymbolicName;
   if (strPropDescSymbolicName.Equals(strSearchName, StringComparison.OrdinalIgnoreCase))
   {
      // PropertyDescription object found
      Console.WriteLine("Property description selected: " + strPropDescSymbolicName);
      Console.WriteLine(objPropDesc);
      Console.WriteLine("Press any key to end");
      Console.ReadLine();
      break;
   }             
}

Retrieving a PropertyDefinition Object

The following code example demonstrates how to find a specific PropertyDefinition object in an object store.

Java Example


System.out.println ("Type the symbolic name of the class definition in which the property definition is located:");
InputStreamReader converter = new InputStreamReader(System.in);
BufferedReader in = new BufferedReader(converter);
String strClassDefSymbolicName = in.readLine(); 

// Construct property filter to ensure PropertyDefinitions property of CD is returned as evaluated
PropertyFilter pf = new PropertyFilter();
pf.addIncludeType(0, null, Boolean.TRUE, FilteredPropertyType.ANY, null); 

// Fetch selected class definition from the server
ClassDefinition objClassDef = Factory.ClassDefinition.fetchInstance(objObjectStore, strClassDefSymbolicName, pf);                       

String objPropDefSymbolicName;   
System.out.println("Type the name of the property definition you want to retrieve:");
String strSearchName = in.readLine();
                 
// Get PropertyDefinitions property from the property cache                     
PropertyDefinitionList objPropDefs = objClassDef.get_PropertyDefinitions();   
                                        
Iterator iter = objPropDefs.iterator();
PropertyDefinition objPropDef = null;
          
// Loop until property definition found
while (iter.hasNext())
{                                               
   objPropDef = (PropertyDefinition) iter.next();
                 
   // Get SymbolicName property from the property cache
   objPropDefSymbolicName = objPropDef.get_SymbolicName();

   if (objPropDefSymbolicName.equalsIgnoreCase(strSearchName))
   {
      // PropertyDefinition object found
      System.out.println("Property definition selected: " + objPropDefSymbolicName);
      System.out.println(objPropDef);
      break;
   }
}

C# Example


Console.WriteLine ("Type the symbolic name of the class definition in which the property definition is located:");
String strClassDefSymbolicName = Console.ReadLine ();

// Construct property filter to ensure PropertyDefinitions property of CD is returned as evaluated
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeType(0, null, true, FilteredPropertyType.ANY, null); 
                        
// Fetch selected class definition from the server
IClassDefinition objClassDef = Factory.ClassDefinition.FetchInstance(objObjectStore, strClassDefSymbolicName, pf);

String objPropDefSymbolicName;    
Console.WriteLine("Type the name of the property definition you want to retrieve:");
String strSearchName = Console.ReadLine ();
                 
// Get PropertyDefinitions property from the property cache                     
IPropertyDefinitionList objPropDefs = objClassDef.PropertyDefinitions;                                          
          
// Loop until property definition found
foreach (IPropertyDefinition objPropDef in objPropDefs)
{
   objPropDefSymbolicName = objPropDef.SymbolicName;

   if (objPropDefSymbolicName.Equals(strSearchName, StringComparison.OrdinalIgnoreCase))
   {
      // PropertyDefinition object found
      Console.WriteLine("Property definition selected: " + objPropDefSymbolicName);
      Console.WriteLine(objPropDef);
      Console.WriteLine("Press any key to end");
      Console.ReadLine();
      break;
   }             
}

Creating a Custom Property

The following code example demonstrates how to create a custom property by creating a property definition from a new property template and adding it to a class definition:

Java Example


System.out.println ("Type the symbolic name of the class definition in which to add the new custom property:");
InputStreamReader converter = new InputStreamReader(System.in);
BufferedReader in = new BufferedReader(converter);
String strClassDefSymbolicName = in.readLine();

// Construct property filter to ensure PropertyDefinitions property of CD is returned as evaluated
PropertyFilter pf = new PropertyFilter();
pf.addIncludeType(0, null, Boolean.TRUE, FilteredPropertyType.ANY, null); 

// Fetch selected class definition from the server
ClassDefinition objClassDef = Factory.ClassDefinition.fetchInstance(objObjectStore, strClassDefSymbolicName, pf);                       
System.out.println("Class definition selected: " + objClassDef.get_SymbolicName());
                        
// Create property template for a single-valued string property
System.out.println ("Type the name of the new property template:");
String strPropTemplateName = in.readLine();
PropertyTemplateString objPropTemplate = Factory.PropertyTemplateString.createInstance(objObjectStore);
                        
// Set cardinality of properties that will be created from the property template
objPropTemplate.set_Cardinality (Cardinality.SINGLE);

// Set up locale
LocalizedString locStr = Factory.LocalizedString.createInstance();
locStr.set_LocalizedText(strPropTemplateName);
locStr.set_LocaleName (objObjectStore.get_LocaleName());

// Create LocalizedString collection
objPropTemplate.set_DisplayNames (Factory.LocalizedString.createList());
objPropTemplate.get_DisplayNames().add(locStr);

// Save new property template to the server
objPropTemplate.save(RefreshMode.REFRESH);

// Create property definition from property template
PropertyDefinitionString objPropDef = (PropertyDefinitionString)objPropTemplate.createClassProperty();
                 
// Get PropertyDefinitions property from the property cache                     
PropertyDefinitionList objPropDefs = objClassDef.get_PropertyDefinitions(); 

// Add new property definition to class definition
objPropDefs.add(objPropDef);
objClassDef.save(RefreshMode.REFRESH);                                                                          
                                        
System.out.println("New property definition: ");
System.out.println(objPropDef);

C# Example


Console.WriteLine ("Type the symbolic name of the class definition in which to add the new custom property:");
String strClassDefSymbolicName = Console.ReadLine();

// Construct property filter to ensure PropertyDefinitions property of CD is returned as evaluated
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeType(0, null, true, FilteredPropertyType.ANY, null); 

// Fetch selected class definition from the server
IClassDefinition objClassDef = Factory.ClassDefinition.FetchInstance(objObjectStore, strClassDefSymbolicName, pf);
Console.WriteLine("Class definition selected: " + objClassDef.SymbolicName);
                        
// Create property template for a single-valued string property
Console.WriteLine("Type the name of the new property template:");
String strPropTemplateName = Console.ReadLine();
IPropertyTemplateString objPropTemplate = Factory.PropertyTemplateString.CreateInstance(objObjectStore);
                        
// Set cardinality of properties that will be created from the property template
objPropTemplate.Cardinality = Cardinality.SINGLE;

// Set up locale
ILocalizedString LocStr = Factory.LocalizedString.CreateInstance();
LocStr.LocalizedText = strPropTemplateName;
LocStr.LocaleName = objObjectStore.LocaleName;

// Create LocalizedString collection
objPropTemplate.DisplayNames = Factory.LocalizedString.CreateList();
objPropTemplate.DisplayNames.Add(LocStr);

// Save new property template to the server
objPropTemplate.Save(RefreshMode.REFRESH);

// Create property definition from property template
IPropertyDefinitionString objPropDef = (IPropertyDefinitionString)objPropTemplate.CreateClassProperty();
                 
// Get PropertyDefinitions property from the property cache                     
IPropertyDefinitionList objPropDefs = objClassDef.PropertyDefinitions; 

// Add new property definition to class definition
objPropDefs.Add(objPropDef);
objClassDef.Save(RefreshMode.REFRESH);                                                                          
                                        
Console.WriteLine("New property definition: ");
Console.WriteLine(objPropDef);
Console.WriteLine("Press any key to end");
Console.ReadLine();

Creating a Property Filter

To create a property filter, follow these steps:

  1. Create a PropertyFilter object.
  2. To set any of the PropertyFilter object's global attributes, call the appropriate method:
    • To set the maxRecursion global attribute, call setMaxRecursion.
    • To set the maxSize global attribute, call setMaxSize.
    • To set the levelDependents global attribute, call setLevelDependents.
    • To set the pageSize global attribute, call setPageSize.
  3. You can either create a FilterElement object (proceed to step 4) or have the server create one for you (skip to step 6).
  4. Create a FilterElement object by using one of its constructors. Set any of its four attributes (maxRecursion, maxSize, levelDependents, and pageSize) with the appropriate parameter in its constructor. Any attribute that you set overrides the value of the corresponding global attribute on the PropertyFilter object.
  5. Call an addIncludeProperty or addIncludeType method, passing the FilterElement object that you created. Repeat steps 4 and 5 for each filter element that you want to create.
  6. If you want the server to create a FilterElement object for your application, call the appropriate addIncludeProperty or addIncludeType method and pass a space-separated list of property identifiers or property types. You can also pass in values for the filter element attributes: maxRecursion, maxSize, levelDependents, and pageSize. Any filter element attribute that you set overrides the value of the corresponding global attribute on the PropertyFilter object. Repeat this step for each filter element that you want the server to create.

Using a Property Filter

Single Property Fetching

This code example demonstrates how to fetch the Reservation property of a Document object by using both the string form and the property filter form of the fetchProperties method.

In the example, the property filter includes a filter element to fetch the Reservation property and uses the default values for the maxRecursion, maxSize, levelDependents, and pageSize attributes. The property filter's global maxRecursion attribute is set to 1, which includes all properties with a symbolic name of "Reservation" that are at a current recursion level of 1 (the DocObj object is at a current recursion level of 0 and the properties that belong to the reservation object returned by the Reservation property are at a current recursion level of 2).

Java Example


public static void fetchReservation(
    boolean usePropertyFilter,
    Document docObj)
{
    // Define property name array
    String propNames[] = {"Reservation"};

    // Define filter element
    FilterElement fe 
        = new FilterElement(null, null, null, propNames[0], null);

    // Define property filter
    PropertyFilter pf = new PropertyFilter();           
    pf.addIncludeProperty(fe);
    pf.setMaxRecursion(1);              
        
    // Fetch reservation property
    if (usePropertyFilter == true) 
    {
        docObj.fetchProperties(pf);          // Using property filter form
    }
    else 
    {   
        docObj.fetchProperties(propNames);      // Using string form
    }
}

C# Example


public static void FetchReservation(
    Boolean usePropertyFilter,
    IDocument docObj)
{
    // Define property name array
    String[] propNames = {"Reservation"};

    // Define filter element
    FilterElement fe
        = new FilterElement(null, null, null, propNames[0], null);

    // Define property filter
    PropertyFilter pf = new PropertyFilter();
    pf.AddIncludeProperty(fe);
    pf.SetMaxRecursion(1);

    // Fetch reservation property
    if (usePropertyFilter == true)
    {
        docObj.FetchProperties(pf);             // Using property filter form
    }
    else
    {
        docObj.FetchProperties(propNames);      // Using string form
    }
}

Multiple Property Fetching

The following code example demonstrates how to fetch the DateCreated and DateLastModified properties, in addition to all singleton properties, except for the Owner property:

Java Example


PropertyFilter pf = new PropertyFilter();       
pf.addIncludeProperty(
    new FilterElement(null, null, null, 
    "DateCreated DateLastModified", null));      
pf.addIncludeType(
    new FilterElement(null, null, null, "Singleton*", null));      
pf.addExcludeProperty("Owner");      
pf.setMaxRecursion(1);          
DocObj.fetchProperties(pf);

C# Example


PropertyFilter pf = new PropertyFilter();       
pf.AddIncludeProperty(
    new FilterElement(null, null, null, 
    "DateCreated DateLastModified", null));      
pf.AddIncludeType(
    new FilterElement(null, null, null, "Singleton*", null));      
pf.AddExcludeProperty("Owner");      
pf.SetMaxRecursion(1);          
DocObj.FetchProperties(pf);

Property Recursion

Depth Definition

The following code example demonstrates the use of the maxRecursion attribute to define the depth of recursion for fetching property relationships:

Java Example


PropertyFilter pf = new PropertyFilter();
pf.setMaxRecursion(1);
pf.addIncludeProperty(new FilterElement(null, null, null, "Reservation Creator", null));     
pf.addIncludeProperty(new FilterElement(new Integer(2), null, null, "FoldersFiledIn DateCreated", null));             
DocObj.fetchProperties(pf);

C# Example


PropertyFilter pf = new PropertyFilter();
pf.SetMaxRecursion(1);
pf.AddIncludeProperty(new FilterElement(null, null, null, "Reservation Creator", null));     
pf.AddIncludeProperty(new FilterElement(2, null, null, "FoldersFiledIn DateCreated", null));                  
DocObj.FetchProperties(pf);

In this property filter, the property filter’s global maxRecursion attribute is set to 1 and applies to the Reservation and Creator properties. However, for the FoldersFiledIn and DateCreated properties, the global maxRecursion attribute is overridden by the filter element maxRecursion attribute that has a value of 2.

The following Document object properties are fetched (the current recursion level for each object is shown in brackets):

Document object #1 [0]

  • DateCreated
  • Creator
  • Reservation: Returns Document object #2 [1]
    • DateCreated
    • Creator
    • Reservation: Returns unevaluated object [2]
    • FoldersFiledIn: Returns a collection of Folder objects [2] (belonging to Document object #2)
      • DateCreated
  • FoldersFiledIn: Returns Folder objects [1] (belonging to Document object #1)
    • DateCreated
    • Creator

In the previous code example, the server performs the following tasks:

  1. Fetches the top-level object, document #1, which has a current recursion level equal to 0.
  2. Analyzes the four properties in the property filter: DateCreated, Creator, Reservation, and FoldersFiledIn. Because the current recursion level (0) is less than the value of the maxRecursion attribute for each of these properties, the values for all these properties are returned.
  3. Traverses into the Reservation object, which returns Document object #2; the current recursion level is now 1. The DateCreated, Creator, and FoldersFiledIn properties are returned, but the Reservation property (note that this property is a recursive document property) returns an unevaluated object instead of a Reservation object because its maxRecursion attribute value is 1.
  4. Traverses into the FoldersFiledIn property of Document object #2; the current recursion level is now 2. The only property that is returned for these folders is DateCreated. Creator is not returned because it has a maxRecursion attribute value of 1.
  5. Traverses into the FoldersFiledIn property of Document object #1; the current recursion level is now 1. The DateCreated and Creator properties for each folder that is returned because both properties have maxRecursion attribute values greater than or equal to 1.

Duplicate Object Suppression

During object retrieval of objects that have object-valued properties, it is possible to reach the same object multiple times if a property filter forces a recursion. (For example, retrieving a folder and forcing deep recursion through the Parent and SubFolders properties.) This scenario can lead to runaway recursion and excessive memory usage on the server. To prevent this recursion, the server uses a mechanism to suppress recursion into duplicate ending recursion at a duplicate object. When duplicate objects are detected, an object reference is placed into the response instead of the object value.

In the following code example, the maxRecursion attribute value is changed to 10 for the filter element that specifies the Reservation property as shown in the following code example:

Java Example


PropertyFilter pf = new PropertyFilter();
pf.setMaxRecursion(1);
pf.addIncludeProperty(new FilterElement(null, null, null, "Creator", null));
pf.addIncludeProperty(new FilterElement(new Integer(2), null, null, "FoldersFiledIn DateCreated", null));
pf.addIncludeProperty(new FilterElement(new Integer(10), null, null, "Reservation", null));
DocObj.fetchProperties(pf);

C# Example


PropertyFilter pf = new PropertyFilter();
pf.SetMaxRecursion(1);
pf.AddIncludeProperty(new FilterElement(null, null, null, "Creator", null));
pf.AddIncludeProperty(new FilterElement(2, null, null, "FoldersFiledIn DateCreated", null));
pf.AddIncludeProperty(new FilterElement(10, null, null, "Reservation", null));
DocObj.FetchProperties(pf);

The server employs a duplicate object detection algorithm and returns the following properties (the current recursion level for each property is shown in brackets):

Document object #1 [0]

  • DateCreated
  • Creator
  • StorageArea [1]
    • DateCreated
    • Creator
  • Reservation: Returns Document object #2 [1]
    • DateCreated
    • Creator
    • Reservation: Returns Document object #2 [2]
    • FoldersFiledIn: Returns a collection of Folder objects [2] (belonging to Document object #2)
      • DateCreated
  • FoldersFiledIn: Returns a collection of Folder objects [1] (belonging to Document object #1)
    • DateCreated
    • Creator

In the results for this example, note that the nested Reservation property returns its parent Document object; otherwise, without duplicate object suppression, the same Document object is retrieved 10 times instead of only once.

For client applications, duplicate object suppression implies the following statements:

  1. Because circular loops are present in the data that is returned, do not attempt to write logic that traverses downward to the bottom of an object tree without detecting duplicates.
  2. The contents of an object found at a lower level in an object tree might not match the property filter at that level because a pointer to an object at a higher level of the object tree might have been returned.

Dependent Objects

The easiest way to use the levelDependents attribute to return dependent objects is to create an empty property filter (no IncludeProperty, IncludeType, or ExcludeProperty specifications) with a maxRecursion attribute value of 0 and a levelDependents attribute value of true. This property filter returns all of an object's scalar properties and all object-valued properties that return dependent objects.

For example, consider the ContentElements property of a Document object, which returns a collection of ContentElement dependent objects. When the levelDependents attribute is false and the maxRecursion attribute set to 0, the collection's elements are not included because their current recursion level is 1. If the levelDependents attribute is changed to true, the collection's elements are included because their current recursion level is either the same as the recursion level of their parent Document object, or 0.

Java Example


public static void fetchProperties(
    Boolean levelDependents,
    Document docObj)
{
    // Specify properties to retrieve
    String propNames 
        = "DateCreated ContentElements ContentType "      
        + "ElementSequenceNumber";

    // Define filter element
    // For levelDependents parameter:
    // If TRUE: elements of ContentElements are fetched  
    // If FALSE: elements of ContentElements are not fetched
    FilterElement fe = new FilterElement(
        null, null, levelDependents, propNames, null);    

    // Define property filter using filter element
    PropertyFilter pf = new PropertyFilter();        
    pf.addIncludeProperty(fe);
    pf.setMaxRecursion(0);     

    // Fetch properties based on property filter
    docObj.fetchProperties(pf); 
}

C# Example


public static void FetchProperties(
    Boolean levelDependents,
    IDocument docObj)
{
    // Specify properties to retrieve
    String propNames 
        = "DateCreated ContentElements ContentType "      
        + "ElementSequenceNumber";

    // Define filter element
    // For levelDependents parameter:
    // If true: elements of ContentElements are fetched  
    // If false: elements of ContentElements are not fetched
    FilterElement fe = new FilterElement(
        null, null, levelDependents, propNames, null);

    // Define property filter using filter element
    PropertyFilter pf = new PropertyFilter();     
    pf.AddIncludeProperty(fe);    
    pf.SetMaxRecursion(0);     
        
    // Fetch properties based on property filter
    docObj.FetchProperties(pf); 
}

When levelDependents is false, the server returns the following properties and maintains the following current recursion levels (shown in brackets) for the previous example as it traverses into a Document object:

Document object [0]

  • DateCreated
  • ContentElements: Returns an unevaluated object [1]

When levelDependents is true, the server returns the following properties and maintains the following current recursion levels (shown in brackets) for the previous example as it traverses into a Document object:

Document object [0]

  • DateCreated
  • ContentElements: Returns a collection of ContentElement objects [0]
    • ContentType
    • ElementSequenceNumber