Defines a hierarchical relationship between two documents as components in a compound document.

One document is the designated parent component (ParentComponent property) and the other is the designated child component. The child component document can be either a P8 Content Engine document (ChildComponent property) or a URI document (URIValue property). A document can be referenced by more than one instance of this class and consequently can be designated as a component in more than one relationship; this capability allows documents to be networked together to form compound documents with numerous components.

The two documents in a component relationship might be bound to each other as a result of that relationship. Document binding means the child component document exists in the child documents collection (ChildDocuments property) for the parent component, and the parent component document exists in the parent documents collection (ParentDocuments property) for the child component. This binding can be conditional; for example, it can be conditional on the value for one of the properties on the child document matching an expected value. Also, the child component can be a URI document instead of a Document object. Consequently, not every component relationship results in a document binding. For more information on component relationship types and which properties you are required to set when you create a new ComponentRelationship object, see the ComponentRelationshipType property.

The two documents in a component relationship do not have to belong to the same object store. Also, these documents can continue to be used and referenced as individual documents, just as if they had never entered into a component relationship with each other.

The parent component document determines security for each instance of this class. Users with write permission (AccessRight.WRITE) to the parent component have the same rights to that component relationship instance. Permission to delete a component relationship instance requires AccessRight.DELETE or AccessRight.UNLINK rights on the parent component document.


The following tables list the members exposed by IComponentRelationship.

Public Properties

 NameDescription
Public propertyAuditedEventsAn EventSet collection of the Event objects containing the audited events that have occurred for the object.
Public propertyChildComponentThe Document object designated as the child in a component relationship.

This property applies when the ComponentRelationshipType property setting is STATIC_CR, DYNAMIC_CR, or DYNAMIC_LABEL_CR. For all other component relationship types the value of this property is null. For a URI component relationship type, you designate the child component by setting the URIValue property.

For a ComponentRelationship object whose relationship type is STATIC_CR, set the value of this property to the specific document version to bind to the parent component document.

For a ComponentRelationship object whose relationship type is DYNAMIC_CR, some version of the child document must be eligible-for-binding; otherwise, calling the Save method on the ComponentRelationship object throws an exception. For example, a major version of the document must exist when the version bind rule specifies only major versions can be bound. For information on the version bind rule, see the VersionBindType property. When you call the Save method, the ChildComponent property is automatically updated to reflect the actual document version bound.

For a ComponentRelationship object whose relationship type is DYNAMIC_LABEL_CR, no version of the child document need be eligible-for-binding. When you call the Save method, the value of the ChildComponent property is automatically updated to null or to the actual document version bound. This bound version is the most recent version of the child document satisfying the version bind rule that has a ComponentBindingLabel property value matching the LabelBindValue property value. For more information on document binding, see the ComponentRelationshipType property. Note that, when the ChildComponent property value has been updated to null, you can still determine the child document for this relationship by using the ChildVersionSeries property.

Public propertyChildVersionSeriesThe VersionSeries object that is the version series of the child component document. Retrieving this property's value is equivalent to calling get_ChildComponent().get_VersionSeries(). This property applies when the ComponentRelationshipType property setting is DYNAMIC_CR or DYNAMIC_LABEL_CR; otherwise, the property value is null.
Public propertyComponentCascadeDeleteThe setting for controlling the deletion of the child component document as an automatic response to the deletion of the parent component document. The ComponentCascadeDeleteAction enumeration has constants defined for the component cascade delete settings.

Valid settings are:

  • CASCADE_DELETE: Causes the child component document to be automatically deleted when the parent component document is deleted. Document deletion succeeds if you have delete rights (AccessRight.DELETE) for all child components involved in the cascade delete. Otherwise no component (including the parent component) can be deleted. For example, if two component relationship objects designate D1 as the parent document for D2, and D2 as the parent document for D3, and define a cascade delete relationship between D1 and D2 and also between D2 and D3, you can delete D1 only if you have delete rights for all three documents.
  • NO_CASCADE_DELETE (default setting): Causes no special action to occur when the parent component document is deleted.
Public propertyComponentPreventDeleteThe setting for the delete behavior for parent and child components. The prevention settings protect a document from deletion by causing an exception to be thrown on a deletion attempt. The ComponentPreventDeleteAction enumeration has constants defined for the component prevent delete settings.

Valid settings are:

  • ALLOW_BOTH_DELETE (default setting): Allows the deletion of both the parent and child component documents.
  • PREVENT_BOTH_DELETE: Prevents the deletion of both the parent and child component documents.
  • PREVENT_PARENT_DELETE: Prevents the deletion of the parent component document.
  • PREVENT_CHILD_DELETE: Prevents the deletion of the child component document if the parent component document exists. This setting also prevents the deletion of a parent component document if the ComponentCascadeDelete property for this ComponentRelationship object is set to CASCADE_DELETE (which deletes the child when the parent is deleted).
Public propertyComponentRelationshipTypeThe setting that determines the type of component relationship between a child document and parent document. The ComponentRelationshipType enumeration has constants defined for the relationship type settings.

Valid settings are:

  • STATIC_CR (default setting): Binds the parent component version to the explicitly specified child component version. Set these required properties to create a ComponentRelationship object with this setting: ParentComponent and ChildComponent.
  • DYNAMIC_CR: Binds the parent component version to the most recent child component version that satisfies the version bind rule. For information on the version bind rule, see the VersionBindType property. This setting expects an eligible-for-binding child component version to exist; for more information on this requirement, see the ChildComponent property. Set these required properties to create a ComponentRelationship object with this setting: ParentComponent, ChildComponent, and VersionBindType.
  • DYNAMIC_LABEL_CR: Binds the parent component version to the most recent child component version satisfying the version bind rule that has a ComponentBindingLabel property value matching the LabelBindValue property value. No binding occurs if no such child document version exists. The value comparison considers the two properties to be matching when they have the same value, or when LabelBindValue has a null value and ComponentBindingLabel has a non-null value. For information on the version bind rule, see the VersionBindType property. Set these required properties to create a ComponentRelationship object with this setting: ParentComponent, ChildComponent, VersionBindType, and LabelBindValue.
  • URICR: Creates a component relationship between the parent component document and the URI document specified by the URIValue property. The URI can be for a P8 Content Engine document, and any other "document" a URI can refer to. Set these required properties to create a ComponentRelationship object with this setting: ParentComponent and URIValue.

When you modify the ComponentRelationshipType property from one setting to another, be aware that the previously set values for some properties might be lost:

  • The URIValue property applies to the URICR setting; the property value is null for all other settings.
  • The ChildComponent property applies to the STATIC_CR, DYNAMIC_CR, and DYNAMIC_LABEL_CR settings; the property value is null for the URICR setting.
  • The VersionBindType property applies to the DYNAMIC_CR and DYNAMIC_LABEL_CR settings; the property value is null for all other settings.
  • The LabelBindType property applies to the DYNAMIC_LABEL_CR setting; the property value is null for all other settings.

For an overview of document binding, see the IComponentRelationship interface.

Public propertyComponentSortOrderThe ascending sort order number that determines the position of this ComponentRelationship object within the ChildRelationships collection as well as the position of the child component document within the ChildDocuments collection. These collections belong to the parent component document. Relative to any other object having the same sort order number, the binary value of the ComponentRelationship object's Id property determines the ascending sort order position for this object and the associated child component.

This property cannot be set to null.

For a new ComponentRelationship object with no explicitly set component sort order, calling the Save method on the object assigns a value to this property equal to the highest component sort order in the ChildRelationships collection plus 1000. For example, if you did not explicitly set the ComponentSortOrder property for any ComponentRelationship objects within the collection, the first object added to the ChildRelationships collection has a component sort order of 1000; the second, 2000; the third, 3000; and so on.

Public propertyCopyToReservationA value indicating whether some particular document feature gets passed on as a default feature for the next document version. The passed-on feature can be a property value or a component relationship. When the CopyToReservation property value is true, source document checkout causes the source feature to be replicated for the newly created document reservation object.

For a PropertyDefinition object, a value indicating whether the value of the property defined by this property definition should be copied, during checkout, from the source document to the newly created reservation object.

For a ComponentRelationship object, a value indicating whether this object gets copied, during checkout of the parent component source document, for the newly created reservation object. The reservation object becomes the parent component for the new copy of this ComponentRelationship object. Consequently, both the reservation object and the source document have an equivalent component relationship with the same child document. Note that the reservation object behaves like any other document with respect to compound document properties and relationships.

Public propertyCreatorIndicates the name of the user assigned as the creator of the object.

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is settable only on create. After initial object creation, this property is read-only for all users.

Public propertyDateCreatedIndicates the date and time the object was created. The Content Engine stores dates and times using Coordinated Universal Time (UTC).

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is settable only on create. After initial object creation, this property is read-only for all users.

Public propertyDateLastModifiedIndicates the date and time the object was last modified. The Content Engine stores dates and times using Coordinated Universal Time (UTC).

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is read/write. (The read/write access for those users can only change if a change is made to the ACL on the object store that controls who has privileged write access to objects in that object store).

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 propertyLabelBindValueThe value matched against the value of the ComponentBindingLabel property on a child component document version that determines whether that version gets bound in a component relationship of type DYNAMIC_LABEL_CR. For all other component relationship types the value of this property is null. For more information, see the ComponentRelationshipType property.
Public propertyLastModifierIndicates the name of the user who last modified the object.

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is read/write. (The read/write access for those users could only change if a change is made to the ACL on the object store that controls who has privileged write access to objects in that object store).

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.

Public propertyParentComponentThe Document object designated as the parent in a component relationship. The setting for the CompoundDocumentState property on this parent Document object must be COMPOUND_DOCUMENT. Also, you must have link rights (AccessRight.LINK) on the document.
Public propertyURIValueThe URI address for the document designated as the child in a component relationship. This property applies when the ComponentRelationshipType property setting is URICR. For other component relationship types, you designate the child component by setting the ChildComponent property. If the ComponentRelationshipType property is set to anything other than URICR, the value of the URIValue property is null. Any String value can be entered into this property; the value does not have to be a valid URI address.
Public propertyVersionBindTypeThe setting for selecting the version bind rule in effect; this rule partly determines the child component document version bound with the parent component for component relationship types of DYNAMIC_CR and DYNAMIC_LABEL_CR. For all other component relationship types the value of this property is null. (For information on document binding specifics, see the ComponentRelationshipType property.) The VersionBindType enumeration has constants defined for the bind type settings.

Valid settings are:

  • LATEST_VERSION: All document versions, major and minor, are considered candidates for binding.
  • LATEST_MAJOR_VERSION: Only the major document versions are considered candidates for binding.
Top

See Also