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. Although it is possible to create a referentially contained folder, in practice, the use case is rare, and applications generally assume that 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.
Folder objects have the following characteristics:
Each object store has an automatically created root folder that represents the default root container that is 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 that are 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 information about the Folder object's system properties, see Folder Properties. For information about how to create a Folder instance, see Creating Folder Objects.
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 through 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.
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 that are permitted in a containment name.
A containment name must always be unique within the 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 property value is null, the containment name is set to the object's Id property value (a GUID). If setting the containment name to the object's Id property value results in a duplicate containment name within the folder, the Content Engine server automatically modifies it to achieve uniqueness.
For user-supplied names, the Folder.file method includes an autounique naming feature that forces the Content Engine to supply a unique containment name if naming collisions occur. However, enabling this feature can have a severe performance impact when used for large numbers of objects that are filed in the same folder by using a duplicate containment name. Under certain conditions, the Content Engine might attempt the filing operation many times before the filing operation succeeds. In those cases, timeouts can occur. Therefore, in your client application, ensure that unique containment names are created for each object, so that the auto-unique naming is only needed infrequently. (See Filing an Object into a Folder).
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 that is filed in the myTopFolder folder whose containment name is myDocument. Note that a containment path uses forward slashes.