Dfc

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 = 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_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

User-defined type

-

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?