Working with Containment

The following information and code examples demonstrate operations for creating and working with folders and referential containment relationship objects.

Creating Folder Objects

To create a folder, do one of the following tasks:

  • 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:

  • Call 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 that uses getInstance. See the following get_ParentFolder example for an example that uses fetchInstance.
  • Call 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;
  • Retrieve 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;
  • Call 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:

  • Call the get_SubFolders method on a Folder object, which returns the subfolders that are 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;
  • Retrieve the Versionable.FoldersFiledIn property for a specific document to get the folders that contain 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;
  • Retrieve 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 by using the Folder.get_Containees method.
    Note: The objects that are 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 (by using fetchInstance) or instantiate (by using getInstance) documents or custom objects by using the following methods:

  • Use the Folder.get_ContainedDocuments method to retrieve all documents that are 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 that a folder is directly contained.

If you are filing a Document (or a subclass of Document), the contained document is 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, 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 Security Inheritance.

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 performance degradation.

The following code snippet 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. Therefore, if the target folder contains an object with the same containment name as the incoming document, 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 that 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 by 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. For more information, see Creating DynamicReferentialContainmentRelationship Objects.

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