IBM FileNet P8, Version 5.2

Working with Containment

This section provides information about, and code examples for, creating and working with folders and referential containment relationship objects.

Creating Folder Objects

To create a folder, do one of the following:

Use one of the createInstance methods in the Factory.Folder class.

Java™ Example

// Creates a top folder. You must explicitly set the Parent and FolderName properties  
// when you use Folder.createInstance.
Folder myFolder = Factory.Folder.createInstance(os, null);
// Specify the parent folder. Here a top folder is created.
myFolder.set_Parent(os.get_RootFolder());
myFolder.set_FolderName("Loans");
myFolder.save(RefreshMode.NO_REFRESH);

C# Example

// Creates a top folder. You must explicitly set the Parent and FolderName properties  
// when you use Folder.CreateInstance.
IFolder myFolder = Factory.Folder.CreateInstance(os, null);
// Specify the parent folder. Here a top folder is created.
myFolder.Parent = os.RootFolder;
myFolder.FolderName = "Loans";
myFolder.Save(RefreshMode.NO_REFRESH);

Use the Folder.createSubFolder method on the parent folder to create a directly contained child folder.

NOTE The Parent property is automatically set when you use Folder.createSubFolder.

The property values for the newly created folder are the default values for the Folder class. You can optionally specify different permissions for the new object. For a code sample, see Setting Permissions.

Java Example

// Retrieves the parent folder and adds a subfolder to it.
String parentFolderPath = "/Loans";

Folder parentFolder = Factory.Folder.getInstance(os, null, parentFolderPath);
Folder newFolder = parentFolder.createSubFolder("MyLoans");
newFolder.save(RefreshMode.NO_REFRESH);

C# Example

// Retrieves the parent folder and adds a subfolder to it.
String parentFolderPath = "/Loans";
IFolder parentFolder = Factory.Folder.GetInstance(os, null, parentFolderPath);
IFolder newFolder = parentFolder.CreateSubFolder("MyLoans");
newFolder.Save(RefreshMode.NO_REFRESH);

Retrieving Folder Objects

You can retrieve a persisted Folder object in the following ways:

By calling fetchInstance on the Factory.Folder class to retrieve a specific folder from the object store. You can also call Factory.Folder.getInstance to instantiate, rather than retrieve, the Folder object, if your purposes do not include accessing properties on the object. See the createSubFolder example for an example using getInstance. See the following get_ParentFolder example for an example using fetchInstance.

By calling get_ParentFolder on a Folder object to retrieve the folder's parent folder.

Java Example

String childFolderPath = "/Loans/MyLoans";
Folder currentFolder = Factory.Folder.fetchInstance(os, childFolderPath, null);
Folder parent = currentFolder.get_Parent();

C# Example

String childFolderPath = "/Loans/MyLoans";
IFolder currentFolder = Factory.Folder.FetchInstance(os, childFolderPath, null);
IFolder parent = currentFolder.Parent;

By retrieving the ReferentialContainmentRelationship.Tail or DynamicReferentialContainmentRelationship.Tail property to get a folder that is the logical tail of a containment relationship.

Java Example

ReferentialContainmentRelationship rcr = Factory.ReferentialContainmentRelationship.createInstance(os, null);
ReferentialContainmentRelationship currentRCR = Factory.ReferentialContainmentRelationship.fetchInstance(os, (rcr.get_Id()), null);
IndependentObject currentTail = currentRCR.get_Tail();

C# Example

IReferentialContainmentRelationship rcr = Factory.ReferentialContainmentRelationship.CreateInstance(os, null);
IReferentialContainmentRelationship currentRCR = Factory.ReferentialContainmentRelationship.FetchInstance(os, rcr.Id, null);
IIndependentObject currentTail = currentRCR.Tail;

By calling get_RootFolder on an ObjectStore object (or by retrieving the object store's RootFolder property) to retrieve the single, automatically created root folder for the object store. See Creating Folder Objects for an example.

You can retrieve a folder collection (directly contained folders) in the following ways:

By calling the get_SubFolders method on a Folder object. This returns the subfolders filed in a folder.

Java Example

String folderPath = "/Loans";
Folder currentFolder = Factory.Folder.fetchInstance(os, folderPath, null);
FolderSet childFolders = currentFolder.get_SubFolders();

C# Example

String folderPath = "/Loans";
IFolder currentFolder = Factory.Folder.FetchInstance(os, folderPath, null);
IFolderSet childFolders = currentFolder.SubFolders;

By retrieving the Versionable.FoldersFiledIn property for a specific document to get the folders containing the document.

Java Example

String docPath = "/Loans/MyLoans/myDoc";
Document currentDoc = Factory.Document.getInstance(os, null, docPath);
currentDoc.refresh();
FolderSet parentFolders = currentDoc.get_FoldersFiledIn();

C# Example

String docPath = "/Loans/myLoans/myDoc";
IDocument currentDoc = Factory.Document.GetInstance(os, null, docPath);
currentDoc.Refresh();
IFolderSet parentFolders = currentDoc.FoldersFiledIn;

By retrieving the ObjectStore.TopFolders property to get the folders that are the immediate subfolders of the single, automatically created root folder for the object store.

Java Example

ObjectStore os = Factory.ObjectStore.fetchInstance(myDomain, myOS, myOSFilter);
FolderSet topFolders = os.get_TopFolders();

C# Example

IObjectStore os = Factory.ObjectStore.FetchInstance(myDomain, myOS, myOSFilter);
IFolderSet topFolders = os.TopFolders;

You can get the folders that are containers or containees in a relationship. These methods return a ReferentialContainmentRelationshipSet collection:

Get the containers using the Containable.get_Containers method.

Java Example

Folder currentFolder = Factory.Folder.getInstance(os, null, "Loans");
ReferentialContainmentRelationshipSet containingFolders = currentFolder.get_Containers();

C# Example

IFolder currentFolder = Factory.Folder.GetInstance(os, null, "/Loans");
IReferentialContainmentRelationshipSet containingFolders = currentFolder.Containers;

Get the containees using the Folder.get_Containees method.
Note: The objects referenced by the ReferentialContainmentRelationship objects in the collection can be folders, documents, custom objects, or DynamicReferentialContainmentRelationship objects (a subclass of ReferentialContainmentRelationship).

Java Example
```
Folder currentFolder = Factory.Folder.getInstance(os, null, "Loans");
ReferentialContainmentRelationshipSet containees = currentFolder.get_Containees(); 
```
C# Example
```
IFolder currentFolder = Factory.Folder.GetInstance(os, null, "/Loans");
IReferentialContainmentRelationshipSet containees = currentFolder.Containees; 
```

Retrieving Documents or Custom Objects from a Folder

Documents and custom objects are always referentially contained in a folder. You can retrieve (using fetchInstance) or instantiate (using getInstance) documents or custom objects using the following methods:

Use the Folder.get_ContainedDocuments method to retrieve all documents contained in the folder.

Java Example

String folderPath = "/NewLoans/MyNewLoans";
Folder myFolder = Factory.Folder.fetchInstance(os, folderPath, null);
DocumentSet myLoanDocs = myFolder.get_ContainedDocuments();

C# Example

String folderPath = "/NewLoans/MyNewLoans";
IFolder myFolder = Factory.Folder.FetchInstance(os, folderPath, null);
IDocumentSet myLoanDocs = myFolder.ContainedDocuments;

Use the Folder.get_Containees method to retrieve all referentially contained objects in the folder (documents, custom objects, and possibly, folders). See Retrieving Folder Objects for an example.

Retrieve the DynamicReferentialContainmentRelationship.Head or (possibly) ReferentialContainmentRelationship.Head property to get a document or custom object that is the logical head of a containment relationship.

Java Example

DynamicReferentialContainmentRelationship currentDRCR = Factory.DynamicReferentialContainmentRelationship.fetchInstance(os, (drcr.get_Id()), null);
IndependentObject currentHead = currentDRCR.get_Head();

C# Example

IDynamicReferentialContainmentRelationship drcr = Factory.DynamicReferentialContainmentRelationship.CreateInstance(os, null);
IDynamicReferentialContainmentRelationship currentDRCR = Factory.DynamicReferentialContainmentRelationship.FetchInstance(os, drcr.Id, null);
IIndependentObject currentHead = currentDRCR.Head;

Filing an Object into a Folder

To file a Containable object into a folder, call the Folder.file method on the object. When the object is filed, a relationship between the object and the containing folder is automatically created for reference: ReferentialContainmentRelationship for Folder and CustomObject instances; DynamicReferentialContainmentRelationship for Document instances. The relationship object is returned by the Folder.file method.

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.

If you are filing a Document (or a subclass of Document), the contained document will be the current document version. 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 cannot use the Folder.file method to file a specific document version into the folder.

The Folder.file method requires a containment name (which can be null) for the object you are filing, and a DefineSecurityParentage property setting. For more information on how the containment name is set in various scenarios, see the ReferentialContainmentRelationship.ContainmentName property. The defineSecurityParentage parameter determines whether the containing folder is to be the security parent for the filed object. For more information, see the Security Inheritance topic in Security.

The Folder.file method also includes the autoUniqueName parameter, which you can set to force the Content Engine to supply a unique containment name if naming collisions occur in the folder. As noted in Containment Names, setting this parameter to force the Content Engine to resolve duplicate names can result in severe performance degradation.

The following code fragment retrieves a document from a folder and files it into another folder. If this call succeeds, the document's containment name is returned. Note that in the Folder.file method, the autoUniqueName parameter is set to NOT_AUTO_UNIQUE. So if the target folder contains an object with the same containment name as the incoming document, then an exception is thrown with a message about duplicate containment names.

Java Example

String folderPath = "/ExistingLoans/MyLoans";
String newFolderPath = "/NewLoans/MyNewLoans";
String newContainmentName = "Loan1";

Document myDoc = Factory.Document.fetchInstance(os, folderPath + "/MyLoan_1", null);
Folder newFolder = Factory.Folder.fetchInstance(os, newFolderPath, null);

// Files the document into the folder with the autoUniqueName parameter disabled and the 
// defineSecurityParentage parameter set to inherit permissions from the folder. You need to 
// cast the returned ReferentialContainmentRelationship object as a DynamicReferentialContainmentRelationship 
// object to get the correct relationship object for the document filed. 
try {
   DynamicReferentialContainmentRelationship drcr = 
      (DynamicReferentialContainmentRelationship) newFolder.file(
         myDoc, AutoUniqueName.NOT_AUTO_UNIQUE, newContainmentName, DefineSecurityParentage.DEFINE_SECURITY_PARENTAGE);
   drcr.save(RefreshMode.NO_REFRESH);
}
catch (Exception ex) 
{   
   if (ex instanceof EngineRuntimeException) {
  EngineRuntimeException fnEx = (EngineRuntimeException) ex;
      if (fnEx.getExceptionCode().equals(ExceptionCode.E_NOT_UNIQUE) ) {
         System.out.println("Exception: " + ex.getMessage() + "\n" +
            "The name " + "\"" + newContainmentName + "\"" + " is already used.\n" + 
            "Please file the document with a unique name.");
      }
      else
         System.out.println("Exception: " + ex.getMessage());
   }
   else
      // A standard Java exception.
      System.out.println("Exception: " + ex.getMessage());
}

C# Example

String folderPath = "/ExistingLoans/MyLoans";
String newFolderPath = "/NewLoans/MyNewLoans";
String newContainmentName = "Loan1";
IDocument myDoc = Factory.Document.FetchInstance(os, folderPath + "/MyLoan_1", null);
IFolder newFolder = Factory.Folder.FetchInstance(os, newFolderPath, null);

// Files the document into the folder with the autoUniqueName parameter enabled and the 
// defineSecurityParentage parameter set to inherit permissions from the folder. You need to 
// cast the returned ReferentialContainmentRelationship object as a DynamicReferentialContainmentRelationship 
// object to get the correct relationship object for the document filed.
try {
   IDynamicReferentialContainmentRelationship drcr = 
     (IDynamicReferentialContainmentRelationship) newFolder.File(
        myDoc, AutoUniqueName.NOT_AUTO_UNIQUE, newContainmentName, DefineSecurityParentage.DEFINE_SECURITY_PARENTAGE);
   drcr.Save(RefreshMode.NO_REFRESH);
}
catch (Exception ex) 
{   
   if (ex is EngineRuntimeException) {
      EngineRuntimeException fnEx = (EngineRuntimeException) ex;
         if (fnEx.GetExceptionCode().Equals(ExceptionCode.E_NOT_UNIQUE) ) {
            System.Console.WriteLine("Exception: " + ex.Message + "\n" +
               "The name " + "\"" + NewContainmentName + "\"" + " is already used.\n" + 
               "Please file the document with a unique name.");
         }
         else
            System.Console.WriteLine("Exception: " + ex.Message);
    }
    else
       // A standard Java exception.
       System.Console.WriteLine("Exception: " + ex.Message);
}

Creating ReferentialContainmentRelationship Objects

You create a ReferentialContainmentRelationship object and persist it to a Content Engine object store by calling createInstance on the Factory.ReferentialContainmentRelationship class. The primary use case for creating a ReferentialContainmentRelationship object is to create a referential containment relationship between a folder and a specific version of a document or custom object.

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.

When you create a ReferentialContainmentRelationship object, you must set the object's Head and Tail properties. Set the Head property to the object you want to contain in the folder, and set the Tail property to the containing folder.

The following example creates a ReferentialContainmentRelationship object, and sets a document as the contained object:

Java Example

String parentFolderPath = "/Loans";

// Create a document as the containee for the folder, and check it in.
Document myDoc = Factory.Document.createInstance(os, null);
myDoc.checkin(null, null);
myDoc.save(RefreshMode.REFRESH);

// Retrieve the containment folder.
Folder container = Factory.Folder.getInstance(os, null, parentFolderPath); 

// Retrieve the current version of the document to contain in the folder. The
// relationship is only with this specific document version.
Document docVer = Factory.Document.getInstance(os, null,(myDoc.get_Id())); 

// Create the ReferentialContainmentRelationship instance.
ReferentialContainmentRelationship rcr =     
    Factory.ReferentialContainmentRelationship.createInstance(os, null); 

// Populate the ReferentialContainmentRelationship object with the required Head 
// (containee) and Tail (container) objects, and save it.
rcr.set_Head(docVer); 
rcr.set_Tail(container); 
rcr.save(RefreshMode.NO_REFRESH);

C# Example

String parentFolderPath = "/Loans";

// Create a document as the containee for the folder, and check it in.
IDocument myDoc = Factory.Document.CreateInstance(os, null);
myDoc.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
myDoc.Save(RefreshMode.REFRESH);

// Retrieve the containment folder.
IFolder container = Factory.Folder.GetInstance(os, null, parentFolderPath);

// Retrieve the current version of the document to contain in the folder. The
// relationship is only with this specific document version.
IDocument docVer = Factory.Document.GetInstance(os, null, myDoc.Id);

// Create the ReferentialContainmentRelationship instance.
IReferentialContainmentRelationship rcr = 
    Factory.ReferentialContainmentRelationship.CreateInstance(os, null);

// Populate the ReferentialContainmentRelationship object with the required Head 
// (containee) and Tail (container) objects, and save it.
rcr.Head = (docVer);
rcr.Tail= (container);
rcr.Save(RefreshMode.NO_REFRESH);

Creating DynamicReferentialContainmentRelationship Objects

You create a DynamicReferentialContainmentRelationship object and persist it to a Content Engine object store by calling createInstance on the Factory.DynamicReferentialContainmentRelationship class.

You must set the DynamicReferentialContainmentRelationship object's Head property to the current version of the document that you want to contain, and the Tail property to the containing folder.

Java Example

String parentFolderPath = "/Loans";

// Create a document as the containee for the folder.
Document doc = Factory.Document.createInstance(os, null);
doc.save(RefreshMode.NO_REFRESH); 

// Retrieve the containment folder.
Folder container = Factory.Folder.getInstance(os, null, parentFolderPath); 

// Create the DynamicReferentialContainmentRelationship instance.
DynamicReferentialContainmentRelationship drcr = 
    Factory.DynamicReferentialContainmentRelationship.createInstance(os, null); 

// Populate the DynamicReferentialContainmentRelationship object with the required Head  
// (current version of the document) and Tail (container) objects, and save it.
drcr.set_Head(doc); 
drcr.set_Tail(container); 
drcr.save(RefreshMode.NO_REFRESH);

C# Example

String parentFolderPath = "/Loans";

// Create a document as the containee for the folder.
IDocument doc = Factory.Document.CreateInstance(os, null);
doc.Save(RefreshMode.NO_REFRESH);

// Retrieve the containment folder.
IFolder container = Factory.Folder.GetInstance(os, null, parentFolderPath);

// Create the DynamicReferentialContainmentRelationship instance.
IDynamicReferentialContainmentRelationship drcr =  
        Factory.DynamicReferentialContainmentRelationship.CreateInstance(os, null);

// Populate the DynamicReferentialContainmentRelationship object with the required Head  
// (current version of the document) and Tail (container) objects, and save it.
drcr.Head=(doc);
drcr.Tail=(container);
drcr.Save(RefreshMode.NO_REFRESH);

Associating a Specific Document Version with a Folder

You cannot file a specific document version using the Folder.file method. If your application requires a specific version of a document to be associated with a folder, you must create a ReferentialContainmentRelationship object to create that relationship. (DynamicReferentialContainmentRelationship objects apply only to the current version of a document.) See Creating DynamicReferentialContainmentRelationship Objects.

The document can then be retrieved using the Folder.get_Containees method, or by retrieving the ReferentialContainmentRelationship.Tail property for the relationship. See Retrieving Folder Objects.