DFC接口手册-V1.0.doc

DFC接口手册

DFC接口手册
1.0.0

一．前言
Documentum Foundation Classes（DFC）是Content Application和Content Server进行通信的主要接口。它提供了完整的访问Documentum Object Model的基于对象的应用程序接口。DFC能够使程序员通过High-level的操作或者Low-level的对象方法调用来访问内容管理。

图1 DFC的层次结构
DFC是基于JAVA的，如果客户端程序是由JAVA实现的话，就能够直接通过接口访问DFC。DFC还提供Documentum Java-COM Brigde，使微软组件对象模型（COM）能够使用DFC的接口，这就说明其他能够COM模型的语言都能够运用DFC的接口。DFC PIA还提供在dotNet环境下访问DFC的能力。
上面这一点讲到外部应用程序可以通过什么样的途径来访问DFC。那么DFC本身是怎么访问外部资源的呢？Java 软件开发工具箱（Java Software Development Kit (SDK)）提供了Java 本机接口（Java Native Interface (JNI)）这么一个本机编程接口。JNI 允许 Java 代码使用以其它语言（譬如 C 和 C++）编写的代码和代码库。因为DFC是基于JAVA的，所有就有能力来访问其他语言写的代码库。
DFC是有许多包组成的，每个包的类和接口都是具有一组特定的功能。
包名 描述
包含通过OLE/COM访问DFC的接口
com.documentum.fc.client 包含管理SESSION和维护Documentum Repository
数据的类和接口
mon 包含所有DFC对象都可能用到的有用的类和接口
com.documentum.operations 包含通用client功能的接口，如checking in和
checking out 文档的操作
com.documentum.registery 包含在客户端本地系统管理Documentum信息需要
用到的类和接口
com.documentum.xml.xdql 包含查询Documentum Repository返回XML结果
所需要用到的类和接口
通过这个手册的描述，掌握Documentum Server 对象模型和DFC接口模型之间的关系是非常重要的。
二．Clients and sessions
Documentum采用的是client/server模型的架构。DFC把所有client功能压缩到一个叫IDfClient的接口，这个接口是所有DFC代码的入口。从IDfClient对象可以获得一个IDfSessionManager。
IDfSession对象是DFC的核心概念。一个DFC Session实现了Documentum server和它提供的服务之间的一个连接。一个session对象是一个IDfSession的实例，所有访问repository的功能都需要一个repository session和DFC session。DFC clients可以通过session manager来得到一个session object。
Session Manager管理着一个或多个repository的session。Client应用程序从Session manager获得session，使用完后，把session释放给Session manager。Session Manager也维护着一个repository session pool来提供DFC session。通常，DFC session应该从Session manager获得，而不是使用IDfClient对象得到。Session manager提供了很多方法，能够让我们处理：
1． Manage Identities/access credentials
2． Authenticate user access
3． Acquire and release sessions
4． Process Transactions
5． Authenticate user access
6． Obtain session statistics
7． Catch checked and unchecked Exceptions

Session Manager提供repository session pool来有效的处理session。当你释放一个从Session Manager获得的session时，Session Manager并不马上切断这个session的连接。如果你在Session Manager切断刚才释放的session连接前，再次申请一个针对同一个repository的session的话，Session Manager会把原来的返回给你。如果Session Manager已经切断了你所释放的session连接，或者你明确要申请一个新session，或者你申请一个不同repository的session，那么Session Manager就提供一个新的session给你。
Session能够支持Transaction来处理多个repository的相互作用。这里需要说明的是，Session管理Transactions不使用两阶段提交算法（two-phase commit algorithm）。举个例子，如果一个多repository 的Transaction，如果其中的一个repository已经commit了transaction，那么这个事务操作就会失败。还有Session Transaction和Session Manager Transaction是不同的。IDfSession接口通过beginTran来启动事务，IDfSessionManager接口通过beginTransaction方法来启动事务，但是beginTransaction方法启动的是一个受管制的事务，只有在beginTransaction方法调用之后获得的session才能参与Transaction，否则就不行。
每一个DFC Client应用的功能，和复杂度是随着业务需求而变化的。但是DFC Client处理session的典型过程是固定的：
1． 获得一个DFC Client对象
2． 取得一个Session Manager的实例
3． 通过Session Manager注册一个访问repository的用户帐号
4． 取得操作repository的一个DFC session
5． 对repository执行业务功能
6． 释放session回Session Manager
7． 销毁Session Manager

在WDK应用中，可以通过SessionManagerHttpBinding.getSessionManager()方法来得到一个Session Manager实例，但是如果我们在WDK应用中需要得到一个IDfSession来处理业务，那么我们应该使用WDK提供的component类的getDfSession方法，而不是从Session Manager里获得。原因是我们不应该让SysObject存在于多个request/response周期，而从Component里得到的session所获得的对象的生存周期只有一个request/response周期。

接口IDfClientX
.IDfClientX

语法
public interface .IDfClientX
描述
IDfClientX接口提供了一组工厂方法，这些方法列举了其他对象，例如IDfClient，它使JAVA与COM程序通信成为了可能。我们可以通过new DfClientX()来创建一个IDfClientX对象。
主要成员变量

主要成员方法
getLocalClient ()
目的 IDfClient对象的工厂方法
语法 public IDfClient getLocalClient() throws DfException
描述 通过返回一个DFC本地客户对象来调用DMCL40.dll跟Documentum Server进行通信。在程序中可以多次使用这个方法。
参数
返回 IDfClient对象
示例 下面的示例为实例化一个IDfClient对象
IDfClientX clientx = new DfClientX();
IDfClient client = clientx.getLocalClient();

getQuery ()
目的 IDfQuery对象的工厂方法
语法 public IDfQuery getQuery()
描述 构造了一个IDfQuery对象来进行对Documentum Server的DQL查询。
参数
返回 IDfQuery对象
示例 下面的示例为通过IDfQuery执行DQL查询
IDfCollection col = null; //Collection for the result
IDfClientX clientx = new DfClientX();
IDfQuery q = clientx.getQuery(); //Create query object
q.setDQL(queryString); //Give it the query
col = q.execute(session, IDfQuery.DF_READ_QUERY);

getLoginInfo ()
目的 IDfLoginInfo对象的工厂方法
语法 public IDfLoginInfo getLoginInfo()
描述 构造了一个IDfLoginInfo空对象，设置登录到Documentum Server的连接信息。
参数
返回 IDfLoginInfo对象
示例 参考接口IDfClient 的getLocalClient方法
com.documentum.fc.client
接口IDfClient
com.documentum.fc.client.IDfClient

语法
public interface com.documentum.fc.client.IDfClient
描述
IDfClient接口提供
session管理功能
设定Principal Support mode，如果需要single login的话。
查询connection broker
获得DBOR管理对象
主要成员变量

主要成员方法
newSessionManager()
目的 IDfSessionManager对象的工厂方法
语法 public IDfSessionManager newSessionManager ()
描述 返回一个IDfSessionManager对象。
参数
返回 IDfSessionManager对象
示例 下面的示例为获得一个IDfSessionManager对象
IDfSessionManager createSessionManager(String repository,
String user, String password) throws Exception {

IDfClientX clientx = new DfClientX();
IDfClient client = clientx.getLocalClient();

//IDfTypedObject config = client.getClientConfig();
//config.setString ("primary_host", "192.168.41.128");

IDfSessionManager sMgr = client.newSessionManager();
IDfLoginInfo loginInfo = clientx.getLoginInfo();
loginInfo.setUser(user);
loginInfo.setPassword(password);
sMgr.setIdentity(repository, loginInfo);

return sMgr;
}

getDocbaseMap()
目的 从connection broker里获得repository信息
语法 public IDfDocbaseMap getDocbaseMap() throws DfException
描述 这个方法返回一个拥有the repository IDs, repository names, and verbose repository descriptions的IDfDocbaseMap对象。
参数
返回 IDfDocbaseMap对象
示例 下面的示例为获得一个repository map
void obtainDocbaseMap() throws Exception {
IDfClientX clientx = new DfClientX();
IDfClient client = clientx.getLocalClient();
IDfDocbaseMap myMap = client.getDocbaseMap();
System.out.println("Repositories for connection broker: " + myMap.getHostName());
System.out.println("Total number of Repositories: " + myMap.getDocbaseCount());
for(int i = 0; i < myMap.getDocbaseCount(); i++) {
System.out.println("Repository " + (i + 1) + ": " + myMap.getDocbaseName(i));
}
}

getClientConfig()
目的 返回DMCL library的信息
语法 public IDfTypedObject getClientConfig() throws DfException
描述 client配置信息存储在DMCL API Config object里面，通过调用这个方法来得到配置信息，来修改client配置信息，需要注意的是，这个修改是进程相关的，不会影响其他进程上的session。
参数
返回 client配置信息的IDfTypedObject对象
示例 下面的示例为获得client配置信息，并修改一个名称为primary_host的属性
IDfClientX clientx = new DfClientX();
IDfClient client = clientx.getLocalClient();

IDfTypedObject config = client.getClientConfig();
config.setString ("primary_host", "192.168.1.4");

com.documentum.fc.client
接口IDfSessionManager
com.documentum.fc.client.IDfSessionManager

语法
public interface com.documentum.fc.client.IDfSessionManager
描述
IDfSessionManager接口管理identities，sessions和transactions
主要成员变量

主要成员方法
setIdentity(String docbase, IDfLoginInfo identity)
目的 设置用户验证的身份
语法 public void setIdentity(String docbase, IDfLoginInfo identity) throws DfServiceException
描述 设置用户验证的身份，如果该身份已经存在于session中的话，会抛异常。
参数 docbase
Repository名
identity
已经设置了用户证明的IDfLoginInfo对象
返回
示例 参考接口IDfClient 的getLocalClient方法

getSession(String docbase)
目的 获得一个IDfSession对象
语法 public IDfSession getSession(String docbase) throws DfIdentityException,
DfAuthenticationException, DfPrincipalException, DfServiceException
描述 取得处理具体应用所需要的session信息，通过该方法可以多次恢复session。
参数 docbase
Repository名
返回 IDfSession对象
示例 下面的示例为获得一个IDfId对象
public IDfId getObjectId(String qual, String repo) throws DfException {
// Get a session from the session manager
// that comes from extending DfService
IDfSession s = getSession(repo);
if (s != null) {
// Use the session to get the ID of an
// object meeting the qualification
return s.getIdByQualification(qual);
} else {
return null;
}
}

release(IDfSession session)
目的 把session对象释放掉
语法 public void release(IDfSession session)
描述 释放session对象，如果你不再使用一个session对象的时候，应尽快调用这个方法把它释放掉。
参数 session
DFC session对象
返回
示例

com.documentum.fc.client
接口IDfSession
com.documentum.fc.client.IDfSession

语法
public interface com.documentum.fc.client.IDfSession
描述
IDfSession接口封装了Documentum Repository的session对象，Client可以通过这个接口来执行Repository操作，查询Repository信息，取得存储在Repository里的持久化对象。
主要成员变量

主要成员方法
getObject(IDfId objectId)
目的 返回一个Repository对象
语法 public IDfPersistentObject getObject(IDfId objectId) throws DfException
描述 通过对象ID来得到一个持久化对象。
参数 objectId
包含object ID的一个IDfId对象
返回 IDfPersistentObject对象
示例 下面的示例为通过对象ID来得到一个持久化对象
IDfId myId = clientx.getId("0900d5bb8001fd00");
IDfSysObject sysObj = (IDfSysObject) session.getObject(myId);
String myName = sysObj.getObjectName();

disconnect()
目的 切断一个DFC session连接
语法 public void disconnect() throws DfException
描述 切断一个DFC session连接，如果结下来仍在使用这个session，就会抛出IDfException.DM_DFCSESS_E_DISCONNECTED这个异常。
参数
返回
示例 下面的示例为执行整个IDfSession操作的过程
//create clientx and client objects
IDfClientX clientx = new DfClientX();
IDfClient client = clientx.getLocalClient();

IDfLoginInfo loginInfoObj = clientx.getLoginInfo();
loginInfoObj.setUser(user);
loginInfoObj.setPassword(password);
loginInfoObj.setDomain(null);

//create a session using newSession
IDfSession session = client.newSession(strDocbaseName, login);

//access the Docbase here

//disconnect from the session
session.disconnect();
if (!session.isConnected()) {
// Successfully disconnected...
}

getRunnableProcesses(String additionalAttributes)
目的 返回repository里所有已安装的dm_process对象的object_name和r_object_id属性集合
语法 public IDfCollection getRunnableProcesses(String additionalAttributes) throws DfException
描述 返回repository里所有已安装的dm_process对象的object_name和r_object_id属性集合，在repository里，workflow是定义在dm_process对象里的，适用前必须确保它合法和已安装。
参数 additionalAttributes
添加你想得到的其他dm_process对象的属性
返回 repository里所有已安装的dm_process对象的object_name，r_object_id和用户指定的属性集合
示例 下面的示例为打印指定repository的所有已安装的workflow
IDfCollection Workflows = session.getRunnableProcesses("");
while ( Workflows.next() )
{
IDfTypedObject Next = Workflows.getTypedObject();
java.util.Enumeration e = Next.enumAttrs();

while ( e.hasMoreElements() )
{
IDfAttr NextAttr = (IDfAttr)e.nextElement();
System.out.print( NextAttr.getName() + " = " );
int AttrCount = 0;
if ( NextAttr.isRepeating() )
AttrCount = Next.getValueCount( NextAttr.getName() );
else
AttrCount = 1;
for (int i=0; i < AttrCount; i++)
{
// Get the next value!
IDfValue NextAttrValue = Next.getRepeatingValue
( NextAttr.getName(), i );
System.out.print( NextAttrValue );
System.out.print( ", " );
}
}
}

newWorkflowBuilder(IDfId processId)
目的 创建一个workflow builder对象
语法 public IDfWorkflowBuilder newWorkflowBuilder(IDfId processId) throws DfException
描述 创建一个workflow builder对象，workflow builder对象能够把dm_process对象转换成dm_workflow对象。
参数 processed
你想追加到workflow builder对象上去的dm_process 对象ID
返回 IDfWorkflowBuilder接口
示例 参考IDfWorkflowBuilder接口的initWorkflow方法示例

三．Type Related Interface
这一部分介绍的接口是类型相关的，这一部分接口是可以被继承的，下图描述了所有类型相关的接口的继承关系。

图2 Type Related Interface Hierarchy and Object Hierarchy

观察上面这张图，这些类型相关的接口基本都能与Documentum的具体Object Type联系起来。这里最重要的一个类型相关接口是IDfSysObject，它提供很多功能相关的方法。
1． 属性相关
2． 内容管理相关（checkin，lock等，接口IDfOperation也能执行这些操作）
3． 内容相关（取得内容路径，存储类型等）
4． 版本相关（控制版本树，标记版本等）
5． 链接/引用相关（控制对象间关系）
6． ACL相关（对象权限控制）
7． Lifecycle相关（对象生命周期控制）
8． VDM相关（虚拟文档管理）
9． Alias相关（别名控制）
10． Events相关（事件注册、注销等）
11． 其他（工作流，日志等）
上面有几个功能相关的方法都涉及到Documentum本身的一些设计模型，比如版本控制模型，ACL模型，了解这些模型的内涵，对实际的应用是有很大的作用的。
在上面这个图中。可以发现，与工作流相关的对象有好几个IDfWorkflow，IDfWorkItem，IDfWorkflowAttachment，IDfProcess。如果要执行一个Workflow，还需要其他的接口，下面描述一下完整的执行一个工作流模版的过程。
创建一个Workflow实例 使用IDfWorkflowBuilder接口将一个工作流
模版（dm_process）转化成一个工作流对象
（dm_workflow）

处理Alias sets 从Workflow获得一个IDfAliasSet对象

处理Package和Activity 从IDfWorkflowBuilder获得Activity集合
添加Package给Activity

Inbox处理 需要用到IDfWorkItem接口

com.documentum.fc.client
接口IDfTypedObject
com.documentum.fc.client.IDfTypedObject

语法
public abstract interface com.documentum.fc.client. IDfTypedObject
描述
IDfTypedObject接口提供所有类型对象的基本操作。
主要成员变量

主要成员方法
getObjectId()
目的 返回对象的object ID
语法 public IDfId getObjectId() throws DfException
描述 取得对象的object ID。
参数
返回 拥有object ID的IDfId对象
示例

com.documentum.fc.client
接口IDfPersistentObject
com.documentum.fc.client.IDfTypedObject
com.documentum.fc.client.IDfPersistentObject

语法
public abstract interface com.documentum.fc.client.IDfPersistentObject
extends com.documentum.fc.client. IDfTypedObject
描述
IDfPersistentObject接口提供了一些与持久对象进行交互所必需的基本功能，还提供验证，对象关联，审计相关的方法。
主要成员变量

主要成员方法
destroy()
目的 从Repository移除对象
语法 public void destroy() throws DfException
描述 使用该方法可以从Repository移除对象，但是该方法不能销毁多版本的对象。
参数
返回
示例 下面的示例为从Repository中移除一个对象
IDfId myId = clientx.getId("09...1");
IDfPersistentObject perObj = session.getObject(myId);
//can also call destroyAllVersions()
perObj.destroy();

fetch()
目的 从Repository取得一个对象，且不锁定该对象
语法 public boolean fetch(String internalType) throws DfException
描述 使用该方法可以从Repository取得一个当前版本的对象，你必须拥有browse permission来调用它，并且无法使用checkin方法更新源对象。
参数 internalType
对象的object type，例如如果fetch的是document对象，输入dm_document，这是一个可选参数，不使用就输入null
返回 true，如果在Server找到一个新版本的对象
false，如果在Serve没有找到一个新版本的对象
示例

save()
目的 保存一个对象到Repository
语法 public void save() throws DfException
描述 对一个对象使用该方法，你必须对该对象拥有write permission。该方法一般使用在创建一个新的对象。也可以使用在版本不发生变化的更新操作。
参数
返回
示例 下面的示例为在Repository创建一个对象
IDfFolder folder = (IDfFolder) session.newObject("dm_folder");
folder.setObjectName(DIR_NAME);
folder.link("/Temp");
folder.save();

com.documentum.fc.client
接口IDfSysObject
com.documentum.fc.client.IDfTypedObject
com.documentum.fc.client.IDfPersistentObject
com.documentum.fc.client.IDfSysObject

语法
public abstract interface com.documentum.fc.client.IDfSysObject
extends com.documentum.fc.client.IDfPersistentObject
描述
IDfSysObject接口提供了与Repository里的"dm_sysobject"对象进行交互所必需的功能，它扩展了IDfPersistentObj