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

dm_folder dm_policy dm_user dm_document

IDfSysObject

IDfPersistentObject

………

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

1. Obtain an IDfClient interface by calling the getLocalClient method of DfClient

2. Create a session, sess, by calling newSession on the IDfClient object

3. Obtain an IDfQuery object, q:

4. Create a DQL query as a text string, dq

5. Call q.setDQL(dq) to set the DQL string into the query object

6. Call q.execute(sess, querytype) to execute the query

7. Iterate through the IDfCollection by calling col.next() until it returns False

8. 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:

1.Obtain a checkout operation2.Add the document to the operation3.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

User-defined type

Extended Attributes

- effective_date

- 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?