Professional Documents
Culture Documents
Documentum
Applications
Version 4.2
December 2000
DOC3-USINGDFC-1200
DOC3-USINGDFC-1200
Copyright © 1999, 2000
Documentum, Inc.
6801 Koll Center Parkway
Pleasanton, CA 94566
All Rights Reserved.
2 Using DFC
Using DFC From Application Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Syntax Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Creating DFC Client Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
COM Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Creating a DFC Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Shared Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Adopted Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Using DFC Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Using the DFC Online Reference Documentation. . . . . . . . . . . . . . . . . . . . . 2-6
Index
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).
Chapter 1, Overview of How DFC helps you connect to a Docbase and gives
Documentum Foundation you an object oriented interface to the Documentum
Classes (DFC) object hierarchy.
Chapter 2, Using DFC Making DFC work with your programming and
execution environments.
Conventions
{} braces (curly Indicates an optional argument that can be repeated more than
brackets) once.
➤ To follow a link:
1. 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.
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.
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:
1. In your Web browser, open
http://www.documentum.com/
2. Click the Technical Support link.
3. Log on to the Technical Support site.
4. In the Resources section, click Documentation.
5. Click the name of the document.
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.
The core of DFC is a set of Java classes, but it includes other elements as well:
■ A collection of DLLs to provide the DFC functionality.
■ A shared library that you must load to use DFC with non-Microsoft Java
virtual machines (JVMs).
■ A type library for accessing DFC via COM from Visual Basic or Visual
C++.
■ A set of C++ wrapper classes that hide many details of the DFC/COM
interface.
DFC Programming
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 object’s
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.
■ The names of DFC Java classes begin with Df (for example, DfWorkflow).
■ Names of interfaces begin with IDf (for example, IDfWorkflow).
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.
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
IDfDocument IDfFolder
dm_document 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.
IDfTypedObject
IDfPersistentObject
IDfACL
IDfAliasSet
IDfAssembly
IDfContainment
IDfFormat
IDfGroup
IDfPackage
IDfQueueItem
IDfRelation
IDfRelationType
IDfActivity
IDfSysObject
IDfDocument
IDfType
IDfFolder
IDfUser
IDfProcess
IDfWorkItem
IDfRouter
IDfWorkflow
IDfCollection
IDfDocbaseMap
IDfOperation
IDfCancelCheckoutOperation
IDfCheckinOperation
IDfCheckoutOperation
IDfCopyOperation
IDfDeleteOperation
IDfExportOperation
IDfImportOperation
IDfMoveOperation
IDfOperationNode
IDfCancelCheckoutNode
IDfCheckinNode
IDfCheckoutNode
IDfCopyNode
IDfDeleteNode
IDfExportNode
IDfImportNode
IDfMoveNode
IDfClientRegistryObject
IDfCheckedOutObject
IDfLocalObject
IDfViewedObject
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.
Typed Objects
The IDfTypedObject interface provides the basis for both persistent and non-
persistent types. Here are the main facts about typed objects:
■ They have attributes (properties) that you can retrieve and set.
■ 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.
■ 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.
Typed objects have IDs, and they hold references to the session that created
them. The IDfTypedObject methods getSession and getObjectId return this
information.
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, boolean value)
void setRepeatingDouble(
String attrName, int index, double value)
void setRepeatingId(
String attrName, int index, IDfId value)
void setRepeatingInt(
String attrName, int index, int value)
void setRepeatingString(
String attrName, int index, String value)
void setRepeatingTime(
String attrName, int index, IDfTime value)
void setRepeatingValue(
String attrName, int index, 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)
returns the string
Sleepy,Dopey,Happy,Sneezy,Grumpy,Doc,Bashful
Attribute Information
The dump method is for debugging. It returns the object’s 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 object’s
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 attribute’s
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
attribute’s 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
IDfAttr’s getLength method.
The enumAttrs method returns an enumeration of IDfAttr objects. This
enables you to iterate over all of the object’s 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.
Every object in the Docbase has an i_vstamp attribute, which contains the
number of committed transactions that have changed the object. This value is
used for versioning, as part of the locking mechanism, to ensure that one user
does not overwrite the changes made by another. The getVStamp method
returns this value.
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 object’s type information, call the getType
method.
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.
Validation Methods
IDfId getPolicyID()
String getStateName()
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
(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
Basic Attributes
The getName method returns the type’s name—a string like dm_format or
dm_document.
The getDescription method returns the type’s 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.
Most types derive from other types. People who deploy Documentum usually
create several layers of new types to meet their specific needs. IDfType
provides the following methods to test whether the type derives from another
type:
String getSuperName()
IDfType getSuperType()
boolean isSubTypeOf(String typeName)
The getSuperName method returns the name of the type’s 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.
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 attribute’s index, call findTypeAttrIndex. The index is 0-
based. 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
They return IDfType.DF_UNDEFINED only in unusual circumstances.
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.
The IDfSysObject interface has a large number of methods. Refer to the DFC
online reference for detailed information. The Documentum eContent Server
Fundamentals manual provides the conceptual background. The following
functional categories provide an overview of IDfSysObject:
■ Checkout/Checkin
“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.
■ Content-Related
The eContent Server Fundamentals manual discusses content, renditions,
and file formats.
■ 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.
■ 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.
■ 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.
■ 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.
■ Business Policy
Business policies are also known as document lifecycles (DLCs). The
Documentum eContent Server Fundamentals manual explains how DLCs
work.
IDfSession
All interaction with a Docbase occurs in a session, that is, using an IDfSession
object. In broad terms, a session:
■ Uses the underlying DMCL library to maintain a connection to a Docbase.
■ Maintains the state of the interaction between an application and the
Docbase.
■ 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.
■ 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()
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 “R”is correct.
Developers sometimes ask why they can’t create a new sysobject as follows:
obj = new DfSysObject;
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)
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
Transaction Support
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 method’s arguments is an object ID, the server can determine the
Docbase scope from the ID.
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 don’t 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
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
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 disconnect()
void flush(String flushType, String cacheKey)
void flushCache(boolean discardChanged)
void purgeLocalFiles()
void 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.
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 in“connectToDocbase 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.
Client applications often present the user with a list of available Docbases.
DFC returns this list through the IDfDocbaseMap interface, which is obtained
by calling the IDfClient getDocbaseMap method. The IDfDocbaseMap
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.
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
attribute’s 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 don’t
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.
■ For Visual Basic and C++ programs, call the getQuery method of
IDfClientX.
4. Create a DQL query as a text string, dq.
5. Call query.setDQL(dq) to set the DQL string into the query object.
6. 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 don’t 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.
IDfCollection
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();
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 Microsoft’s MFC, include the following
files in your Visual C++ project: DfClientX.h, DfClientX.cpp, dfc.h, and dfc_i.c
If you don’t 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:
■ 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;
■ A procedure that returns a DFC object should return a pointer to the object,
as demonstrated in the following Visual C++ example:
CDfSysObject *myFunction();
{
CDfSysObject sobj1 = session.getObject(id);
CDfSysObject *retval = new CDfSysObject (sobj1);
return retval;
}
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.
Java (DFC datatype) Visual Basic C++ with MFC C++ directly to COM
(and Docbasic) wrapper classes
Java Example
COM Example
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
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:
■ “Connecting and Disconnecting” on page 3-1
■ “Using a Docbase Map” on page 3-5
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();
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
}
} catch(DfException dfe) {
System.out.println("\n" + dfe.toString());
}
return retVal;
}
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());
} }
disconnectFromDocbase = retVal
Exit Function
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
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());
} }
DfExMainForm.cbxDocbase.Text = docbaseName
Set sess = exSess.connectToDocbase(sess) 'Connect to Docbase
If Not sess Is Nothing Then
writeDiagnostic "Connected to: " +
docbaseName, False
exSess.displaySessionInfo sess 'Display session details
exSess.disconnectFromDocbase sess 'Disconnect
End If
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
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:
■ “Creating and Destroying” on page 4-1
■ “Checking Sysobjects In and Out” on page 4-7
■ “Working With Sysobject Versions” on page 4-11
dqlStatement = createDQLStatement(typeName,
supertypeName, lstAttrs)
Set exQuery = New DfExSimpleQuery 'Use DfExSimpleQuery class
exQuery.execQuery sess, dqlStatement
createDQLStatement = ""
If lstAttrs.ListCount > 0 Then 'Build comma-separated
For i = 0 To (lstAttrs.ListCount - 1) ' string of attributes
If Not attrDefs = "" Then
attrDefs = attrDefs + "," + lstAttrs.List(i)
Else
attrDefs = lstAttrs.List(i)
End If
Next i
End If
createCabinet in Java
void createCabinet(IDfSession sess) throws IOException {
try {
IDfSysObject sysObj = //Create cabinet obj
(IDfSysObject)sess.newObject("dm_cabinet");
createFolder in Java
void createFolder(IDfSession sess) throws IOException {
try {
IDfSysObject sysObj = //Create folder obj
(IDfSysObject)sess.newObject("dm_folder");
sysObj.setObjectName("SampleFolder"); //Set attributes
sysObj.setSubject("DFC example folder");
sysObj.link("SampleParent"); //Assume it exists
sysObj.save(); //Save
displayObjectInfo(sysObj); //Display details
} catch (DfException dfe) {
System.out.println("\n" + dfe.toString());
} }
createDocument in Java
void createDocument(IDfSession sess) throws IOException {
try {
IDfSysObject sysObj = //Create document obj
(IDfSysObject)sess.newObject("dm_document");
sysObj.setObjectName("SampleDoc"); //Set attributes
sysObj.setSubject("Sample document");
sysObj.setContentType("crtext");
sysObj.setTitle("Sample Document");
sysObj.setFile("C:\test.txt"); //Assume content file
sysObj.link("SampleCabinet"); // and cabinet exist
sysObj.save(); //Save
displayObjectInfo(sysObj); //Display details
} catch (DfException dfe) {
System.out.println("\n" + dfe.toString());
} }
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); //objId --> IDfId obj
IDfSysObject sysObj = //Get the object
(IDfSysObject)sess.getObject(sysObjId);
createType in Java
void createType(
IDfSession sess, //Session
String typeName, //Name of the new type
String superName, //Supertype
String attrDefs //Attribute definitions
) {
try {
String dqlStatement = createDQLStatement();
DfExSimpleQuery exQuery = new DfExSimpleQuery();
exQuery.execQuery(sess, dqlStatement);
} catch (Exception e) {
System.out.println("\n" + e.toString());
} }
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 {
checkOutObject = True
Set sysObjId = clientx.getId(objId) 'Create IDfId object
Set sysObj = sess.GetObject(sysObjId) 'Create IDfSysObject
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
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);
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);
checkInObject in Java
void checkInObject(IDfSession sess, String objId)
throws IOException {
try {
IDfId sysObjId = new DfId(objId); //Create IDfId object
IDfSysObject sysObj = //Create IDfSysObject
(IDfSysObject)sess.getObject(sysObjId);
removeLocalFile in Java
void removeLocalFile(IDfSysObject sysObj)
throws IOException {
try {
IDfFile f = new DfFile(sysObj.getObjectName()); //Create file object
f.deleteFile(); //Delete file
} 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);
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 = Nothing
Set sysObj = Nothing
Set verPolObj = Nothing
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
Else 'Otherwise
'ERROR ACTION ' Take error action
End If
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();
} 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);
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
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
col.Close
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
exQuery in Java
IDfCollection execQuery(IDfSession sess, String queryString)
{
IDfCollection col = null; //For the result
try {
displayResults in Java
//Step through a collection and display results
void displayResults(IDfCollection col) throws IOException
{
try {
int resItems = 1; //Count rows
while (col.next()) {
System.out.println("\nResult row: " + resItems++); //Display row num
for (int i = 0; i < col.getAttrCount(); i++) { //For attribute
IDfAttr attr = col.getAttr(i);
System.out.print("\t" + attr.getName() + ": "); // Display name
if (attr.getDataType() == attr.DM_BOOLEAN) { // Display value
System.out.println( // using method
col.getBoolean(attr.getName())); // for its type
} 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 { //Unknown type
//ERROR ACTION // Handle error
} } }
col.close(); //Close collection
} catch (DfException dfe) {
System.out.println("\n" + dfe.toString());
} }
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:
■ “Checking Objects Against Validation Rules” on page 6-1
■ “Changing Permissions” on page 6-2
■ “Using Private ACLs” on page 6-5
■ “ACL Utility Methods” on page 6-7
validate in Java
// Perform validation
void validate(
IDfSession sess, //Session
String objIdStr, //ID of the object to validate
String attrName) //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();
Changing Permissions
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
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
throws IOException {
try {
//Use ID string to obtain the ID, then the object
IDfId sysObjId = new DfId(objId);
IDfSysObject sysObj = (IDfSysObject)sess.getObject(sysObjId);
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);
Exit Sub
ErrorHandler:
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);
Exit Function
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
Exit Function
ErrorHandler:
writeDiagnostic Err.Description, False
End Function
writeDiagnostic
" ACL Name: " +
sysObj.getACLName, False 'ACL name
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
writeDiagnostic
" ACL Name: " + sysObj.getACLName, False 'ACL name
Exit Sub
ErrorHandler:
writeDiagnostic Err.Description, False
End Sub
permissionToString in Java
//Convert permission code to name
String permissionToString(String permission)
{
String retVal = null;
return retVal;
}
extendedPermissionToString in Java
//Convert extended permission code to name
String extendedPermissionToString(String permission)
{
String retVal = null;
return retVal;
}
displayBasicPermissions in Java
//Display object permissions
void displayBasicPermissions(IDfSysObject sysObj)
{
try {
System.out.println(
"\tACL Name: " + //ACL name
sysObj.getACLName());
displayExtendedPermissions in Java
//Display the object's extended permissions
void displayExtendedPermissions(IDfSysObject sysObj)
{
try {
System.out.println(
"\tACL Name: " + sysObj.getACLName()); //ACL name
This chapter provides an index to the major DFC methods, organized by the
tasks the methods accomplish. The methods appear under the following
categories:
■ “Communicating with the Server” on page 7-2
■ “Administering the System” on page 7-3
■ “Handling Objects” on page 7-5
■ “Retrieving and Setting Attributes” on page 7-10
■ “Searching the Docbase” on page 7-12
■ “Handling Content Objects” on page 7-13
■ “Printing Documents” on page 7-15
■ “Handling Virtual Documents” on page 7-16
■ “Handling Workflows” on page 7-18
■ “Handling Process Definitions” on page 7-19
■ “Handling Activity Definitions” on page 7-20
■ “Handling Work Items” on page 7-21
■ “Managing Inboxes” on page 7-22
IDfClient
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 user’s
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)
IDfClient
IDfSession
Remove query caches, release memory for the server, or remove data
dictionary information.
void flush(
String flushType,
String cacheKey)
Return a list of subconnections and the Docbases to which they are connected.
apiGet("dumpconnection[,session]")
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)
IDfPersistentObject
Fetch the object from the Docbase again (discard unsaved changes).
void revert()
IDfSysObject
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)
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()
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 don’t
change the version.
void saveLock()
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
IDfSession
IDfTypedObject
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
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 single-
valued attribute).
int getValueCount(String attrName)
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
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)
Return the collection that resulted from the most recently executed query.
IDfCollection getLastCollection()
IDfCollection
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)
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)
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)
Set the next position (byte range) for reading a content collection.
apiExec("seek,session,collection,
position[,direction]")
Printing Documents
The following methods perform print operations.
IDfSysObject
IDfSysObject
Insert the specified component at the specified position in the object’s list of
components.
IDfId insertPart(
IDfId componentID,
String versionLabel,
IDfId beforeContainmentId,
double orderNo,
boolean orderNoFlag,
boolean useNodeVerLabel,
boolean followAssembly,
int copyChild)
Force the server to treat the object as a virtual document, even though it may
have no components.
void setIsVirtualDocument(boolean treatAsVirtual )
Handling Workflows
The following methods manage running workflows.
IDfWorkflow
IDfProcess
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)
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)
Remove the specified package from the specified port of the activity
definition.
void removePackageInfo(
String portName,
String packageName)
IDfWorkitem
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
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)
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:
■ “Relationship to DMCL” on page 8-1
This section explains the relationship between DFC and the Documentum
client library (DMCL).
■ “Calling DMCL Directly” on page 8-3
This section describes a way to bypass DFC and to communicate with the
server via DMCL.
■ “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.
DocApp
errHandler:
Dim e As IDfException
Set e = cx.parseException(Err.Description)
MsgBox e.getMessage
finish:
The Visual Basic fragment assumes you have set cx via code like the
following:
Dim cx as IDfClientX
cx = CreateObject(“Documentum.Dfc“)
Method Description
DMCL DFC
DMCL DFC
DMCL DFC
DMCL DFC
DMCL DFC
Id IDfSession :: getIdByQualification
DMCL DFC
Query IDfQuery.execute
Readquery IDfQuery.execute
DMCL DFC
DMCL DFC
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 Sub cmdGetPath_Click()
Dim id_obj As IDfId
Dim po As IDfPersistentObject
Dim regobj As IDfClientRegistryObject
Dim reg As IDfClientRegistry
Dim checked_out_obj As IDfCheckedOutObject
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.
Answer
Answer
The following are the valid strings that can be passed as operation name to
IDfClientX::getOperation to get an IDfOperation:
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 we’re currently passing a DfList of IDfUser objects for the first
argument, an empty DfList for the second argument (since we don’t 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. The type
'String' cannot be returned as type 'Object'."
Answer
Don’t insert IDfUser into the IDfList. Just insert the user name as a string.
Don’t use the user’s OS name. Try with a user name in the Docbase.
Dim cx As DfClientX
Dim client As IDfClient
End Sub
Sub makeSession()
obj.appendId objID
End Sub
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