dfc fundamentals

DFC Overview

2

Module Objective

• Introduce Documentum Foundation Classes (DFC)

• Walk through a DFC program• Use the DFC JavaDocs• Install and use the DFC

3

• Documentum Foundation Classes (DFC) is an object-oriented programming interface to the Documentum Content Server

- Most clients make calls to the DFC• Implemented as a set of Java classes and interfaces, along with a Java-COM

bridge

- Some DFC objects simply wrap DMCL methods

Client, session, persistent object, query collection

- Some provide high-level logic

Data validation, workflow management, version policy, Business Object Framework (BOF),XML functionality

This logic is REQUIRED for ALL modern clients and applications

What is DFC?

4

What is DFC Used for?

• Foundation for Documentum clients and applications, including

- Documentum Desktop

- Webtop

- Also used for customization of the clients• Methods execution on the Content Server• Foundation for custom management applications• Integration of content management functionality into third party enterprise

applications• Creating business objects using the Business Object Framework (BOF)

- Can be used with any of the items above

5

Application and the DFC

DMCL

DMCL

Custom Client/Server App

Desktop Client

Webtop

Custom Web App

DFCCLIENT

SERVERAll communication

Between the client andServer is through theDMCL, however, the

DFC is the recommendedProgramming approach

With Documentum

Content Server/Docbase

6

Associating DFC Calls with Documentum Desktop

Consider the steps you take to create a cabinet in Documentum Desktop

- Behind the scenes, calls to DFC are being made

1.Provide login information

a) Here we are providing the user name and password

b) Behind the scenes, an object of type IDfLoginInfo is created and populated with the user and password

Also, objects of type IDfClientX and IDfClient are created, but we will discuss them later

2.Click Log On to see if you can access to the Docbase

a) Behind the scenes, same DFC objects are created, including IDfSessionManager

3.Create a new cabinet

Behind the scenes, one of the methods of your IDfSession object is called: newObject(“dm_cabinet”), which you can use to create a new cabinet object

• Once you have created the cabinet object (uses the IDfFloder interface), you can set its name using setObjectName( cabinetName)

• Then you can save the new cabinet to the Docbase with IDfFolder.save();

7

4.Once you have done your Docbase work, you can log off Behind the scenes, the release(session) method of the IDfSessionManager object is

called and the program can be ended

Our First DFC Program This example program will create a cabinet in the Docbase, just as in our last

exampleExample: 1. Get login information and prepare to create sessions with the Content Server - Provide Docbase name, user name and password - Create a session Manager object

2. Get a session with the Content Server - A session is required to securely access the Docbase

3. Create a cabinet in the Docbase 4. Release the session with the Content Server

8

1.Logging In and Preparing for Sessions (Java)

This really a “boilerplate” method that you can reuse

-Provide the Docbase name, user name and password and it creates a Session Manager so that you can have sessions with the server

IDfSessionManager createSessionManager (String docbase, String user, String password) throws Exception {

//create a Client object

IDfClientX clientx = new DfClientX();

IDfClient client = clientx.getLocalClient();

//create a session manager object

IDfSessionManager sMgr = client.newSessionManager();

//create an IDfLoginInfo object names “loginInfoObj”

IDfLoginInfo loginInfoObj = clientx.getLoginInfo();

loginInfoObj.setUser (user);

loginInfoObj.setPassword (password);

//bind the Session Manager to the login info

sMgr.setIdentity(docbase, loginInfoObj);

Return sMgr;

}

9

2. Create a Session with the Server

Before creating a cabinet, we need a session with the Content Server:

IDfSession session = sMgr.getSession(StrDocbaseName);

Assuming your login information is valid, you now have a valid session with the Content Server

- You have obtained a session from the Session Manager

- Now you can work with objects in the Docbase

3.Create a cabinet in the DocbaseThe following method creates a cabinet in the Docbase

- Pass it a session and a cabinet name, and the cabinet created

- Does not check if the cabinet already existsPrivate static IDfFolder createCabinet ( IDfSession session, String cabinetName) throws

DfException { //Create the cabinet uses the IDfFolder interface

IDfFolder myCab = (IDfFolder) session.newObject(“dm_cabinet”);

//commit object to the Docbase

myCab.save();

return myCab; }

10

4. Release the Session with the Server

When using the Session Manager, you always want to pair a getSession() call with a release (IDfSession session) call

- Put the release call in a finally block in Java to ensure that it is called

finally

{

sMgr.release(session);

}

11

Working with Objects in the DFC

• In our example, we were introduced to several DFC interfaces and objects

- For example, to create a loginInfoObj object that has the IDfLoginInfo interface:


- To set the user name on the IDfLoginInfo object

loginInfoObj.setUser (user);

• How do we know what interfaces and objects are available and what methods they contain?

- Consult the JavaDocs

12

DFC JavaDocs

JavaDocs are organized into Packages, Classes and Interfaces

- DFC packages begin with ‘com.documentum’

- DFC classes begin with a ‘D’ (DfClientX)

- DFC interfaces begin with an ‘I’ (IDfSession)

13

DFC JavaDocs

• Inside of a class or interface, you can see the available methods• Use the Index feature of JavaDocs to search for specific information

• Our Example- Setting the User Name

• Click on the IDfLoginInfo interface, scroll through the methods and notice the method name setUser()

- The parameter list shows what is required when calling the method, as well as return type for the method

void setUser (String u);

Working with Field• Fields in interfaces are used for creating groups of “constants”• This avoids the need to hard-code values for method arguments.

14

Installing the DFC

• DFC is installed when you install most Documentum products, including the Content Server, Documentum Desktop and Webtop

- There is also a standard DFC installer• After installation, you should have the following:

- A Java runtime environment

Usually in C:\Program Files\Documentum\jre

- A dfc.jar file and other jar files

Usually in C:\Program Files\Documentum\Shared

- dctm.jar referenced in your ClassPath

This contains a manifest which points to the files

This simplifies the ClassPath• dctm.jar contains a manifest that points to other jar files.

15

Referencing the DFC

To use the DFC in your programs, you must reference it

- In your Java IDE, mount dfc.jar (and other needed files

If your IDE can read manifest files, mount dctm.jar

Also include import statements in the source code

import com.documentum.fc.client.*

Clients and Sessions

17

Module Objectives

• Compare the Document Server object model to the DFC interface model• List the categories of interfaces in the DFC• Create a session with a Content Server• Obtain available Docbase information from the Docbroker• Instantiate and use objects of the following interfaces:

- IDfClientX

- IDfClient

- IDfLoginInfo

- IDfSessionManager

- IDfSession

- IDfDocbaseMap

18

DFC Interface Hierarchy and the Server Object Hierarchy

IDfTypeObject

Non-Persistent Type

IDfDobaseMap

Docbase LocatorIDfPersistentObject

Persistent Object

IDfCollection

Non Persistent

IDfUser

dm_user

IDfGroup

dm_group

IDfSysObject

dm_sysobject

IDfType

dm_type

IDfFormat

dm_format

IDfContainment

dmr_containment

IDfACL

dm_acl

IDfWorkflow

dm_workflow

IDfFolder

dm_floder

dm_cabinet

IDfDocument

dm_document IDfProcess

dm_process

(workflow template)IMYInterface

my_document (BOF)

19

DFC Interface- The Big Picture

Client and SessionsIDfClientxIDfClientIDfDocbaseMapIDfLogInfoIDfSessionManager*IDfSession

Query Related

IDfQuery

IDfQueryMgr

IDfXMLQuery

Validation Related

IDfValidator

IDfValueAssistance

Virtual Document

IDfVirtualDocument

IDfVirtualDocumentNode

Registry and Local Files

IDfClientRegistryObject

IDfCheckedOutObject

Convenience/

Programming Tools

IDfCollection

IDfException

IDfId

IDfProperties

IDfFile

IDfListBusiness Object

Framework (BOF)

IDfBusinessObject*

IDfService*

IDfDbor*

Operation and Nodes

IDfOperation

IDfOperationNode

IDfOperationError

IDfCheckinOperation

IDfDeleteOperationNode

IDfXMLTransformOperation

IDfValidationOperation

20

This module- Clients and Sessions

Client and SessionsIDfClientxIDfClientIDfDocbaseMap**IDfLogInfoIDfSessionManager*IDfSession

Query Related

IDfQuery

IDfQueryMgr

IDfXMLQuery

Validation Related

IDfValidator

IDfValueAssistance

Virtual Document

IDfVirtualDocument




IDfCheckedOutObject

Convenience/

Programming Tools

IDfCollection

IDfException

IDfId

IDfProperties

IDfFile


Framework (BOF)

IDfBusinessObject*

IDfService*

IDfDbor*

Operation and Nodes

IDfOperation

IDfOperationNode

IDfOperationError

IDfCheckinOperation




21

Our First Program Revisited

In the next few slides, we will look at the interfaces in the createSessionManager method we saw earlier:

IDfSessionManager createSessionManager (String docbase, String user, String password) throws Exception {

//create a Client objectIDfClientX clientx = new DfClientX();IDfClient client = clientx.getLocalClient();//create a session manager objectIDfSessionManager sMgr = client.newSessionManager();//create an IDfLoginInfo object names “loginInfoObj”IDfLoginInfo loginInfoObj = clientx.getLoginInfo();loginInfoObj.setUser (user);loginInfoObj.setPassword (password);//bind the Session Manager to the login infosMgr.setIdentity(docbase, loginInfoObj);Return sMgr;}

22

IDfClientX

• The IDfClientX interface contains factory methods (and others)

- These methods instantiate other objects, including IDfClient

- Factory methods work for both Java and COM programs

• Creating the IDfClientX object is one of the few places where you use “new” rather than a factory method ( a bootstrap object)

- Java: IDfClientX clientx = new DfClientX ();

• Sample methods:

- getLocalClient() – Factory for IDfClient objects

- getCheckoutOperation() – Factory for IDfCheckoutOperation object

23

IDfClient

• Contains methods that obtain Docbase information, creates a Session Manager and other objects, and manages sessions

- After creating an IDfClientX object, call the IDfClientX.getLocalClient() method to create an IDfClient object:

IDfClient client = clientx.getLocalClient ();

• Sample methods:

- getDocbaseMap() – Asks the Docbroker for a list of known Docbases

Usually this information in presented in a login dialog

- newSessionManager()- Factory for IDfSessionManager objects

IDfSessionManager sMgr = client.newSessionManager();

- newSession(docbaseName, loginInfo) – Not recommended – suggest you use IDfSessionManager methods in DFC 5.x

24

IDfLoginInfo

• Contains methods for setting and getting login information for users

- After creating an IDfClientX objects, you can use getLoginInfo() factory method to create an IDfLoginInfo object


- An IDfLoginInfo object is passed as an argument to the IDfSessionManager.setIdentity() method later

• Sample methods:

- setUser(String user)

loginInfoObj.setUser(user);

- setPassword(String password)

loginInfoObj.setPassword(password);

- setDomain(String domain)- optionally sets the windows domain

25

IDfSessionManager

• An IDfSessionManager object is used to manage identities, sessions and transactions

- In this course we will focus on session management

- Create an IDfSessionManager object using the IDfClient factory method IDfSessionManager sMgr = client.newSessionManager();

• Sample methods:

- setIdentity(String docbase, IDfLoginInfo identity) – Binds an identity to the Session Manager

sMgr.setIdentity(docbase, loginInfoObj);

- authenticate(String docbase) – Throws an IDfException of the user credentials are not valid – used with login dialogs

- getSession(String docbase) – Provides a handle to a Docbase session. Authenticates the user if user has not been authenticated.

- release(IDfSession session)- Release the session to the session pool

26

IDfSession

• Encapsulates a session with a Docbase

• Clients use this interface to query for Docbase information, create persistent objects in the Docbase and access existing objects.

• Create an IDfSession object using the Session Manager

IDfSession session = sMgr.getSession(strDocbaseName)

• Sample methods:

- getDocbaseName() – Returns the default Docbase name

- newObject(typename) – Creates a persistent object of Server type typename

- getFolderByPath(folderPath) – Returns an existing IDfFolderObject

27

The createSessionManager Method

One last look at this method…IDfSessionManager createSessionManager (String docbase, String user, String

password) throws Exception {//create a Client objectIDfClientX clientx = new DfClientX();IDfClient client = clientx.getLocalClient();//create a session manager objectIDfSessionManager sMgr = client.newSessionManager();//create an IDfLoginInfo object names “loginInfoObj”IDfLoginInfo loginInfoObj = clientx.getLoginInfo();loginInfoObj.setUser (user);loginInfoObj.setPassword (password);//bind the Session Manager to the login infosMgr.setIdentity(docbase, loginInfoObj);Return sMgr;}

28

Docbase Connection Dynamics

Docbroker

PROD

What Docbases are available?

Dev, TEST and PROD

Connect me to PROD as joesmith, password “secret”

Here’s your session ID

29

IDfDocbaseMap

• The IDfDocbaseMap interface allows you to obtain Docbase information from the Docbroker

- This is often presented to the user in the login dialog

- Also used to populate the Docbases in Desktop Client• Instantiate an IDfDocbaseMap object with:

- IDfClient.getDocbaseMap()• Sample methods:

- getHostName() – Returns the Docbroker host name

- getDocbaseCount() – Returns the number of Docbases known to the Docbroker

- getDocbaseName(index) – Returns a Docbase name

30

Factory Methods vs. New(Java)

How do you know which factory methods to use?

- Here is a summarized list for client and session-related objects

Interface How to Instantiate an Object

IDfClientX IDfClientX clientx = new DfClientX();

IDfClient IdfClient client = clientx.getLocalClient();

IDfDocbaseMap IDfDocbaseMap docbaseMap = client.getDocbaseMap();

IDfLoginInfo IDfLoginInfo loginInfoObj = clientx.getLoginInfo();

IDfSessionManager IDfSessionManager sMgr = client.newSessionManager();

IDfSession IDfSession session = sMgr.getSession(strDocbaseName);

DFC Type Related Interfaces

32

Module Objectives

• Use inherited methods• Use methods of IDfTyped objects and subtypes• Create cabinets, folders and documents

33

Documentum Object Hierarchy

• Some DFC interfaces relate to the Documentum object model…

Non-Persistent Type

Non-PersistentPersistent ObjectDocbase Locator

dm_document

dm_acl dm_group dm_sysobject dm_type dm_user

dm_folder

dm_cabinet

34

DFC Interface Hierarchy and the Server Object Hierarchy

IDfTypeObject

Non-Persistent Type

IDfDobaseMap

Docbase LocatorIDfPersistentObject

Persistent Object

IDfCollection

Non Persistent

IDfUser

dm_user

IDfGroup

dm_group

IDfSysObject

dm_sysobject

IDfType

dm_type

IDfFormat

dm_format

IDfContainment

dmr_containment

IDfACL

dm_acl

IDfWorkflow

dm_workflow

IDfFolder

dm_floder

dm_cabinet

IDfDocument

dm_document IDfProcess

dm_process

(workflow template)IMYInterface

my_document (BOF)

35

Inheritance

• Inheritance allows you to extend and add to the definition of an existing class to reuse some properties and methods, and add or override others

• Inheritance applies to Content Server object types and to DFC interfaces

- For server object types, the key concern for DFC programmers is attribute (property) inheritance

- For DFC classes, you also have method inheritance

36

Content Server Attribute Inheritance

• Server objects of a certain type have the attributes of that type plus all of the attributes of the supertypes.

- For example, dm_document has an r_object_id attribute

Type Super_Type Sample attribute

Persistent object (internal type)

None r_onject_id

i_vstamp

SysObject

(dm_sysobject)

Persistent Object r_creator_name

acl_name

object_name

Document

(dm_document)

SysObject none

37

DFC Interface Inheritance

• An object with a certain interface inherits methods of all super interfaces

- For example, IDfDocument inherits the save() method from IDfPersistentObject

Interface Super Interface Sample Methods

IDfTypeObject getObjectId();

getString(attrName);

IDfPersistentObject IDfTypedObject save();

IDfSysObject IDfPersistentObject checkout()

getObjectName();

getContent();

IDfDocument IDfSysObject none

38

Interface Inheritance in Java

Each interface inherits methods and constants from interfaces above it-

try{ IDfDocument docobj = (IDfDocument) session.newObject(“dm_document”) docobj.setContentType(“msw8”); // method of IDfSysObject docobj.setFile(“c:/temp/chap1.doc”); doc.link(“/mycabinet”); …//call other methods docobj.save(); // method of IDfPersistentObject}catch(DfException dfe){ //Report error}

39

IDfTypedObject

• Description: - Provides the basic functionality for persistent and non-persistent objects - Persistent objects are stored in the Docbase - Non-persistent objects are in memory (for example, query results) - Provides basic methods to get and set object attributes (properties)

- Includes single and repeating value attributes boolean isPrivate = myCabinet.getBoolean(“is_private”) - Use getValueCount(attrName) to determine the number of values in a

repeating attribute - Use these methods if more derived interfaces do not have a

dedicated method (for example, IDfSysObject.getObjectName() ) - Use these methods for custom attributes - Since typed objects are created with a session, there are some session – related

methods (for example, IDfTypedObject.getSession() )

40

IDfPersistentObject

Description:

- Provides basic functionality needed to interact with persistent objects

save(), fetch(), destroy()

- Contains pass through methods to use the DMCL API

apiGet(), apiSet(), apiExec()

- Contains a factory method for validation (getValidator() )

- Contains relation object-related methods (addChildRelative() )

dm_relation objects define a relationship between two objects

Can be system relationships (dm_notes for a sysobject)

Can be user-defined relationships (for example, subscription)

- Contains a method related to audit trails

signoff()

41

IDfSysObject

• This is where many content management related methods are

- However, use IDfOperations if you can (like for checkout)• dm_sysobjects can (but not must):

- Have content

- Be checked in and checked out of a Docbase

- Be versioned

- Have permissions

- Reside in a folder

- Be part of virtual document

- have an attached lifecycle• Many of these have a related category of methods in IDfSysObject…

42

IDfSysObject

Categories of methods in IDfSysobject:

- Attribute related – use these where available rather than the get and set methods of IDfTypedObject

- Content management related – where you can, use the IDfOperation interface for these tasks

- Content related

- Version related

- Link/reference related

- ACL related

- Lifecycle related

- Virtual document related

- Event related

- Alias related

- Other

43

IDfVirtualDocument and IDfSysObject

Use IDfSysObject.asVirtualDocument() to instantiate a Virtual Document representation

of an object

IDfVirtualDocument vDoc = sysObj.asVirtualDocument(“CURRENT”, false);

- If the sysObj was not a virtual Document, this call creates it

- The resulting object is of type IDfVirtualDocument

Can then call methods like addNode() and removeNode() to manipulate the virtual Document at high level

A node is represented as IDfVirtualDocumentNode

- IDfVirtualDocument is not a subtype of IDfSysObject

You will use both the IDfSysObject and IDfVirtualDocument representations of the object in your code

For example, sysObj.getObjectName() and vDoc.addNode()

- Virtual Documents can be manipulated with Operations

44

IDfSysObject Subtypes

IDfSysObjectdm_sysobject

IDfDocument dm_document

IDfFolderdm_folder

IDfProcessdm_process

IDfActivitydm_activity

IDfRouterdm_router

<none>dm_method

IDfSOPDoc* SOP_document

<none>dm_cabinet

• IDfSysObject includes the sub-interfaces shown above

- IDfFolder (getContents(), getFolderPath() )

- There is no IDfCabinet (use IDfFolder)

- IDfDocument has no new methods (all methods are inherited)

• *Custom interfaces can be created to extend existing interfaces

- Using the Business Object Framework (BOF)

45

Working with Folder Objects

• To obtain an IDfFolder object:

- Use IDfSession.getFolderByPath (String folderName)

- For example, session.getFolderByPath(“/dmadmin”);

- Returns an IDfFolder object• To get certain attributes of each object in the folder:

- IDfFolder.getContents (String attrNames)

For example, folder.getContents(“r_object_id”);

Returns an IDfCollection object containing string values of the object ids of all children in the folder

- The following attributes can be specified (separated by commas)

object_name, a_content_type, r_object_type, r_object_id, r_lock_owner, and i_is_replica

- Set the argument to (null) to return all of these values

46

IDfType

• Use this to discover information about Content Server object types• The factory method is IDfSession.getType(String typeName)• To print all of the attributes for dm_document:

IDfType typeObj = sess.getAttrCount();

for (int i = 0; i < typeObj.getAttrCount(); i++) {

IDfAttr attrObj = typeObj.getAttr(i);

System.out.println(“Attribute Name: “ + attrObj.getName(); }• Can also get data dictionary information for the type:

//user friendly name for type for example “Document”

String myDesc = typeObj.getDescription();

47

Object Creation

Session, give me an empty

object of type X

Session

Object, set your

properties to these

values and save

yourself

48

Create a Cabinet in the Docbase

- Pass it a session and a cabinet name, and the cabinet is created- Creates a new object of type “dm_cabinet”, but uses the IDfFolder interface.There is no IDfCabinet interface

public static IDfFolder createCabinet (IDfSession session, String cabinetName)throws DfException {//First see if the cabinet already existsIDfFolder myCabinet = session.getFolderByPath (“/” + cabinetName);If(myCabinet != null){ System.out.println(“Cabinet already exists!”); return myCabinet; } //it already existed//Create the cabinet-uses the IDfFolder interfacemyCabinet = (IDfFolder)session.newObject(“dm_cabinet”);myCabinet = setObjectName(cabinetName);myCabinet.save();return myCabinet; }

49

Create a Folder in the Docbase

- Pass it a session, parent folder path and a folder name- Creates a new object of type “dm_folder”, and uses the IDfFolder Interface

public static IDfFolder createFolder(IDfSession session, String path, String folderName) throws DfException {

//NOTE This method should check the path exists, the folder does not exist and string // are formatted correctly IDfFolder myFolder = (IDfFolder)session.newObject(“dm_folder”); myFolder.setObjectName(foldername); myFolder.link (path); //link to parent folder MyFolder.save(); return myFolder; }

50

Create a Document in the Docbase

public static IDfDocument createDocument (IDfSession session, String objectName, IDfFolder folder, String content) throws DfException

{//Create a dm_document objectIDfDocument document = (IDfDocument) session.newObject(“dm_document”);//Set the document namedocument.setObjectName(objectName);//Set the content “type” to crtextdocument.setContentType(“crtext”);//Content on the file system to usedocument.setFile(content);//Specify the folder in which to create the documentdocument.link(folder.getObjectId().toString() );//save the document in the Docbase. Actual create of the object in the Docbase happens after the// save()document.save();//return the newly created documentreturn document; }

Common DFC Tools

52

Module Objectives

• Work with files on the file system with IDfFile• Work with folders in the Docbase• Use IDfCollection or IDfList objects to return results

with multiple values• Obtain object IDs for Docbase objects• Create a reference to an existing Docbase object• Perform Docbase queries and process the results

53

Common DFC Tools

Client and SessionsIDfClientxIDfClientIDfDocbaseMap**IDfLogInfoIDfSessionManager*IDfSession

Query Related

IDfQuery

IDfQueryMgr

IDfXMLQuery

Validation Related

IDfValidator

IDfValueAssistance

Virtual Document

IDfVirtualDocument




IDfCheckedOutObject

Convenience/

Programming Tools

IDfCollection

IDfException

IDfId

IDfProperties

IDfFile


Framework (BOF)

IDfBUsinessObject*

IDfService*

IDfDbor*

Operation and Nodes

IDfOperation

IDfOperationNode

IDfOperationError

IDfCheckinOperation




54

Working With Files

• The IDfFile interface allows you to work with files on the file system

- It is a DFC object that represents a file

- For example, use when you want to delete a local copy of a file or add a file to an IDfImportOperation

• The factory method for IDfFile objects is:

IDfClientX.getfile (String filePath)• Example:

IDfFile myFile = clientx.getFile (“c:\\mydoc.txt”);• Sample methods:

- deleteFile() – removes the file from the file system

- exists() – determines if the file exists

- setExtension() – sets the extension on the file

55

Working With Collections

• Some methods return collections (IDfCollection)• An IDfCollection is a cross-platform way to return multiple objects’ attributes from a

method call• For example, to return the object name (as a string) of all of the objects in a

Docbase folder:IDfCollection collection = folder.getContents(“object_name”);

• Iterate through the collection with a while loop, using the next() method while (collection.next() ) {

//do something with an object System.out.println (collection.getString(“object_name”)); }

• The key methods of IDfCollection are: next(), close()• Usually methods of IDfTyped objects are used inside of the while loop

- IDfCollection is a subclass of IDfTypedObjectIDfId myId = collection.getId(“r_object_id”);

• Close collections when you are finished with them collection.close();

56

Working with IDfList Objects

• IDfLists are similar to Vectors in Java and Collections in visual basic

- They provide more “robust” functionality than IDfCollection objects

- The IDfList can contain any object type

- Can create an IDfList and work on that list in future methods

- IDfCollections contain only primitive objects and can only be used once: after calling next(), you can not go back

- Convert an IDfCollection to an IDfList by using IDfCollection.getTypedObject() to add each object to a new IDfList

• You will use lists to work with new objects created when using IDfOperations(new objects, root nodes, child nodes)

IDfList listObjectsNew = opCheckin.getNewObjects();• You will use lists when working with errors in the IDfOperations package

IDfList opErrors = operation.getErrors()

57

Obtaining a Reference to an Object

• Often you will want to obtain a reference to an object so that you can call methods on it:

- IDfSession.getObject(IDfId objID)

- IDfSession.getObjectByPath(String path)

- IdfSession.getObjectByQualification(String qualification)

58

Obtaining an Object ID(IDfId)

• If you have a reference to the object:

- IDfTypedObject.getObjectId()

returns an IDfId

• Obtaining an object ID with a query- IDfSession.getIdByQualification(String qualification)

returns an IDfId

• Obtaining an object ID from a folder path- Combination of IDfSession.getFolderByuPath() and IDfFolder.getObjectId()

59

IDfQuery

• An IDfQuery object is a non-persistent object that passes a DQL query to the DQL engine for execution, and returns an IDfCollection object for processing

• When the underlying RDBMS returns rows for a SELECT statement, the Content Server places each returned row in a query result object and then associates the set of query result objects with an IDfCollection object

DQL Query

Session ID

IDfQuery IDfCollection

60

Build and Execute a Query

IDfCollection execQuery (IDfSession sess, String queryString){ IDfCollection col = null; // Collection for the result try { IDfQuery q = clientx.getQuery(); // Create query object q.setDQL(querystring); // Give it the query DF_READ_QUERY is the query type col = q.execute(Sess, IDfQuery.DF_READ_QUERY); } catch (DfException dfe) { // catch exception here }return col;}

Operations

62

Objectives

• Use the IDfOperations package as a high level interface for common Docbase actions

• Become familiar with the use of the general “ design patterns “ for using the Operations interfaces

• Perform Import , Checkout , Checkin and Export Operations

63

DFC Architecture

There are 3 main layers of DFC

- The Operations Layer

- The Services Layer

- The Core Layer

Operations

Workflow VDM Validation Query Builder

Core

IDfCheckinOperation

IDfSysObject.getFile( )

64

The Operations Package

• The Operations package is a high-level set of interfaces for performing common content management functions

– For example, import, checkin, checkout, export, delete

• This is the recommended approach when performing content management tasks

- Can work with many objects at a time(for ex. Deep folder contents)

- Handles most of the details for you(simple vs. virtual documents, Registry entries)

- Works with XML documents

- Works across multiple Docbases (for example copying)

65

Operations and Nodes

• Use Operation to perform content management tasks programmatically

- Example : For to Check out a document use IDfCheckoutOperation interface

• Working with Nodes that corresponds to the Operation

- The Nodes define the items you need to work with

- Example : A Node will represent the IDfSysObject that will be checked out

- Create Nodes using Operation’s add ( ) method

- This creates an object of type IDfCheckoutNode

- There can be many Nodes for a single operation ( Example : Adding a simple

document as well as Virtual Document with three children results in five Nodes )

- A single add() can create many Nodes.

66

Operations Design Pattern

Using any Operation typically follows this pattern :

1. Create an Operation object ( Example : IDfCheckoutOperation )

1 a. Set Parameters on Operation object ( override defaults )

2. Populate using the add ( ) method to create Nodes

2 a. Set Parameters on Node objects ( override Node defaults )

3. Execute the operation ( returns true or false)

4. Handle Errors ( rollback if possible)

5. Process Results

67

Patterns

Import

Export

Checkout

Checkin

CancelCheckout

Copy

Delete

Move

Validation

XMLTransform

Create

the Operation

Object

Populate

The Operation

Object with…

Virtual Documents

Virtual

Document

Components

Objects(Documens)

Folders

Files

Directories

D E

Doc2

B

A

C

The same operational steps are

repeated for each Node

(for example, Checkin for

each node, or XML Transform for each Node )

Executeadd( ) Creates NodesUse

s Nod

es

68

Design Pattern – Skeleton (Java)

IDfCheckinOperation opCheckin = clientx . getCheckinOperation ( ) ; 1

opCheckin . setVersionLabels ( “Approved” ) ; 1a

IDfSysObject sysObj1 = ( IDfSysObject ) sess . getObject ( clientx . getId ( “09…1” ) ) ;

IDfCheckinNode node1 = ( IDfCheckinNode ) opCheckin . add ( sysObj1 ) ; 2

If ( node1 == null ) // check for null

// handle null case here

node1 . setFormat ( “crtext” ) ; 2a

boolean success = opCheckin . execute ( ) ; 3If ( ! success ) {

myProcessErrors ( opCheckin . getErrors ( ) ) ; } 4

IDflist listObjectsNew = opCheckin . getNewObjects ( ) ; 5

1 Create

1a Set Parameters

2 Populate

2a Set Parameters

3 Execute

4 Handle Errors

5 Process Results

69

Population – Simple Documents

• Populate the Operation object by adding Nodes• Each Node “ executes “ individually

IDfCheckinoperation

IDfCheckinNode

IDfCheckinNode

Contract

Exhibit A

IDfCheckinOperation operation = clientx . getCheckinOperation ( ) ;

IDfSysObject sysObj1 = ( IDfSysObject ) session . getObject ( clientx . getId ( “09…1 “ ) ) ;

IDfCheckinNode = ( IDfCheckinNode ) operation . add ( sysObj1 ) ;

IDfSysObject sysObj2 = ( IDfSysObject ) session . getObject ( clientx . getId ( “09…2 “ ) ) ;

IDfCheckinNode node2 = ( IDfCheckinNode ) operation . add ( sysObj2 ) ;

Boolean success = operation . Execute ( ) ;

Specify objects to operate on

70

Executing an Operation

• Running the execute ( ) method of the Operation will automatically cause a number of steps to be done on each Node

- Processes the first step of Operation on all Nodes

- Then processes each of the other steps

- Returns true if all are successful• For example, with the IDfCheckOutOperation :

- Obtain a lock on each document

- Set up the destination directory path to checkout directory

- Construct a reasonable filename

- Download the primary content file from the Content Server

- Add the checked out file to the Registry• Using Operations, similar code can process a simple document or a very complicated

set of Virtual Documents or XML documents

71

Example : Import Operation

IDfImportOperation opImport = clientx . getImportOperation ( ) ;

//Docbase session for the import operation to use

opImport . setSession ( session ) ;

//Set the destination folder

opImport . setDestinationFolderId ( clientx . getId ( “ 0b0… “ ) ) ;

//Setup the file path for the file to import

IDfFile myFile = clientX . getFile ( “ C:\\mydoc . Txt “ ) ;

//Add the file to the import operation

//Create a cast to the import node interface

IDfImportNode node = ( IDfImportNode ) opImport . add ( myFile ) ;

opImport . execute ( );

Required !

72

What is the Import Operation?

• Performs complete client import of one or more Nodes

- Can import individual files or directories• Includes all contents of a directory with a single add ( )

- Can import compound and XML files

• Steps of an IDfImportOperation

- Apply XML Application ( if applicable )

- Scan referenced files ( if applicable )

- Validate Import Operation ( if applicable )

- Create new folder objects

- Create objects , set properties, checkin objects

- Remove local files ( if applicable )

- Clean up the Registry ( if necessary )

73

Checkout Operation

• Checkout places a lock on the object and copies it to the local file system - By default, the document is placed in the Checkout directory can override with setDestinationDirectory ( )• Can add ( ) IDfSysObject , IDfVirtualDocument or IDfVirtualDocumentNode IDfSysObject simpleObject = ( IDfSysObject ) session . getObject ( “ 09 --- 1 “ ) ; IDfCheckoutOperation checkout = clientx . getCheckoutOperation ( ) ; IDfCheckoutNode node = ( IDfCheckNode ) checkout . add ( simpleObject ) ; if ( checkout . execute ( ) = = false ) { this . displayErrorList ( checkout . getErrors ( ) ) ; }

IDfSysObject simpleObject = ( IDfSysObject ) session . getObject ( “ 09 --- 2 “ ); IDfVirtualDocument vDoc = simpleObject . asVirtualDocument ( “CURRENT” , false ) ; IDfCheckoutOperation checkout = clientx . getCheckoutOperation ( ) ; IDfCheckoutNode node = ( IDfCheckout Node ) checkout . add ( vDoc ) ; if ( checkout . execute ( ) = = false ) { this . displayErrorList ( checkout . getErrors ( ) ) ; }

Checkout a Simple Document

Checkout a Virtual Document

74

Checkin Operation

• Performs a check in of all nodes - Detects compound references ( links ) - Creates new Docbase objects for new links - Uploads content files to the server - Clears checkout flags - Updates the local client Registry and cleans up the local content files• Can add ( ) IDfSysObject, IDfVirtualDocument or IDfVirtualDocumentNode ( )

IDfCheckinOperation checkin = clientx . getCheckinOperation ( ) ; IDfSysObject sysObject = ( IDfSysObject ) session . getObject ( “ 09…1 “ ) ; IDfCheckinNode node = ( IDfCheckinNode ) checkin . add ( sysObject ) ; checkin . setCheckinVersion ( IDfCheckinOperation . NEXT _ MINOR ) ; checkin . setVersionLabels ( “ CURRENT , DRAFT , WIP “ ) ; node . setFilePath ( “C:\\myfile.doc “ ); // like “ Checkin from file..” if ( checkin . execute ( ) ) { DfId freshNode = node . getNewObjectId ( ) ; // newly created checked in obj }

Checkout a Simple Document – Specify Check – in Version and Symbolic label

add ( IDfSysObject )

or IDfVirtualDocument

or IDfVirtualDocumentNode

75

Questions & Answers