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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `GENERATE_RESOURCE_FORK`
  A resource fork will be generated if it is not explicitly available.
  `static final int`
  `IGNORE_RESOURCE_FORK`
  Resource fork information will not be used even if resource fork is available
  `static final int`
  `REQUIRE_RESOURCE_FORK`
  Resource fork is required.
  `static final int`
  `RESOURCE_FORK_UNDEFINED`
  This is the default value returned when no mac option is set explicitly.
  `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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `abort()`
  Abort the operation.
  `IDfOperationNode`
  `add(Object newObject)`
  Adds an object to the operation and returns an operation node for the newly added object.
  `boolean`
  `areDisabledRegistryUpdates()`
  `boolean`
  `canUndo()`
  Indicates whether the operation can be undone.
  `void`
  `disableRegistryUpdates(boolean disableRegistryUpdates)`
  Specifies whether information about object and its associated file should be maintained in the registry.
  `void`
  `enablePopulateWithReferences(boolean shouldPopulateWithReferences)`
  Specifies whether reference objects should be dereferenced during population i.e. when files/objects are added to the operation.
  `boolean`
  `execute()`
  Execute the operation.
  `IDfOperationContext`
  `getContext()`
  Gets operation context for this operation instance
  `String`
  `getDescription()`
  Returns the description of the operation.
  `IDfList`
  `getErrors()`
  Returns the list of operation errors.
  `String`
  `getName()`
  Returns the name of the operation (e.g.
  `IDfList`
  `getNodes()`
  Returns the list of all operation nodes.
  `IDfOperationMonitor`
  `getOperationMonitor()`
  `String`
  `getOperationType()`
  Returns the type of the operation.
  `IDfProperties`
  `getProperties()`
  Returns the properties of the operation.
  `IDfList`
  `getRootNodes()`
  Returns a list of the root level nodes of the operation.
  `IDfSession`
  `getSession()`
  Returns session to be used during operation execution
  `IDfList`
  `getSteps()`
  Returns the list of operation steps.
  `boolean`
  `isAborted()`
  Indicates that the operation terminated early as the result of an abort being returned from the progress monitor.
  `boolean`
  `isEnabledPopulateWithReferences()`
  `void`
  `logError(IDfOperationError error)`
  Records an operation error.
  `void`
  `removeNode(IDfOperationNode nodeToRemove)`
  Removes an operation node (and its descendants) from the operation.
  `void`
  `reportError(IDfOperationNode node, int errorCode, String message, IDfException dfException)`
  Report an error.
  `void`
  `resetErrors()`
  Clears any logged errors for this operation.
  `IDfOperationMonitor`
  `setOperationMonitor(IDfOperationMonitor monitor)`
  Sets the interface to be used to monitor events in the operation.
  `void`
  `setSession(IDfSession session)`
  Sets the session that will be used during operation execution.
  `boolean`
  `succeeded(Object object)`
  Check if the operation succeded for the specified object.

- ## 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

- ## 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:
      - `IDfSession`

  - ### 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:
      - `IDfSession`