Represents a single choice item in a choice list that can be assigned to a property, or represents a group node for a nested collection of choice items within a choice list. A choice item is a single possible value, or choice, in a choice list. A choice item can be of two possible types: integer or string. An integer-type choice item holds a single integer value and can be assigned only to an integer-valued property. A string-type choice item holds a single string value and can be assigned only to a string-valued property.

A Choice object is a dependently persistable object; it has no Save method and therefore cannot be independently saved. Because any given Choice object is dependent on the independently persistable com.filenet.api.admin.ChoiceList object to which it belongs, its state is not saved until you call the Save method of the ChoiceList object that owns it. For a given Choice object to belong to a com.filenet.api.admin.ChoiceList object, it must be added to the com.filenet.api.collection.ChoiceList collection that is returned by the com.filenet.api.admin.ChoiceList object's ChoiceValues property.

The type of data that a Choice object can represent is determined by the ChoiceType constant value that you specify with its ChoiceType property. This property determines whether a Choice object represents an integer-type choice item, a string-type choice item, a group node for a nested collection of integer-type choice items, or a group node for a nested collection of string-type choice items.

Localization is provided by the DisplayNames property, using the same mechanism that ClassDefinition and PropertyTemplate objects use. However, unlike those objects, the Choice object does not have a DescriptiveTexts property. To localize a Choice object, set its DisplayNames property to a LocalizedStringList object containing a collection of LocalizedString objects. Each object in this collection represents a locale-specific, user-readable display name that can be used for a Choice object; set its LocaleName property to a locale ID and its LocalizedText property to the localized text for the display name. Once you have set the DisplayNames property, the server will automatically set the value of the DisplayName property to the LocalizedText property value of the LocalizedString object in the LocalizedStringList collection that corresponds to the object store's default locale.

A Choice object's display name, or label, identifies it and is stored by its DisplayName property. You can either set the DisplayName property directly or you can set it indirectly by setting the DisplayNames property. Setting the DisplayNames property is the preferred method. You must set either a Choice object's DisplayName property or its DisplayNames property; you cannot set both. If you set the DisplayName property, the server will automatically create a LocalizedString object with its LocaleName property set to the object store's default locale and add it as a single item in the DisplayNames property's LocalizedStringList collection. If you set the DisplayName property directly, localization will be bypassed and the language of its text may not match the specified locale. For example, if you store English text (en-us) in the DisplayName property and the default locale is French (fr-fr), the DisplayNames property will return a collection containing a single LocalizedString object that specifies a French locale with English text. Note that this behavior is unique to Choice objects.

A Choice object's display name, which is always a string value, should not be confused with its value, which can be a string, an integer, or a collection of Choice objects (when a Choice object acts as a group node). A Choice object's display name is assigned with the DisplayName property, while its value is assigned using the appropriate property, depending on its type: ChoiceIntegerValue for integer-type choice items, ChoiceStringValue for string-type choice items, or ChoiceValues for group nodes. Although the server does not check the display names and values of the choice items within a given choice list for uniqueness, it is recommended that they be unique to avoid ambiguity.

To create a Choice object, call the Factory.Choice.CreateInstance method. In order to save the state of a new Choice object (when you save the com.filenet.api.collection.ChoiceList object to which it belongs), you must, at a minimum, set its ChoiceType and DisplayNames properties. The DisplayNames property can be either set directly, by setting it to a LocalizedStringList object; or set indirectly, by setting the DisplayName property. To create a list collection of Choice objects (com.filenet.api.collection.ChoiceList object), call the Factory.Choice.CreateList method.


The following tables list the members exposed by IChoice.

Public Properties

 NameDescription
Public propertyChoiceIntegerValueThe value of a Choice object that holds an integer data type in a choice list.
Public propertyChoiceStringValueThe value of a Choice object that holds a string data type in a choice list.
Public propertyChoiceTypeSpecifies a ChoiceType constant that determines the type of data that a Choice object represents: an integer-type choice item, a string-type choice item, a group node for a nested collection of integer-type Choice objects, or a group node for a nested collection of string-type Choice objects.
Public propertyChoiceValuesA ChoiceList object representing a set of allowable values. If it is associated with a property, ChoiceValues provides a discrete set of possible values that the property can hold. Otherwise, if a ChoiceValues is associated with a Choice object, it defines the set of possible values in a choice list group.
Public propertyDisplayNameThe user-readable, provider-specific name of an object. This property is usually the designated Name property of the object's class.
Public propertyDisplayNamesSpecifies a LocalizedStringList object containing a collection of LocalizedString objects, each of which represents a locale-specific, user-readable display name for a class definition, property template, or choice.
Public propertyIdA representation of the Globally Unique Identifier (GUID), a unique 128-bit number, that is assigned to this Content Engine object when the object is created. When converted to a string, the Id property is typically depicted as 32 hexadecimal characters enclosed by brackets in the following format: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}. For example, {3F2504E0-4F89-11D3-9A0C-0305E82C3301}.

For IUser and IGroup classes, the Id property takes the value of the Security Identifier (SID) rather than the 128-bit GUID. The string representation of the SID is in this example format: S-1-5-21-1559522492-2815155736-3711640725-55269. When Active Directory is used as the directory service for IBM FileNet P8, IUser.Id and IGroup.Id always return the current SID for the principal, even if this user or group has only historical SIDs populating the Active Directory server.

For a given property representation, the Id property has the following characteristics:

  • PropertyDescription.Id is equal to PropertyTemplate.Id, which is equal to PropertyDefinition.PrimaryId.
  • PropertyDefinition.Id is not equal to PropertyDefinition.PrimaryId.
  • PropertyDefinition.Id is not equal to PropertyDescription.Id.

For a newly created document object, you can override the Id property of its associated VersionSeries object before you save or check in the document for the first time.

Public propertyNameThe name for this object.

For most classes, this property is read-only and returns the value of the designated name property for the object, or its ID if there is no name property. If ClassDescription.NamePropertyIndex has a value, this property contains the value of the designated name property. If there is no designated name property value, and the object has an Id property, this property contains the string value of the Id property. If neither of these conditions is satisfied, this property contains an empty string.

For a ComponentRelationship object, this property is read/write and specifies the name of the object.

Top

See Also