DFC接口手册 V10.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 sessionsDocumentum采用的是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 credentials2 Authenticate user access3 Acquire and release sessions4 Process Transactions5 Authenticate user access6 Obtain session statistics7 Catch checked and unchecked ExceptionsSession 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 session5 对repository执行业务功能6 释放session回Session Manager7 销毁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, 28);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, );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中的话，会抛异常。参数docbaseRepository名identity已经设置了用户证明的IDfLoginInfo对象返回示例参考接口IDfClient 的getLocalClient方法getSession(String docbase)目的获得一个IDfSession对象语法public IDfSession getSession(String docbase) throws DfIdentityException,DfAuthenticationException, DfPrincipalException, DfServiceException描述取得处理具体应用所需要的session信息，通过该方法可以多次恢复session。参数docbaseRepository名返回IDfSession对象示例下面的示例为获得一个IDfId对象public IDfId getObjectId(String qual, String repo) throws DfException / Get a session from the session manager/ that comes from extending DfServiceIDfSession s = getSession(repo);if (s != null) / Use the session to get the ID of an/ object meeting the qualificationreturn s.getIdByQualification(qual); else return null;release(IDfSession session)目的把session对象释放掉语法public void release(IDfSession session)描述释放session对象，如果你不再使用一个session对象的时候，应尽快调用这个方法把它释放掉。参数sessionDFC 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的所有已安装的workflowIDfCollection 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() );elseAttrCount = 1;for (int i=0; i 0) String strTemp = clientx.ByteArrayInputStreamToString(bais);getContentType()目的取得一个对象的内容文件格式语法public String getContentType() throws DfException描述返回一个对象的内容文件格式，就是说返回的是dm_sysobject对象的a_content_type属性。参数返回返回一个对象的内容文件格式示例下面的示例为复制了一个rendition IDfId myId = clientx.getId(09.1); IDfSysObject sysObj = (IDfSysObject)session.getObject(myId); IDfFormat myFormat = session.getFormat(document.getContentType(); String ext = myFormat.getDOSExtension(); String filePath = c:/temp/ + document.getObjectName() + . + ext;document.getFileEx2(filePath, document.getContentType(), 0, , false);setContentType(String contentType)目的设置一个对象的内容文件格式语法public void setContentType(String contentType) throws DfException描述设置一个对象的内容文件格式，这个对象必须是Documentum Server能够识别的。参数contentType内容文件格式，例如crtext是文本文件的格式，msw8是microsoft word文档的格式返回示例下面的示例为创建一个新对象到Repository document = (IDfDocument) session.newObject(dm_document); document.setObjectName(FILE_NAME); document.setContentType(crtext);/ add content to this dm_document document.setFile(c:/temp.txt);document.save();link(String folderSpec)目的关联对象到folder或者cabinet语法public void link(String folderSpec) throws DfException描述这个关联操作只有在执行save和checkin操作后才生效。参数folderSpec定义你想关联的folder，cabinet对象ID，或者是folder path返回示例下面的示例为移动一个对象 IDfId myId = clientx.getId(09.1); IDfSysObject sysObj = (IDfSysObject)session.getObject(myId); sysObj.unlink(/DFCSourceCab); sysObj.link(/DFCTargetCab); sysObj.save();unlink(String folderSpec)目的移除对象到folder或者cabinet的关联语法public void unlink(String folderSpec) throws DfException描述这个移除关联操作只有在执行save和checkin操作后才生效。参数folderSpec定义你想移除关联的folder，cabinet对象ID，或者是folder path返回示例参考link()checkin(boolean fRetainLock, String versionLabels)目的创建一个新版本的对象，解除给前一个版本所加的锁语法public IDfId checkin(boolean fRetainLock, String versionLabels) throws DfException描述创建一个新版本的对象，解除给前一个版本所加的锁，并且保证前面已经checkout该对象。参数fRetainLockTrue，给新创建的版本加锁False，不给新创建的版本加锁versionLabels给新版本创建一个新的字符标签，可以是一个或多个，如果不指定，则系统会默认赋CURRENT给它返回返回对象新版本的一个IDfId对象示例下面的示例为checkin指定的对象 IDfId myId = clientx.getId(09.1); IDfSysObject sysObj = (IDfSysObject)session.getObject(myI