IBM FileNet P8, Version 5.2            

Working with Properties

This topic 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 using one of its constructors. Set any of its four attributes (maxRecursion, maxSize, levelDependents, and pageSize) via the appropriate parameter in its constructor. Any attribute that you set will override the value of the corresponding global attribute on the PropertyFilter object.
  5. Call an addIncludeProperty or addIncludeType method, passing the FilterElement object you just 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 will override 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

The code example below demonstrates how to fetch the Reservation property of a Document object 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 belonging 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, with the exception of 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]

In the above 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 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 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 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 more than once if a property filter forces a recursion. (For example, retrieving a folder and forcing deep recursion through the Parent and SubFolders properties.) This can lead to runaway recursion and excessive memory usage on the server. To prevent this, the server uses a mechanism to suppress recursion into duplicate objects. This duplicate object suppression mechanism overrides the true recursion level and operates as if the maximum recursion level has already been reached for the duplicate object, therefore terminating 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 specifying 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]

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 would be retrieved 10 times instead of only once.

For client applications, duplicate object suppression implies the following:

  1. Because circular loops are present in the data returned, you should 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 may not match the property filter at that level, because a pointer to an object at a higher level of the object tree may 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 will return 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 the same as that 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 above example as it traverses into a Document object:

Document object [0]

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

Document object [0]


Feedback

Last updated: October 2013
property_procedures.htm

© Copyright IBM Corporation 2014.
This information center is powered by Eclipse technology. (http://www.eclipse.org)