Enterprise Information Portal APIs

com.ibm.mm.sdk.common
Class DKDocRoutingServiceICM

java.lang.Object
  |
  +--com.ibm.mm.sdk.common.DKDocRoutingServiceICM
All Implemented Interfaces:
dkService, java.io.Serializable

public class DKDocRoutingServiceICM
extends java.lang.Object
implements dkService, java.io.Serializable

The DKDocRoutingServiceICM represents a document routing service in Content Manager.It provides the methods for managing a process including starting, terminating, continuing, suspending and resuming a process. It also provides helper methods for listing work packages based on various selection criteria.A document routing service can be established by sequentially performing the following two operations. 1. connecting to a datastore associated with a Content Manager version 8 library server and 2. instantiating a DKDocRoutingServiceICM object that allows access to the document routing APIs To perform CRUD (create, retrieve, update, delete) operations on work nodes, work lists and processes, the user will need to use the DKDocRoutingServiceMgmtICM helper class.

See Also:
DKDocRoutingServiceMgmtICM, Serialized Form

Constructor Summary
DKDocRoutingServiceICM(dkDatastore ds)
          Constructs and initializes a document routing service object associated with the specified datastore
 
Method Summary
 boolean checkOutItemInWorkPackage(java.lang.String workpackage_pid)
          Checks out the given item from the specified work package.
 DKHandle connection()
          Returns the connection handle for this document routing service.
 java.lang.String continueProcess(java.lang.String pidString, java.lang.String selection, java.lang.String owner)
          The continueProcess method will route the item referenced by the specified item persistent identifier (PID) in the specified work package from the current work node to the next work node as determined by the selection.
 java.lang.String continueProcess(java.lang.String pidString, java.lang.String selection, java.lang.String owner, dkCollection container_data)
          The continueProcess method will route the item referenced by the item persistent identifier (PID) in the specified work package from the current work node to the next work node that is determined by the selection.
 int getCount(java.lang.String worklist_name, java.lang.String owner)
          Retrieves the count of work packages in the specified work list for the specified owner.
 dkDatastore getDatastore()
          Retrieves a reference to the datastore object associated with this document routing service.
 DKDocRoutingServiceMgmtICM getDocRoutingServiceMgmt()
          Retrieves a reference to the document routing management helper object associated with this document routing service object.
 DKWorkPackageICM getNextWorkPackage(java.lang.String worklist_name, java.lang.String owner)
          Retrieve the next work package in the work list for the given owner and check it out.
 java.lang.String getNextWorkPackagePidString(java.lang.String worklist_name, java.lang.String owner)
          Retrieves the persistent identifier (PID) string for the next work package in the specified work list for the given owner.
 dkCollection getWorkPackageContainerData(java.lang.String workpackage_pid)
          Retrieves the container data for the specified work package.
 java.lang.String getWorkPackageOwner(java.lang.String workpackage_pid)
          Retrieves the owner for the specified work package.
 int getWorkPackagePriority(java.lang.String workpackage_pid)
          Retrieves the priority of the specified work package
 boolean isConnected()
          Returns a value that determines whether this service is connected to the persistent store or not.
 java.lang.String[] listWorkPackagePidStrings(java.lang.String worklist_name, java.lang.String owner)
          Retrieves an array of the persistent identifier (PID) strings for the work packages in the given work list for the given owner.
 java.lang.String[] listWorkPackagePidStringsWithItem(java.lang.String item_pid)
          Retrieves an array of persistent identifier strings for work package that are associated with the specified item id
 dkCollection listWorkPackages(java.lang.String worklist_name, java.lang.String owner)
          Retrieves a collection of the work packages in the given work list for the given owner.The work packages are not checked out by performing this operation
 dkCollection listWorkPackagesWithItem(java.lang.String item_pid)
          Retrieves a list of the work packages associated with the specified item
 void resumeProcess(java.lang.String pidString)
          The resumeProcess method will reset the suspend flag of the specified work package to false even before the suspension reaches the specified duration and the resume list is satisfied.
 DKWorkPackageICM retrieveWorkPackage(java.lang.String pidString, boolean checkOut)
          Retrieves the work package referred to by the pidString parameter as a DKWorkPackageICM reference .
 java.lang.String serviceCategory()
          Returns the category for this document routing service
 java.lang.String serviceId()
          Retrieves the identifier for this document routing service
 java.lang.String serviceName()
          Returns the name of this document routing service.
 java.lang.String serviceType()
          Returns the type for this document routing service.
 void setDatastore(dkDatastore ds)
          Sets a reference to the datastore object associated with this document routing service.
 void setServiceName(java.lang.String service_name)
          Sets the name for this document routing service.
 void setWorkPackageContainerData(java.lang.String workpackage_pid, dkCollection container_data)
          Sets the container data for the specified work package.
 void setWorkPackageOwner(java.lang.String workpackage_pid, java.lang.String owner)
          Sets the owner name for the specified work package.
 void setWorkPackagePriority(java.lang.String workpackage_pid, int priority)
          Sets the priority of the specified work package.
 java.lang.String startProcess(java.lang.String processName, java.lang.String pidString, int priority, java.lang.String owner)
          The startProcess method will start a process with the specified process name, item persistent identifier (PID), priority and owner name.
 java.lang.String startProcess(java.lang.String processName, java.lang.String pidString, int priority, java.lang.String owner, dkCollection container_data)
          The startProcess method will start a process with the specified process name, item persistent identifier (PID), priority, owner name, and container data.
 void suspendProcess(java.lang.String pidString, int duration, dkCollection resume_list)
          The suspendProcess method will suspend a process with the specified work package persistent identifier (PID) for a duration (specified in minutes) or for a given resume list.
 void terminateProcess(java.lang.String pidString)
          The terminateProcess method will terminate the work package specified in the persistent identifier (PID).
 java.lang.String userName()
          Returns the name of the user connected to this document routing service.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.mm.sdk.common.dkService
addExtension, connect, destroy, disconnect, getExtension, listExtensionNames, removeExtension, setUserName
 

Constructor Detail

DKDocRoutingServiceICM

public DKDocRoutingServiceICM(dkDatastore ds)
                       throws DKException,
                              java.lang.Exception
Constructs and initializes a document routing service object associated with the specified datastore

  DKDatstoreICM ds = new DKDatastoreICM();
  ds.connect("icmnlsdb", "icmadmin" ,"password" ,"");
  DKDocRoutingServiceICM doc = new DKDocRoutingServiceMgmtICM(ds);
  
Parameters:
ds - datastore reference as an instance of DKDatastoreICM
Throws:
DKException - when error occurs in the server
java.lang.Exception - when error occurs
See Also:
DKDatastoreICM, DKDocRoutingServiceMgmtICM
Method Detail

serviceName

public java.lang.String serviceName()
                             throws java.lang.Exception
Returns the name of this document routing service.
Specified by:
serviceName in interface dkService
Returns:
name of this document routing service as a string
Throws:
java.lang.Exception - when error occurs

serviceType

public java.lang.String serviceType()
                             throws java.lang.Exception
Returns the type for this document routing service.
Specified by:
serviceType in interface dkService
Returns:
service type as a string.
Throws:
java.lang.Exception - when error occurs

serviceId

public java.lang.String serviceId()
                           throws java.lang.Exception
Retrieves the identifier for this document routing service
Specified by:
serviceId in interface dkService
Returns:
identifier of this document routing service as a string
Throws:
java.lang.Exception - when error occurs

serviceCategory

public java.lang.String serviceCategory()
                                 throws java.lang.Exception
Returns the category for this document routing service
Specified by:
serviceCategory in interface dkService
Returns:
service category as a string.
Throws:
java.lang.Exception - when error occurs

userName

public java.lang.String userName()
                          throws java.lang.Exception
Returns the name of the user connected to this document routing service.
Specified by:
userName in interface dkService
Returns:
user name as a string variable.
Throws:
java.lang.Exception - when error occurs

connection

public DKHandle connection()
                    throws java.lang.Exception
Returns the connection handle for this document routing service.
Specified by:
connection in interface dkService
Returns:
connection handle as an instance of DKHandle.
Throws:
java.lang.Exception - when error occurs

isConnected

public boolean isConnected()
                    throws java.lang.Exception
Returns a value that determines whether this service is connected to the persistent store or not.
Specified by:
isConnected in interface dkService
Returns:
boolean value indicating the connection status for this document routing service.
Throws:
java.lang.Exception - when error occurs

setServiceName

public void setServiceName(java.lang.String service_name)
                    throws java.lang.Exception
Sets the name for this document routing service.
Specified by:
setServiceName in interface dkService
Parameters:
new - value for the service name.
Throws:
java.lang.Exception - when error occurs

getDatastore

public dkDatastore getDatastore()
                         throws DKException,
                                java.lang.Exception
Retrieves a reference to the datastore object associated with this document routing service.
Returns:
associated datastore object as an instance of DKDatastoreICM.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

setDatastore

public void setDatastore(dkDatastore ds)
                  throws DKException,
                         java.lang.Exception
Sets a reference to the datastore object associated with this document routing service.
Parameters:
ds - reference to the datastore that will be associated with this document routing service . The parameter should be an instance of DKDatastoreICM.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getDocRoutingServiceMgmt

public DKDocRoutingServiceMgmtICM getDocRoutingServiceMgmt()
                                                    throws DKException,
                                                           java.lang.Exception
Retrieves a reference to the document routing management helper object associated with this document routing service object.

The following code assumes docSv is an existing DKDocRoutingServiceMgmt object.

  DKDocRoutingServiceMgmtICM docMgmt = docSv.getDocRoutingServiceMgmt();
  
Returns:
reference to the associated document routing management helper object as an instance of DKDocRoutingServiceMgmtICM.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

startProcess

public java.lang.String startProcess(java.lang.String processName,
                                     java.lang.String pidString,
                                     int priority,
                                     java.lang.String owner)
                              throws DKException,
                                     java.lang.Exception
The startProcess method will start a process with the specified process name, item persistent identifier (PID), priority and owner name. It will return the persistent identifier (PID) of the work package created as a result of executing this method. The work package will be located at the first work node of the given process at the conclusion of this method call.

The following code assumes docSv is an existing DKDocRoutingServiceICM object. "Process1" is the name of an existing process that is to be started, "pidString1" is an item PID, prority is 1 and owner of the process is "ICMADMIN".

 String wpPidString = docSv.startProcess("Process1", "pidString1", 1, "ICMADMIN");
 
Parameters:
processName - the name of the process to be started
pidString - the persistent identifier (pid) string of the item to be routed
priority - of the work package to be created
owner - of the work package to be created
Returns:
the persistent identifier (pid) of the newly created work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

startProcess

public java.lang.String startProcess(java.lang.String processName,
                                     java.lang.String pidString,
                                     int priority,
                                     java.lang.String owner,
                                     dkCollection container_data)
                              throws DKException,
                                     java.lang.Exception
The startProcess method will start a process with the specified process name, item persistent identifier (PID), priority, owner name, and container data. It will return the persistent identifier (PID) of the work package created as a result of executing this method. The work package will be located at the first work node of the given process at the conclusion of this method call.

The following code assumes docSv is an existing DKDocRoutingServiceICM object. "Process1" is the name of an existing process that is to be started, "pidString1" is an item persistent identifier (PID), prority is 1 and owner of the process is "ICMADMIN".

 String wpPidString = docSv.startProcess("Process1", "pidString1", 1, "ICMADMIN");
 
Parameters:
processName - the name the process to be started
pidString - the persistent identifier (pid) string of the item to be routed
priority - of the work package to be created
owner - of the work package to be created
container_data - of the work package to be created
Returns:
the persistent identifier (pid) of the newly created work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

terminateProcess

public void terminateProcess(java.lang.String pidString)
                      throws DKException,
                             java.lang.Exception
The terminateProcess method will terminate the work package specified in the persistent identifier (PID). The work package will be removed from the system. This method will also check in the item referenced in the specified work package persistent identifier (PID) if the item has been previously checked out.

The following code assumes docSv is an existing DKDocRoutingServiceICM object. "wpPidString1" is the PID of the workpackage to be moved out of the routing process.

  docSv.terminateProcess("wpPidString1");
  
Parameters:
pidString - the persistent identifier (pid) of the work package to be removed from the document routing process
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

continueProcess

public java.lang.String continueProcess(java.lang.String pidString,
                                        java.lang.String selection,
                                        java.lang.String owner)
                                 throws DKException,
                                        java.lang.Exception
The continueProcess method will route the item referenced by the specified item persistent identifier (PID) in the specified work package from the current work node to the next work node as determined by the selection. The specified work package will be removed from the Library Server, and a new work package will be created for the specified owner. The item referenced by the item PID will be checked in if it has been checked out. The persistent identifier (PID) of the newly created work package is returned to the user. A null string is returned if the process ends as a result of the continueProcess call.

The following code assumes docSv is an existing DKDocRoutingServiceICM object. "pidString1" is the pid string of the work package to be routed, "Continue" is a selection name from the current node where the work package resides. "ICMADMIN" is the new owner of of this work package.

  String wpPidString = docSv.continueProcess("pidString1", "Continue", "ICMADMIN");
  
Parameters:
pidString - the pid string of the work package to be routed
selection - value indicating the branch this work package should take out of the current work node
owner - the new owner of this work package
Returns:
the pid of the work package created as a result of this operation
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

continueProcess

public java.lang.String continueProcess(java.lang.String pidString,
                                        java.lang.String selection,
                                        java.lang.String owner,
                                        dkCollection container_data)
                                 throws DKException,
                                        java.lang.Exception
The continueProcess method will route the item referenced by the item persistent identifier (PID) in the specified work package from the current work node to the next work node that is determined by the selection. The specified work package will be removed from the Library Server, and a new work package is created for the specified owner. The item referenced by the item PID will be checked in if it has been checked out. The PID of the new work package is returned to the user. A null string is returned if the process ends as a result of the continueProcess call.

The following code assumes docSv is an existing DKDocRoutingServiceICM object. "pidString1" is the pid string of the work package to be routed, "Continue" is a selection name from the current node where the work package resides. "ICMADMIN" is the new owner of of this work package.

  String wpPidString = docSv.continueProcess("pidString1", "Continue", "ICMADMIN");
  
Parameters:
pidString - the pid string of the work package to be routed
selection - value indicating the branch this work package should take out of the current work node.
owner - the new owner of this work package
container_data - the new container data associated with this work pacakge
Returns:
the pid of the work package created as a result of this operation
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

suspendProcess

public void suspendProcess(java.lang.String pidString,
                           int duration,
                           dkCollection resume_list)
                    throws DKException,
                           java.lang.Exception
The suspendProcess method will suspend a process with the specified work package persistent identifier (PID) for a duration (specified in minutes) or for a given resume list. The suspend flag of the specified work package is set to true. This method will check in the item referenced in the specified work package PID if the item had been previously checked out. The duration specifies how long the suspend flag for the work package remains as a boolean true value. The resume list is specified as a sequential collection of resume list entries as instances of DKResumeListEntryICM objects each consisting of an item type value and quantity. The resume list is only applicable to a folder, and based on it, the process waits for the arrival of the specified item types in the specified quantities. If the suspension time period reaches the specified duration, the suspension flag will be reset to false. Also, if the resume list is satisfied, the suspend flag will be reset to false.
Parameters:
pidString - the pid of the work package whose associated process is to be suspended
duration - the duration that this work package will be suspended
resume_list - the resume list for which this work package is waiting to resume again.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

resumeProcess

public void resumeProcess(java.lang.String pidString)
                   throws DKException,
                          java.lang.Exception
The resumeProcess method will reset the suspend flag of the specified work package to false even before the suspension reaches the specified duration and the resume list is satisfied. No routing or checkout will be performed. In essence, the resumeProcess method is used to prematurely abort a previous suspendProcess call on a specified process.
Parameters:
pidString - the pid of the work package whose associated process is to be removed
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getNextWorkPackage

public DKWorkPackageICM getNextWorkPackage(java.lang.String worklist_name,
                                           java.lang.String owner)
                                    throws DKException,
                                           java.lang.Exception
Retrieve the next work package in the work list for the given owner and check it out. If the owner value is not specified, then all work packages in the work list will be used to determine the next work package
Parameters:
worklist_name - the name of the work list for which the work package is to be retrieved
owner - the owner of the work package to be retrieved. Owner may be left unspecified
Returns:
the next work package in the work list based on the specified criteria. The work package definition is returned as an instance of DKWorkPackageICM
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getNextWorkPackagePidString

public java.lang.String getNextWorkPackagePidString(java.lang.String worklist_name,
                                                    java.lang.String owner)
                                             throws DKException,
                                                    java.lang.Exception
Retrieves the persistent identifier (PID) string for the next work package in the specified work list for the given owner.
Parameters:
worklist_name - the work list name for which the work package PID string is to be retrieved.
owner - the owner of the work package.If not specified, the PID string for the next work package sequentially is retrieved.
Returns:
pid string of the next work package based on specified selection criteria
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

checkOutItemInWorkPackage

public boolean checkOutItemInWorkPackage(java.lang.String workpackage_pid)
                                  throws DKException,
                                         java.lang.Exception
Checks out the given item from the specified work package.
Parameters:
workpackage_pid - persistent identifier (pid) whose associated item is to be checked out.
Returns:
true if the item in the work package successfully checked out, otherwise return false
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getCount

public int getCount(java.lang.String worklist_name,
                    java.lang.String owner)
             throws DKException,
                    java.lang.Exception
Retrieves the count of work packages in the specified work list for the specified owner.
Parameters:
worklist_name - name of work list
owner - the owner of the work package for which work package count is to be retrieved.
Returns:
the count of the work packages in the specified work list for the specified owner.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

listWorkPackagePidStrings

public java.lang.String[] listWorkPackagePidStrings(java.lang.String worklist_name,
                                                    java.lang.String owner)
                                             throws DKException,
                                                    java.lang.Exception
Retrieves an array of the persistent identifier (PID) strings for the work packages in the given work list for the given owner. The work packages are not checked out by performing this operation.
Parameters:
worklist_name - name of the work list for which work packages PID strings are to be retrieved.
owner - the owner of the work package
Returns:
an array of work package pid strings for the specified work list
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

listWorkPackages

public dkCollection listWorkPackages(java.lang.String worklist_name,
                                     java.lang.String owner)
                              throws DKException,
                                     java.lang.Exception
Retrieves a collection of the work packages in the given work list for the given owner.The work packages are not checked out by performing this operation
Parameters:
worklist_name - name of the work list for which work packages are to be retrieved.
owner - the owner of the work packages to be retrieved from the given work list
Returns:
a collection of work packages as instances of DKWorkPackageICM.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

retrieveWorkPackage

public DKWorkPackageICM retrieveWorkPackage(java.lang.String pidString,
                                            boolean checkOut)
                                     throws DKException,
                                            java.lang.Exception
Retrieves the work package referred to by the pidString parameter as a DKWorkPackageICM reference . If the checkOut parameter is set to true, the work package will be checked out. If the checkout parameter is set to false, the work package will not be checked out.
Parameters:
pidString - the pidString of the work package whose definition is to be retrieved.
checkOut - flat that indicates whether this work package is to be checked out or not.
Returns:
the work package for the specified work package pid string as an instance of DKWorkPackageICM.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

listWorkPackagesWithItem

public dkCollection listWorkPackagesWithItem(java.lang.String item_pid)
                                      throws DKException,
                                             java.lang.Exception
Retrieves a list of the work packages associated with the specified item
Parameters:
item_pid - the pidString of the item whose associated work packages are to be retrieved.
Returns:
the collection of work packages associated with the given item as instances of DKWorkPackageICM.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

listWorkPackagePidStringsWithItem

public java.lang.String[] listWorkPackagePidStringsWithItem(java.lang.String item_pid)
                                                     throws DKException,
                                                            java.lang.Exception
Retrieves an array of persistent identifier strings for work package that are associated with the specified item id
Parameters:
item_pid - the pidString of the item whose associated work packages are to be retrieved.
Returns:
an array of work package pid strings associated with the specified item
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getWorkPackagePriority

public int getWorkPackagePriority(java.lang.String workpackage_pid)
                           throws DKException,
                                  java.lang.Exception
Retrieves the priority of the specified work package
Parameters:
workpackage_pid - the pidString of the work package whose priority is to be retrieved.
Returns:
the priority of the specified work package.
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

setWorkPackagePriority

public void setWorkPackagePriority(java.lang.String workpackage_pid,
                                   int priority)
                            throws DKException,
                                   java.lang.Exception
Sets the priority of the specified work package.
Parameters:
workpackage_pid - the pidString of the work package whose priority is to be set.
priority - the new priority for the specified work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getWorkPackageOwner

public java.lang.String getWorkPackageOwner(java.lang.String workpackage_pid)
                                     throws DKException,
                                            java.lang.Exception
Retrieves the owner for the specified work package.
Parameters:
workpackage_pid - the pidString of the work package whose owner is to be retrieved.
Returns:
the owner name of the specified work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

setWorkPackageOwner

public void setWorkPackageOwner(java.lang.String workpackage_pid,
                                java.lang.String owner)
                         throws DKException,
                                java.lang.Exception
Sets the owner name for the specified work package.
Parameters:
workpackage_pid - the pid string of the work package whose owner is to be set.
owner - the new owner of the work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

getWorkPackageContainerData

public dkCollection getWorkPackageContainerData(java.lang.String workpackage_pid)
                                         throws DKException,
                                                java.lang.Exception
Retrieves the container data for the specified work package.
Parameters:
workpackage_pid - the pidString of the work package whose container data is to be retrieved.
Returns:
a collection of DKNVPair objects, each of which contains a container data name and the corresponding container data value for the specified work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

setWorkPackageContainerData

public void setWorkPackageContainerData(java.lang.String workpackage_pid,
                                        dkCollection container_data)
                                 throws DKException,
                                        java.lang.Exception
Sets the container data for the specified work package.
Parameters:
workpackage_pid - the pid string of the work package whose container data is to be set.
container_data - the new collection of DKNVPair objects, each of which contains a container data name and the corresponding container data value for the specified work package
Throws:
DKException - when error occurs
java.lang.Exception - when error occurs

EIP Java APIs

(c) Copyright International Business Machines Corporation 1996, 2002. IBM Corp. All rights reserved.