Enterprise Information Portal APIs

com.ibm.mm.beans.workflow
Class CMBWorkFlowQueryService

java.lang.Object
  |
  +--com.ibm.mm.beans.workflow.CMBWorkFlowQueryService
All Implemented Interfaces:
CMBConnectionReplyListener, CMBWorkListRequestListener, java.util.EventListener, java.io.Serializable

public class CMBWorkFlowQueryService
extends java.lang.Object
implements java.io.Serializable, CMBWorkListRequestListener, CMBConnectionReplyListener

This bean provide workflow query capabilities

See Also:
Serialized Form

Constructor Summary
CMBWorkFlowQueryService()
          Creates a new instance of CMBWorklfowQueryService object with default values
 
Method Summary
 void addCMBExceptionListener(CMBExceptionListener alistener)
          CMBExceptionEvent registration method.
 void addCMBTraceListener(CMBTraceListener alistener)
          CMBTraceEvent registration method.
 void addCMBWorkListReplyListener(CMBWorkListReplyListener aListener)
          CMBWorkListReplyEvent registration method.
 void clearCache()
          Clears out the cache.
 CMBWorkFlowAction getAction(java.lang.String actionName)
          Get the CMBWorkFlowAction object for the given actionName.
 java.lang.String[] getActionList(java.lang.String actionListName)
          Returns a list of the action names for a given actionListName.
 java.util.Collection getAllWorkFlowTemplates()
          Returns a collection of CMBWorkFlowTemplate objects.
 CMBConnection getConnection()
          Gets the connection bean reference.
 CMBWorkFlowContainer getContainer(java.lang.String workflowName)
          Returns a CMBWorkFlowContainer object for a workflow process instance.
 CMBWorkFlowContainer getContainer(java.lang.String workflowName, java.lang.String nodeName, java.lang.String owner)
          Returns a CMBWorkFlowContainer object for a work item.
 int getState(java.lang.String workflowName, java.lang.String nodeName, java.lang.String owner)
          Returns the state of the work item.
 CMBWorkFlow getWorkFlow(java.lang.String workflowName)
          Returns a CMBWorkFlow object for a given workflow name.
 java.util.Collection getWorkFlows()
          Returns a collection of CMBWorkFlow objects that the user is authorized to view.
 java.util.Collection getWorkFlows(java.lang.String filter, java.lang.String sort_criteria, int threshold)
          Returns a collection of CMBWorkFlow objects which the user is authorized to view.
 java.util.Collection getWorkFlowTemplateNames()
          Returns a collection of String objects.
 java.util.Collection getWorkFlowTemplates()
          Returns a collection of CMBWorkFlowTemplate objects.
 CMBWorkItem getWorkItem(java.lang.String workflowName, java.lang.String nodeName, java.lang.String owner)
          Returns a CMBWorkItem object.
 java.util.Collection getWorkItems(java.lang.String workListName, boolean wiCheckOutFlag)
          Returns a collection of CMBWorkItems objects.
 java.util.Collection getWorkItems(java.lang.String filter, java.lang.String sort_criteria, int threshold)
          Returns a collection of CMBWorkItem objects which the user is authorized to view.
 CMBWorkList getWorkList(java.lang.String workListName, boolean checkOut)
          Returns the CMBWorkList for a given workList name.
 java.util.Collection getWorkListNames()
          Returns a collection of String objects; the workList names in the workflow system.
 java.util.Collection getWorkLists(boolean checkOut)
          Returns a collection of CMBWorkList objects which the user has authority to view.
 java.util.Collection getWorkNotificationList()
          Returns a collection of CMBWorkNotification objects which the user is authorized to view.
 java.util.Collection getWorkNotifications(java.lang.String workListName)
          Returns a collection of CMBWorkNotification objects.
 boolean isCacheEnabled()
          Returns the cacheEnabled property value
 boolean isTraceEnabled()
          Checks to see if trace is enabled
 void onCMBConnectionReply(CMBConnectionReplyEvent evt)
          Implementation of Connection reply service method.
 void onWorkListRequest(CMBWorkListRequestEvent evt)
          Implementation of worklist request service method.
 void removeCMBExceptionListener(CMBExceptionListener alistener)
          CMBExceptionEvent unregistration method.
 void removeCMBTraceListener(CMBTraceListener alistener)
          CMBTraceEvent unregistration method.
 void removeCMBWorkListReplyListener(CMBWorkListReplyListener aListener)
          CMBWorkListReplyEvent unregistration method.
 void setCacheEnabled(boolean newValue)
          Cache the results of the workflow query services.
 void setConnection(CMBConnection newConnBean)
          Sets the connection bean reference.
 void setTraceEnabled(boolean enabled)
          Sets the trace property value.
 void vetoableChange(java.beans.PropertyChangeEvent evt)
          Check if property allows to be changed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMBWorkFlowQueryService

public CMBWorkFlowQueryService()
Creates a new instance of CMBWorklfowQueryService object with default values
Method Detail

setConnection

public void setConnection(CMBConnection newConnBean)
Sets the connection bean reference.
Parameters:
newConnBean - the reference to the CMBConnection object.

getConnection

public CMBConnection getConnection()
Gets the connection bean reference.
Returns:
the reference to the CMBConnection object.

isTraceEnabled

public boolean isTraceEnabled()
Checks to see if trace is enabled
Returns:
true if trace is enabled, false otherwise

setTraceEnabled

public void setTraceEnabled(boolean enabled)
Sets the trace property value.
Parameters:
enabled - new trace value

onWorkListRequest

public void onWorkListRequest(CMBWorkListRequestEvent evt)
Implementation of worklist request service method.
Specified by:
onWorkListRequest in interface CMBWorkListRequestListener
Parameters:
evt - a CMBWorkListRequestEvent

addCMBWorkListReplyListener

public void addCMBWorkListReplyListener(CMBWorkListReplyListener aListener)
CMBWorkListReplyEvent registration method. Adds a new listener object to listener list
Parameters:
aListener - a CMBWorkListReplyListener object to be added

removeCMBWorkListReplyListener

public void removeCMBWorkListReplyListener(CMBWorkListReplyListener aListener)
CMBWorkListReplyEvent unregistration method.
Parameters:
aListener - a listener to be unregistered

addCMBExceptionListener

public void addCMBExceptionListener(CMBExceptionListener alistener)
CMBExceptionEvent registration method. It ignores a registration request if the listener is already registered.
Parameters:
alistener - listener to be registered

removeCMBExceptionListener

public void removeCMBExceptionListener(CMBExceptionListener alistener)
CMBExceptionEvent unregistration method.
Parameters:
alistener - listener to be unregistered

addCMBTraceListener

public void addCMBTraceListener(CMBTraceListener alistener)
CMBTraceEvent registration method. It ignores a registration request if the listener is already registered.
Parameters:
alistener - listener to be registered

removeCMBTraceListener

public void removeCMBTraceListener(CMBTraceListener alistener)
CMBTraceEvent unregistration method.
Parameters:
alistener - listener to be unregistered

vetoableChange

public void vetoableChange(java.beans.PropertyChangeEvent evt)
                    throws java.beans.PropertyVetoException
Check if property allows to be changed.
Parameters:
evt - a property changed event
Throws:
java.beans.PropertyVetoException - if property value is invalid

clearCache

public void clearCache()
Clears out the cache.

getWorkNotificationList

public java.util.Collection getWorkNotificationList()
                                             throws CMBException
Returns a collection of CMBWorkNotification objects which the user is authorized to view.
Throws:
CMBException -  

getWorkItems

public java.util.Collection getWorkItems(java.lang.String workListName,
                                         boolean wiCheckOutFlag)
                                  throws CMBException
Returns a collection of CMBWorkItems objects. The work item in the workflow server is "checked out" if the wiCheckOutFlag is set to true. A null is returned if the worklist does not exist.
Note: if the cache attribute is enabled then the cached data is returned and the parameter wiCheckOutFlag is ignored.
Parameters:
workListName - the worklist name of the work items to be returned.
wiCheckOutFlag - this flag indicates if the work item is to be "checked out" of the workflow server.
Throws:
CMBException -  

getWorkNotifications

public java.util.Collection getWorkNotifications(java.lang.String workListName)
                                          throws CMBException
Returns a collection of CMBWorkNotification objects. A null is returned if the worklist does not exist.
Note: if the cache attribute is enabled then the cached data is returned.
Parameters:
workListName - the worklist name of the notifications to be returned.
Throws:
CMBException -  

isCacheEnabled

public boolean isCacheEnabled()
Returns the cacheEnabled property value
Returns:
cacheEnabled property value

setCacheEnabled

public void setCacheEnabled(boolean newValue)
Cache the results of the workflow query services. The default value is false. To refresh the cached data call this method: setCacheEnabled(false).
Parameters:
newValue - cache option for workflow query service

getWorkLists

public java.util.Collection getWorkLists(boolean checkOut)
                                  throws CMBException
Returns a collection of CMBWorkList objects which the user has authority to view.
If the checkOut parameter is set to true the work items are "checked out" of the workflow system. The state of the work item is evaluated. If the work item is in the state CMBWorkFlowConstants.CMB_WI_READY then the work item will be "checked out". Once the work item is "checked out" the state of the work item in the workflow system is changed to: CMBWorkFlowConstants.CMB_WI_CKECKEDOUT.
Note: By setting the checkOut parameter to true this method allows a client to implement a "Continue" action. To "Continue" a work item the work item must be "checked in". If the "check in" is successful the workflow system will move the work item to the next node on the workflow.
Note: if the cache attribute is enabled then the cached data is returned, and the checkOut parameter is ignored.
Parameters:
checkOut - set to true if the work items in the workLists are to be "checked out". otherwise set the checkOut parameter to false.
Throws:
CMBConnectFailedException -  
CMBException -  
See Also:
CMBWorkFlowConstants, com.ibm.mm.beans.workflow.CMBWorkFlowDataManagement.checkIn(String,String,String), com.ibm.mm.beans.workflow.CMBWorkFlowDataManagement.

getWorkListNames

public java.util.Collection getWorkListNames()
                                      throws CMBException
Returns a collection of String objects; the workList names in the workflow system. A collection with no elements indicates that there are no workLists in the workflow system.
Throws:
CMBConnectFailedException -  
CMBException -  

getWorkList

public CMBWorkList getWorkList(java.lang.String workListName,
                               boolean checkOut)
                        throws CMBException
Returns the CMBWorkList for a given workList name. If the checkOut parameter is true, the work items in the workList are "checked out". If the user does not have the authority to view the workList or the worklist does not exist a CMBException is thrown. The state of the work item and the workflow are evaluated. If the work item is in the state, CMBWorkFlowConstants.CMB_WI_READY then the work item will be "checked out". If the state of the workflow is CMBWorkFlowConstants.CMB_WPN_SUSPENDED or CMBWorkFlowConstants.CMB_WPN_SUSPENDED then an Exception is thrown. Also, besides the states of the work item and workflow, the user must be the owner of the work item. Once the work item is checkedOut the state of the work item in the workflow system is changed to: CMBWorkFlowConstants.CMB_WI_CKECKEDOUT.
Null is returned if the CMBWorkList object is not created.
Note: By setting the checkOut parameter to true this method allows a client to implement a "Continue" action. To "Continue" a work item the work item must be "checked in". If the "check in" is successful the workflow system will move the work item to the next node on the workflow.
Note: if the cache attribute is enabled then the cached data is returned, and the checkOut parameter is ignored.
Parameters:
workListName - the name of the workList
checkOut - set it to true if you want to check out the work items in the workList otherwise set it to false.
Throws:
CMBConnectFailedException -  
CMBException -  
See Also:
CMBWorkFlowConstants, com.ibm.mm.beans.workflow.CMBWorkFlowDataManagemen.checkIn(String, String, String)

getAction

public CMBWorkFlowAction getAction(java.lang.String actionName)
                            throws CMBException
Get the CMBWorkFlowAction object for the given actionName.
Note: this method does not support the cache feature.
Parameters:
actionName - the action name for the CMBWorkFlowAction
Throws:
CMBException -  
See Also:
CMBWorkItem, CMBWorkFlowAction

getActionList

public java.lang.String[] getActionList(java.lang.String actionListName)
                                 throws CMBException
Returns a list of the action names for a given actionListName. For each action in the list you can get the CMBWorkFlowAction object by using the getAction method. A null is returned if the action list for the given action list name does not exist.
Note: this method does not support the cache feature.
Parameters:
actionListName - the name of the actionList
Returns:
the list of action names
Throws:
CMBException -  
See Also:
CMBWorkFlowAction

getWorkItems

public java.util.Collection getWorkItems(java.lang.String filter,
                                         java.lang.String sort_criteria,
                                         int threshold)
                                  throws CMBException
Returns a collection of CMBWorkItem objects which the user is authorized to view. The collection is based on the given filter, sort criteria, and threshold.
Parameters:
filter - filter criteria for querying
sort_criteria - sort criteria for sorting
threshold - number of returned results (CMBWorkFlowContants.CMB_WL_MAX_RESULTS for max results)
Returns:
a collection of CMBWorkItem objects.

Details for the getWorkItems query:
  • filter
    • keywords: Note: all keywords are in uppercase
      • NAME
      • DESCRIPTION
      • PROCESS_NAME
      • PRIORITY
      • OWNER
      • LAST_MODIFICATION_TIME
      • RECEIVED_TIME
      • STATE
      • PROCESS_STATE
    • operators:
      • =
      • >
      • >=
      • <
      • <=
      • <>
      • IN
      • LIKE
      • NOT LIKE
      • AND
      • OR
    • state:
      • READY
      • RUNNING
      • SUSPENDED
      • CHECKED_OUT
    • process state:
      • READY
      • RUNNING
      • SUSPENDED
  • sort:
    • ASC for ascending
    • DESC for descending
  • threshold:
    • an integer indicating the number of results
    • CMBWorkFlowContants.CMB_WL_MAX_RESULTS for returning all

Filtering on Global Container Member names.
Note: Filtering on container member names requires MQSWF server version 3.3.2 or higher.

Syntax for filtering on Global Container members:

TemplateName:Global Container Member name
Valid Global Container Member names:
  • PersistentID
  • UserVariableValue0 - UserVariableValue4


Example of a valid filter when filtering on Global Container Members: getWorkItems("Definition1:PersistentID = 'PID' ", "NAME ASC", 50"); filter: work items for workflow template Definition1 where persistent id = PID sort: sort by work item name in the ascending order threshold: 100

Examples of valid filters when not filtering on Global Container Members: getWorkItems("NAME LIKE '*ST*'", "NAME DESC", CMB_WL_MAX_RESULTS); filter: work item name with a substring 'ST' sort: sort by work item name in the descending order threshold: CMB_WL_MAX_RESULTS indicating all
getWorkItems("NAME < 'Collect'", "NAME DESC", 20); filter: work item name less than 'Collect' sort: sort by work item name in the descending order threshold: 20
getWorkItems("DESCRIPTION LIKE '*accident*'", "NAME DESC", 100); filter: work item description with a substring 'accident' sort: sort by work item name in the descending order threshold: 100
getWorkItems("STATE IN (RUNNING, READY) AND NAME = 'Start'", "NAME ASC", 10); filter: work item state in either running or ready state and work item name is 'Start' sort: sort by workflow name in the ascending order threshold: 10
getWorkItems("STATE IN (RUNNING, READY) OR NAME = 'Start'", "NAME ASC", 10); filter: work item state in either running or ready state or work item name is 'Start' sort: sort by work item name in the ascending order threshold: 10
getWorkItems("STATE IN RUNNING", "NAME ASC", 50); filter: work item state in the running state sort: sort by work item name in the ascending order threshold: 50
getWorkItems("PROCESS_STATE IN RUNNING", "", 50); filter: workflow state in the running state sort: default order (ascending) threshold: 50
getWorkItems("OWNER = 'CMBADMIN'", "", 10); filter: owner name is 'CMBADMIN' sort: default order (ascending) threshold: 10
getWorkItems("PRIORITY > 100", "", 10); filter: priority is greater than 100 sort: default order (ascending) threshold: 10
getWorkItems("LAST_MODIFICATION_TIME < '2001-05-25 11:30:00'", "NAME ASC", 100); filter:the last modification time is earlier than 2001-05-25 11:30:00 sort: sort by work item name in the ascending order threshold: 100
getWorkItems("STATE <> CHECKED_OUT", "PRIORITY DESC", 1); filter:the last modification time is earlier than 2001-05-25 11:30:00 sort: work item state is not equal to 'CHECKED_OUT' threshold: 1
Throws:
CMBException -  

getWorkFlows

public java.util.Collection getWorkFlows(java.lang.String filter,
                                         java.lang.String sort_criteria,
                                         int threshold)
                                  throws CMBException
Returns a collection of CMBWorkFlow objects which the user is authorized to view. The collection is based on the given filter, sort criteria, and threshold.
Parameters:
filter - filter criteria for querying
sort_criteria - sort criteria for sorting
threshold - number of returned results (CMBWorkFlowContants.CMB_WL_MAX_RESULTS for max results)
Returns:
a collection of CMBWorkFlow objects.

Details for the getWorkFlows query:
  • filter
    • keywords:
      • NAME
      • DESCRIPTION
      • LAST_MODIFICATION_TIME
      • LAST_STATE_CHANGE_TIME
      • STATE
    • operators:
      • =
      • >
      • >=
      • <
      • <=
      • <>
      • IN
      • LIKE
      • NOT LIKE
      • AND
      • OR
    • state:
      • READY
      • RUNNING
      • SUSPENDED
  • sort:
    • ASC for ascending
    • DESC for descending
  • threshold:
    • an integer indicating the number of results
    • CMBWorkFlowContants.CMB_WL_MAX_RESULTS for returning all

Note: all keywords are in uppercase

Filtering on Global Container Member names.
Note: Filtering on global ;pncontainer member names requires MQSWF server version 3.3.2 or higher.

Syntax for filtering on Global Container members:

TemplateName:Global Container Member name
Valid Global Container Member names:
  • PersistentID
  • UserVariableValue0 - UserVariableValue4


Example of a valid filter when filtering on Global Container Members: getWorkFlows("Definition1:PersistentID = 'PID' ", "NAME ASC", 50"); filter: work items for template Definition1 where persistent id = PID sort: sort by work item name in the ascending order threshold: 100

Examples of valid filters when not filtering on Global Container Members: getWorkFlows("NAME LIKE '*Claim*'", "NAME DESC", CMB_WL_MAX_RESULTS); filter: workflow name with a substring 'Claim' sort: sort by workflow name in the descending order threshold: CMB_WL_MAX_RESULTS indicating all
getWorkFlows("NAME < 'Claim'", "NAME DESC", 20); filter: workflow name less than 'Claim' sort: sort by workflow name in the descending order threshold: 20
getWorkFlows("DESCRIPTION LIKE '*Claim*'", "NAME DESC", 100); filter: workflow description with a substring 'Claim' sort: sort by workflow name in the descending order threshold: 100
getWorkFlows("STATE IN (RUNNING, READY) AND NAME = 'Claim'", "NAME ASC", 10); filter: workflow state in either running or ready state and workflow name is 'Claim' sort: sort by workflow name in the ascending order threshold: 10
getWorkFlows("STATE IN (RUNNING, READY) OR NAME = 'Claim'", "NAME ASC", 10); filter: workflow state in either running or ready state or workflow name is 'Claim' sort: sort by workflow name in the ascending order threshold: 10
getWorkFlows("LAST_STATE_CHANGE_TIME < '2001-05-25 11:30:00'", "NAME ASC", 10); filter: the last state change time is earlier than 2001-05-25 11:30:00 sort: sort by process name in the ascending order threshold: 10
getWorkFlows("LAST_MODIFICATION_TIME < '2001-05-25 11:30:00'", "NAME ASC", 100); filter: the last modification time is earlier than 2001-05-25 11:30:00 sort: sort by process name in the ascending order threshold: 100
Throws:
CMBException -  

getWorkFlows

public java.util.Collection getWorkFlows()
                                  throws CMBException
Returns a collection of CMBWorkFlow objects that the user is authorized to view. The user must have CMBWorkFlowConstants.CMB_PRIV_WF_VIEW_WORKITEM privilege to view workflows. The collection consists of all the CMBWorkFlow objects in the system.
Throws:
CMBException -  

getAllWorkFlowTemplates

public java.util.Collection getAllWorkFlowTemplates()
                                             throws CMBException
Returns a collection of CMBWorkFlowTemplate objects. The collection consists of all the CMBWorkFlowTemplate objects in the workflow system. CMBWorkFlowTemplate objects.
Throws:
CMBException -  

getWorkFlowTemplates

public java.util.Collection getWorkFlowTemplates()
                                          throws CMBException
Returns a collection of CMBWorkFlowTemplate objects.
Throws:
CMBException -  
CMBException -  
See Also:
CMBWorkFlowConstants

getWorkFlowTemplateNames

public java.util.Collection getWorkFlowTemplateNames()
                                              throws CMBException
Returns a collection of String objects.
Throws:
CMBException -  
CMBException -  
See Also:
CMBWorkFlowConstants

getWorkItem

public CMBWorkItem getWorkItem(java.lang.String workflowName,
                               java.lang.String nodeName,
                               java.lang.String owner)
                        throws CMBException
Returns a CMBWorkItem object. A null CMBWorkItem may be returned if an error occurs or the user does not have the authority to view the work item. The work item is not "checked out" of the workflow server.
Parameters:
workflowName - the workflow name
nodeName - the node name of the work item
owner - the owner of the work item.
Throws:
CMBException -  

getContainer

public CMBWorkFlowContainer getContainer(java.lang.String workflowName,
                                         java.lang.String nodeName,
                                         java.lang.String owner)
                                  throws CMBException
Returns a CMBWorkFlowContainer object for a work item. A null CMBWorkFlowContainer may be returned if an error occurs or the user does not have the authority.
Parameters:
workflowName - the workflow name
nodeName - the node name of the work item
owner - the owner of the work item.
Throws:
CMBException -  

getContainer

public CMBWorkFlowContainer getContainer(java.lang.String workflowName)
                                  throws CMBException
Returns a CMBWorkFlowContainer object for a workflow process instance. A null CMBWorkFlowContainer may be returned if an error occurs or the user does not have the authority.
Parameters:
workflowName - the workflow name of the workflow process instance
Throws:
CMBException -  

getWorkFlow

public CMBWorkFlow getWorkFlow(java.lang.String workflowName)
                        throws CMBException
Returns a CMBWorkFlow object for a given workflow name. A null CMBWorkFlow may be returned if an error occurs or the user does not have the authority to view the workflow or the workflow does not exist.
Parameters:
workflowName - the name of the workflow

getState

public int getState(java.lang.String workflowName,
                    java.lang.String nodeName,
                    java.lang.String owner)
             throws CMBException
Returns the state of the work item. The state of a work item can be one of the following:
Note: this method does not support the cache feature.
Parameters:
workflowName - the workflow name
nodeName - the node name
owner - the owner
Throws:
CMBException -  
See Also:
com.ibm.mm.beans.workflow.CMBWorkFlowDataManagement.checkOut(String,String,String), CMBWorkFlowConstants

onCMBConnectionReply

public void onCMBConnectionReply(CMBConnectionReplyEvent evt)
Implementation of Connection reply service method.
Specified by:
onCMBConnectionReply in interface CMBConnectionReplyListener
Parameters:
evt - a CMBConnectionReplyEvent

EIP JavaBeans

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