Working With

Documentum Foundation Class (DFC)

&
Documentum Query Language (DQL)
What is DFC?

 Documentum Foundation Classes(DFC) is an object oriented

application programming interface for accessing Documentum
functionality

 Documentum has implemented DFC as a set of Java interfaces and

implementation classes

 DFC also provides the Documentum Java-COM bridge (DJCB) to

make the interfaces available in Microsoft’s Component Object
Model (COM) environment
Object Hierarchy

Hierarchy of DFC Objects

IDfPersistentObject

IDfSysObject

dm_folder dm_policy dm_user dm_document ………

Where is DFC?

DFC runs on a Java virtual machine (JVM), which can be on:

 The machine that runs Content Server

 A middle-tier system

 An end user’s computer

Working With Docbase
Sessions
Sessions

 A session is an object that implements the IDfSession interface. A

session gives a specific user access to a specific repository

 An IDfSession object represents a connection with the Documentum

server and provides services related to that session

 Sessions support transactions that are based on the transaction

mechanism of the repository’s underlying relational database
Session Managers

 A session manager is an object that implements the

IDfSessionManager interface

 A session manager, running within an application, manages

sessions with one or more repository

 Authenticates before giving the connection

 A session manager relies on the Content Server session pooling

capability
Client/Server Model

 DFC encapsulates its client functionality in the IDfClient interface,

which serves as the entry point for DFC code

 You obtain the initial IDfClient interface by calling the static

getLocalClient method of the DfClientX class

 The IDfClient interface then serves as a factory for IDfSession

objects

 An IDfSession object represents a connection with the Documentum

server and provides services related to that session

 DFC programmers create new Docbase objects or obtain

references to existing Docbase objects through the IDfSession
interface
Client/Server Model (Cont..)

IDfClient clientObj = DfClient.getLocalClient();

// Setup login credentials

IDfLoginInfo liObj = new DfLoginInfo();

// Set username
liObj.setUser(username);

// Set password
liObj.setPassword(password);
m_sessObj = clientObj.newSession(strDocbase, liObj);
Processing a Docbase Object

 Obtain a session manager by calling the newSessionManager

method of the IDfClient object

 Use the sessionmanager to obtain a session with the Docbase, that

is, a reference to an object that implements the IDfSession interface

 If you do not have a reference to the Docbase object, call an

IDfSession method (for example, newObject or
getObjectByQualification) to create an object or to obtain a
reference to an existing object

 Manipulate the object—check it out, check it in, and so forth

 Release the session

Processing a Docbase Object (Cont..)

IDfClient client = DfClientX.getLocalClient();

IDfSessionManager sMgr = client.newSessionManager();
IDfLoginInfo loginInfo = new DfLoginInfo();
loginInfo.setUser( "Mary" );
loginInfo.setPassword( "ganDalF" );
sMgr.setIdentity( strDocbaseName, loginInfo );
IDfSession session = sMgr.getSession( strDocbaseName );
IDfDocument document = (IDfDocument)session.newObject(
"dm_document" );
document.setObjectName( "Report on Wizards" );
document.setContentType( "crtext" );
document.setFile( "C:\Temp\Wiz.txt" );
document.save();
sMgr.release( session );
Packages

 DFC comprises a number of packages, that is, sets of related

classes and interfaces

 The names of DFC java classes begin with Df (for example,

DfCollectionX)

 Names of interfaces begin with IDf (for example,

IDfSessionManager)

 Interfaces expose DFC’s public methods and constants. Each

interface contains a set of related methods. The Javadocs describe
each package and its purpose
Using Docbase Queries with DFC

This section describes the way to use DFC to create and perform queries
and to process the results.

We will learn more about:

IDfQuery
IDfCollection
IDfQuery

 An IDfQuery object holds a DQL query string and allows you to

perform that query in any session

 You pass the session and the query to the execute method, and it
returns results as an IDfCollection object
IDfCollection

 An IDfCollection object is like an SQL cursor. It contains references

to the objects that the query returns, in an ordered sequence of
rows

 The collection points to one row of data at a time. You must call next
before accessing the first row

 Subinterface of IDfTypedObject - can access rows by using get

methods of IDfTypedObject
Flow of Query Processing

• Obtain an IDfClient interface by calling the getLocalClient method of

DfClient
• Create a session, sess, by calling newSession on the IDfClient
object
• Obtain an IDfQuery object, q:
• Create a DQL query as a text string, dq
• Call q.setDQL(dq) to set the DQL string into the query object
• Call q.execute(sess, querytype) to execute the query
• Iterate through the IDfCollection by calling col.next() until it returns
False
• Close the IDfCollection and IDfSession objects
execQuery in Java

IDfCollection execQuery(IDfSession sess, String queryString)

{
IDfCollection col = null; //For the result
try {
IDfQuery q = new DfQuery(); //Create query object
q.setDQL(queryString); //Give it the query
col = q.execute(sess, DfQuery.DF_READ_QUERY);
} catch (DfException dfe) {
System.out.println("\n" + dfe.toString());
}
return col;
}
Permission Set - Basic

 None - No access is permitted

 Browse - Can view property values, but not associated content

 Read - Can read content but cannot update the object or its content

 Relate - Can attach annotations to the object

 Version - Can create a new version of the object; can update

properties; cannot check in as the same version after editing

 Write - Can write to and update the object

 Delete - Can delete the object

Permission Set - Extended

 Change State - The user can change the document lifecycle state of
the object

 Change Permission - The user can change the basic permissions of

the object

 Change Ownership - The user can change the owner of the object

 Execute Procedure - The user can run the external procedure

associated with the object

 Change Location - The user can change move an object from one
folder to another
Using Private ACLs

void privateACLs(IDfSession sess,String objId, String permission,String

extPermission,

String aclName) throws IOException {

try {
IDfId sysObjId = new DfId(objId);
IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);
IDfPersistentObject pObj = (IDfPersistentObject)sess.newObject("dm_acl");
pObj.apiSet("set", "object_name", aclName);
pObj.apiExec("grant", "dm_owner," + permission + "," + extPermission);
pObj.apiExec("grant", "dm_world," + permission + "," + extPermission);
pObj.save();
IDfACL newACL = sess.getACL(sess.getLoginUserName(), aclName);
sysObj.setACL(newACL);
Create User

IDfUser objUser = (IDfUser) objIDfSession.newObject("dm_user");

objUser.setUserName(userName);

//followed by other setter methods

Create Cabinet

IDfSysObject sysObj = (IDfSysObject)sess.newObject("dm_cabinet");

sysObj.setObjectName(DfExUtils.getInput("\nEnter a new cabinet

name: "));

sysObj.setSubject("DFC Example Cabinet");

sysObj.save();
Create Folder

IDfSysObject sysObj = (IDfSysObject)sess.newObject("dm_folder");

sysObj.setObjectName(DfExUtils.getInput("\nEnter a new folder name: "));
sysObj.setSubject("DFC Example folder");

// Have the user specify the parent cabinet/folder

sysObj.link(DfExUtils.getInput("Enter a parent path (e.g. /Temp): "));

sysObj.save();
Create Document

IDfSysObject sysObj = (IDfSysObject)sess.newObject("dm_document");

sysObj.setObjectName(DfExUtils.getInput("\nEnter a new document
name: "));
sysObj.setSubject("DFC Example Doc");
sysObj.setContentType("crtext");
sysObj.setTitle("DFC Example Doc");
// Have the user specify a file on disk

sysObj.setFile(DfExUtils.getInput("Enter a text file on disk (e.g.

c:\\test.txt): "));
// Have the user specify the parent cabinet/folder

sysObj.link(DfExUtils.getInput("Enter a Docbase location for the document

(e.g. /Temp): "));
sysObj.save();
Create Type

 System Types

 Custom Types
Create Type (Cont..)

CREATE TYPE custtype (attr1 STRING(50), attr2 STRING(40), attr3

STRING(60), attr4 STRING(10)) WITH SUPERTYPE dm_document
Create Business Policy

// Create the dm_policy object with the following states: preliminary, reviewed
IDfSysObject bpObj = (IDfSysObject)sess.newObject("dm_policy");
bpObj.setObjectName(“PolicyName”);
// Include the type that can use this business policy
bpObj.setRepeatingString("included_type", 0, "dm_sysobject");
// Add the "preliminary" state
sess.apiGet("appendstate", bpObj.getObjectId().toString());
bpObj.setRepeatingString("state_name", 0, "preliminary");
// Add the "reviewed" state
sess.apiGet("appendstate", bpObj.getObjectId().toString());
bpObj.setRepeatingString("state_name", 1, "reviewed");
bpObj.link("/Temp");
bpObj.save();
Attach Business Policy

// Instantiate an IDfId object

IDfId sysObjId = new DfId(objId);

// Instantiate an IDfSysObject object from the IDfId

IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);

System.out.println("\nAttaching the business policy object to the
sysobject...");

// Attach the business policy to the sysobject

sysObj.attachPolicy(bpObj.getObjectId(), "preliminary", "");

// Promote the object to the next state

sysObj.promote("reviewed", false, false);

Create Virtual Documents

// Instantiate an IDfSysObject object root

IDfSysObject sysObjRoot = (IDfSysObject)sess.getObject(new DfId(objId));
// Instantiate an IDfVirtualDocument from the root object
IDfVirtualDocument vDoc = sysObjRoot.asVirtualDocument("CURRENT",
false);
// Instantiate an IDfVirtualDocument as the root node of the VDM
IDfVirtualDocumentNode rootNode = vDoc.getRootNode();
// Instantiate an IDfVirtualDocument which will be the tail node of VDM tree
IDfVirtualDocumentNode insertAfterNode = null;
// Checkout the root sysobject
sysObjRoot.checkout();
System.out.println("\nNow add child objects to the VDM...");
(Cont….)
Create Virtual Documents (Cont..)

IDfSysObject sysObjChild = (IDfSysObject)sess.getObject(new

DfId(childObjId));

// Obtain the chronicle id of child (the root version of the object)

IDfId chronIdChild = sysObjChild.getChronicleId();
IDfVirtualDocumentNode childNode = vDoc.addNode(rootNode, null
,chronIdChild, "CURRENT", false, true);

// Ask the user for a target location for the new VDM
sysObjRoot.link(DfExUtils.getInput("\nEnter a Docbase location for the VDM
(e.g. /Temp): "));

// Save the VDM - this will also handle the checkin

sysObjRoot.save();
Introduction To Operations

 Operations provide interfaces and a processing environment to ensure

that Documentum can handle a variety of documents and collections of
documents in a standard way

 You obtain an operation of the appropriate kind, place one or more

documents into it, and “run it through the machine,” that is, execute the
operation
Example

To check out a document, take the following steps:

3.Obtain a checkout operation

4.Add the document to the operation
5.Execute the operation
An IDfClientX object provides methods for creating operations. For this
reason we call it a factory for operations.
// Obtain a checkout operation
IDfCheckoutOperation checkout = cX.getCheckoutOperation;
// Add the document to the checkout operation
checkout.add(doc); //This might fail and return a null

// Checkout the document

checkout.execute();
Steps for Manipulating Documents

 Use the appropriate factory method of IDfClientX to obtain an

operation of the type appropriate to the document-manipulation task.
For example, if you wish to check documents into a Docbase, start by
calling getCheckinOperation

 Set parameters to control the way the operation performs the task.
Each operation type has setXxx methods for setting its parameters

 Add documents to the operation. Use its inherited add method to place
a document, file, or folder into the operation. The add method returns
the newly created node (or a null if it fails)

 Invoke the operation’s inherited execute method to perform the task

Error Handling

 If it detects errors, the execute method returns the boolean value

false.You can use the operation’s inherited getErrors method to obtain a
list of failures
Check-out Operation

void testCheckoutVdoc( IDfClientX clientx,IDfDocument doc, String strDir )

throws DfException
{
IDfCheckoutOperation checkout = clientx.getCheckoutOperation();
checkout.setDestinationDirectory( strDir );
IDfCheckoutNode node = (IDfCheckoutNode) checkoutOperation.add(doc);
if(checkoutOperation.execute() == false)
{
System.out.println("\nCheckout Operation failed!");
}
else
System.out.println("\nCheckout Operation successful!");
Check-in Operation

IDfCheckinOperation checkin = clientx.getCheckinOperation();

checkin.setCheckinVersion( IDfCheckinOperation.NEXT_MINOR );
checkin.setVersionLabels( "DRAFT,WIP" );

// Add the document to the operation

IDfCheckinNode node = (IDfCheckinNode)checkin.add( doc );

Checkin.execute();
What is DQL?

 DQL – Documentum Query Language

 Uses syntax that is a superset of SQL

 Provides additional content management specific extensions to SQL

such as REGISTER statement

 Statements operate on objects and sometimes on tables / rows

while SQL statements operate on tables / rows only

 DQL Tools :
– From Documentum Administrator
– Through DFC Programs
A Basic DQL Query

 Uses basic DQL SELECT statement to retrieve objects from repository

 In a DQL SELECT statement, you can specify object properties in the

SELECT clause and an object type in the FROM clause

 All subtypes of the specified type are also searched

e.g.
SELECT object_name, title, r_creation_date from dm_document;
WHERE Clause

Allows the search to be narrowed by imposing search conditions on your

query

SELECT object_name, subject FROM dm_document WHERE r_object_id

= <object_id> AND title LIKE ‘%SOP%’
REGISTER Statement : What it does?

 Registers an RDBMS table so the Content Server can see it

 Allows access to data in an existing RDBMS table that may be
– Created to support additional application data
– Part of another application
– Owned by someone else

 Creates a dm_registered object in the System cabinet which provides a

description of the table and user access to it
 Only repository owner with SUPERUSER privilege can register a table
from with Documentum and READ permission on DB table is required

REGISTER Statement : register table product

(product_name char(20)
(part_num char(20))
What is Server API?

 Instructions sent to the Content Server by Clients in

the form of Server API calls

 Server APIs are invoked through the DMCL APIs on

the client machine

Syntax :
method_name,session,addressed_object,argument,{argument}

Example :
Get, c, <object_id>, object_name
All arguments are positional.
“c” stands for current session.

Tools Used : DA, IAPI

Managing Objects

Creating an object :

create creates an object of a specified type

create, session,object_type

set assigns the value of an object’s attribute

set, session,object_id,attribute[index], value

setfile associates content with an object

setfile,session,object_id,file_name,format

save saves the object to the Docbase

save,session,object_id
DQL Vs API

Consider the DQL query to change owner of documents from ‘abc’ to ‘xyz’

update dm_document objects set owner_name=‘abc where

owner_name=‘xyz’
– Processing of all the documents occur on the server only.
– No caching to the client

However, the equivalent API call

– One call at a time
– Increase client/server traffic
– Caches processed objects to the client
Custom Types

 A specialized type that business rules may require

 Usually created as a subtype of an existing type
 Inherits all characteristics of its parent type
 Includes any newly added properties

Example :
dm_document
sop_doc

Extended Attributes
- effective_date
User-defined type
- sop_number
- affected_dept
Creating and Modifying Types

 Must have CREAYE TYPE privilage to create a type

 Users with Sysadmin, superuser and co-ordinators can create types

 Following tools can be used to create a type :

– Documentum Administrator
– DocApp Builder

 Custom object types are created using DAB and packaged into DocApp.
DocApp can be installed in the target repository
Data Dictionary

 A reservoir of information about persistent object types maintained

by the Content Server

 It provides a common server based repository of rules for objects

and properties

 Allows the same rules for web and client server development

 Validates data when save method is called

Questions?