Containment Concepts

A folder represents a container that can hold other objects. These objects can be custom objects, documents, and folders (and their subclasses).

Child folders are typically directly-contained. That is, their containment models a 1:N, or one-to-many, relationship. A containing (parent) folder can contain multiple child folders, but each child folder is directly contained within at most one parent folder. Note that an excessive number of subfolders for a single folder can affect retrieval performance. For more information, refer to the IBM FileNet P8 Platform Recommendations for Handling Large Numbers of Folders and Objects. To download this guide from the IBM support page, see Accessing IBM FileNet documentation.

Note: Although it is possible to create a referentially-contained folder, in practice, the use case is rare, and applications generally assume a folder is directly-contained.

Custom objects and documents are always referentially-contained. For referentially-contained objects, their containment models an N:M, or many-to-many, relationship. A referentially-contained object can be contained within multiple folders, and can also be contained multiple times in the same folder.

Folders

Folder objects have the following characteristics:

Each object store has an automatically-created root folder that represents the default root container associated with the object store. You cannot create or delete a root folder, but you can access it by calling the getRootFolder method on an ObjectStore object or by retrieving its RootFolder property.

Folders directly contained under the root folder are referred to as top folders. These folders typically represent the starting points for folder navigation, because for many applications you might not want to display or allow users to add objects to the root folder. You can navigate to an object store's top folders by either:

For descriptions of the Folder object's system properties, see Folder Properties. For information on how to create a Folder instance, see Creating Folder Objects. For additional conceptual information on folders, see Folders and About folders in the Content Engine Administration Help.

Referential Containment Relationships

There are two types of referential containment relationships: dynamic and static.

Static Relationships

A static referential containment relationship is a relationship between a folder and a CustomObject object, a specific document version in a version series, or (rarely) a folder. This type of relationship is represented by a ReferentialContainmentRelationship object.

For a CustomObject object, you implicitly create this type of relationship when you call the Folder.file method to file the object into a folder. You can explicitly create this type of relationship for a CustomObject object, or a document, by creating a ReferentialContainmentRelationship object and setting its Head property to the object you want contained in the folder, and its Tail property to the containing folder.

The ReferentialContainmentRelationship object provides the following additional containment capabilities that are not available via other interfaces (such as the Folder and the Containable interfaces).

Dynamic Relationships

A dynamic referential containment relationship is a relationship between a folder and the current version of a document. In this case, the current document version is (in order of use): the released version (if there is one), else the current version (if there is one), otherwise, the reservation version. You implicitly create this type of relationship when you call the Folder.file method to file a document into a folder. You can also explicitly create this type of relationship by creating a DynamicReferentialContainmentRelationship object.

Containment Names

A containment name is the name of the object as it appears in a folder in a user interface. It can differ from the object's name. Containment names are also subject to additional rules that do not restrict document titles. Refer to the ReferentialContainmentRelationship.ContainmentName property for a description of the characters permitted in a containment name.

A containment name must always be unique within the folder. By setting the autoUniqueName parameter when you use the Folder.file method, you can have Content Engine automatically supply a unique containment name if naming collisions occur. (See Filing an Object into a Folder).

If you file an object into a folder and do not specify its containment name, the containment name is set to the object's Name property. If the Name value is null, the containment name is set to the object's Id property (a GUID). If setting the containment name to the object's ID property results in a duplicate containment name within the folder, the Content Engine server will automatically modify it to achieve uniqueness.

Containment Paths

A containment path is the full path, including the object's containment name, to where an object is filed in the object store. The root folder's path is "/". For example, "/myTopFolder/myDocument" is the containment path for a document filed in the "myTopFolder" folder whose containment name is "myDocument". (Note that a containment path uses forward slashes.)