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:
PropertyFilter
object.PropertyFilter
object's global attributes, call the appropriate method:
setMaxRecursion
.setMaxSize
.setLevelDependents
.setPageSize
.FilterElement
object (proceed to step 4) or have the server create one for you (skip to step 6). 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. 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. 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.
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 } }
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);
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 above code example, the server performs the following tasks:
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. 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. 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. 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]
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 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]
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 above example as it traverses into a Document
object:
Document
object [0]
DateCreated
ContentElements: Returns a collection of ContentElement
objects [0]
ContentType
ElementSequenceNumber