This section provides information about, and code examples for, creating and working with folders and referential containment relationship objects.
To create a folder, do one of the following:
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);
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.
// 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);
You can retrieve a persisted Folder
object in the following ways:
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
. 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;
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;
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:
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;
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;
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:
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;
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;
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:
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;
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.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;
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.
When you specify the containment name, you can use the autoUniqueName
parameter to indicate whether the containment name is to be automatically modified (appended with an integer in parentheses) if it is not a unique containment name for objects in the folder. 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 Concepts.
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.
Java Example
String folderPath = "/ExistingLoans/MyLoans"; String newFolderPath = "/NewLoans/MyNewLoans"; 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 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. DynamicReferentialContainmentRelationship drcr = (DynamicReferentialContainmentRelationship) newFolder.file( myDoc, AutoUniqueName.AUTO_UNIQUE, "Loan1", DefineSecurityParentage.DEFINE_SECURITY_PARENTAGE); drcr.save(RefreshMode.NO_REFRESH);
C# Example
String folderPath = "/ExistingLoans/MyLoans"; String newFolderPath = "/NewLoans/MyNewLoans"; 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. IDynamicReferentialContainmentRelationship drcr = (IDynamicReferentialContainmentRelationship) newFolder.File( myDoc, AutoUniqueName.AUTO_UNIQUE, "Loan1", DefineSecurityParentage.DEFINE_SECURITY_PARENTAGE); drcr.Save(RefreshMode.NO_REFRESH);
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);
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);
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 a DynamicReferentialContainmentRelationship Object.
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.