public interface IDfOperation
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:
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 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()); }
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.// 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()); }
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:
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.// 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(); }
Modifier and Type | Field and Description |
---|---|
static int |
GENERATE_RESOURCE_FORK
A resource fork will be generated if it is not explicitly
available.
|
static int |
IGNORE_RESOURCE_FORK
Resource fork information will not be used even if resource fork is available
|
static int |
REQUIRE_RESOURCE_FORK
Resource fork is required.
|
static int |
RESOURCE_FORK_UNDEFINED
This is the default value returned when no mac option is set explicitly.
|
static 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
|
Modifier and Type | Method and Description |
---|---|
void |
abort()
Abort the operation.
|
IDfOperationNode |
add(java.lang.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
|
java.lang.String |
getDescription()
Returns the description of the operation.
|
IDfList |
getErrors()
Returns the list of operation errors.
|
java.lang.String |
getName()
Returns the name of the operation (e.g.
|
IDfList |
getNodes()
Returns the list of all operation nodes.
|
IDfOperationMonitor |
getOperationMonitor() |
java.lang.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,
java.lang.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(java.lang.Object object)
Check if the operation succeded for the specified object.
|
static final int RESOURCE_FORK_UNDEFINED
static final int IGNORE_RESOURCE_FORK
static final int USE_RESOURCE_FORK_IF_AVAILABLE
static final int REQUIRE_RESOURCE_FORK
static final int GENERATE_RESOURCE_FORK
IDfOperationNode add(java.lang.Object newObject) throws DfException
newObject
- object to be added to the operaiton
(e.g. IDfSysObject, file path, IDfVirtualDocument).DfException
java.lang.String getName() throws DfException
DfException
java.lang.String getOperationType() throws DfException
DfException
IDfList getRootNodes() throws DfException
DfException
IDfList getNodes() throws DfException
DfException
void removeNode(IDfOperationNode nodeToRemove) throws DfException
nodeToRemove
- node to remove from the operation.DfException
boolean execute() throws DfException
DfException
IDfList getErrors() throws DfException
DfException
IDfOperationContext getContext()
void resetErrors() throws DfException
DfException
IDfList getSteps() throws DfException
DfException
IDfProperties getProperties() throws DfException
"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.
DfException
void logError(IDfOperationError error) throws DfException
error
- error to be added to the list for the operation.DfException
void reportError(IDfOperationNode node, int errorCode, java.lang.String message, IDfException dfException) throws DfException
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.DfException
java.lang.String getDescription() throws DfException
DfException
boolean succeeded(java.lang.Object object) throws DfException
object
- specifies the object to test for success/failure.
The object can be IDfSysObject, IDfOperationNode or IDfOperationStep.DfException
void abort() throws DfException
DfException
IDfOperationMonitor getOperationMonitor()
IDfOperationMonitor setOperationMonitor(IDfOperationMonitor monitor) throws DfException
monitor
- interface to use monitor events in the operation.DfException
void disableRegistryUpdates(boolean disableRegistryUpdates)
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.boolean areDisabledRegistryUpdates()
boolean isEnabledPopulateWithReferences()
void enablePopulateWithReferences(boolean shouldPopulateWithReferences)
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.boolean isAborted()
boolean canUndo() throws DfException
DfException
IDfSession getSession() throws DfException
DfException
IDfSession
void setSession(IDfSession session) throws DfException
session
- session that will be used during operation executionDfException
IDfSession
Copyright 1994-2023 OpenText Corporation. All rights reserved.