DFC DfOperations Classes – Part 2

Before I get into specific implementations of DfOperation classes (next post), I want to give you a general overview of how operations are implemented.  Each operation class contains methods and attributes specific to its particular operation (e.g., checkout is different from move). However, they also share a lot of commonality (inherited from the DfOperation class).  Thus, the invocation of each operation class is basically the same:

  • Instantiate the class – instantiate an interface class for the operation you want to implement.  Operation classes are manufactured from the DfClientX factory classes (e.g., DfClientX.getXXXOperation() where XXX denotes a specific operation name).
  • Populate the operation class – populate the operation with the necessary objects, properties, and execution options.
  • Execute – run the operation.
  • Check for errors – check for errors that occurred during the execution of the operation.  Because operations can be run on multiple objects and not all objects might fail, errors are caught and handled internally as opposed to being thrown to the caller.  Errors should be checked and processed accordingly.
  • Process results – each operation returns different results that might require additional processing.  For example, the Checkin operation returns object ids for newly created objects.

The following pseudocode demonstrates the generic setup and execution of a DfOperation.  Note the use of XXX where specific operation names should be used.


try {
   // #1 - create a clientX factory object
   IDfClientX cx = new DfClientX();

   // #2 - manufacture a specific operation
   IDfXXXOperation opObj = cx.getXXXOperation();

   // #3 - add an object to the operation
  opObj.add(sObj);

   // #4 - execute the operation
   boolean result = opObj.execute();

   // #5 - check for errors
  if (!result) {
    IDfList errors = OpObj.getErrors();
    for (int i=0; i<errors.getCount(); i++) {
      IDfOperationError err = (IDfOperationError) errors.get(i);
      System.out.println("Error in operation: " + err.getErrorCode() + " - " + err.getMessage());
    }
  } else {

    // #6 - get new obj ids
    IDfList newObjs = checkoutOpObj.getNewObjects();
    for (int i=0; i<newObjs.getCount(); i++) {
      IDfSysObject sObj = (IDfSysObject) newObjs.get(i);
      System.out.println("\tnew object is " + sObj.getObjectId().toString());
  }
// #7 - exceptions
} catch(Exception e) {
    System.out.println("Exception in operation: " + e.getMessage());
    e.printStackTrace();
}

  1. Get an IDfClientX object.
  2. Get the specific operation object from the IDfClientX class.  The XXX represent the name of a real operation (found here).
  3. Add an object to operate on. In this example, I assume sObj (an IDfSysObject) was passed to this method. The object itself could represent a document, a folder, a virtual document, or an XML document depending upon the operation. The add() method must be called for each individual object, so if you pass this method an IDfList of objects, loop through them and add each one individually. The exception to this rule is if you add the root of a virtual document (as an IDfVirtualDocument), the add() method is smart enough to add all of its children also. The same is true for an XML document. Notice that the add() method wants an actual IDfSysObject and not an IDfID or String.
  4. Execute the operation.
  5. If an error occurred, the result of the execute() method will be false.  Errors are contained in an IDfList object. Remember that operations do not throw exceptions except for fatal errors.  All other exceptions are caught internally and stored as IDfOperationError objects in the IDfOperation object itself.  An error while processing one object in the operation does not necessarily terminate the operation for all the remaining objects.
  6. If the operation created new objects in the repository (e.g., checkin or copy), these objects are also stored in the operation object.  If the operation did not create new objects (e.g., move or delete), the method call is getObjects() (as opposed to getNewObjects() above) and returns the objects that the operation processed.
  7. Catch any fatal operation errors just in case.

Next week I’ll show you a sample implementation for the Checkout operation.

Advertisements

About Scott
I have been implementing Documentum solutions since 1997. In 2005, I published a book about developing Documentum solutions for the Documentum Desktop Client (ISBN 0595339689). In 2010, I began this blog as a record of interesting and (hopefully) helpful bits of information related to Documentum, and as a creative outlet.

2 Responses to DFC DfOperations Classes – Part 2

  1. Pingback: DFC DfOperations Classes – Part 3 « dm_misc: Miscellaneous Documentum Tidbits and Information

  2. Type Writer says:

    I’m trying to write a DFC app to do a checkout operation but I’m running into a NullPointerException on Step #3, i.e., where I add an object to the operation. Any pointers on how to debug that?

    Sheldon Robertson

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: