EMC Documentums Foundation Classes (DFC)

Kamel BELGACEM S.C. Euroscript-Certitude S.R.L. December 2010

How to interact with content?

Using a Web Application

Documentum Administrator
Webtop
Using a Desktop Application
Documentum Composer: also a development tool
Using a Query Tool
IDQL: Interactive DQL
IAPI: Interactive API, became deprecated
Using a Custom Application
Using Documentum Foundation Classes (DFC)
Using Documentum Foundation Services (DFS)
Using an Integration Technology
Documentum Process Integrator
Documentum Foundation Classes

Set of Java classes (Java API)

Make server functionalities available to custom client
applications
May be considered as the Object-Relational-Mapper (ORM)
for programmatically accessing documents inside the
repository (the docbase)
DFC Hierarchy Diagram
Useful classes and interfaces

IDfClient
Establishes and manages session with server
Provides information about server

IDfCollection
Provides access to collection objects

IDfDocument
Provides functionality to interact with dm_document object

IDfFolder
Provides access to folder-related data stored in folders

IDfPersistentObject
Base class for all Documentum persistent objects
Useful classes and interfaces

IDfQuery
Provides functionality to run DQL queries against a repository

IDfSession
Encapsulates a session within Documentum repository

IDfSessionManager
Manages identities, pooled sessions and transactions

IDfSysObject
Provides functionality to interact with dm_sysobject object

IDfTypedObject
Provides basic operations for all typed objects
Setting up a DFC project

Use any IDE (Eclipse, Netbeans, JDeveloper, etc.)

Install/Get the frameworks

DFC framework
LOG4J (optional. Most known logging API for Java)

Link the JARs

dfc.jar
dfcbase.jar
log4j.jar (optional, if you want better logging)

Create and add to your project directory

config/ as a symbolic link to <dcmt-install>/config/
Log in/out of the DocBase

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

public class DFCTutorial {

private static final String DOCBASE = "(your docbase)";

private static final String USERNAME = "(your username)";
private static final String PASSWORD = "(your password)";

private IDfSessionManager sessionMgr = null;

private IDfSession session = null;

private void connect() throws Exception {

IDfClient client = DfClient.getLocalClient();
sessionMgr = client.newSessionManager();

IDfLoginInfo login = new DfLoginInfo();

login.setUser(USERNAME);
login.setPassword(PASSWORD);
login.setDomain(null);
sessionMgr.setIdentity(DOCBASE, login);

session = sessionMgr.newSession(DOCBASE);
}

private void disconnect() throws Exception {

sessionMgr.release(session); // Do not forget this everytime youre finished with sessions
}
}
Create a folder

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

public class DFCTutorial {

[...]
private static final String DIR_NAME = "SubDirectory";

private IDfFolder folder = null;

[...]

private void createFolder() throws Exception {

folder = (IDfFolder) session.newObject("dm_folder");

folder.setObjectName(DIR_NAME);
folder.link("/Temp");
folder.save();

System.out.println("Created folder: " + folder.getId("r_object_id"));

}
}
Create and link a document

[...]
public class DFCTutorial {
[...]
private static final String FILE_NAME = "Documentums D.F.C. Presentation";
private static final String DIR_PATH = "/Temp/" + DIR_NAME;

private IDfDocument document = null;

[...]

private void createDocument() throws Exception {

document = (IDfDocument) session.newObject("dm_document");

document.setObjectName(FILE_NAME);
document.setContentType("crtext");
document.setFile("F:/Presentation.pptx"); // Add content to this dm_document
document.save(); // Dont forget to save your modifications

System.out.println("Created file: " + document.getId("r_object_id"));

}

private void linkFileToFolder() throws Exception {

document.link(DIR_PATH);
document.save(); // Dont forget this
}
}
Modify a document (metadata)

[...]
public class DFCTutorial {
[...]
private static final String DOC_AUTHOR = "Kamel BELGACEM";
[...]

private void modifyDocument() throws Exception {

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".
}
}
Fetch folder content (using IDfFolder)

[...]
public class DFCTutorial {
[...]
private void fetchFolderContentUsingIDfFolder() throws Exception {
IDfFolder folder = session.getFolderByPath(DIR_PATH); // (!) Control the case when null

IDfCollection collection = null;

IDfDocument doc = null;
int count = 0;
try {
// Get all the documents inside the folder and iterate on them
collection = folder.getContents("r_object_id");
while (collection.next()) {
count++;
IDfId id = collection.getId("r_object_id");
doc = (IDfDocument) session.getObject(id);
System.out.println(id + ": " + doc.getObjectName());
}
} finally {
// ALWAYS! clean up your collections
if (collection != null) {
collection.close();
}
}
}
}
Fetch folder content (using DQL)

[...]
public class DFCTutorial {
[...]
private void fetchFolderContentUsingDQL() throws Exception {
String dqlString = "SELECT r_object_id, object_name FROM dm_document " +
"WHERE folder('" + DIR_PATH + "');";

IDfQuery query = new DfQuery();

query.setDQL(dqlString);

IDfCollection collection = null;

String docName = null;
int 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");
System.out.println(id + ": " + docName);
}
} finally {
// ALWAYS! clean up your collections
if (collection != null) {
collection.close();
}
}
}
}
Query documents (by path)

[...]
public class DFCTutorial {
[...]
private static final String FILE_PATH = DIR_PATH + "/" + FILE_NAME;
[...]

private void queryDocumentByPath() throws Exception {

// Get the file by path ...
IDfDocument doc = (IDfDocument) session.getObjectByPath( FILE_PATH);
// ... and start using it!
}

private void queryDocumentByDQL() throws Exception {

String dqlString = "SELECT r_object_id FROM dm_document"
+ " WHERE object_name = '" + FILE_NAME + "'"
+ " AND ANY authors = '" + DOC_AUTHOR + "'";

IDfQuery query = new DfQuery();

query.setDQL(dqlString);

IDfCollection collection = query.execute(session, IDfQuer y.DF_READ_QUERY);

try {
collection.next(); // Move the pointer to the first item
doc = (IDfDocument) session.getObject(collection.getI d("r_object_id"));
} finally {
// ALWAYS! clean up your collections
if (collection != null) {
collection.close();
}
}
}
}
Remove folders and documents

[...]
public class DFCTutorial {
[...]

private void removeDocument() throws Exception {

document.destroyAllVersions(); // Dont forget that versionning is enabled
}

private void removeFolder() throws Exception {

folder.destroyAllVersions(); // Dont forget that versionning is enabled
}
}
Best Practices for Resource Cleanup

The IDfCollection object

Similar to a java.sql.ResultSet object
Once opened, has to be closed
Number of collections opened is limited

The IDfSession object

Similar to a java.sql.Connection object
Opened and closed by IDfSessionManager
Dont forget to release the session once finished
Checkpoint

Say if these information are true or false:

IDfCollection objects are automatically closed
IDfSession objects have to be closed manually
We cannot fetch folder content using DQL. It should be performed
using IDfFolder object
Once a checkin() is performed, a save() has to be called otherwise
checkin is aborted
Disconnecting from the docbase is performed by closing all open
sessions
Checkpoint

What happens when running this method ?

private void updateAuthors() throws Exception {
IDfDocument doc = (IDfDocument) session.getObjectByPath(FILE_PATH);
int numAuthors = document.getAuthorsCount();
document.setAuthors(numAuthors, DOC_AUTHOR);
document.checkin(false, null);
}

Does this help to upload my XYZ.TXT document ?

private void uploadMyDocument() throws Exception {
IDfDocument document = new DfDocument();
document.setObjectName("My XYZ.TXT Document");
document.setContentType("crtext");
document.setFile("F:/XYZ.TXT");
}
Answers

Say if these information are true or false:

False: IDfCollection objects should be manually closed
True: IDfSession objects have to be closed manually
False: We can fetch folder content using DQL and IDfFolder object
False: checkin() uploads a new version of the document and its
metadata up-to-date, so no save() is required
True: Closing all sessions disconnects us from the docbase
Answers

This will raise an exception. Here's the correction:

private void updateAuthors() throws Exception {
IDfDocument doc = (IDfDocument) session.getObjectByPath(FILE_PATH);
document.checkout(); // Checking out a document before modification is required
int numAuthors = document.getAuthorsCount();
document.setAuthors(numAuthors, DOC_AUTHOR);
document.checkin(false, null);
}

No, it doesn't help since it raises an exception. Here's the

correction:
private void uploadMyDocument() throws Exception {
// We cannot instantiate (I)DfDocument, we need to pass by a builder (Session)
IDfDocument document = (IDfDocument) session.newObject("dm_document");
document.setObjectName("My XYZ.TXT Document");
document.setContentType("crtext");
document.setFile("F:/XYZ.TXT");
document.save(); // If you dont save the document, nothing will happen
}
Thank you very much!
V mulumesc !