Package com.documentum.operations

Interface IDfOperation

All Known Subinterfaces:
IDfCancelCheckoutOperation, IDfCheckinOperation, IDfCheckoutOperation, IDfCopyOperation, IDfDeleteOperation, IDfExportOperation, IDfImportOperation, IDfMoveOperation, IDfPredictiveCachingOperation, IDfValidationOperation, IDfXMLTransformOperation
public interface IDfOperation
IDfOperation is the base class for all library service operations. The intent of operations is to simplify the processing of complex groups of documents. Operations support any combination of simple documents, virtual documents, compound documents (e.g. XML), and deep folder contents. Examples of operations include check in, check out, cancel checkout, import, export, copy, delete, and XML transformation and validation.

Each operation consists of one or more root nodes. Each node can have zero or more child nodes, and thus an operation can incorporate multiple graphs of objects. Operations account for an object appearing more than once in the graph through different paths, for example and object appearing more than once in a check in operation will only get checked in once.

Nodes are created by calling IDfOperation.add(). The types of objects that can be added varies from operation to operation. If a simple document (IDfSysObject) is added to an operation, then a single node will be created in the operation and returned by the add() method call. If a virtual document is added to an operation (IDfVirtualDocument), then the node returned from the add() method will represent the root of the virtual document in the operation. The method IDfOperationNode.getChildren() can then be used to return the first level of children under the root node, and this can be done recursively for all nodes until the leaves of the virtual document are reached.

Objects in an operation are processed as a group, with the operation invoking multiple individual DFC calls for each object to carry out the purpose of the operation. An operation encapsulates documentum client conventions such as the registration of checked out objects and local content file naming and management.

Operations provide distributed support. Objects from multiple docbases may be processed within a single operation.

To use an operation, construct it, populate it with docbase objects using the add() method, set any required options (e.g. session, destination folder) then call execute(). Execute will return false if any errors occurred, and you can use getErrors() to obtain a list of failures.

Unlike other areas of DFC, operations rely on errors rather than throwing exceptions. Only a fatal condition will cause an exception to be thrown from an operation call. Exceptions are otherwise caught internally and stored as an IDfOperationError. An error during processing of one node in an operation does not have to terminate processing for the other remaining nodes in the operation. For example, if there are 100 objects to be checked out, and one of them raises an error, say due to permissions or perhaps the object is locked by another user, the other 99 objects can be still be checked out. When an operation completes, a list of errors is made available that indicates which nodes encountered failures. The calling program can then decide to either abort (undo) the operation, or accept the results for those objects that were processed successfully.

Calling programs can be notified of errors as they occur by creating a class that implements the IDfOperationMonitor interface and installing it through IDfOperation.setOperationMonitor(). An operation monitor is called as errors are encountered, allowing the monitor to decide whether processing should continue for remaining nodes or should be terminated. An operation monitor is also called with progress information; a message is sent to the monitor for every node as each step is executed.

Operations do not rely on docbase transactions. This is because they support distributed operations involving multiple docbases, they may potentially process a vast number of objects, and they manage non-database resources such as the system registry and the local file system. Most operations can be undone nonetheless by calling IDfOperation.abort(). The abort method is specific to each operation, but will generally undo docbase actions and clean up registry entries and local content files. Some operations cannot be undone once they have been executed, such as delete. If you know an operation only contains objects from a single docbase, and the number of objects being processed is reasonable enough to ensure sufficient database resources, you can wrap the operation execution in a transaction.

Operations are intended to be executed once. Once a step for an object in a given operation has been performed, executing that step again will not process the object a second time. After an operation has been executed, if you need to perform an additional operation, create a new operation, populate and execute it.

Here is an example of a simple checkout of one document:


 // Get the document we want to checkout.
 IDfSysObject simpleObject = (IDfSysObject) session.getObject("09...");

 // Create a checkout operation.
 IDfCheckoutOperation checkout = clientX.getOperation("Checkout");

 // Add the document to the checkout operation.
 checkout.add(simpleObject);

 // Checkout the document. Execute() runs all of the operation
 // steps in sequence.
 if(checkout.execute() == false)
        {
        // Display an errors encountered to the user.
        this.displayErrorList (checkout.getErrors());
        }
Note that the checkout operation sample above would have automatically obtained the lock on the document, setup a destination directory path to the normal documentum checkout directory, constructed a reasonable file name, avoided file system path collisions, downloaded the primary content file from the server, and added the checked out file to the system registry. Things are just as simple when operating upon a virtual document: 


 // Get the virtual document we want to check out.
 IDfVirtualDocument vdoc = new VirtualDocument("09...", "CURRENT");

 // Create a checkout operation.
 IDfCheckoutOperation checkout = clientX.getOperation("Checkout");

 // Add the virtual document to the checkout operation. Checkout
 // the whole virtual document, so start at the root node.
 checkout.add(vdoc.getRootNode());

 // Checkout the document.
 if(checkout.execute() == false)
        {
        // Display an errors encountered to the user.
        this.displayErrorList(checkout.getErrors());
        }
The example above would have expanded the operation to include each object in the virtual document. Again, each object would have been locked, its content file downloaded, and registered as a checked out item. If any of the nodes in the virtual document could not be checked out, an error would have been logged for that node; the checkout for the other nodes would have proceeded.

Clients of operations can exercise more control over the execution of an operation. For example, the execute() could be replaced with calls to the individual steps in the operation: 


 // Execute the checkout operation one step at a time
 // instead of calling execute().
 IDfList steps = checkout.getSteps();
 int stepCount = steps.getCount();
 for(int stepIndex = 0; stepIndex < stepCount; stepIndex++)
        {
        IDfOperationStep step = (IDfOperationStep) steps.get(stepIndex);
        System.out.println("Executing step: " + step.getName());
        step.execute();
        }
After any of the individual steps in the above example, a client could do error checking, could change attributes for the objects involved in the operation, etc.

  • Field Details

    • RESOURCE_FORK_UNDEFINED

      static final int RESOURCE_FORK_UNDEFINED
      This is the default value returned when no mac option is set explicitly.
      Since:
      5.2.5
      See Also:

    • IGNORE_RESOURCE_FORK

      static final int IGNORE_RESOURCE_FORK
      Resource fork information will not be used even if resource fork is available
      Since:
      5.2.5
      See Also:

    • USE_RESOURCE_FORK_IF_AVAILABLE

      static final int USE_RESOURCE_FORK_IF_AVAILABLE
      Resource fork will be used if: It is supplied by the caller during import and check in operations It is available in the docbase for export and check out operations
      Since:
      5.2.5
      See Also:

    • REQUIRE_RESOURCE_FORK

      static final int REQUIRE_RESOURCE_FORK
      Resource fork is required. An error will be generated if resource fork is not made available.
      Since:
      5.2.5
      See Also:

    • GENERATE_RESOURCE_FORK

      static final int GENERATE_RESOURCE_FORK
      A resource fork will be generated if it is not explicitly available.
      Since:
      5.2.5
      See Also:

  • Method Details

    • add

      IDfOperationNode add(Object newObject) throws DfException
      Adds an object to the operation and returns an operation node for the newly added object.
      Parameters:
      newObject - object to be added to the operaiton (e.g. IDfSysObject, file path, IDfVirtualDocument).
      Returns:
      operation node for added object, or null if the object could not be added.
      Throws:
      DfException

    • getName

      String getName() throws DfException
      Returns the name of the operation (e.g. Export).
      Returns:
      the name of the operation.
      Throws:
      DfException

    • getOperationType

      String getOperationType() throws DfException
      Returns the type of the operation. Examples include Checkout, Checkin, Import, Export, CancelCheckout, Copy, Move, Delete.
      Returns:
      the type of the operation.
      Throws:
      DfException

    • getRootNodes

      IDfList getRootNodes() throws DfException
      Returns a list of the root level nodes of the operation.
      Returns:
      a collection of IDfOperationNode objects.
      Throws:
      DfException

    • getNodes

      IDfList getNodes() throws DfException
      Returns the list of all operation nodes.
      Returns:
      a collection of all nodes in this operation..
      Throws:
      DfException

    • removeNode

      void removeNode(IDfOperationNode nodeToRemove) throws DfException
      Removes an operation node (and its descendants) from the operation.
      Parameters:
      nodeToRemove - node to remove from the operation.
      Throws:
      DfException

    • execute

      boolean execute() throws DfException
      Execute the operation. Performs all of the operation steps in sequence. Throws an exception only if the operation is aborted due to a fatal error. Non-fatal error information can be obtained through getErrors().
      Returns:
      true if operaiton succeeds without error, false if errors occurred.
      Throws:
      DfException

    • getErrors

      IDfList getErrors() throws DfException
      Returns the list of operation errors. Returns null if no errors have occurred since the last resetErrors() call.
      Returns:
      list of IDfOperationError objects or null if no errors have occurred.
      Throws:
      DfException

    • getContext

      IDfOperationContext getContext()
      Gets operation context for this operation instance
      Returns:
      static context provided at the time of instantiation of the operation.

    • resetErrors

      void resetErrors() throws DfException
      Clears any logged errors for this operation.
      Throws:
      DfException

    • getSteps

      IDfList getSteps() throws DfException
      Returns the list of operation steps.
      Returns:
      list of IDfOperationStep objects required to execute the operation.
      Throws:
      DfException

    • getProperties

      IDfProperties getProperties() throws DfException
      Returns the properties of the operation. Most properties of an operation are considered internal implementation details. However, there are a couple of special properties you may wish to manipulate. Please note that, while Documentum strives for release to release compatibility for properties, they are more subject to change than are the DFC COM interfaces. The properties listed here will likely migrate to the official COM interfaces in future DFC releases. 

      
 "RecordInlineDescendants" - This is a Boolean property of the operation. The property
 specifies whether or not registry entries will be made to record inline XML component
 chunks. The advantage of recording these registry entries is that it affords protection
 from checking in or canceling the checkout of child, inline XML chunks. When this property
 is true, check in and cancel checkout operations will error out if an inline XML chunk
 is operated on outside of the root level XML instance. Performance, particularly
 in server-based, non-client oriented, or lage scale XML processing may be improved with this sanity
 checking disabled, as there may be many inline chunks per XML instance. The default value
 for this property is 'true' for all Windows based platforms, and 'false' for Unix platforms.

 "DisableRegistryUpdates" - This is a Boolean property of the operation. The property specifies
 whether or not registry entries will be made. The advantage of disabling the registry updates is
 that no registry access is required. Performance, particularly
 in server-based, non-windows, non-client oriented, or lage scale XML processing may be improved with
 this seting turned on(i.e., "DisableRegistryUpdates" value set to true).
 Note that if registry update is disabled then file path for the object needs to be specified explicitly
 during check in operation.
 The default value for this property is 'false' for all platforms.
      Returns:
      list of IDfOperationStep objects required to execute the operation.
      Throws:
      DfException

    • logError

      void logError(IDfOperationError error) throws DfException
      Records an operation error.
      Parameters:
      error - error to be added to the list for the operation.
      Throws:
      DfException

    • reportError

      void reportError(IDfOperationNode node, int errorCode, String message, IDfException dfException) throws DfException
      Report an error.
      Parameters:
      node - node in which the error occurred.
      errorCode - code describing the type of error.
      message - textual message describing the error condition.
      dfException - exception that triggered the error.
      Throws:
      DfException

    • getDescription

      String getDescription() throws DfException
      Returns the description of the operation.
      Returns:
      description of the operation.
      Throws:
      DfException

    • succeeded

      boolean succeeded(Object object) throws DfException
      Check if the operation succeded for the specified object. The object can be IDfSysObject,IDfOperationNode or IDfOperationStep.
      Parameters:
      object - specifies the object to test for success/failure. The object can be IDfSysObject, IDfOperationNode or IDfOperationStep.
      Returns:
      true if operation succeeded on the object else false.
      Throws:
      DfException

    • abort

      void abort() throws DfException
      Abort the operation. Can be called after the exeucte method of the operation or any step to abort and rollback the operation. Aborted operations will have all changes reverted. Not all operations can be aborted. Check the canUndo method of the operation to determine if an operation can be undone. This method does nothing if this specific operation cannot be undone. This method may only be called when no operation code is executing, that is when outside of any execute() call.
      Throws:
      DfException

    • getOperationMonitor

      IDfOperationMonitor getOperationMonitor()

    • setOperationMonitor

      IDfOperationMonitor setOperationMonitor(IDfOperationMonitor monitor) throws DfException
      Sets the interface to be used to monitor events in the operation.
      Parameters:
      monitor - interface to use monitor events in the operation.
      Returns:
      the operation monitor that was previously in effect.
      Throws:
      DfException

    • disableRegistryUpdates

      void disableRegistryUpdates(boolean disableRegistryUpdates)
      Specifies whether information about object and its associated file should be maintained in the registry. The information in registry is used during execution of some operations. For e.g., during check in operation, the location of the check in file is obtained from registry. However, when the user does want DFC to store the information in registry, he can call this method with 'true'. In such cases, user will need to furnish the information explicitly to the operation. For e.g., during check in of the object, user will need to provide location of the check in file explicitly.
      Parameters:
      disableRegistryUpdates - true indicates that various information about the object and its related file should be maintained in the registry. false indicates that the information about the object and its related file should be maintained in the registry. The default is false.

    • areDisabledRegistryUpdates

      boolean areDisabledRegistryUpdates()

    • isEnabledPopulateWithReferences

      boolean isEnabledPopulateWithReferences()

    • enablePopulateWithReferences

      void enablePopulateWithReferences(boolean shouldPopulateWithReferences)
      Specifies whether reference objects should be dereferenced during population i.e. when files/objects are added to the operation. True will indicate that the reference objects themseleves will be added to the operation. False will indicate that reference objects will be dereferenced and the remote object will be added to the operation. The default is false.
      Parameters:
      shouldPopulateWithReferences - true will indicate to add reference object to the operation. false will indicate to dereference the reference object and add remote object to the operation. The default is false.

    • isAborted

      boolean isAborted()
      Indicates that the operation terminated early as the result of an abort being returned from the progress monitor.
      Returns:
      true if the operation was aborted, false otherwise

    • canUndo

      boolean canUndo() throws DfException
      Indicates whether the operation can be undone. The operations that can be undone are import, check out, copy and move.
      Returns:
      true if the operation can be undone, false otherwise.
      Throws:
      DfException

    • getSession

      IDfSession getSession() throws DfException
      Returns session to be used during operation execution
      Returns:
      session that will be used during operation execution
      Throws:
      DfException
      See Also:

    • setSession

      void setSession(IDfSession session) throws DfException
      Sets the session that will be used during operation execution.
      Parameters:
      session - session that will be used during operation execution
      Throws:
      DfException
      See Also: