Working with properties

Each object in the CE has

metadata

. This metadata can range from the date that the object was created to the title of a document to a binary large object (BLOB) of data. Metadata is stored and accessed using the

properties

of the given object.

The CE provides the following metadata types for use: 򐂰 Text

򐂰 32-bit Integer 򐂰 64-bit Floating Point 򐂰 Binary

򐂰 Boolean 򐂰 Date/Time 򐂰 GUID 򐂰 Object

Note: When creating objects, specifying the object ID for the object being

created is possible by setting the value of the ID property. In addition, the ID class offers a method to create an IBM FileNet P8 object ID. Unless you have a specific reason for doing so, you should not explicitly specify the object ID. An ID will be created by the API or by the CE server.

Properties can also can be either

single-valued

or

multi-valued

, meaning the property can store either a single value or one or more values.

Object properties

Object-valued properties

(OVP) work a bit differently than the other property types. For more information, see 4.3.1, “Object-valued properties” on page 94.

Properties collections

All CE objects have properties, or metadata, that describe that object. When an object has been retrieved with the API, these properties are stored locally in a

properties collection

. This collection holds property values for existing objects or stores new or updated values to be committed to the CE.

The primary property collection classes are Properties for Java and IProperties for .NET and are typically accessed with the .getProperties() method in Java or the .Properties property in .NET. Although the properties collection can be iterated or enumerated, a more common approach is to access a given property directly through the .get(name) method or .Item[name]

property, which returns a Property object that represents that property and its value (or values).

Dynamically determining property type requires a cascade of instanceof in Java or is in .NET.

Setting single-valued property value

To set the value of a single-valued property in Java: 1. Create it locally or retrieve the object.

2. Get the properties collection.

3. Add the value by using the .putValue() method.

Example 3-10 on page 55, adapted from the ITSONewVehicleActivity.java program, shows how to retrieve the properties of a document and to update the

Note: For clarity, the following code examples omit the save method call, so,

Example 3-10 Setting a single-valued property in Java

// Get the properties collection

Properties props = activity.getProperties(); // Get the start date

Date start = new Date(System.currentTimeMillis()); // Set the properties

props.putValue("ITSOStartDate", start);

The .NET API works slightly different from the Java API. To set a single value property in .NET:

1. Create locally or retrieve the object. 2. Get the properties collection.

3. Set the value of the property by using the properties["propertyname"] convention.

Example 3-11 shows how to retrieve the properties of a document and to update the value of the ITSOStartDate property with the current date and time.

Example 3-11 Getting and setting properties in C#

// Get the properties collection for a Document IProperties properties = d.Properties;

Property["ITSOStartDate"] = DateTime.Now;

Setting multi-valued property values

To set a multi-valued property in Java: 1. Retrieve or create the object.

2. Set the value of the property to be a list using the .putValue() method.

Example 3-12 on page 56 shows how to retrieve the properties of a document, create a list of integer properties with two values, and to set the local value of the property "MutliValuedIntProperty" to be those values.

Note: For clarity, the following code examples omit the save method call, so,

as written, the examples would not commit any property changes.

Note: Setting the value of a multi-valued object-valued property is not

Example 3-12 Setting a multi-valued property in Java

// Get the properties collection for a Document Properties properties = document.getProperties(); // Create a multi-value integer list

Integer32List list = Factory.Integer32List.createList(); list.add(100);

list.add(212);

// Add that to the properties for the document properties.putValue("MutliValuedIntProperty",list);

To set a multi-valued property in .NET: 1. Create or retrieve the object. 2. Get the properties collection. 3. Create the value list.

4. Add the values.

5. Set the value of the property to be the list using the properties["name"] convention.

See Example 3-13.

Example 3-13 Setting multi-valued property in C#

IProperties properties = d.Properties;

// Create a multi-value integer list and add 2 values IInteger32List list = Factory.Integer32List.CreateList(); list.Add(100);

list.Add(212);

property["MultiValuedIntProperty"] = list;

Retrieving property values

Example 3-14 shows, using Java, how to retrieve the value of a single-valued string property, StringProperty, and a multi-valued ID property, RelatedIds.

Example 3-14 Retrieving property values from a CE object using Java

// Get the properties collection from a custom object Properties properties = o.getProperties();

// Get a string value and print to the console

System.out.println( properties.getStringValue("StringProperty") ); // Get a multi-value ID property

IdList ids = properties.getIdListValue("RelatedIds");

// Iterate through the list of values, printing them to the console for( Iterator i = ids.iterator(); i.hasNext(); )

{

// Get the value and cast to an Id property type Id property = (Id)i.next();

// Print the value to the console

System.out.println(property.toString()); }

To retrieve property values in C#: 1. Retrieve the object.

2. Get the properties collection.

3. Get the value(s) using .Get

<

type

>

Value() or .Get

<

type

>

ValueList() (for example, GetStringValue or GetInt32ListValue())

Example 3-15 shows how to retrieve the value of a single-valued string property, StringProperty, and a multi-valued ID property, RelatedIds.

Example 3-15 Retrieving property values from a CE object using C#

// Get the properties for a custom object Properties properties = o.Properties; // Write out the string property value Console.WriteLine("Property value: " +

properties.GetStringValue("StringProperty")); // Get a multi-valued ID property

IIdList ids = properties.GetIdListValue("RelatedIds"); // Loop through the properties

for( IEnumerator i = ids.GetEnumerator(); i.MoveNext(); ) {

// Cast the current property to an Id property Id property = (Id)i.Current;

// Print out the value to the console Console.WriteLine(property.ToString()); }

Properties in local cache

The CE APIs give you explicit control over whether or not any particular property is in the local cache. For example, when retrieving an object from the CE, having the result exclude some of the properties is possible. For details about how, see 3.4.7, “Working with property filters” on page 66. If a PropertyFilter has been applied during the fetchInstance, refresh, or fetchProperties calls, not all properties of an object will be available. Trying to get any of the missing properties will result in an EngineRuntimeException exception.

In document Developing Applications With IBM FileNet P8 APIs (Page 73-78)