Professional Documents
Culture Documents
Dfcoverview
Dfcoverview
DOC3-USINGDFC-1200
DOC3-USINGDFC-1200
Copyright 1999, 2000 Documentum, Inc. 6801 Koll Center Parkway Pleasanton, CA 94566 All Rights Reserved.
Documentum, Documentum 4i, Docbase, Documentum eContent Server, Documentum Server, Documentum Desktop Client, Documentum Intranet Client, Documentum WebPublisher, Documentum ftpIntegrator, Documentum RightSite, Documentum Administrator, Documentum Developer Studio, Documentum Web Development Kit, Documentum WebCache, Documentum ContentCaster, AutoRender Pro, Documentum iTeam, Documentum Reporting Gateway, Documentum Content Personalization Services, Documentum Site Delivery Services, Documentum Content Authentication Services, Documentum DocControl Manager, Documentum Corrective Action Manager, DocInput, Documentum DocViewer, Virtual Document Manager, Docbasic, Documentum DocPage Server, Documentum WorkSpace, Documentum SmartSpace, and Documentum ViewSpace are trademarks or registered trademarks of Documentum, Inc. in the United States and throughout the world. All other company and product names are used for identification purposes only and may be trademarks of their respective owners.
iii
Inbox and Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Session State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IDfClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Sessions and Obtaining References to Existing Sessions . Maps and Config Information . . . . . . . . . . . . . . . . . . . . . . . . Service Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow of Query Processing . . . . . . . . . . . . . . . . . . . . . . . . . . IDfQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IDfCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.1-30 .1-30 .1-31 .1-31 .1-31 .1-31 .1-32 .1-33 .1-34 .1-34 .1-34 .1-35 .1-36 . . . . . . . . . . . . . . . . . . . . 2-1 2-1 2-1 2-2 2-3 2-3 2-4 2-4 2-4 2-5 2-5 2-5 2-6 3-1 3-2 3-2 3-3 3-3 3-4 3-4
Using DFC
Using DFC From Application Programs . . . . . . Java . . . . . . . . . . . . . . . . . . . . . Visual Basic . . . . . . . . . . . . . . . . C++ . . . . . . . . . . . . . . . . . . . . . Syntax Differences . . . . . . . . . . . . . . . Creating DFC Client Objects. . . . . . . . . . . . . Java Example . . . . . . . . . . . . . . . . . . COM Example. . . . . . . . . . . . . . . . . . Creating a DFC Session . . . . . . . . . . . . . . . Shared Sessions . . . . . . . . . . . . . . Adopted Sessions . . . . . . . . . . . . . Using DFC Tracing . . . . . . . . . . . . . . . . . . Using the DFC Online Reference Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
Using a Docbase Map . . . . . . . . . . . . . . . displayDocbaseInfo in Java . . . . . . . . . connectToDocbase(map, index) in Java . . Step through Docbases in Java . . . . . . . displayDocbaseInfo in Visual Basic . . . . connectToDocbase(name) in Visual Basic.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 3-5 . 3-5 . 3-5 . 3-5 . 3-6 . 3-6 . 4-1 . 4-1 . 4-2 . 4-2 . 4-3 . 4-3 . 4-4 . 4-5 . 4-5 . 4-5 . 4-6 . 4-6 . 4-6 . 4-7 . 4-7 . 4-7 . 4-8 . 4-8 . 4-9 . 4-9 . 4-9 4-10 4-10 4-11 4-11 4-11 4-11 4-12 4-13 4-13
vi
Retrieving and Setting Attributes . . . . . . IDfSession . . . . . . . . . . . . . . . . IDfTypedObject . . . . . . . . . . . . . Searching the Docbase . . . . . . . . . . . . IDfQuery . . . . . . . . . . . . . . . . . IDfSession . . . . . . . . . . . . . . . . IDfCollection . . . . . . . . . . . . . . . Handling Content Objects . . . . . . . . . . IDfSysObject . . . . . . . . . . . . . . . DMCL (No Associated DFC Methods) Printing Documents . . . . . . . . . . . . . . IDfSysObject . . . . . . . . . . . . . . . DMCL (No Associated DFC Methods) Handling Virtual Documents . . . . . . . . IDfSysObject . . . . . . . . . . . . . . . DMCL (No Associated DFC Methods) Handling Workflows . . . . . . . . . . . . . IDfWorkflow . . . . . . . . . . . . . . . Handling Process Definitions . . . . . . . . IDfProcess . . . . . . . . . . . . . . . . Handling Activity Definitions . . . . . . . . IDfActivity . . . . . . . . . . . . . . . . Handling Work Items . . . . . . . . . . . . . IDfWorkitem . . . . . . . . . . . . . . . Managing Inboxes . . . . . . . . . . . . . . . IDfSession . . . . . . . . . . . . . . . . IDfSysObject . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
7-10 7-10 7-10 7-12 7-12 7-12 7-13 7-13 7-13 7-15 7-15 7-15 7-15 7-16 7-16 7-17 7-18 7-18 7-19 7-19 7-20 7-20 7-21 7-21 7-22 7-22 7-23
Index
vii
viii
PREFACE
Intended Audience
This manual is intended for application developers. It assumes a knowledge of object-oriented programming, Java, interfaces, and, in some places, the Microsoft component object model (COM).
ix
Chapter/Appendix Chapter 1, Overview of Documentum Foundation Classes (DFC) Chapter 2, Using DFC Chapter 3, Managing DFC Sessions
Contents How DFC helps you connect to a Docbase and gives you an object oriented interface to the Documentum object hierarchy. Making DFC work with your programming and execution environments.
Annotated examples, based on the classes DfExSession and DfExDocbaseMap, of how to work with DFC sessions and a Docbase map. Annotated examples, based on the classes DfExCreate, DfExCheckinCheckout, DfExVersionPolicy, and DfExDestroy, of how to manipulate Docbase objects.
Chapter 5, Managing Docbase Annotated examples, based on the class Queries with DFC DfExSimpleQuery, of how to create and execute
Docbase queries.
Chapter 6, Automating Business Rules with DFC
Annotated examples, based on the classes DfExSimpleValidation and DfExACL, of how to use Documentum to enforce business rules. An index to the major DFC methods, organized by the tasks the methods accomplish. An explanation of DFC in terms of the methods that previous Documentum client products use to access server capabilities.
Questions that developers who are starting to work with DFC have asked.
Conventions
This manual uses the following conventions:
Convention
Represents a variable name for which you must provide a value, or a defined term. Represents code samples, user input, and computer output. Indicates an optional argument. Indicates an optional argument that can be repeated more than once.
To follow a link: Move the pointer over a linked area. The pointer changes to a pointing finger when positioned over a link. The finger pointer displays a W when moved over a Web link.
1.
2.
Click to follow the link. Note: To follow Web links, your Weblink preferences must specify a Web browser. See Setting Weblink preferences in Adobe Acrobat Help for more information.
xi
To apply for access to online support: In your Web browser, open http://www.documentum.com/ Click the Technical Support link. Click the Request Access link. Complete the form and send it. Documentum responds to access requests within two business days.
1. 2. 3. 4.
To view the list of fixed bugs: In your web browser, open http://www.documentum.com/ Click the Technical Support link. Log on to the Technical Support site. In the Troubleshooting section, click View Bugs. Click Fixed Bugs and Feature Requests Lists. Click the name of the bug list.
1. 2. 3. 4. 5. 6.
xii
Product Documentation
Customers with a software support agreement can view PDF format product documentation at the documentum.com Web site. First request a user name and password (refer to Applying for Access).
To view a document: In your Web browser, open http://www.documentum.com/ Click the Technical Support link. Log on to the Technical Support site. In the Resources section, click Documentation. Click the name of the document.
1. 2. 3. 4. 5.
xiii
xiv
1
1
Desktop Client components use the foundation class library Documentum Foundation Classes (DFC) to access the capabilities of eContent Server. This chapter describes DFC and introduces basic DFC concepts. It contains the following major sections:
s Introduction to DFC on page 1-1 s Overview of DFC Interface Capabilities on page 1-12 s IDfSession on page 1-26 s IDfClient on page 1-31 s Common Package on page 1-34 s Queries on page 1-34
Introduction to DFC
Documentum applications depend heavily on the Documentum object model, which is the object-oriented structure by which eContent Server organizes the contents and control mechanisms of Docbases. The eContent Server Fundamentals manual describes this object model and provides an overview of how to interact with it through the Documentum client library (DMCL), an application programming interface (API). DMCL flattens the object model as a set of commands issued via text string arguments to the dmAPIGet, dmAPISet, and dmAPIExec commands. DFC exposes the Documentum object model as an object-oriented client library. Client-side applications, such as Desktop Client or applications that you develop, and middle-tier libraries and applications, such as Web Development Kit (WDK), use DFC.
11
The core of DFC is a set of Java classes, but it includes other elements as well:
s A collection of DLLs to provide the DFC functionality. s A shared library that you must load to use DFC with non-Microsoft Java
C++.
s A set of C++ wrapper classes that hide many details of the DFC/COM
interface.
DFC Programming
Before you begin to use DFC, it is important to understand the DFC programming approach. Because of the complexities of accessing Docbases efficiently and reliably from remote client machines, Documentum centralizes this access in client-side software that establishes and maintains communication sessions with eContent Server and Docbases. DFC encapsulates this client-side software in the IDfClient interface, which serves as the entry point for DFC code. IDfClient handles basic connection details. It loads the necessary shared libraries. You obtain the initial IDfClient interface by calling the static method DfClient.getLocalClient. The IDfClient interface then serves as a factory for IDfSession objects. If you are familiar with the standard Java database connectivity package, JDBC, you can see an analogy between that programming model and this one. An object that implements IDfSession represents a session 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. With DFC you usually dont create objects directly. Instead, you obtain objects by calling the methods of other objects. Those methods create or obtain the requested object. Methods that create new Docbase objects or fetch existing ones return objects that implement IDfPersistentObject. The following general procedure may help to clarify the DFC approach. Dont worry if you dont completely understand the references to the interface hierarchy. Subsequent sections deal with that subject.
12
To process a Docbase object: Obtain an IDfClient object by calling DfClient.getLocalClient. Call the IDfClient method newSession or getSharedSession to create a session with the Docbase (see connectToDocbase in Java on page 3-2). If you have a reference to the object, call the IDfSession checkout method to lock it. Otherwise call an IDfSession method (for example, newObject or getObjectByQualification) to create an object or to obtain a reference to an existing object. If the object is an IDfSysObject, you can call a. setContentType to set the objects format. b. setFile to set the its content. c. setObjectName to set its name. d. save to save the object in the Docbase.
1. 2. 3.
4. 5.
If you checked out the object in Step 3, call checkin to release the lock. Close the session if you are done with it. The following fragment from a Java program that uses DFC contains three blocks of code. They implement the first three steps of the procedure.
Example
IDfClient client = DfClient.getLocalClient(); IDfLoginInfo loginInfo = new DfLoginInfo(); loginInfo.setUser("Mary"); loginInfo.setPassword("ganDalF"); loginInfo.setDomain(""); session = client.newSession("MyDocbase", loginInfo); IDfDocument document = null; document = (IDfDocument) session.newObject("dm_document"); document.setObjectName("Report on Wizards"); document.setContentType("crtext"); document.setFile("C:\Temp\Wiz.txt"); document.save();
The first block creates the client object, which encapsulates the Documentum client software. The second block creates and populates an object to hold login information and uses it to manufacture an IDfSession object, which encapsulates a session for this application program with the specified Docbase.
13
The third block of code creates and populates an IDfDocument object and saves it in the Docbase. Notice that the newObject method of the session object manufactures the object. The newObject method returns an IDfPersistentObject object. The program explicitly casts it to an IDfDocument object, then uses the document objects save method, a method that IDfDocument inherits from IDfPersistentObject. COM does not support interface inheritance, so the Visual Basic and C++ versions of the above code explicitly cast the document object to a persistent object before saving it (see createDocument in Visual Basic on page 4-2). Most DFC methods throw DfException to report errors. Java code like that in the above example normally appears within a try/catch/finally block, with an error handler in the catch block. Visual Basic code uses the On Error Goto statement to handle exceptions.
Packages
DFC is organized into packages, that is, sets of related classes and interfaces.
s The names of DFC Java classes begin with Df (for example, DfWorkflow). s Names of interfaces begin with IDf (for example, IDfWorkflow).
Interfaces expose DFCs public methods and constants. Each interface contains a set of related methods. Table 1-1 describes the purpose of the classes and interfaces of DFC packages. Table 1-1
Description of DFC Packages Java Package Name com.documentum.fc.client Purpose Provides basic functionality: s Establishing DFC sessions s Retrieving and validating data s Managing workflows s Manipulating virtual documents s Working with document versions common.documentum.fc.client.qb Constructs and runs queries and SmartLists. com.documentum.com Facilitates accessing DFC from COM.
14
Table 1-1
Description of DFC Packages (continued) Java Package Name com.documentum.fc.common com.documentum.fc.common .session com.documentum.operations Purpose Supplies utility methods for other DFC classes. Supports Docbase sessions. Provides high-level functionality, such as checking documents or virtual documents in and out. Maintains Documentum information on the clients system, using the Windows registry on Win32 platforms, and .ini files otherwise.
com.documentum.registry
Both the com.documentum.operations package and the IDfSysObject interface in the com.documentum.fc.client package have methods for high-level client operations, such as checking in and checking out documents. The methods in the operations package perform additional work, such as writing to the registry. Use the interfaces in the operations package to interact with Desktop Client components. Use the operation methods in IDfSysObject only if your code does not interact with Desktop Client components. The DFC interfaces form a hierarchy; some derive methods and constants from others. Use the Tree link from the home page of the DFC online reference (see Using the DFC Online Reference Documentation on page 2-6) to examine the interface hierarchy. Click any interface to go to its definition. Each interface inherits the methods and constants of the interfaces above it in the hierarchy. For example, in Java you can call the save method of a sysobject, because IDfSysObject inherits save from IDfPersistentObject (see Persistent Objects on page 1-16 and SysobjectsPersistent Objects With Content on page 1-24). Visual Basic does not support interface inheritance. Visual Basic or C++ programs access DFC via COM and see DFC as a type library. The library is flat, that is, it contains all of the interfaces but none of the inheritance information. For example, you must convert a sysobject to a persistent object before you can save it.
15
appears in the example on page 1-3. It tells the document object to apply its save method to itself, that is, to save the document in the Docbase. Methods that operate on other objects take references to those objects as arguments.
16
Persistence
Most objects the server manipulates are persistent, that is, they reside in the Docbase and persist across sessions. A document you create and save in one session is still there in another session on another day. Some objects are not persistent, that is, they do not reside in the Docbase. The server creates them as needed at runtime. For example, collection objects and query result objects, which return the results of DQL statements, are not persistent. When the server executes a DQL query it creates a collection object to contain the results of the query. It creates a query result object for each row that the underlying database returns for the underlying SELECT statement, and it associates the query result objects with the collection object. When you close a collection, the server destroys the collection object and the query result objects.
17
18
You can operate on a more derived type with a less-derived interface, but some methods are available only on more derived interfaces. For example, you cannot perform a save on the IDfTypedObject interface. To save, you must hold a reference to an IDfPersistentObject interface or an interface that derives from IDfPersistentObject. Similarly, to perform checkins and checkouts on an object whose type derives from dm_sysobject, you need to refer to that object with at least an IDfSysObject interface. A small subset of the Documentum object hierarchy appears in Figure 1-1. DFC interfaces are in the top (white) parts of the boxes. The corresponding server objects are in the lower (gray) parts. Figure 1-1
DFC Hierarchy Corresponds to Documentum Object Hierarchy
IDfTypedObject Non-Persistent Type
IDfCollection Non-Persistent
IDfACL dm_acl
IDfFormat dm_format
IDfGroup dm_group
IDfSysObject dm_sysobject
IDfType dm_type
IDfUser dm_user
IDfDocument dm_document
IDfFolder dm_folder
<None> dm_cabinet
In Figure 1-2 on page 1-10, you can see how the interfaces that derive from the Documentum hierarchy fit into the total DFC interface hierarchy.
19
Figure 1-2
IDfTypedObject
IDfPersistentObject IDfACL IDfAliasSet IDfAssembly IDfContainment IDfFormat IDfGroup IDfPackage IDfQueueItem IDfRelation IDfRelationType IDfSysObject IDfType IDfFolder IDfUser IDfProcess IDfWorkItem IDfRouter IDfWorkflow IDfCollection IDfDocbaseMap IDfActivity IDfDocument
110
IDfOperation IDfCancelCheckoutOperation IDfCheckinOperation IDfCheckoutOperation IDfCopyOperation IDfDeleteOperation IDfExportOperation IDfImportOperation IDfMoveOperation IDfOperationNode IDfCancelCheckoutNode IDfCheckinNode IDfCheckoutNode IDfCopyNode IDfDeleteNode IDfExportNode IDfImportNode IDfMoveNode
DFC interfaces that are not in the above diagrams are not part of the interface hierarchy. They do not derive from other DFC interfaces, and vice versa.
111
Typed Objects
The IDfTypedObject interface provides the basis for both persistent and nonpersistent types. Here are the main facts about typed objects:
s They have attributes (properties) that you can retrieve and set. s In almost all cases, you obtain them directly or indirectly through a DFC
session; therefore they have a reference to the session that created them.
s A unique object ID identifies them.
The ID of a persistent object uniquely identifies the object in the Docbase. The ID of a non-persistent object, such as a collection or a Docbase map, identifies the object only for the session that creates it. The DFC online reference contains signatures of the methods of DFC interfaces (see Using the DFC Online Reference Documentation on page 2-6). This section describes the general categories of methods of the IdfTypedObject interface. IDfTypedObject is the base object for most DFC objects.
112
Documentum defines the following types for attribute values: Boolean, Integer, String, ID, Time, and Double. The IDfTypedObject methods for setting and getting attribute values reflect these types. For single-valued attributes, call one of the following methods:
boolean getBoolean(String attrName) double getDouble(String attrName) IDfId getId(String attrName) int getInt(String attrName) String getString(String attrName) IDfTime getTime(String attrName) IDfValue getValue(String attrName)
The argument attrName refers to the attribute, such as object_name. Regardless of the type of the attribute, you can call getString to retrieve the value in the form of a string. If you call a get method that is inappropriate for the type of the attribute, for example, getInt("object_name"), DFC attempts to convert the value to that type. To set the value of a single-valued attribute, call one of the following methods, where attrName is the name of the attribute and value is the value you want to assign to that attribute:
void void void void void void void setBoolean(String attrName, boolean value) setDouble(String attrName, double value) setId(String attrName, IDfId value) setInt(String attrName, int value) setString(String attrName, String value) setTime(String attrName, IDfTime value) setValue(String attrName, IDfValue value)
There are several sets of methods that relate to repeating attributes. The server maintains an indexed array of values for a repeating attribute. For example, the authors attribute may contain the following values with the specified indexes:
[0] [1] [2] [3] [4] [5] [6] Sleepy Dopey Happy Sneezy Grumpy Doc Bashful
Methods that operate on repeating attributes often take an index, which specifies which value the operation should affect. The descriptions that follow refer to the authors listed above.
113
The set and get methods for repeating attributes are similar to the set and get methods for single-valued attributes:
boolean getRepeatingBoolean(String attrName, int index) double getRepeatingDouble(String attrName, int index) IDfId getRepeatingId(String attrName, int index) int getRepeatingInt(String attrName, int index) String getRepeatingString(String attrName, int index) IDfTime getRepeatingTime(String attrName, int index) IDfValue getRepeatingValue(String attrName, int index) void setRepeatingBoolean( String attrName, int index, void setRepeatingDouble( String attrName, int index, void setRepeatingId( String attrName, int index, void setRepeatingInt( String attrName, int index, void setRepeatingString( String attrName, int index, void setRepeatingTime( String attrName, int index, void setRepeatingValue( String attrName, int index,
boolean value) double value) IDfId value) int value) String value) IDfTime value) IDfValue value)
You can use single-value attribute methods to set/get repeating attributes and repeating-attribute methods to get/set single valued attributes. Single-valued methods always operate on the repeating attribute value at index 0. To use a repeating-attribute method for a single-valued attribute, the index argument must be 0. The call
getAllRepeatingStrings(String attrName, String separator)
returns all values of a repeating attribute as a single string with values delimited by separator, or by a comma if separator is null. For example, given the authors mentioned above,
getAllRepeatingStrings("authors", null)
114
The appendType methods add values to the end of a repeating attributes list of values. For example, to add an eighth dwarf, call
myobj.appendString ("authors", "Burpy")
The insertType methods are similar, but they add the value at the specified index rather than at the end. To make Burpy the fourth dwarf, call
myobj.insertString ("authors", 3, "Burpy")
Generally, appending is more efficient, because insertions can force the server to copy existing values to new index locations. The find methods retrieve the first index at which a specified value appears. For example, findString ("authors", "Happy") returns 2. The remove method deletes the value at the specified index. The truncate method deletes all values from the specified index onward. The removeAll method deletes all values from the specified repeating attribute. The getValueCount method returns the number of values the specified repeating attribute has.
Attribute Information
IDfTypedObject has a number of methods that allow you to get information about the objects attributes:
String dump() int getAttrCount() boolean hasAttr(String attrName) boolean isAttrRepeating(String attrName) int getAttrDataType(String attrName) int findAttrIndex(String attrName) IDfAttr getAttr(int index) Enumeration enumAttrs()
115
The dump method is for debugging. It returns the objects attributes and values in a formatted string. The getAttrCount method returns the number of attributes that the object has. The hasAttr method returns a boolean value indicating whether the objects type has the specified attribute. The isAttrRepeating method returns a boolean value indicating whether the specified attribute is repeating (True) or single (False). The getAttrDataType method returns an integer representing the attributes type (see the DFC online reference for IDfAttr for the possible return values). The attributes of a Documentum object have a column order. The findAttrIndex method returns the column index of the specified attribute. The getAttr and enumAttrs methods provide more detailed information about the specified attribute. The getAttr method returns an IDfAttr object for the attribute at the specified index. An IDfAttr object allows you to get the attributes name and type. IDfAttr also allows you to determine whether an attribute is repeating. If an attribute is of type String, the maximum character length of any value stored in that attribute may be obtained by calling IDfAttrs getLength method. The enumAttrs method returns an enumeration of IDfAttr objects. This enables you to iterate over all of the objects attributes.
Persistent Objects
Persistent objects are at the second level of the DFC interface hierarchy. They are typed objects that reside in the Docbase. The IDfPersistentObject interface inherits from the IDfTypedObject interface, and hence, IDfPersistentObject has all the methods of IDfTypedObject. In addition IDfPeristentObject has the following sets of methods.
116
You can replicate Documentum objects, that is, have them appear in more than one Docbase. The isReplica method returns True if the object is a local replica of an object in a remote Docbase. Every object in the Docbase has an object type. DFC exposes the type through the IDfType interface. To obtain an objects type information, call the getType method.
The save method directs the server to store the local copy of the object into the Docbase. When you create a new Docbase object, others cannot see it until you explicitly call its save method. Saving an existing object fails if your version of the object is older than the object in the Docbase, that is, if the i_vstamp of your version contains a lower number than the i_vstamp of the object in the Docbase. This happens if another user saves changes to the object between the time you obtain a copy and the time you try to save it. You can prevent this from happening by checking out the object before changing it. The destroy method directs the server to remove the object from the Docbase. The isDeleted method tells you whether the object has been destroyed in the current session. This method does not detect deletion by another user or even in another session subsequent to the time that you obtained the local copy. The isNew method returns False if the object has ever been successfully saved in the Docbase. The isDirty method returns True if you have made unsaved changes to the local copy of the object. The fetch method obtains the latest version of the object from the Docbase if and only if the Docbase version has a newer i_vstamp. If the values are the same, the local copy retains any changes you have made.
117
The revert method obtains the latest version of the object from the Docbase unconditionally. The local copy loses any changes you have made to it.
Audit Trail
Auditing enables you to record information about system events and preserve information in an audit trail, which you can then use to track events and generate reports. You choose which events to monitor, and the audit system logs pertinent data, including the time of the event. To support this process, IDfPersistentObject has the signoff method, which creates an audit trail entry of signoff information for an object.
118
Validation Methods
DFC provides the IDfValidator interface, which makes it easy to validate proposed new or changed attribute values against information in the data dictionary. Normally, you need to do this when you interact with a user to obtain the attribute values. A related interface, IDfValueAssistance, supports providing contitional value assistance in the user interface. The following method returns an IDfValidator object for the persistent object:
IDfValidator getValidator()
119
Use these methods only where necessary, that is, to access functionality that is not available via DFC. Calling these methods bypasses built-in support for validation:
String apiGet(String cmd, String args) boolean apiSet(String cmd, String args, String value) boolean apiExec(String cmd, String args)
IDfACL
IDfACL provides the functionality associated with the server type dm_acl. An access control list (ACL), also called a permission set, is the usual server mechanism for controlling who has access to an object. If the Docbase security mode is set to acl, then every sysobject (that is, every object of type dm_sysobject or of a type that derives from dm_sysobject) has an associated ACL that specifies which users that can operate on an object and what they can do. The Documentum eContent Server Fundamentals manual discusses the two kinds of permissions: basic and extended. Chapter 6, Automating Business Rules with DFC contains an extended example of how to use DFC to work with these permissions.
IDfFormat
IDfFormat provides the interface methods for obtaining the attribute information from a dm_format object. A format object contains information about a file format recognized by the server. All content stored in the Docbase has an associated format such as msw8 (Microsoft Word 97 document), pdf (Acrobat PDF document), or html
120
(an HTML file). All sysobjects that have associated content keep the content type in the a_content_type attribute. This value corresponds to a dm_format object. Administrators can create new format objects for formats that the server does not support automatically. Format objects provide the information necessary to open a viewer or editor appropriate to the content type.
IDfType
IDfType provides methods for getting information about a type. IDfType provides the following categories of information.
Basic Attributes
The getName method returns the types namea string like dm_format or dm_document. The getDescription method returns the types user-friendly name from the data dictionary. The user interface uses the user-friendly name. For example, a search dialog box may display the name Format rather than dm_format.
The getSuperName method returns the name of the types parent type, or null if the type has no parent type. For example, if you hold an IDfType reference to the dm_document type, getSuperName returns dm_sysobject.
121
The method getSuperType returns an IDfType reference to the supertype, not just its name. You can call isSubTypeOf to test whether a type is a subtype of another type. For example, if you hold an IDfType reference to the dm_document type, isSubTypeOf("dm_sysobject") returns True. By convention, a type is not a subtype of itself, so isSubTypeOf("dm_document") returns False.
Type Information
Programs typically make use of IDfType objects to get information about the attributes of that type. The type dm_type contains several repeating attributes that describe the attributes of the type. The DFC methods for most of these methods come in two flavors. One takes an index into the array of repeating attributes; the other takes a string specifying the attribute name. The indexed methods are slightly more efficient. The following IDfType methods return type information:
int getTypeAttrCount() String getTypeAttrNameAt(int index) int getTypeAttrDataTypeAt(int index) int getTypeAttrDataType(String attrName) boolean isTypeAttrRepeatingAt(int index) boolean isTypeAttrRepeating(String attrName) int getTypeAttrLengthAt(int index) int getTypeAttrLength(String attrName) int findTypeAttrIndex(String attrName) String getTypeAttrDescriptionAt(int index) String getTypeAttrDescription(String attrName)
The getTypeAttrCount method returns the number of attributes the type has. The method getTypeAttrNameAt returns the attribute name at the specified index. To find an attributes index, call findTypeAttrIndex. The index is 0based. The above get type attribute methods return the type of the attribute. This is one of the following values:
IDfType.DF_BOOLEAN IDfType.DF_INTEGER IDfType.DF_STRING IDfType.DF_ID IDfType.DF_TIME IDfType.DF_DOUBLE IDfType.DF_UNDEFINED
122
The isRepeating methods indicate whether the attribute is repeating. For attributes whose type is DF_STRING, the getTypeAttrLengthAt and getTypeAttrLengthAt methods return the maximum character length of any string that can be stored in that attribute. For attributes of other types, these methods return 0. The get type attribute description methods return attribute descriptions from the data dictionary. This information does not reside in the dm_type object. Recall that IDfType derives from IDfPersistentObject, which, in turn, derives from IDfTypedObject. IDfTypedObject has the following methods:
Enumeration enumAttrs() int findAttrIndex(String attrName) IDfAttr getAttr(int index) int getAttrCount() int getAttrDataType(String attrName) boolean hasAttr(String attrName) isAttrRepeating(String attrName)
Developers often find this confusing. Calling these methods on an IDfType object returns information about the attributes of the type dm_type, not the type that the IDfType object describes. For example, suppose that the IDfType object named doctype describes the type dm_document. The method doctype.getAttrCount returns 15, even though dm_document has almost 70 attributes. The reason is that getAttrCount returns the number of attributes that dm_type has, not the number of attributes that dm_document has. To get the number attributes for dm_document, call
doctype.getTypeAttrCount
Similarly, if you call doctype.getAttrDataType("object_name"), DFC throws an exception, because dm_type does not have an attribute called "object_name". To discover the type of the dm_document attribute object_name, call getTypeAttrDataType("object_name"). All IDfType methods that return attribute information about the type that the IDfType object describes have method names that begin with getTypeAttr. The methods inherited from IDfTypedObject return information about dm_type.
123
Types that need any of these capabilities derive from dm_sysobject. Since the primary focus of Docbases is content, most objects in the Docbase are either sysobjects or objects whose type derives from dm_sysobject.
Checking Sysobjects In and Out on page 4-7 contains examples of how to check objects out of and into a Docbase and how to cancel a checkout.
s Content-Related
The eContent Server Fundamentals manual discusses content, renditions, and file formats.
s Versioning
Documentum provides implicit versions, major and minor version changes, version labels, and branching. Working With Sysobject Versions on page 4-11 contains examples of how to use DFC to work with versions.
124
s Security
Documentum provides two kinds of permissions: basic and extended. A user can have one basic permission level, and each basic permission level includes the capabilities of all of the lower levels. Users can also have any combination of the extended permissions. Using Private ACLs on page 6-5 and ACL Utility Methods on page 6-7 contain examples of how to use DFC to work with basic and extended permissions.
s Folder-Related
Documentum provides folder and cabinet objects to organize the contents of a Docbase. All sysobjects and sysobject subtypes (except cabinets) must reside in a cabinet or in a folder.
s Virtual Document
A virtual document is a compound document whose components are either simple documents or other virtual documents. The content that users see is the content files associated with these components. A virtual document can also have its own associated content file (or files). The components of virtual documents can have a mixture of formats.
s Business Policy
Business policies are also known as document lifecycles (DLCs). The Documentum eContent Server Fundamentals manual explains how DLCs work.
125
The dm_cabinet type has an attribute is_private, which is not an attribute of dm_folder. To retrieve this value, call the getBoolean method inherited from IDfTypedObject. For example,
boolean bIsPrivate = myCabinet.getBoolean("is_private");
Folders and cabinets do not usually have associated content. They derive from IDfSysObject because folders use the ACL security mechanism. The preceding sections discuss all of the interfaces in Figure 1-1, except for IDfDocbaseMap and IDfCollection. Discussion of those interfaces follows the discussion of the IDfSession and IDfClient interfaces.
IDfSession
All interaction with a Docbase occurs in a session, that is, using an IDfSession object. In broad terms, a session:
s Uses the underlying DMCL library to maintain a connection to a Docbase. s Maintains the state of the interaction between an application and the
Docbase.
s Caches information to increase performance.
A session keeps track of the objects you fetch and change. It provides explicit and implicit transaction support. The underlying DMCL does most of this, but DFC also caches some information and maintains some state.
s Provides service methods for creating and fetching objects, performing
administrative tasks, and obtaining session information. An IDfSession provides the following categories of functionality.
Provide Information
The following methods ask for information that the session has access to:
IDfClient getClient(); IDfLoginInfo getLoginInfo() String getDBMSName() String getDMCLSessionId() String getDocbaseId() String getDocbaseName() String getDocbaseOwnerName()
126
String getLoginUserName() String getSecurityMode() String getServerVersion() String getSessionId() boolean isACLDocbase() boolean isAdopted() boolean isConnected() boolean isRemote() boolean isShared()
Note: be careful not to write getRDBMSName for getDBMSName. The version without the Ris correct.
The short answer is that all persistent objects reside in the Docbase, so you can create or fetch them only through a session. DFC Programming on page 1-2 discusses this point in more detail. The getObject methods return IDfPersistentObject interfaces, because IDfPersistentObject is the most derived interface that is general to all of the possible return types. For example, getObject could return an IDfType, an IDfUser, an IDfDocument, or an IDfFolder (among other possibilities). The only interfaces common to those types are IDfTypedObject and IDfPersistentObject. IDfPersistentObject is the more derived. The effect of this is that Java code must provide an explicit cast. For example
IDfFormat format = (IDfFormat) mysession.getObjectByQualification ("dm_format where name = 'tex');
The following methods support creating objects and obtaining object references:
int getDefaultACL() IDfACL getACL(String aclDomain, String aclName) IDfFolder getFolderByPath(String folderPath) IDfFormat getFormat(String formatName) IDfGroup getGroup(String groupName) IDfId getIdByQualification(String qualification) IDfPersistentObject getObject(IDfId objectId) IDfPersistentObject getObjectByPath(String objectPath) IDfPersistentObject getObjectByQualification( String qualification)
127
IDfPersistentObject getObjectWithType( IDfId objectId, String objType, String className) DfPersistentObject newObject(String typeName) DfPersistentObject newObjectWithType( String typeName, String className) DfType getType(String typeName) DfTypedObject getTypeDescription( String typeName, String attribute, IDfId businessPolicyId, String state) DfUser getUser(String userName) DfUser getUserByOSName( String userOSName, String userOSDomain)
Configuration Information
The eContent Server documentation discusses configuration objects (see the sections dealing with apiconfig, sessionconfig, and serverconfig). The IDfClient interface provides the following methods. They return typed objects, because they return configuration information, not Docbase objects.
IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject getClientConfig() throws DfException; getConnectionConfig() getDocbaseConfig() getDocbrokerMap() getServerConfig() getServerMap(String DocbaseName) getSessionConfig()
Transaction Support
The following are the basic methods for managing transactions:
void abortTrans() void beginTrans() void commitTrans()
Docbase Scope
Docbase scope tells the server which Docbase a method applies to. In many cases this does not change; in other cases, the server can determine it by examining a method argument that conveys the scope implicitly. For example, if one of the methods arguments is an object ID, the server can determine the Docbase scope from the ID.
128
The following are the basic methods for managing Docbase scope when necessary:
String getDocbaseScope() String setDocbaseScope(String DocbaseName) String setDocbaseScopeById(IDfId objectId)
Multithreading Support
If more than one thread can access a session, you must take care to lock and unlock the session before using it. The following IDfSession methods provide this capability:
boolean lock(int timeoutInMsec); boolean unlock();
You can lock the session explicitly (calling a method of IDfSession) or implicitly (calling a method of IDfPersistentObject, because persistent objects hold a reference to a session). Generally, you should lock and unlock blocks of code. If you lock and unlock a session at too fine a granularity, performance suffers and you increase the chance of making a mistake. If you lock too big a chunk of code, you cause other threads to wait needlessly, also hurting performance. DFC does not enforce the locking mechanism on sessions, so a multithreaded application must be careful to lock and unlock the session. Failure to do so can cause crashes. The need to protect a session against concurrent access applies to both shared sessions and private sessions (sessions obtained through the newSession call), but you must be especially careful if you share sessions across components in a multithreaded environment. You dont need to lock and unlock a session if only one thread at a time can use it. Tip: In Java you can use the finally statement to ensure that a thread releases its lock when it dies. Tip: Lock sessions during transactions to prevent synchronization problems.
API Calls
Occasionally, an application needs to interact directly with the sessions underlying DMCL programs in ways for which DFC does not provide interfaces. The following routines allow such interactions:
129
ByteArrayInputStream apiGetBytes( String cmd, String args, String buf, String buflen, int length) IDfCollection apply( String objId, String functionName, IDfList args, IDfList dataType, IDfList values) IDfCollection getLastCollection() IDfList apiDesc(String api) String apiGet(String cmd, String args) String describe(String type, String objType) String getMessage(int severityLevel) boolean apiExec(String cmd, String args) boolean apiSet(String cmd, String args, String value) boolean apiSetBytes( String cmd, String args, ByteArrayOutputStream content) void traceDMCL(int level, String traceFile)
Administration
The following methods support system administration:
IDfId archive( String predicate, String operatorName, int priority, boolean sendMail, IDfTime dueDate)
130
IDfId restore( String predicate, String dumpFile, String operatorName, int priority, boolean sendMail, IDfTime dueDate) void changePassword(String oldPasswd, String newPasswd) void reInit(String serverConfigName) void reStart(String serverConfigName, boolean restartClient) void shutdown(boolean immediate, boolean deleteEntry)
Session State
The following methods enable you to control certain aspects of the session:
void void void void void disconnect() flush(String flushType, String cacheKey) flushCache(boolean discardChanged) purgeLocalFiles() setBatchHint(int batchSize)
Miscellaneous
IDfRelationType getRelationType(String relationName) IDfVersionTreeLabels getVersionTreeLabels(IDfId chronicleId) String getLoginTicket()
IDfClient
Most DFC programs start by obtaining an object that implements the IDfClient interface, through a call like the following:
IDfClient client = DfClient.getLocalClient();
The IDfClient object loads the DMCL shared library. Its main function is to create and share sessions, but programs also use IDfClient to get information about the available Docbases and to obtain certain DMCL configuration information. IDfClient also enables client programs to cache information.
131
IDfSession newSession( String DocbaseName, IDfLoginInfo loginInfo) IDfSession getSharedSession( String DocbaseName, IDfLoginInfo loginInfo, String key) IDfSession adoptDMCLSession(String dmclSessionId) void unadoptDMCLSession(String dmclSessionId) Enumeration enumSharedSessions(String key) IDfSession findSession(String dfcSessionId)
The methods for creating a new session (newSession and getSharedSession) take an IDfLoginInfo object as an argument. An IDfLoginInfo object carries the user name, the password, and, optionally, the domain name. The sample code inconnectToDocbase in Java on page 3-2 shows how to use IDfLoginInfo. Shared sessions enable the components of a DFC application to share a DFC session. The getSharedSession method uses a key known to all components that share the session. Internally, DFC checks whether it has already created a session for the same Docbase, the same login information, and same key. If it has, it returns that session. Otherwise, it creates a new session. Sharing sessions saves resources on both the client and the server sides. The getSharedSession method does not allow sharing sessions among users. It is for sharing sessions across components accessed by the same user for the same Docbase in the same application. The method newSession always creates a new session. Applications should call newSession if they do not intend to share sessions across components. The method adoptDMCLSession is intended for integrating with legacy applications that use DMCL. This method takes the identifier for a session created by a DMCL connect call (s0, for example) and wraps the underlying session as a DFC session so DFC code can use it. If you adopt a session, you must call unadoptDMCLSession when you finished with the session. Do not call the close method of IDfSession. The DFC online reference contains detailed information about the enumSharedSessions and findSession methods.
132
interface provides methods for getting the number of Docbases in the list, the name of the Docbase at a specified index, a description of the Docbase at the specified index, and the version of the server at the specified index. IDfClient also provides methods for obtaining a docbroker map (the list of docbrokers that you can access) and a server map (the servers that you can access). It returns these maps as IDfTypedObjects. Typical client applications do not need these maps. The server documentation provides more information about them under the headings Docbroker Locator and Server Locator. The examples in Using a Docbase Map on page 3-5 show how to work with Docbase maps. IDfClient allows you to obtain information about your general client configuration through the getClientConfig method. This client configuration object maps to the API Config object discussed in the server documentation. Through this object you can dynamically configure such things as your Docbroker, the maximum number of simultaneous sessions allowed, and the maximum number of open collections allowed. You should alter the default values only after reading the server administration documentation.
Service Methods
The IDfClient object provides an IDfProperties object for caching and sharing information within your application. An IDfProperties object is an object that allows you to store name-value pairs. The method
getContext(String contextId)
returns the properties object for the specified ID or creates a new one if one does not already exist. The method
removeContext(String contextId)
removes the specified properties object. Some applications share data within a session by using this object. In this case, they typically use the session ID returned by the IDfSession method getSessionId as the context ID. You should not use the DMCL session ID (for example, s0) for this purpose. Applications should be careful to remove the properties object associated with a session when they no longer use that session.
133
Common Package
The com.documentum.fc.common package contains interfaces that client programs sometimes find useful. DFC wraps IDs and Time values in IDfId and IDfTime objects. To get an ID as a string you can call either getId or toString (they return the same thing). IDfTime objects allow you to perform time format conversions. Both the IDfId and IDfTime interfaces provide convenience methods. The getValue method returns an IDfValue object, which contains not only the attributes value, but also its type. IDfValue objects are convenient when you need to store an attribute value as an object (such as inserting it into a Java hashtable), but later need to determine its type as well as its value. Avoid calling getValue if you can, because creating an additional object and obtaining and storing the type information are needless overhead if you dont use those features.
Queries
DFC provides an easy-to-use mechanism for querying the Docbase and processing the query results.You use a query object to submit the query, and receive the results in a collection object.
To query the Docbase and process the results: Obtain an IDfClient interface by calling DfClient.getLocalClient. Create a session, sess, by calling newSession or getSharedSession on the IDfClient object. Obtain an IDfQuery object, query:
s For Java-based DFC programs, call new DfQuery.
1. 2. 3.
134
s For Visual Basic and C++ programs, call the getQuery method of
IDfClientX. 4. 5. 6. Create a DQL query as a text string, dq. Call query.setDQL(dq) to set the DQL string into the query object. Call query.execute(sess, querytype) to execute the query. The arguments of the execute method include a session reference, because the query is not tied to the session, and a code for the type of query to execute. The method returns an IDfCollection, col. 7. Iterate through the IDfCollection by calling col.next() until it returns False. Obtain values from an IDfCollection by calling the various get methods of IDfTypedObject (the parent type of IDfCollection). For example, if you know that attribute 0 of the object at the current row of the collection is a string, the following code prints it:
IDfAttr attr = col.getAttr(0) System.out.println(typedObj.getString(attr.getName()))
If you dont know that the attribute is a string, you can find out what it is by calling
attr.getDataType()
and changing the second line above according to what getDataType returns. 8. Close the IDfCollection and IDfSession objects. IDfQuery has no close method, because a query object is not tied to a session. Be careful to close open collections and sessions even in the event of an exception. The best place for a Java program to call close is in a finally block, because Java executes a finally block whether there is an exception or not.
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.
135
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 (if the collection is empty, the first call to next returns False). Note: An IDfCollection is a typed object. You access the current rows data by calling the IDfTypedObject methods getBoolean, getInt, getString, and so forth, as if the collection were the same as its current row. You should not, and do not need, to call the collections getTypedObject method unless you want to save the current row for later use (compare the code in Step 7 on page 1-35, which does not call getTypedObject, with the code in displayResults in Visual Basic on page 5-2, which does call getTypedObject).
136
Using DFC
2
2
This chapter discusses operational issues that arise when you set up and use DFC in your programming environment.
Java
From Java, use the Java interface. Simply add the DFC class and interface files (for example, ...Documentum\DFCre40\lib\dfc.jar) to your CLASSPATH.
Visual Basic
From Visual Basic, the dfc.tlb type library provides access to DFC through COM. Visual Basic hides the details. Interface inheritance requires a workaround if you access DFC from Visual Basic, because the Microsoft Java virtual machine does not support COM interface inheritance. For example, in Java you can use the save method that a SysObject inherits from a PersistentObject.
//Java IDfSysObject sysobj = session.newObject("dm_document"); sysobj.setObjectName("test"); sysobj.save();
21
Using DFC
Using DFC From Application Programs
In Visual Basic, however, you must assign the IDfSysObject object to an IDfPersistentObject object before calling its save method:
'Visual Basic Dim sysobj As IDfSysObject Dim pobj As IDfPersistentObject Set sysobj = session.newObject("dm_document") sysobj.setObjectName ("test") set pobj = sysobj pobj.save
C++
From C++, use COM directly, or you can use classes, called wrapper classes, that Documentum provides to hide some of the complexities of the COM interface. To use these classes with Microsofts MFC, include the following files in your Visual C++ project: DfClientX.h, DfClientX.cpp, dfc.h, and dfc_i.c If you dont use MFC or if you wish to write your own wrapper classes, include only dfc.h and dfc_i.c. Note: Interface inheritance requires a workaround if you access DFC from C++, because the Microsoft Java virtual machine does not support COM interface inheritance. See the Visual Basic example in the previous section. Follow these rules for objects and pointers:
s Always assign a DFC object to a new pointer.
First delete the old pointer, then create a new CDfSysObject, as in the following C++ example:
//Get a DFC object CDfSysObject sobj1 = session.getObject(id); CDfSysObject *pSysObj = null; //Delete the old pointer if (pSysObj) delete pSysObj; //Create new CDfSysObject pSysObj = new CDfSysObject(sobj1);
22
Using DFC
Creating DFC Client Objects
s A procedure that returns a DFC object should return a pointer to the object,
Syntax Differences
COM and Java give you access to the same DFC classes and interfaces, but COM datatypes differ slightly from Java datatypes. Table 2-1 shows the COM equivalents of DFC datatypes. Table 2-1 Equivalents for DFC Datatypes
Java (DFC datatype) boolean int String double IDfinterfacename Visual Basic (and Docbasic) Boolean Long String Double C++ with MFC wrapper classes BOOL long CString double C++ directly to COM VARIANT_BOOL int BSTR double IDfinterfacename
Perform the following steps before calling DFC methods: Create a DFC client object as an interface to DFC. The DFC client object must reside in the same process as the Documentum client library, DMCL. DFC client objects are also called local DFC clients. Java and COM use different interfaces to create the DFC client object, as shown in the examples.
1.
23
Using DFC
Creating a DFC Session
2.
Provide login information and establish a DFC session (refer to Creating a DFC Session on page 2-4).
Java Example
Use the DfClient.getLocalClient static method.
IDfClient myclient = DfClient.getLocalClient();
This line of code creates an interface, myclient, to a local DFC client object. The interface provides access to the methods and data in the DFC client object. Call the objects methods through the interface.
COM Example
IDfClientX creates DFC objects in COM development environments. You must instantiate an IDfClientX object before you can create DFC objects. Use the IDfClientX interfaces getLocalClient static method. The following example demonstrates how to create a DFC client object in Visual Basic.
Dim Dim Set Set myclient myclientx myclientX myclient As IDfClient As DfClientX = CreateObject(Documentum.Dfc) = myclientX.getLocalClient
24
Using DFC
Using DFC Tracing
Shared Sessions
If you ask for a shared session, DFC returns an existing one or creates a new one for you. Using shared sessions decreases the number of sessions you must connect and disconnect yourself. To establish a shared session, you must specify a session key. For security reasons, there is no DFC method to retrieve this key, so you must save it if you need to use it again. To use a specific shared session, you must know its key.
Adopted Sessions
To create an adopted session, DFC uses the ID of an existing DMCL session, that is, a session established by a direct call to the connect method. When migrating pre-DFC customizations, you may find adopted sessions convenient. Otherwise, Documentum recommends establishing sessions through DFC. To prevent synchronization problems, DFC allows a DMCL session to be adopted only once. Adopted sessions cannot be shared. Note: You cannot disconnect an adopted session through DFC. After you unadopt an adopted session with the DFC unadopt method, you must use the disconnect server API to disconnect the underlying DMCL session.
Visual Basic programs can access the same methods through the IDfClientX interface. Trace levels are 0 to turn off tracing or an integer from 1 to 10. Higher levels provide more detailed tracing. If you dont set a trace file, the information goes to the standard output. Because static methods implement tracing, the facility is independent of specific objects or sessions.
25
Using DFC
Using the DFC Online Reference Documentation
To find the interface that provides a specified operation: If you wish to operate on an object in the Docbase, determine the most general interface that should support the operation, and look there. For example, you can save any persistent object, so look for a save method in IDfPersistentObject. If the functionality involves content, security, versioning, or checkout/ checkin, look at IDfSysObject or interfaces derived from it.
1.
2.
If you wish to create an object, obtain a reference to an object, or perform a general operation, a. If the operation depends on having a session, look in IDfSession. b. Otherwise, look in IDfClient.
26
3
3
This chapter describes the way to work with DFC sessions and a Docbase map. The examples in it are based on the classes DfExSession and DfExDocbaseMap, which are available in Java and Visual Basic versions on the distribution CD. The chapter contains the following main sections:
s Connecting and Disconnecting on page 3-1 s Using a Docbase Map on page 3-5
in the Visual Basic version both assume that the corresponding mechanism returns a valid user name. The code that establishes the session is
sess = client.newSession(docbase, li);
31
in the Visual Basic version. In either case, the call can produce a DfException. The Java code uses a try block followed by a catch statement to handle this exception. The visual Basic code uses an On Error statement and an error handling section to accomplish the same thing.
connectToDocbase in Java
//Connect to the Docbase. IDfSession connectToDocbase() throws IOException { IDfSession sess = null; String docbase = null; try { //Get local client object that calls into DMCL40 to connect //to Documentum servers - this is the entrance to DFC IDfClient client = DfClient.getLocalClient(); //Set up login credentials. IDfLoginInfo li = new DfLoginInfo(); //Assume user has entered user name, password, //and Docbase via DfExUtils li.setUser(DfExUtils.gUsername); li.setPassword(DfExUtils.gPassword); docbase = DfExUtils.gDocbase; sess = client.newSession(docbase, li); if(sess.isConnected()) { System.out.println("\nConnected"); } } catch(DfException dfe) { System.out.println("\n" + dfe.toString()); } return sess; } //Connect to docbase
disconnectFromDocbase in Java
boolean disconnectFromDocbase(IDfSession sess) { boolean retVal = false; try { if(sess.isConnected()) { //If session is connected sess.disconnect(); // Disconnect if(!sess.isConnected()) { // If disconnect succeeded retVal = true; // Report success } else { // If disconnect failed //ERROR ACTION // Take error action } } else { //If session not connected //ERROR ACTION // Take error action
32
displaySessionInfo in Java
//Display details about the active session. void displaySessionInfo(IDfSession s) { try { System.out.println("\nDocbase : " + s.getDocbaseName()); System.out.println("Srvr Vers : " + s.getServerVersion()); System.out.println("DBMS : " + s.getDBMSName()); System.out.println("Owner : " + s.getDocbaseOwnerName()); System.out.println("Sess Id : " + s.getSessionId()); System.out.println("DMCL Sess Id: " + s.getDMCLSessionId()); System.out.println("Docbase Id : " + s.getDocbaseId()); System.out.println("Scope : " + s.getDocbaseScope()); System.out.println("User : " + s.getLoginUserName()); System.out.println("Login Ticket: " + s.getLoginTicket()); System.out.println("Security : " + s.getSecurityMode()); } catch(DfException dfe) { System.out.println("\n" + dfe.toString()); } }
'Get client object 'Get login info object 'Assume username, 'password,domain, 'and Docbase 'from DfExMainForm
'Establish the session Set sess = client.newSession(DfExMainForm.cbxDocbase.Text, li) End If Set connectToDocbase = sess Exit Function ErrorHandler: writeDiagnostic Err.Description, False End Function
33
disconnectFromDocbase = retVal Exit Function ErrorHandler: writeDiagnostic Err.Description, False End Function
34
displayDocbaseInfo in Java
void displayDocbaseInfo(IDfDocbaseMap m, int idx){ try { System.out.println("Docbase: " + m.getDocbaseName(idx)); System.out.println("Descrip: " + m.getDocbaseDescription(idx)); System.out.println("Id : " + m.getDocbaseId(idx)); System.out.println("Server : " + m.getServerVersion(idx)); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
35
for (int i = 0; i < m.getDocbaseCount(); i++) { exDbMap.displayDocbaseInfo(m, i); // Display details exDbMap.connectToDocbase(m, i); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
36
4
4
This chapter describes the way to manipulate Docbase objects. The examples in it are based on the classes DfExCreate, DfExCheckinCheckout, DfExDestroy, and DfExVersionPolicy, which are available in Java and Visual Basic versions on the distribution CD. The chapter contains the following main sections:
s Creating and Destroying on page 4-1 s Checking Sysobjects In and Out on page 4-7 s Working With Sysobject Versions on page 4-11
41
42
writeDiagnostic "Subject: " + sysObj.getSubject, writeDiagnostic "Content type: " + sysObj.getContentType, Exit Sub ErrorHandler: writeDiagnostic Err.Description, False End Sub
False False
Dim verString As String 'Display version labels verString = "" For i = 0 To (sysObj.getVersionLabelCount - 1) If i = 0 Then verString = verString + sysObj.getVersionLabel(i) Else verString = verString + ", " + sysObj.getVersionLabel(i) End If Next i writeDiagnostic verString, False If version = "DESTROYCURRENT" Then Set pObj = sysObj pObj.destroy Else sysObj.destroyAllVersions End If If Not pObj.isDeleted Then 'ERROR ACTION End If Set sysObj = Nothing Set IDfId = Nothing Exit Sub ErrorHandler: writeDiagnostic Err.Description, False End Sub 'If call specifies current ' Make it persistent, ' then destroy it 'Otherwise ' Destroy all versions 'If object still exists ' Take error action 'Release memory
43
As As
dqlStatement = createDQLStatement(typeName, supertypeName, lstAttrs) Set exQuery = New DfExSimpleQuery exQuery.execQuery sess, dqlStatement Set exQuery = Nothing Exit Sub ErrorHandler: writeDiagnostic Err.Description, False End Sub
createDQLStatement = "" If lstAttrs.ListCount > 0 Then For i = 0 To (lstAttrs.ListCount - 1) If Not attrDefs = "" Then attrDefs = attrDefs + "," + lstAttrs.List(i) Else attrDefs = lstAttrs.List(i) End If Next i End If
dqlStatement = "CREATE TYPE " + typeName 'Construct statement If Not attrDefs = "" Then dqlStatement = dqlStatement + " (" + attrDefs + ")" End If dqlStatement = dqlStatement + " WITH SUPERTYPE " + superName createDQLStatement = dqlStatement Exit Function ErrorHandler: writeDiagnostic Err.Description, False End Function
44
createCabinet in Java
void createCabinet(IDfSession sess) throws IOException { try { IDfSysObject sysObj = (IDfSysObject)sess.newObject("dm_cabinet"); sysObj.setObjectName("SampleCabinet"); sysObj.setSubject("Sample Cabinet"); sysObj.save(); displayObjectInfo(sysObj); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
createFolder in Java
void createFolder(IDfSession sess) throws IOException { try { IDfSysObject sysObj = (IDfSysObject)sess.newObject("dm_folder"); sysObj.setObjectName("SampleFolder"); sysObj.setSubject("DFC example folder"); sysObj.link("SampleParent"); sysObj.save(); displayObjectInfo(sysObj); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
//Create folder obj //Set attributes //Assume it exists //Save //Display details
createDocument in Java
void createDocument(IDfSession sess) throws IOException try { IDfSysObject sysObj = (IDfSysObject)sess.newObject("dm_document"); sysObj.setObjectName("SampleDoc"); sysObj.setSubject("Sample document"); sysObj.setContentType("crtext"); sysObj.setTitle("Sample Document"); sysObj.setFile("C:\test.txt"); sysObj.link("SampleCabinet"); sysObj.save(); displayObjectInfo(sysObj); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } } { //Create document obj //Set attributes
45
displayObjectInfo in Java
void displayObjectInfo(IDfSysObject Obj) { try { System.out.println("\tID : " + Obj.getObjectId().getId()); System.out.println("\tName : " + Obj.getObjectName()); System.out.println("\tOwner : " + Obj.getOwnerName()); System.out.println("\tCreated : " + Obj.getCreationDate()); System.out.println("\tSubject : " + Obj.getSubject()); System.out.println("\tContent : " + Obj.getContentType()); } catch (Exception e) { System.out.println("\n" + e.toString()); } }
destroyObject in Java
void destroyObject(IDfSession sess, String objId, String version) throws IOException { try { IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); //objId --> IDfId obj //Get the object
//Display version labels for (int i = 0; i < sysObj.getVersionLabelCount(); i++) { System.out.println(sysObj.getVersionLabel(i)); } if (version == "A") { //If call specifies "A" sysObj.destroyAllVersions(); // Destroy all versions } else if (version == "C") { //If "C" sysObj.destroy(); // Destroy current } //Otherwise, do nothing } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
createType in Java
void createType( IDfSession sess, String typeName, String superName, String attrDefs ) { //Session //Name of the new type //Supertype //Attribute definitions
try { String dqlStatement = createDQLStatement(); DfExSimpleQuery exQuery = new DfExSimpleQuery(); exQuery.execQuery(sess, dqlStatement); } catch (Exception e) { System.out.println("\n" + e.toString()); } }
46
createDQLStatement in Java
//Return a create type statement in the form: // CREATE TYPE typeName (attr_name datatype, ...) with supertype superName String createDQLStatement( String typeName, //Name of the new type String superName, //Supertype String attrDefs //Attribute definitions ) throws IOException { //Construct the DQL statement String dqlStatement = "CREATE TYPE " + typeName; if (attrDefs != null) { dqlStatement = dqlStatement + " (" + attrDefs + ")"; } dqlStatement = dqlStatement + " WITH SUPERTYPE " + superName; return dqlStatement; }
47
If sysObj.isCheckedOut Then writeDiagnostic "Version: CURRENT, " + sysObj.getVersionPolicy.getNextMinorLabel, False sysObj.setFile sysObj.getObjectName Set newSysObjId = sysObj.checkin(False, "") writeDiagnostic "Checked in: " + newSysObjId.getId, False removeLocalFile sysObj checkInObject = True Else 'ERROR ACTION End If Set sysObjId = Set sysObj = Nothing Nothing
' Get the file ' Check in as default version ' Display ID ' Remove local file 'If not checked out ' Take error action 'Release memory
48
Set newSysObjId = Nothing Exit Function ErrorHandler: writeDiagnostic Err.Description, False End Function
Shell "NOTEPAD.EXE " + 'Call editing program sysObj.getObjectName, vbNormalFocus editFile = True Set sysObjId = Nothing Set sysObj = Nothing Exit Function ErrorHandler: writeDiagnostic Err.Description, False End Function 'Release memory
checkOutObject in Java
boolean checkOutObject(IDfSession sess, String objId) { boolean retVal = false; try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId);
49
if (sysObj.isCheckedOut()) { //ERROR ACTION } else { sysObj.checkout(); sysObj.getFile(sysObj.getObjectName()); retVal = true; } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } return retVal; }
//If object checked out // Take error action //If not checked out // Lock it // Get local copy
cancelCheckout in Java
void cancelCheckout(IDfSession sess, String objId) throws IOException { try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId); if (sysObj.isCheckedOut()) { //If object checked out sysObj.cancelCheckout(); // Cancel checkout removeLocalFile(sysObj); // Delete local copy } else { //If not checked out //ERROR ACTION // Handle error } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
checkInObject in Java
void checkInObject(IDfSession sess, String objId) throws IOException { try { IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);
if (sysObj.isCheckedOut()) { //If checked out System.out.println("\nObject version: " + // Show label "CURRENT, " + sysObj.getVersionPolicy().getNextMinorLabel()); sysObj.setFile(sysObj.getObjectName()); // Get local copy IDfId newSysObjId = sysObj.checkin(false, ""); // Check in as // default version removeLocalFile(sysObj); // Delete local file } else { //If not checked out //ERROR ACTION // Handle error } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
410
removeLocalFile in Java
void removeLocalFile(IDfSysObject sysObj) throws IOException { try { IDfFile f = new DfFile(sysObj.getObjectName()); f.deleteFile(); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
editFile in Java
void editFile(IDfSession sess, String objId) throws IOException { try { IDfId sysObjId = new DfId(objId); //Create IDfId object IDfSysObject sysObj = //Create IDfSysObject (IDfSysObject)sess.getObject(sysObjId); //Spawn child process for the editor to run in String editor = /*Obtain name of editor executable*/; Runtime.getRuntime().exec(editor + " " + sysObj.getObjectName()); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
411
if verPolObj.getDefaultCheckinVersion() = DFCLib.IDfVersionPolicy_DF_NEXT_MAJOR Then writeDiagnostic "Default label: DF_NEXT_MAJOR", False ElseIf verPolObj.getDefaultCheckinVersion = DFCLib.IDfVersionPolicy_DF_NEXT_MINOR Then writeDiagnostic "Default label: DF_NEXT_MINOR", False ElseIf verPolObj.getDefaultCheckinVersion = DFCLib.IDfVersionPolicy_DF_SAME_VERSION Then writeDiagnostic "Default label: DF_SAME_VERSION", False ElseIf verPolObj.getDefaultCheckinVersion = DFCLib.IDfVersionPolicy_DF_BRANCH_VERSION Then writeDiagnostic "Default label: DF_BRANCH_VERSION", False End If writeDiagnostic "Label: " + verPolObj.getBranchLabel, False writeDiagnostic "Summ: " + verPolObj.getVersionSummary("; "), False writeDiagnostic "Comnt: " + verPolObj.getLogComment, False 'Free memory Set sysObjId = Set sysObj = Set verPolObj = Exit Sub ErrorHandler: writeDiagnostic End Sub Nothing Nothing Nothing Err.Description, False
Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId) If Not sysObj.isCheckedOut Then sysObj.checkout End If if sysObj.isCheckedOutBy(sess.getLoginUserName) Then sysObj.mark symbolicLabel Set newId = sysObj.checkin(False, "") displayVersionInfo sess, newId.getId Else 'ERROR ACTION End If ' Free memory. Set sysObjId = Nothing Set sysObj = Nothing
412
Set newId = Nothing Exit Sub ErrorHandler: writeDiagnostic "\n" + Err.Description, False End Sub
displayVersionInfo in Java
//Display version info for an object void displayVersionInfo(IDfSession sess, String objId) { try { //Get ID, then corresponding sysobject, then version policy object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); IDfVersionPolicy verPolObj = sysObj.getVersionPolicy(); //Display version label details about the sysobject System.out.println("Version : " + verPolObj.getSameLabel()); System.out.println("Nxt minor: " + verPolObj.getNextMinorLabel()); System.out.println("Nxt major: " + verPolObj.getNextMajorLabel()); if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_NEXT_MAJOR) { System.out.println("Default label : DF_NEXT_MAJOR"); } else if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_NEXT_MINOR) { System.out.println("Default label : DF_NEXT_MINOR"); } else if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_SAME_VERSION) { System.out.println("Default label : DF_SAME_VERSION"); } else if (verPolObj.getDefaultCheckinVersion() == verPolObj.DF_BRANCH_VERSION) { System.out.println("Default label : DF_BRANCH_VERSION"); } System.out.println("Br label : " + verPolObj.getBranchLabel()); System.out.println("Vers summ: " + verPolObj.getVersionSummary(";")); System.out.println("Log cmt : " + verPolObj.getLogComment()); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
changeVersionInfo in Java
//Change the version of an object. void changeVersionInfo(IDfSession sess, String objId) throws IOException { //Obtain the object ID, then the corresponding sysobject try { IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); if (!sysObj.isCheckedOut()) { sysObj.checkout(); } //Check out if // necessary
413
if (sysObj.isCheckedOutBy(sess.getLoginUserName())) { //String symbolicLabel = OBTAIN LABEL FROM USER; sysObj.mark(symbolicLabel); IDfId newId = sysObj.checkin (false, ""); displayVersionInfo(sess, newId.getId()); } else { //ERROR ACTION } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
//If user owns lock // get label // assign it // check in //Otherwise // error action
414
5
5
This chapter describes the way to use DFC to create and perform queries and to process the results. The examples in it are based on the class DfExSimpleQuery, which is available in Java and Visual Basic versions on the distribution CD. You can find out more about queries by examining the DfExFullTextQuery class on the distribution CD. This manual does not contain examples from that class.
Basic Queries
exQuery in Visual Basic
Function execQuery( sess As IDfSession, queryString As String) As IDfCollection Dim clientx As New DfClientX Dim col As IDfCollection Dim q As IDfQuery On Error GoTo ErrorHandler Set execQuery = Nothing Set q = clientx.getQuery q.setDQL queryString Set col = q.execute(sess, DFCLib.IDfQuery_DF_READ_QUERY) Set execQuery = col Exit Function ErrorHandler: writeDiagnostic Err.Description, False 'Initialize return value 'Create query object 'Give it the query string 'Execute the query and get ' back a collection 'Set the return value 'Session 'Query string 'Return a collection
51
End Function
exQuery in Java
IDfCollection execQuery(IDfSession sess, String queryString) { IDfCollection col = null; //For the result try {
52
IDfQuery q = new DfQuery(); q.setDQL(queryString); col = q.execute(sess, DfQuery.DF_READ_QUERY); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } return col; }
displayResults in Java
//Step through a collection and display results void displayResults(IDfCollection col) throws IOException { try { int resItems = 1; while (col.next()) { System.out.println("\nResult row: " + resItems++); for (int i = 0; i < col.getAttrCount(); i++) { IDfAttr attr = col.getAttr(i); System.out.print("\t" + attr.getName() + ": "); if (attr.getDataType() == attr.DM_BOOLEAN) { System.out.println( col.getBoolean(attr.getName())); } else if (attr.getDataType() == attr.DM_DOUBLE) { System.out.println( col.getDouble(attr.getName())); } else if (attr.getDataType() == attr.DM_ID) { System.out.println( col.getId(attr.getName()).toString()); } else if (attr.getDataType() == attr.DM_INTEGER) { System.out.println( col.getInt(attr.getName())); } else if (attr.getDataType() == attr.DM_STRING) { System.out.println( col.getString(attr.getName())); } else if (attr.getDataType() == attr.DM_TIME) { System.out.println( col.getTime(attr.getName()).toString()); } else { //ERROR ACTION } } } col.close(); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
//Count rows //Display row num //For attribute // Display name // Display value // using method // for its type
53
54
6
6
This chapter describes the way to work with Documentum features that help you automate your business rules. The examples in it are based on the classes DfExSimpleValidation andDfExACL, which are available in Java and Visual Basic versions on the distribution CD. The classes DfExBusinessPolicy and DfExWorkflow show other ways to automate business rules. This manual does not contain examples from those classes. The chapter contains the following main sections:
s Checking Objects Against Validation Rules on page 6-1 s Changing Permissions on page 6-2 s Using Private ACLs on page 6-5 s ACL Utility Methods on page 6-7
//Session //ID of the object to validate //Attribute to validate (null or "" = perform both // object level and attribute level validation) throws DfValidationException, IOException { try { IDfId objId = new DfId(objIdStr); IDfPersistentObject perObj = sess.getObject(objId); IDfValidator validator = perObj.getValidator(); IDfType type = perObj.getType();
61
if (attrName == null || attrName.equals("")) { validator.validateAll(null, false); } else { if (type.findTypeAttrIndex(attrName) < 0) { //ERROR ACTION return; } // validate the value of the specific attribute validator.validateAttrRules(attrName, null, null); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
Changing Permissions
changeBasicPermissions in Visual Basic
'Change and display object permissions Sub changeBasicPermissions( sess As IDfSession, 'Session objId As String, 'ID of obj for which to change permissions anotherUser As String) 'A user to whom to assign permissions Dim Dim Dim Dim clientx sysObjId sysObj pObj As New DfClientX As IDfId As IDfSysObject As IDfPersistentObject
On Error GoTo ErrorHandler 'Use ID string to obtain the ID, then the object Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId) displayBasicPermissions sysObj sysObj.grant anotherUser, 6, "" sysObj.grant "dm_world", 6, "" Set pObj = sysObj pObj.save displayBasicPermissions sysObj sysObj.revoke anotherUser, "" sysObj.grant "dm_world", 3, "" Set pObj = sysObj pObj.save displayBasicPermissions sysObj Set sysObjId = Nothing 'Display the object's permissions 'Grant the user and dm_world ' WRITE permission 'Make the object persistent ' then save it 'Display the object's permission 'Revoke the user's permissions 'Grant dm_world READ permission 'Make the object persistent ' then save it 'Display the object's permission 'Free memory
62
Set sysObj =
Nothing
'Use ID string to obtain the ID, then the object Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId) displayExtendedPermissions sysObj sysObj.grant anotherUser, 6, "CHANGE_STATE" Set pObj = sysObj pObj.save displayExtendedPermissions sysObj sysObj.revoke anotherUser, "CHANGE_STATE" sysObj.revoke anotherUser, "" Set pObj = sysObj pObj.save displayExtendedPermissions sysObj Set sysObjId = Nothing Set sysObj = Nothing Exit Sub ErrorHandler: writeDiagnostic Err.Description, False End Sub 'Make the object persistent ' then save it 'Display the ext permissions 'Free memory 'Display the ext permissions 'Grant WRITE and CHANGE_STATE 'Make the object persistent ' then save it 'Display the ext permissions
changeBasicPermissions in Java
//Change and display object permissions void changeBasicPermissions( IDfSession sess, //Session String objId, //ID of obj for which to change permissions String anotherUser) //A user to whom to assign permissions
63
throws IOException { try { //Use ID string to obtain the ID, then the object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); displayBasicPermissions(sysObj); //Display the object's permissions
//Grant the user and dm_world WRITE permission sysObj.grant( anotherUser, 6, ""); sysObj.grant("dm_world", 6, ""); sysObj.save(); displayBasicPermissions(sysObj); //Save the object //Display the object's permissions
//Revoke the user's permissions and grant dm_world READ permission sysObj.revoke(anotherUser, ""); sysObj.grant ("dm_world", 3, ""); sysObj.save(); displayBasicPermissions(sysObj); //Save the object //Display the object's permissions
changeExtendedPermissions in Java
//Change and display extended object permissions void changeExtendedPermissions( IDfSession sess, //Session String objId, //ID of obj for which to change permissions String anotherUser) //A user to whom to assign permissions throws IOException { try { //Use ID string to obtain the ID, then the object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); displayExtendedPermissions(sysObj); //Display the ext permissions
//Grant the user WRITE and CHANGE_STATE permissions sysObj.grant(anotherUser, 6, "CHANGE_STATE"); sysObj.save(); displayExtendedPermissions(sysObj); sysObj.revoke(anotherUser, "CHANGE_STATE"); sysObj.revoke(anotherUser, ""); sysObj.save(); displayBasicPermissions(sysObj); } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } } //Save the object //Display the ext permissions //Revoke user's CHANGE_STATE //Revoke user's basic perms //Save the object //Display the ext permissions
64
'Use ID string to obtain the ID, then the object Set sysObjId = clientx.getId(objId) Set sysObj = sess.GetObject(sysObjId) 'Create a new ACL object and give it the specified name Set pObj = sess.newObject("dm_acl") pObj.apiSet "set", "object_name", aclName 'Grant the specifiedpermissions to owner and world pObj.apiExec "grant", "dm_owner," + permission + "," + extPermission pObj.apiExec "grant", "dm_world," + permission + "," + extPermission pObj.save Set oldACL = sysObj.getACL 'Save the new private ACL 'Save the object's current ACL
'Instantiate an instance of the new private ACL Set newACL = sess.getACL(sess.getLoginUserName(), aclName) sysObj.setACL newACL Set pObj = sysObj pObj.save displayBasicPermissions sysObj displayExtendedPermissions sysObj sysObj.setACL oldACL pObj.save displayBasicPermissions sysObj displayExtendedPermissions sysObj Set Set Set Set sysObj = Nothing sysObjId = Nothing oldACL = Nothing newACL = Nothing 'Apply new ACL to the sysobject 'Use persistent obj interface to ' save it with its new ACL 'Display the new permissions 'Apply old ACL to the sysobject 'Save it (pObj & sysObj are the same) 'Display restored permissions 'Free memory
65
privateACLs in Java
//Create a private ACL and apply it to an object void privateACLs( IDfSession sess, //Session String objId //Object with which to associate the ACL String permission, //Permission to grant to world and owner String extPermission, //Ext permissions to grant world and owner String aclName //Name of ACL to create ) throws IOException { try { //Use ID string to obtain the ID, then the object IDfId sysObjId = new DfId(objId); IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId); //Create a new ACL object and give it the specified name IDfPersistentObject pObj = (IDfPersistentObject)sess.newObject("dm_acl"); pObj.apiSet("set", "object_name", aclName); //Grant the specified permissions to owner and world pObj.apiExec("grant", "dm_owner," + permission + "," + extPermission); pObj.apiExec("grant", "dm_world," + permission + "," + extPermission); pObj.save(); IDfACL oldACL = sysObj.getACL(); //Save the new private ACL //Save the object's current ACL
// Instantiate an instance of the new private ACL IDfACL newACL = sess.getACL(sess.getLoginUserName(), aclName); sysObj.setACL(newACL); sysObj.save(); displayBasicPermissions(sysObj); displayExtendedPermissions(sysObj); sysObj.setACL(oldACL); sysObj.save(); displayBasicPermissions(sysObj); displayExtendedPermissions(sysObj); //Apply new ACL to the sysobject //Save sysobject with its new ACL //Display new permissions //Apply old ACL to the sysobject //Save sysobj with restored ACL //Display restored permissions
66
'ACL name
67
For i = 0 To (sysObj.getAccessorCount - 1) 'For each accessor writeDiagnostic " Accessor: " + ' Name sysObj.getAccessorName(i) + " Permission: " + ' Permission permissionToString(sysObj.getAccessorPermit(i)), False Next i Exit Sub ErrorHandler: writeDiagnostic Err.Description, False End Sub
permissionToString in Java
//Convert permission code to name String permissionToString(String permission) { String retVal = null; if else else else else else else } if if if if if if (permission.equals("1")) (permission.equals("2")) (permission.equals("3")) (permission.equals("4")) (permission.equals("5")) (permission.equals("6")) (permission.equals("7")) retVal retVal retVal retVal retVal retVal retVal = = = = = = = "NONE"; "BROWSE"; "READ"; "NOTE"; "VERSION"; "WRITE"; "DELETE";
return retVal;
68
extendedPermissionToString in Java
//Convert extended permission code to name String extendedPermissionToString(String permission) { String retVal = null; if else else else else } if if if if (permission.equals("1")) (permission.equals("2")) (permission.equals("3")) (permission.equals("4")) (permission.equals("5")) retVal retVal retVal retVal retVal = = = = = "CHANGE_STATE"; "CHANGE_PERMIT"; "CHANGE_OWNER"; "EXECUTE_PROC"; "CHANGE_LOCATION";
return retVal;
displayBasicPermissions in Java
//Display object permissions void displayBasicPermissions(IDfSysObject sysObj) { try { System.out.println( "\tACL Name: " + sysObj.getACLName());
//ACL name
for (int i = 0; i < sysObj.getAccessorCount(); i++) { //For each accessor System.out.println( "\tAccessor: " + //Name sysObj.getAccessorName(i) + " Permission: " + //Permission permissionToString(sysObj.getAccessorPermit(i))); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
displayExtendedPermissions in Java
//Display the object's extended permissions void displayExtendedPermissions(IDfSysObject sysObj) { try { System.out.println( "\tACL Name: " + sysObj.getACLName()); for (int i = 0; i < sysObj.getAccessorCount(); i++) { System.out.println( "\tAccessor: " + sysObj.getAccessorName(i) + " Extended Permissions: " + sysObj.getAccessorXPermitNames(i)); } } catch (DfException dfe) { System.out.println("\n" + dfe.toString()); } }
69
610
7
7
This chapter provides an index to the major DFC methods, organized by the tasks the methods accomplish. The methods appear under the following categories:
s Communicating with the Server on page 7-2 s Administering the System on page 7-3 s Handling Objects on page 7-5 s Retrieving and Setting Attributes on page 7-10 s Searching the Docbase on page 7-12 s Handling Content Objects on page 7-13 s Printing Documents on page 7-15 s Handling Virtual Documents on page 7-16 s Handling Workflows on page 7-18 s Handling Process Definitions on page 7-19 s Handling Activity Definitions on page 7-20 s Handling Work Items on page 7-21 s Managing Inboxes on page 7-22
Under each category, the methods are grouped by interface. Some tasks have no associated DFC methods. The apiSet, apiGet, and apiExec methods of the IDfSession interface enable you to use the Documentum client library (DMCL) API to perform those tasks. Such tasks appear under the DMCL headings at the ends of their categories.
71
IDfClient
Establish a session with a Docbase.
IDfSession newSession( String docbaseName, IDfLoginInfo loginInfo) IDfSession getSharedSession(String docbaseName, IDfLoginInfo loginInfo, String key)
IDfSession
Cancel the transaction opened by the last beginTrans call, and discard all of its changes.
void abortTrans()
Open a transaction.
void beginTrans()
Save changes made since the last beginTrans call, and close the transaction.
void commitTrans()
Obtain a ticket that an application can substitute for the current users password as an argument to the Connect method.
String getLoginTicket()
Return all error and informational messages at or above the specified severity level for a session.
String getMessage(int severityLevel)
72
IDfClient
Return information about all Docbases known to the DocBroker.
IDfDocbaseMap getDocbaseMap() IDfDocbaseMap getDocbaseMapEx( String protocol, String hostName, String portNumber)
73
IDfSession
Send a DM_ARCHIVE event to the Docbase operator.
IDfId archive( String predicate, String operatorName, int priority, boolean sendMail, IDfTime dueDate)
Remove query caches, release memory for the server, or remove data dictionary information.
void flush( String flushType, String cacheKey)
74
Return a list of subconnections and the Docbases to which they are connected.
apiGet("dumpconnection[,session]")
Return the subconnection identifier for an existing connection or establish a new subconnection.
apiGet("getconnection,session,scoping_value[,connect_flag]")
Return the subconnections and the Docbases associated with them for a specified session.
apiGet("listconnection,session")
Handling Objects
The following methods manipulate objects.
IDfSession
Create a new persistent object of the specified type, optionally specifying the fully qualified name of the DFC-derived subclass of IDfPersistentObject.
IDfPersistentObject newObject(String typeName) IDfPersistentObject newObjectWithType( String typeName, String className)
75
IDfPersistentObject
Remove the object from the Docbase.
void destroy()
Fetch the object from the Docbase again (discard unsaved changes).
void revert()
IDfSysObject
Attach a dm_note (annotation) to the object.
void addNote( IDfId annotationId, boolean keepPermanent)
Simultaneously check the object out and create a new version branch.
IDfId branch(String versionLabel)
Create and save a new version of the checked-out object and remove the lock from the previous version.
IDfId checkin( boolean fRetainLock, String versionLabels)
76
IDfId checkinEx( boolean fRetainLock, String versionLabels, String oldCompoundArchValue, String oldSpecialAppValue, String newCompoundArchValue, String newSpecialAppValue)
Create and save a new version of the checked-out object and remove the lock from the previous version. This method is intended for use internally and by user-written applications. It differs from checkin by providing arguments that set the a_special_app and a_compound_architecture attributes.
checkinApp()
Obtain the ID of the remote object pointed to by the object. This only applies if the object is a local mirror object.
IDfId getRemoteId()
77
Promote the object to the specified state of its lifecycle, optionally overriding entry criteria. Optionally, test the entry criteria without promoting the object.
void promote( String state, boolean override, boolean fTestOnly)
Remove all old versions of the object, optionally keeping labeled versions.
void prune(boolean keepSLabel)
Refresh attribute values from the remote object pointed to by the object. This applies only if the object is a local mirror object.
void refreshReference()
Move the object from a suspended state to a normal state in its lifecycle.
void resume( String state, boolean toBase, boolean override, boolean fTestOnly)
Remove all access control entries from this object for the specified user or group.
void revoke( String accessorName, String extendedPermission)
Save the object, overwriting the copy in the Docbase. Keep the lock, and dont change the version.
void saveLock()
78
Move the object from the specified lifecycle state to the associated exception state.
void suspend( String state, boolean override, boolean fTestOnly)
Specify which ACL to use for the object (folder, user, type, or none).
void useACL(String aclType)
IDfAcl
Create an access control entry in the object.
void grant( String accessorName, int accessorPermit, String extendedPermission)
Remove the access control entries or an extended permission for a user or group.
void revoke( String accessorName, String extendedPermission)
79
IDfSession
Return a description of the attributes of an object type or registered table.
String describe( String type, String objType)
IDfTypedObject
Some of the methods of IDfTypedObject that deal with attributes have different versions for each of the allowed attribute types. In this section the notation MethodType represents a collection of methods, one for each of the following values of Type:
Boolean, Double, Id, Int, String, Time, Value
The declaration of the value parameter for each of these methods is:
boolean value, double value, Id value, int value String value, IDfTime value, IDfValue value
710
Return the index of the first occurrence of the specified value in the specified repeating attribute.
int findType( String attrName, type value)
Return all the values of the specified repeating attribute, concatenated into a single string.
String getAllRepeatingStrings( String attrName, String separator)
Return the value at the specified index in the specified repeating attribute.
type getRepeatingType( String attrName, int valueIndex)
Return the number of values the specified attribute has (always 1 for a singlevalued attribute).
int getValueCount(String attrName)
711
Remove the value at the specified index from the specified repeating attribute.
void remove( String attrName, int valueIndex)
Remove all values with index greater than or equal to the specified index from the specified repeating attribute.
void truncate( String attrName, int valueIndex)
IDfQuery
Execute a DQL query, and return the results as a collection.
void setDQL(String dqlStatement) IDfCollection execute( IDfSession session, int queryType)
IDfSession
Return the object (or its ID) that satisfies the search condition, which is the portion of a SELECT statement that begins with the keyword FROM.
IDfPersistentObject getObjectByQualification (String qualification)
712
Return the collection that resulted from the most recently executed query.
IDfCollection getLastCollection()
IDfCollection
Close the collection.
void close()
To access the current item of the collection, use methods IDfCollection inherits from IDfTypedObject (see Retrieving and Setting Attributes on page 7-10).
IDfSysObject
Add a rendition to the document, using the specified format and the contents of the specified file.
void addRendition( String fileName, String formatName) void addRenditionEx( String fileName, String formatName, int pageNumber, String storageName, boolean atomic)
Append information in working memory as the last content file for the document (used in applications to append content to multipaged documents).
void appendContent(ByteArrayOutputStream content)
713
Bind a content object belonging to another document to this document at the specified page number. The content then belongs to both documents.
void bindFile( int pageNumber, IDfId srcId, int srcPageNumber)
Fetch the specified content file from the Docbase, and return the file path at which the system places it.
String getFile(String fileName) String getFileEx( String fileName, String formatName, int pageNumber, boolean getResource)
Insert content from a byte array stream into the document at the specified page. (Used by applications to insert data into multipaged documents.)
void insertContent( ByteArrayOutputStream content, int pageNumber)
Remove the specified rendition from the document, optionally saving the changes to the Docbase as part of the operation.
void removeRendition(String formatName) void removeRenditionEx( String formatName, int pageNumber, boolean atomic)
714
Set data in working memory as new content or use it to replace content. (Used in applications to set the content of an object.)
boolean setContent(ByteArrayOutputStream content)
Printing Documents
The following methods perform print operations.
IDfSysObject
Send a document to a printer.
print()
715
IDfSysObject
Add a new component to the end of the objects list of components.
IDfId appendPart( IDfId componentId, String versionLabel, boolean useNodeVerLabel, boolean followAssembly, int copyChild)
Insert the specified component at the specified position in the objects list of components.
IDfId insertPart( IDfId componentID, String versionLabel, IDfId beforeContainmentId, double orderNo, boolean orderNoFlag, boolean useNodeVerLabel, boolean followAssembly, int copyChild)
716
Force the server to treat the object as a virtual document, even though it may have no components.
void setIsVirtualDocument(boolean treatAsVirtual )
Return paths to a component in one or more virtual documents. This method provides more flexibility in choosing the paths but slower performance.
apiGet("vdmpathdql,session, component_id[,root_id] [,shortest_path][,type] [,binding_condition][,nodesort_by]")
717
Handling Workflows
The following methods manage running workflows.
IDfWorkflow
Abort the workflow.
void abort()
718
IDfProcess
Add an activity to a process definition.
void addActivity( String actName, IDfId actId, String actType, int actPriority)
Create a link to connect the specified output port of the specified source activity to the specified input port of the specified destination activity (all ports and activities are already part of the process definition).
void addLink( String linkName, String linkSrcActivity, String linkSrcPortName, String linkDestActivity, String linkDstPortName)
Install the validated process definition and, if necessary, its activities. Specify whether to resume or to abort workflows that are based on this definition.
void install( boolean installActivity, boolean resume)
719
IDfActivity
Add the specified package to the specified port of the activity definition.
void addPackageInfo( String portName, String packageName, String packageType, IDfId packageId, String packageLabel, String packageOperation)
Add the specified route case (a conditional selection of a set of destination portslike a line in a case statement) to the activity definition.
void addRouteCase( String routeCaseIdentifier, String condition, IDfList outputPorts)
720
Remove the specified package from the specified port of the activity definition.
void removePackageInfo( String portName, String packageName)
IDfWorkitem
Acquire the work item for the performer.
void acquire()
721
Designate a list of additional users or groups to receive the work item when the performer finishes it.
void repeat(IDfList list)
Managing Inboxes
The following methods manage inboxes (user queues).
IDfSession
Remove the specified item from the users queue.
void dequeue(IDfId stampId)
722
IDfSysObject
Register the user to receive notification if the specified event happens to the object.
void registerEvent( String message, String event, int priority, boolean sendMail)
723
724
8
8
This chapter assumes that you are familiar with the methods that previous Documentum client products use to access server capabilities. It explains DFC by relating it to those methods. It contains the following main sections:
s Relationship to DMCL on page 8-1
This section explains the relationship between DFC and the Documentum client library (DMCL).
s Calling DMCL Directly on page 8-3
This section describes a way to bypass DFC and to communicate with the server via DMCL.
s DMCL to DFC Correspondence on page 8-4
This section contains a table of DMCL methods and the corresponding DFC methods.
Relationship to DMCL
The Documentum client library, DMCL, is a library of procedures and functions that implement the server API. DFC implements the API and an additional layer of related business logic, as shown in Figure 8-1. It does so through a set of interfaces that client programs can use to access DFC from Java or COM.
81
Figure 8-1
DocApp Data Validation DFC Object-Oriented Access to Server API DMCL Server API Using DFC differs from using DMCL in the following ways:
s DMCL communicates via strings of arguments and results. DFC creates
Workflow Runtime
VDM
Version Policy
Operations
mechanism. Example The following calls show the ways to use DMCL to access the server.
s Pass DMCL a method (connect) and its arguments. char *session = dmAPIGet("connect,docbase,user,password") s Pass the method (create), the session ID (s0), and the argument. char *object = dmAPIGet("create,s0,dm_document") s Pass the method (get), the session ID (s0), the object ID (09017...), and the
argument.
char *name = dmAPIGet("get,s0,09017...,object_name")
DFCs IDfSession interface hides the session ID and object ID, leading to the following code corresponding to the first DMCL call:
IDfClient client = DfClient.getLocalClient(); IDfLoginInfo loginInfo = new DfLoginInfo(); loginInfo.setUser("user"); loginInfo.setPassword("password"); IDfSession session = client.newSession("docbase",loginInfo );
82
The third DMCL call can take either of the following forms with DFC:
String name = object.getString("object_name"); String name = object.getObjectName();
In the first form, you know that the attribute is a string. In the second form, you know that the object is of type dm_sysobject. If any of the DFC calls fails, DFC throws DfException, and the getMessage method of the exception object returns the same string that the DMCL getmessage method returns. DFC also performs the reset automatically. The following code fragments show how to handle the error: first in Java, then in Visual Basic:
try //Java { object.checkout(); } catch (DfException e) { // checkout failed System.out.println(e.getMessage()); } On Error GoTo errHandler object.checkout GoTo finish #Visual Basic
The Visual Basic fragment assumes you have set cx via code like the following:
Dim cx as IDfClientX cx = CreateObject(Documentum.Dfc)
83
DFC provides complete, object-oriented access to the server API. Sometimes, such as when migrating legacy customizations, you may wish to call the server API directly. Table 8-1 describes DFC methods in the IDfSession interface that provide direct access to DMCL. Note: When you call DMCL directly, you bypass the DFC validation services. You must provide code to validate the data explicitly. Table 8-1
DFC Methods Providing Access to DMCL Method apiGet apiSet apiExec Description Equivalent to calling dmAPIGet from DFC. Equivalent to calling dmAPISet from DFC. Equivalent to calling dmAPIExec from DFC.
Refer to the eContent Server reference documentation for more information about how to use these methods. DFC returns a DfException object when a DMCL error occurs. In Java, use a try . . . catch code block to handle the error.
84
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Addnote Addrendition Anyevents Append DFC IDfSysObject :: addNote IDfSysObject :: addRendition IDfSysObject :: addRenditionEx IDfSession :: hasEvents IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject :: :: :: :: :: :: :: appendBoolean appendDouble appendId appendInt appendString appendTime appendValue
Appendcontent Appendfile Appendpart Appendtask Apply Archive Assemble Attach Begintran Bindfile Branch Changepassword Checkin Checkinapp Checkout
IDfSysObject :: appendContent IDfSysObject :: appendFile IDfSysObject :: appendPart IDfRouter :: appendTask IDfSession :: apply IDfSession :: archive IDfSysObject :: assemble IDfSysObject :: attachPolicy IDfSession :: beginTrans IDfSysObject :: bindFile IDfSysObject :: branch IDfSession :: changePassword IDfSysObject :: Checkin IDfSysObject :: CheckinEx IDfSysObject :: checkinApp IDfSysObject :: Checkout IDfSysObject :: CheckoutEx
85
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Close Commit Connect Count Create Datatype Demote Dequeue Describe Destroy Disassemble Disconnect Dump End Fetch DFC IDfCollection :: close IDfSession :: commitTrans IDfClient :: newSession IDfClient :: getSharedSession IDfTypedObject :: getAttrCount IDfSession :: newObject IDfSession :: newObjectWithType IDfTypedObject :: getAttrDataType IDfSysObject :: demote IDfSession :: dequeue IDfSession :: describe IDfPersistentObject :: destroy IDfSysObject :: disassemble IDfSession :: disconnect IDfTypedObject :: dump IDfRouter :: end IDfPersistentObject :: fetch IDfSession :: getObject IDfSession :: getObjectWithType IDfSession :: flush IDfSession :: flushCache IDfRouter :: force IDfRouter :: forward IDfSysObject :: freeze
86
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Get DFC IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject :: :: :: :: :: :: :: :: :: :: :: :: :: :: :: getBoolean getDouble getId getInt getString getTime getValue getAllRepeatingStrings getRepeatingBoolean getRepeatingDouble getRepeatingId getRepeatingInt getRepeatingString getRepeatingTime getRepeatingValue
Getcontent Getdocbasemap Getdocbrokermap Getevents Getfile Getlastcoll Getlogin Getmessage Getpath Getservermap Grant
IDfSysObject :: getContent IDfSysObject :: getContentEx IDfClient :: getDocbaseMap IDfClient :: getDocbaseMapEx IDfClient :: getDocbrokerMap IDfClient :: getDocbrokerMapEx IDfSession :: getEvents IDfSysObject :: getFile IDfSysObject :: getFileEx IDfSession :: getLastCollection IDfSession :: getLoginTicket this happens automatically when the error occurs IDfSession :: getMessage IDfSysObject :: getPath IDfClient :: getServerMap IDfClient :: getServerMapEx IDfACL :: grant IDfSysObject :: grant
87
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Halt Id Insert DFC IDfRouter :: halt IDfSession :: getIdByQualification IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject :: :: :: :: :: :: :: insertBoolean insertDouble insertId insertInt insertString insertTime insertValue
IDfSysObject :: insertContent IDfSysObject :: insertFile IDfSysObject :: insertPart IDfRouter :: insertTask IDfSysObject :: link IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject :: :: :: :: :: :: :: findBoolean findDouble findId findInt findString findTime findValue
IDfSysObject :: mark IDfCollection :: next IDfTypedObject :: findAttrIndex IDfRouter :: pause IDfSysObject :: print IDfSysObject :: promote IDfSysObject :: prune IDfSession :: purgeLocalFiles
88
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Query Queue Readquery Reassign Register Reinit Remove Removecontent Removenote Removepart Removerendition Removetask Repeating Reset Restart Restore Resume Retrieve Reverse Revert Revoke DFC IDfQuery.execute IDfSysObject :: queue IDfQuery.execute IDfRouter :: reAssign IDfSysObject :: register IDfSession :: reInit IDfTypedObject :: remove IDfTypedObject :: removeAll IDfSysObject :: removeContent IDfSysObject :: removeNote IDfSysObject :: removePart IDfSysObject :: removeRendition IDfSysObject :: removeRenditionEx IDfRouter :: removeTask IDfTypedObject :: isAttrRepeating Happens automatically when the error occurs IDfSession :: reStart IDfSession :: restore IDfRouter :: resumeRouter IDfSysObject :: resume IDfSession :: getObjectByQualification IDfRouter :: reverse IDfPersistentObject :: revert IDfSysObject :: revertACL IDfACL :: revoke IDfSysObject :: revoke
89
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Save Saveasnew Scope Set DFC IDfPersistentObject :: save IDfSysObject :: saveLock IDfSysObject :: saveAsNew IDfSession :: setDocbaseScope IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject IDfTypedObject :: :: :: :: :: :: :: :: :: :: :: :: :: :: setBoolean setDouble setId setInt setString setTime setValue setRepeatingBoolean setRepeatingDouble setRepeatingId setRepeatingInt setRepeatingString setRepeatingTime setRepeatingValue
Setbatchhint Setcontent Setdoc Setfile Setpath Shutdown Signoff Start Suspend Trace Truncate
IDfSession :: setBatchHint IDfSysObject :: setContent IDfSysObject :: setContentEx IDfSysObject :: setIsVirtualDocument IDfSysObject :: setFile IDfSysObject :: setFileEx IDfSysObject :: setPath IDfSession :: shutdown IDfRouter :: signOff IDfRouter :: start IDfSysObject :: suspend IDfSession :: traceDMCL IDfTypedObject :: truncate
810
Table 8-2
DFC methods corresponding to DMCL API commands (continued) DMCL Type Unfreeze Unlink Unlock Unmark Unregister Updatepart Useacl Validate Values DFC IDfSession :: getTypeDescription IDfSysObject :: unfreeze IDfSysObject :: unlink IDfSysObject :: cancelCheckout IDfSysObject :: cancelCheckoutEx IDfSysObject :: unmark IDfSysObject :: unRegister IDfSysObject :: updatePart IDfSysObject :: useACL IDfRouter :: validateRouter IDfTypedObject :: getValueCount
811
812
A
A
This appendix contains a selection of questions that developers sometimes ask as they start to work with DFC. Many of the questions come from an internal mailing list at Documentum. This appendix contains the following questions:
s Folder Path on page A-1 s Create a Microsoft Word Document on page A-3 s Name Strings for IDfOperation on page A-3 s IDfSession.sendToDistributionList Arguments on page A-4
Folder Path
How do I get the path on the local file system for the content file for a document, given its folder path in Documentum?
Answer 1
The first answer comes from service note 4810. It pertains to the case when the object is checked out. This example uses a hardcoded object_id. Normally, the ID comes from an earlier query or selection. The example also assumes a valid IDfClientX object and session (sess) object.
Private Dim Dim Dim Dim Dim ' Sub cmdGetPath_Click() id_obj As IDfId po As IDfPersistentObject regobj As IDfClientRegistryObject reg As IDfClientRegistry checked_out_obj As IDfCheckedOutObject
object_id = "0909f883800003ac"
A1
' '
If object_id = "" Then MsgBox "Please select an object_id from _ the Results list" Exit Sub Else Set id_obj = clientx.getId(object_id) chk_id$ = id_obj.getId MsgBox chk_id Set po = sess.GetObject(id_obj)
Set reg = clientx.getClientRegistry Set checked_out_obj = reg.getCheckedOutObjectById(id_obj) ' This failed originally... ' VB shows getFilePath as a method of an ' IDfCheckedOutObject object ' filepath$ = checked_out_obj.getFilePath ' ' ' ' ' ' VB lets you access inherited methods from the children. You need to call the method from the parent class where it is defined. IDfCheckedOutObject extends IDfClientRegistryObject so getFilePath is called from IDfClientRegistryObject ...so the right way to do it is.
Answer 2
If the document is checked out, you can get the path from the object ID using IDfClientRegistry.getCheckedOutObjectById(), which returns an IDfCheckedOutObject, which is a subclass of IDfClientRegistryObject. Use IDfClientRegistryObject.getFilePath() to get the path to the checked out file. There are similar calls for viewed or local files documents.
A2
Answer
Look at createDocument in Visual Basic on page 4-2. Substitute msw8 for crtext in the example. The relevant portion of the code looks like this:
Set sysObj = sess.newObject("dm_document") 'Create doc obj sysObj.setObjectName docName 'Set attributes sysObj.setSubject "Sample document" sysObj.setContentType "msw8" sysObj.setTitle "DFC Example Doc" sysObj.setFile contentFile sysObj.link linkName Set pObj = sysObj '"Cast" to persistent object pObj.save 'Save
Dont forget to create a persistent object version before saving. If you try to execute sysObj.save, Visual Basic crashes, because a sysobject inherits its save method from the persistent object type, but COM does not handle this inheritance. See the discussion following the example on page 1-3.
creates an IDfCopyOperation object. What are the valid strings that can be passed as operation name to IDfClientX::getOperation to get an IDfOperation?
A3
Answer
The following are the valid strings that can be passed as operation name to IDfClientX::getOperation to get an IDfOperation: Checkout Checkin Import Export CancelCheckout Copy Delete Move Checkout operation Checkin operation Import operation Export operation CancelCheckout operation Copy operation Delete operation Move operation
IDfSession.sendToDistributionList Arguments
We need help with the IDfSession.sendToDistributionList method. Several arguments are identified as being of type IDfList, which is a container object, but what type does sendToDistributionList expect to be in the IDfList objects? For instance were currently passing a DfList of IDfUser objects for the first argument, an empty DfList for the second argument (since we dont want to route to groups, only named users), a string containing a message for the third argument, a DfList of DfID objects for the documents parameter, an integer, and a boolean. The error message we get back is:
[DM_DFC_E_TYPE_MISMATCH_GET]error: "Type mismatch. 'String' cannot be returned as type 'Object'." The type
Answer
Dont insert IDfUser into the IDfList. Just insert the user name as a string. Dont use the users OS name. Try with a user name in the Docbase.
A4 Using DFC in Documentum Applications
It is fine if you dont insert any IDfGroup to the IDfList. The following VB program runs the sendToDistributionList method:
Dim session82ID As String Dim session82 As IDfSession Dim cx As DfClientX Dim client As IDfClient Private Sub Form_Load() makeSession End Sub Sub makeSession() Set cx = New DfClientX cx.setTraceFileName "D:\OpenDialogVBTestTrace.txt" cx.setTraceLevel 6 Set client = cx.getLocalClient Dim li As IDfLoginInfo Set li = cx.getLoginInfo li.setUser ("yourUserName") li.setPassword ("yourPassword") Set session82 = client.getSharedSession("yourDocbase",_ li, "my_key") session82ID = session82.getSessionId Dim ticket As String ticket = session82.getLoginTicket() Dim users As IDfList Set users = cx.getList users.appendString "tuser1" users.appendString "tuser2" 'users.appendString "Lazyworm" Dim groups As IDfList Set groups = cx.getList Dim obj As IDfList Set obj = cx.getList Dim objID As IDfId 'for docbs Set objID = cx.getId("Document Object ID")
A5
obj.appendId objID session82.apiExec "trace", "8,d:\temp\dmcl.txt" session82.sendToDistributionList users, groups,_ "Testing", obj, 10, False 'session82.apiExec "trace", "0" End Sub
A6
INDEX
A
abortTrans method 1-28 ACLs 6-2 private 6-5 adoptDMCLSession method 1-32 API calls 1-30 API Config object 1-33 apiDesc method 1-30 apiExec method 1-30, 6-5 apiGet method 1-30 apiGetBytes method 1-30 apiSet method 1-30, 6-5 apiSetBytes method 1-30 apply method 1-30 archive method 1-30 attributes methods related to 7-10
B
beginTrans method 1-28
com.documentum.fc.common package 1-5, 1-34 com.documentum.fc.common.session package 1-5 com.documentum.operations package 1-5 com.documentum.registry package 1-5 commitTrans method 1-28 common.documentum.fc.client.qb package 1-4 connections methods related to 7-3 connectToDocbase method 3-6 content objects methods that work with 7-13 create type statement 4-4, 4-7 creating cabinets 4-1, 4-5 documents 4-2, 4-5 folders 4-2, 4-5 types 4-7
C
cabinets 4-1, 4-5 cancelCheckout method 4-8 cancelling checkouts 4-8 changePassword method 1-31 checkin method 4-8 checking in objects 4-8 checking out objects 4-7 checkout method 4-7 close method 1-35 collections stepping through 5-2 COM inheritance 1-5, 4-1, 4-2 com.documentum.com package 1-4 com.documentum.fc.client package 1-4
D
deleteFile 4-9 deleting local files 4-9 See also destroying dequeue method 1-30 describe method 1-30 destroy method 4-6 destroyAllVersions method 4-3, 4-6 destroying objects 4-3, 4-6 DFC (Documentum Foundation Classes) COM interface 1-2 elements 1-2 DFC (Documentum foundation classes) adopted sessions 2-5 comparison with DMCL 8-4
Index1
datatypes 2-3 DMCL process 2-3 inheritance 2-1 migrating to 8-4 naming convention 1-4 objects and pointers 2-2 online reference 2-6 server API calls 8-4 shared sessions 2-5 DFC interface hierarchy 1-9 DfClient class 1-31, 3-1, 3-2, 3-5 DfClientX class 4-7, 4-8 DfLoginInfo class 3-2 DfPersistentObject class 1-28 DfQuery class 1-34 DfType class 1-28 DfTypedObject class 1-28 DfUser class 1-28 DfValidationException class 6-1 disconnect method 1-31 disconnectFromDocbase method 3-5 dm_cabinet type 1-26 dm_folder type 1-26 DMCL commands 8-4 DMCL shared library 1-31 Docbase scope 1-28 Docbases querying with methods 7-12 docbrokers 1-33, 3-5 documents 4-2 methods for printing 7-15 Documentum foundation classes. See DFC DQL (Document Query Language) methods that work with 7-12 DQL queries 1-35 DQL statements 4-4, 4-7
E
eContent Server communicating with 7-2 methods for communicating with 7-2 enumAttrs method 1-23 enumSharedSessions method 1-32 execute method 5-1
F
findAttrIndex method 1-23 findSession method 1-32 flush method 1-31 flushCache method 1-31 folders 4-2, 4-5
G
getACL method 1-27 getAllRepeatingStrings method 1-14 getAttr method 1-23, 1-35 getAttrCount method 1-23 getAttrDataType method 1-23 getBoolean method 1-13, 1-26 getClient method 1-26 getClientConfig method 1-28, 1-33 getConnectionConfig method 1-28 getContext method 1-33 getDataType method 1-35 getDBMSName method 1-26, 3-4 getDefaultACL method 1-27 getDMCLSessionId method 1-26, 3-4 getDocbaseConfig method 1-28 getDocbaseDescription method 3-6 getDocbaseId method 1-26, 3-4 getDocbaseMap method 1-32, 3-5 getDocbaseName method 1-26, 3-5, 3-6 getDocbaseOwnerName method 1-26, 3-4 getDocbaseScope method 1-29, 3-4 getDocbrokerMap method 1-28 getDouble method 1-13 getEvents method 1-30
Index-2
getFile method 4-9 getFolderByPath method 1-27 getFormat method 1-27 getGroup method 1-27 getId method 1-13, 4-8 getIdByQualification method 1-27 getInt method 1-13 getLastCollection method 1-30 getLocalClient method 3-1 getLoginInfo method 1-26 getLoginTicket method 1-31, 3-4 getLoginUserName method 1-27, 3-4 getMessage method 1-30 getNextMinorLabel method 4-8 GetObject method 4-8 getObject method 1-27, 4-3 getObjectByPath method 1-27 getObjectByQualification method 1-27 getObjectName method 4-7, 4-8 getObjectWithType method 1-28 getQuery method 1-35 getRDBMSName is incorrect 1-27 getRelationType method IDfRelationType interface 1-31 getRepeatingBoolean method 1-14 getRepeatingDouble method 1-14 getRepeatingId method 1-14 getRepeatingInt method 1-14 getRepeatingString method 1-14 getRepeatingTime method 1-14 getRepeatingValue method 1-14 getRunnableProcesses method 1-30 getSecurityMode method 1-27, 3-4 getServerConfig method 1-28 getServerMap method 1-28 getServerVersion method 1-27, 3-4, 3-6 getSessionConfig method 1-28 getSessionId method 1-27, 3-4 getSharedSession method 1-32 getString method 1-13, 1-35 getTasks method 1-30
getTime method 1-13 getType method 1-28 getTypeDescription method 1-28 getTypedObject method 1-36 getUser method 1-28 getUserByOSName method 1-28 getValue method 1-13, 1-34 when to avoid 1-34 getVersionLabel method 4-6 getVersionLabelCount method 4-3, 4-6 getVersionPolicy method 4-8, 4-11 getVersionTreeLabels method 1-31 grant method 6-2, 6-3
H
hasAttr method 1-23 hierarchy, of DFC interfaces 1-9
I
IdfACL interface 1-27 IDfAttr interface 1-23 IDfClient interface 1-2, 1-26, 1-28, 1-31, 31, 3-2, 3-5 IDfClientX interface 1-35 IDfCollection interface 1-30, 1-35, 5-1 IDfDocbaseMap interface 1-32, 3-5 IDfDocument interface 1-25 IDfFolder interface 1-27 IDfFormat interface 1-27 IDfGroup interface 1-27 IDfId interface 1-13, 1-14, 1-27, 1-30, 1-31 IDfList interface 1-30 IDfLoginInfo interface 1-26, 1-32, 3-2, 3-3 IDfPersistentObject interface 1-8, 1-27, 128 IDfProperties interface 1-33 IDfSession interface 1-2, 1-26, 1-29, 1-32 IDfSysObject interface 1-5, 1-24 IDfTypedObject interface 1-28 IDfValidator interface 6-1
Index-3
IDfValue interface 1-34 IDfVersionTreeLabels interface 1-31 IDfWorkflowBuilder interface 1-30 inboxes methods related to 7-22 isACLDocbase method 1-27 isAdopted method 1-27 isAttrRepeating method 1-23 isCheckedOut method 4-7, 4-8 isConnected method 1-27, 3-2 isDeleted method 4-3 isRemote method 1-27 isShared method 1-27
Q
queries 1-36, 5-1 displaying results 5-2 flow of processing 1-34 queues, user. See inboxes
R
reInit method 1-31 removeContext method 1-33 repeating attributes 1-15 resolveAlias method 1-30 restore method 1-31 revoke method 6-3 rows 1-36
L
link method 4-2, 4-5
S
save method 4-5, 6-5 saving sysobject as persistent object 4-1, 4-2 sendToDistributionList method 1-30 sessions 1-26, 1-31, 1-32, 3-1 keys 1-32 multithreading 1-29 shared 1-32 setACL method 6-5 setBatchHint method 1-31 setBoolean method 1-13 setContentType method 4-2, 4-5 setDocbaseScope method 1-29 setDocbaseScopeById method 1-29 setDomain method 3-3 setDouble method 1-13 setFile method 4-2, 4-5, 4-8 setId method 1-13 setInt method 1-13 setObjectName method 4-1, 4-2, 4-5 setPassword method 3-2 setRepeatingBoolean method 1-14 setRepeatingDouble method 1-14 setRepeatingId method 1-14
M
methods server communication 7-2
N
newObject method 4-1, 4-2, 4-5 newObjectWithType method 1-28 newSession method 1-32, 3-1, 3-2 newWorkflowBuilder method 1-30
O
objects methods for handling 7-5
P
passwords 1-32 permissions 6-2, 6-3 persistent objects 1-7, 1-27 printing methods related to 7-15 private ACLs 6-5 purgeLocalFiles method 1-31
Index-4
setRepeatingInt method 1-14 setRepeatingString method 1-14 setRepeatingTime method 1-14 setRepeatingValue method 1-14 setString method 1-13 setSubject method 4-1, 4-2, 4-5 setTime method 1-13 setTitle method 4-2, 4-5 setUser method 3-2 setValue method 1-13 shared sessions 1-32 shutdown method 1-31 subconnections methods related to 7-3 subtypes 1-7 supertypes 1-7, 1-8 sysobjects 1-24 system administration methods for 7-3
T
traceDMCL method 1-30 transactions 1-28 type libraries 1-2 typed objects 1-28
U
unlock method 1-29 user names 1-32
V
validateAttrRules method 6-2 versions 4-11 virtual documents methods related to 7-16
W
warnings COM interface inheritance fails 2-1
Index-5
Index-6