dm_notes: Documentum Notes

October 15, 2007

Virtual Documents in detail

Filed under: dfc, vdm, virtual document — Tags: , , — Raj V @ 9:49 am

Ran through a good explanation on Virtual documents in EMC| Documentum Forums Link.

Excerpt from the forum (copied as is)
——————————

Inherently Virtual documents are complex. Assemblies add a little to that but here goes as simple as possible:

From the server object perspective, the dmr_containment object is the key to understanding Virtual Documents
dm_sysobjects
+ r_is_virtual_doc- A dm_sysobject in the Docbase becomes a Virtual Document if r_is_virtual_doc is set to 1.
+ r_link_cnt- Defines the number of components of the Virtual Document.
+ resolution_label- Defines the the version label for late-bound nodes of the Virtual Document. We will discuss this shortly.

dmr_containment objects
+ A dmr_containment object defines the link between the parent and child nodes.
+ parent_id- The Object ID of the parent node.
+ component_id- This is the chronicle_id, or original version id, of the child node.
+ version_label- Version label for the child component. This overrides parent’s resolution_label.
+ use_node_vers_label- If set to TRUE for early-bound components, the server uses the early-bound symbolic label to resolve late-bound descendants of the component during assembly.
+ follow_assembly- If set to TRUE, directs the system to resolve a component using the component’s Assembly (if the component has an Assembly).
Note that only the root node and the dmr_containment objects have attributes related to Virtual Documents. Because of this, the dm_sysobject can be the child of “thousands” of Virtual Documents without the need for setting “thousands” of attribute values for the object. The connection between the parent and child is maintained in the dmr_containment object.

When a parent node is versioned, new containment objects are created between the existing child node documents and the new parent version.
When a child node is versioned, no containment object is created. This is because the containment object links the version of the parent to “any” version of the child node. (Usually, the “CURRENT” version is requested but other options are available as will be described in the coming Binding section). This is accomplished by the containment object referring to the “chronicle_id” of the child node. The chronicle_id is the r_object_id of the first, original version of that SysObject.
The parent “edge” object contains the link information that relates the parent to “any” version of the child.

To DFC programmers, an “edge” is referenced using an IDfContainment or IDfAssembly reference.

Assembly
+ An Assembly is a “snapshot” of a version of a Virtual Document at the time it was assembled
+ Assembly Objects= dm_assembly on the server
+ An Assembly is a record or “snapshot” of a version of a Virtual Document as it existed at the moment of assembling versions of its parts. Each Assembly object (dm_assembly) contains static binding information between a specific version of a parent node and a specific version of a child node of a Virtual Document. Assemblies will be discussed in greater detail at the end of this module

There are two wrapper interfaces in the fc.client package that publicly expose the operations required to access the services of the vdm package. These two Virtual Document wrapper interfaces are:
+ IDfVirtualDocument – provides a tree representation of a Virtual Document. A Virtual Document tree is comprised of a collection of nodes. Each node object corresponds to a sub-component of a Virtual Document. The IDfVirtualDocument object tracks node changes and manages tree node dynamics as changes are made to the Virtual Document graph. (A Virtual Document is modeled as an “acyclic directed graph”. An object cannot directly or indirectly have itself as a child).
+ IDfVirtualDocumentNode – Represents a single node in a Virtual Document graph.

IDfAssembly – This class provides the functionality for the client to interact with dm_assembly objects in the Docbase.
IDfContainment – Represents a dmr_containment object.
IDfSysObject – This class provides the functionality for the client to interact with dm_sysobject objects in the Docbase. Use the asVirtualDocument() method to turn a dm_sysobject into a Virtual Document.

Fetching a Virtual Document using asVirtualDocument( “preferredVersion”,t/f), causes the system to populate a node tree corresponding to the binding criteria encountered when fetching the descendants of the Virtual Document. This procedure is called, “assembling” a Virtual Document. Until now we have avoided using that term to prevent confusion with this topic. “Assembling” is the act of populating a node tree according to the 6 binding factors mentioned earlier. The purpose is to obtain a “version” of the Virtual Document. The node tree is a “versioned” node tree.
Assemblies allow you to “record” the collection of ObjectIDs from a versioned node tree. You would want to do this if:
A) You would like a “shortcut” to a version you reproduce often.
B) You need to lock certain child object versions from being deleted in order to guarantee the ability to reproduce the same version of the child nodes in the future.
Note: Although the current version of DFC does not support creating assemblies of XML documents, you may find them useful to create a Virtual Document from various Docbase objects.
Tip: An alternative approach to creating assemblies is to use version labels (like, “Assembly 1”) and binding to retrieve specific past versions of the graph. This hint may be useful until DFC supports assemblies of XML documents.

Assembly Objects
An Assembly, therefore, is a recording (or “snapshot”) of a version of a Virtual Document. It is comprised of a collection of Assembly object elements. Each Assembly object in the Assembly collection references one version of one component (sysObject) of the Virtual Document. For each node in the Assembly collection, an “Assembly object” exists in the Docbase server. An Assembly object is actually an instance of “dm_assembly” and contains the absolute ObjectID of the version of the sysObject referenced by that node in the versioned Virtual Document.
Each “dm_assembly” object has fields that are used when fetching the Assembly collection in the future. All Assembly objects of the same Assembly have the same value for their “book_id” field. The book_id is the objectID of a unique sysObject chosen to act as a “handle” for that snapshot.
You can associate the collection Assembly objects with a single sysObject by calling:

Assembly Document
The Assembly collection is conceptually accessed from the Docbase server as a single unit using a unique sysObject we term an “Assembly Document”. An Assembly Document is a unique sysObject (specific version of a document) that refers to that “snapshot” (collection of Assembly objects). It is the sysObject passed to the node.assemble() method.
An Assembly Document can only reference one collection of Assembly objects at a time. Therefore, make sure that the sysObject passed to the assemble() method is not already associated with an Assembly or you will lose the previous Assembly.
The Assembly Document (or “book“) can be either the sysObject referenced by the Assembly’s root node or some other sysObject. However, since an Assembly Document can only reference a single Assembly, a separate Assembly Document would be necessary when multiple assemblies from the same Virtual Document are required in order to avoid overwrite.

Re-Assembling
When the Assembly is requested in the future, the system looks for the dm_assembly objects that share the same “book_id” value and fetches the sysObjects referenced by the “component_id” of that dm_assembly object.

IDfSysObject doc =   sess.getObject (  new   DfID ( "09001234567890ab" ) );
IDfSysObject aDoc1=  sess.getObject (  new   DfID ( "0900ba0987654321" ) );
IDfSysObject aDoc2=  sess.getObject (  new   DfID ( "0900ba0987654322" ) );

In this example, three documents are fetched from the Docbase. “doc” is a Virtual Document. aDoc1 and aDoc2 are generic document objects.
The “doc” object refers to a Virtual Document but does not actually populate the node tree until asked to do so.

IDfVirtualDocument vDoc =  doc.asVirtualDocument (  "Released" ,  false  );
IDfVirtualDocumentNode node =  vDoc.getRootNode ();
 node.assemble ( aDoc1 );

Here, the node tree is finally populated using the binding criteria starting with “Released” as the preferred version. As you can see from the table on the left, the different nodes did not all retrieve the “Released” version of each child. This is because of the binding criteria as well as settings in the nodes (such as early binding) may override the preferred version. Once all the child nodes are assembled, that collection of objects is recorded by calling node.assemble( aDoc1 ). This sets a value in the aDoc1 object as a reference to the collection of the bound version of the object at each node.
aDoc1 is the Assembly Document for the “Released” version of Virtual Document “A”.

IDfVirtualDocument vDoc =  doc.asVirtualDocument (  "CURRENT" ,  false  );
IDfVirtualDocumentNode node =  vDoc.getRootNode ();
 node.assemble ( aDoc2 );

Here, another version of the node tree is populated (assembled) using the binding criteria starting with “CURRENT” as the preferred version. As you can see from the table on the right, the different nodes did not all retrieve the “CURRENT” version of each child. This is because of the binding criteria as well as settings in the nodes (such as early binding) may override the preferred version. Once all the child nodes are assembled, that collection of objects is recorded by calling node.assemble( aDoc2 ). This sets a value in the aDoc2 object as a reference to the collection of the bound version of the object at each node.
aDoc2 is the Assembly Document for the “CURRENT” version of Virtual Document “A”.

Sometimes a Virtual Document nests an Assembly within its hierarchy. When fetching a Virtual Document that potentially has sub-assemblies within it, it is often necessary to obtain the sub-assemblies.
When you include an Assembly Document as a node in a Virtual Document, you must decide if the Assembly components should replace that node, and any of its containment components, with the whole Assembly, or to ignore Assembly altogether.
+ The default is that the Assembly components should be ignored and instead the server uses the binding criteria to fetch the components referenced in the dmr_containment objects;
+ The node can optionally override the binding criteria so the server fetches the Assembly components based on the dm_assembly collection instead of the node or any of its virtual children.
To direct the server to use the node’s Assembly components, call node.setFollowAssembly(true).
If the node is not a Virtual Document, or it does not have children, or it does not have an Assembly, this setting on the node is ignored.

Freeze
+ Cannot add or delete components from the Assembly
+ That version of the component will be frozen
– Can’t change contents or attributes
– Assembly Document will be frozen
– Can’t change contents or attributes

Unfreeze
+ May add or delete from the Assembly again
+ That version of the component is unfrozen
– r_frzn_assembly_cnt = 0
– Can change contents and attributes
+ Only works if it is not nested within another frozen Assembly

Disassemble()
To remove the Assembly status from a sysObject and to remove all its Assembly objects, either call sysObject.disassemble() or node.disassemble(). You must have at least VERSION permission for the sysObject in order to delete its Assembly.
Deleting an Assembly will remove all the Assembly objects but does not remove the sysObject components of the Assembly objects.

Note: The ownership of the article lies with the Original Author and is here only as a reference.
The copyright laws applicable to this note are as defined by EMC Forums.

Advertisements

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: