This topic describes tasks and provides Java™ and C# code examples that use property-related objects.
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;
}
}
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;
}
}
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();
To create a property filter, follow these steps:
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);
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:
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:
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]