DFC Fundamentals
-
Upload
aruna-chaparala -
Category
Documents
-
view
1.876 -
download
9
Transcript of 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:
IDfLoginInfo loginInfoObj = clientx.getLoginInfo();
- 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
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
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
IDfLoginInfo loginInfoObj = clientx.getLoginInfo();
- 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
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
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