Package Com.bluefish.dfc.test; Import Junit.framework.testcase; Import Import Import Import Import Import

package com.bluefish.dfc.test; import junit.framework.TestCase; import import import import import import

com.documentum.fc.client.DfClient; com.documentum.fc.client.IDfClient; com.documentum.fc.client.IDfSession; com.documentum.fc.client.IDfSessionManager; com.documentum.fc.common.DfLoginInfo; com.documentum.fc.common.IDfLoginInfo;

public class Dfc5BaseTest extends TestCase { // TODO: refactor to private static final private static final private static final

pull from a properties file String DOCBASE = "YOUR DOCBASE"; String USERNAME = "YOUR USERNAME"; String PASSWORD = "YOUR PASSWORD";

private IDfSessionManager sessionMgr = null; protected IDfSession session = null; protected void setUp() throws Exception { super.setUp(); IDfClient client = DfClient.getLocalClient(); sessionMgr = client.newSessionManager(); // Setup login details. IDfLoginInfo login = new DfLoginInfo(); login.setUser(USERNAME); login.setPassword(PASSWORD); login.setDomain(null); sessionMgr.setIdentity(DOCBASE, login); }

session = sessionMgr.newSession(DOCBASE);

protected void tearDown() throws Exception { super.tearDown(); if (session != null) { sessionMgr.release(session); } } protected void log(String message) { System.out.println(message); } }

And then I tested my login code with the following subclass: package com.bluefish.dfc.test; public class LoginTest extends Dfc5BaseTest {

public void testLogin() throws Exception { // login happens in setUp(), so nothing to do here assertNotNull("session is null", session); } }

There are a couple of important points regarding the above code samples: •

Be sure always to clean up your IDfSessions when you're finished with them.

•

If available, always use the session manager to access and release sessions.

Prior to DFC 5.x, there wasn't an IDfSessionManager and the developer was required to call IDfSession.disconnect() whenever a session was no longer needed. However, the IDfSessionManager supports session pooling, so it is critical that any session acquired through a session manager is released through that session manager as well. Otherwise, bad things can happen and probably will. This is typical Object/Relational Mapper design, so those familiar with a similar persistence framework should find the transition rather painless.

Overview of Documentum Foundation Classes (DFC) DFC's object model for managing docbase objects is a deep and complex hierarchy, but we can get started with the basics by looking at only a small subset of these classes: *Arrows represent object inheritance levels. IDfClient IDfSessionManager IDfSession IDfQuery IDfTypedObject --> IDfCollection IDfPersistentObject --> IDfSysObject --> IDfFolder IDfDocum

ent

We've already been introduced to IDfClient, IDfSessionManager, and IDfSession in the previous section. So what are the remaining classes used for? The DFC Javadoc describes them as follows: Class

Description

IDfClient

This interface provides functionality to establish and manage sessions with a Documentum server, and provides information about the server before a session is established.

IDfCollect This interface provides access to collection objects. ion IDfDocum This class provides the functionality for the client to interact with ent "dm_document" objects in the repository. IDfFolder

This interface provides access to folder-related data stored in folder objects.

IDfPersist This interface extends IDfTypedObject and is the base class for all entObject Documentum persistent objects. IDfQuery

This interface provides functionality for running queries against a repository.

IDfSession This interface encapsulates a session with a Documentum repository. IDfSession Manages identities, pooled sessions, and transactions. Manager IDfSysObj This class provides the functionality for the client to interact with ect "dm_sysobject" objects in the repository. IDfTyped Object

This interface provides basic operations for all typed objects.

We'll get a better understanding once we see them in action, so let's put them to use.

CRUD: Create, Read, Update, and Delete Finally, it's time to do what we all love: Write code. Let's revisit our chosen exercises: •

Create folder

•

Create file

•

Link file to folder

•

Modify file

•

Fetch folder contents

•

Query files by attribute (name and author)

•

Delete file

•

Delete folder

I've created a single test case class, DfcCrudTest.java, with test methods present for each of our exercises. For some of our exercises, there turned out to be more than one viable

way of accomplishing our goal. For example, to obtain a folder's contents, you can perform a simple DQL query, or if you have a handle on the IDfFolder object, you can call the getContents(..) method on the folder object. To demonstrate this, I included both options within my testFolderContents() method. Please keep in mind that these tests are written for clarify, not for optimal design. package com.bluefish.dfc.test; import import import import import import

com.documentum.fc.client.DfQuery; com.documentum.fc.client.IDfCollection; com.documentum.fc.client.IDfDocument; com.documentum.fc.client.IDfFolder; com.documentum.fc.client.IDfQuery; com.documentum.fc.common.IDfId;

public class DfcCrudTest extends Dfc5BaseTest { private private private and DQL.txt"; private FILE_NAME; private

static String DIR_NAME = "Subdir"; static String DIR_PATH = "/Temp/" + DIR_NAME; static String FILE_NAME = "Getting Started with DFC static String FILE_PATH = DIR_PATH + "/" + static String DOC_AUTHOR = "Steve McMichael";

private IDfFolder folder; private IDfDocument document; public void testSimpleDfc() throws Exception { initialize(); // tests are order dependent createFolder(); createFile(); linkFileToFolder(); modifyFile(); fetchFolderContents(); queryFiles(); deleteFile(); deleteFolder(); } private void createFolder() throws Exception { log("** Testing folder creation"); folder = (IDfFolder) session.newObject("dm_folder"); folder.setObjectName(DIR_NAME); folder.link("/Temp"); folder.save(); log("created folder " + folder.getId("r_object_id"));

assertEquals("unexpected folder path", DIR_PATH, folder.getFolderPath(0)); } private void createFile() throws Exception { log("** Testing file creation"); document = (IDfDocument) session.newObject("dm_document"); document.setObjectName(FILE_NAME); document.setContentType("crtext"); document.setFile("E:/clipboard.txt"); // add content to this dm_document document.save(); log("created file" + document.getId("r_object_id")); } private void linkFileToFolder() throws Exception { log("** Testing file linking to folder"); document.link(DIR_PATH); document.save(); log(FILE_PATH); assertNotNull("unexpected folder path", session.getObjectByPath( FILE_PATH)); } private void modifyFile() throws Exception { log("** Testing file modification"); document.checkout(); int numAuthors = document.getAuthorsCount(); document.setAuthors(numAuthors, DOC_AUTHOR); //doc.checkin(false, "Prevents promotion to CURRENT"); document.checkin(false, null); // When a null version label is provided, // DFC automatically gives the new version // an implicit version label (1.1, 1.2, etc.) // and the symbolic label "CURRENT". } private void fetchFolderContents() throws Exception { log("** Testing folder contents"); // (1) Fetch using IDfFolder object IDfFolder folder = session.getFolderByPath(DIR_PATH); assertNotNull("folder is null", folder); IDfCollection collection = null; IDfDocument doc = null; int count = 0; try {

collection = folder.getContents("r_object_id"); while (collection.next()) { count++; IDfId id = collection.getId("r_object_id"); doc = (IDfDocument) session.getObject(id); log(id + ": " + doc.getObjectName()); } } finally { // ALWAYS! clean up your collections if (collection != null) { collection.close(); } } count);

assertEquals("wrong number of files in folder", 1,

assertEquals("unexpected doc name", FILE_NAME, doc.getObjectName()); // (2) Fetch using DQL folder(..) String dql = "SELECT r_object_id, object_name from dm_document where folder('"+DIR_PATH+"');"; // Or we can fetch the contents of our folder and all of its subfolders using // // folder('/Temp/Subdir', descend) // // But since we haven't added any subfolders, this will return the same set of dm_documents. // // String dql = "SELECT r_object_id, object_name from dm_document where folder('"+DIR_PATH+"', descend);"; IDfQuery query = new DfQuery(); query.setDQL(dql); collection = null; String docName = null; count = 0; try { collection = query.execute(session, IDfQuery.DF_READ_QUERY); while (collection.next()) { count++; String id = collection.getString("r_object_id"); docName = collection.getString("object_name"); log(id + ": " + docName); } } finally { // ALWAYS! clean up your collections if (collection != null) { collection.close(); } }

assertEquals("wrong number of files in folder", 1,

count);

assertEquals("unexpected doc name", FILE_NAME, docName); } private void queryFiles() throws Exception { log("** Testing file query"); // (1) load by path IDfDocument doc = (IDfDocument) session.getObjectByPath(FILE_PATH); assertNotNull("null doc returned", doc); assertEquals("unexpected doc name", FILE_NAME, doc.getObjectName()); // (2) load by query // NOTE: Authors is a "repeating attribute" in Documentum terminology, // meaning it is multi-valued. So we need to use the ANY DQL keyword here. doc = null; String dql = "SELECT r_object_id" + " FROM dm_document" + " WHERE object_name = '" + FILE_NAME + "'" + " AND ANY authors = '" + DOC_AUTHOR + "'"; IDfQuery query = new DfQuery(); query.setDQL(dql); IDfCollection collection = query.execute(session, IDfQuery.DF_READ_QUERY); try { assertTrue("query did not return any results", collection.next()); doc = (IDfDocument) session.getObject(collection.getId("r_object_id")); } finally { // ALWAYS! clean up your collections if (collection != null) { collection.close(); } } assertNotNull("null doc returned", doc); assertEquals("unexpected doc name", FILE_NAME, doc.getObjectName()); } private void deleteFile() throws Exception { if (document != null) { log("** Testing file deletion"); document.destroyAllVersions(); }

} private void deleteFolder() throws Exception { if (folder != null) { log("** Testing folder deletion"); folder.destroyAllVersions(); } }

this will

private void initialize() { // If something bad happened during the previous run, // make sure we're back in a good state for this test

run.

try { session.getObjectByPath(FILE_PATH).destroy(); } catch (Exception e) { // ignore } try { session.getObjectByPath(DIR_PATH).destroy(); } catch (Exception e) { // ignore } }

}