Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

com.netscape.pm.model
Interface IProcessInstance

public interface IProcessInstance

Defines the interface for a process instance in the Process Manager world. The interface provides for the management of data dictionary elements (that is, fields) and the instance itself (for example, suspension and resumption).

The ProcessInstance object that implements this interface may not be instantiated manually, rather the IPMApplication and IFinder interfaces may be used to obtain a handle on a ProcessInstance object. 

 // The localName is the name of the application, "myApp" for instance.
 //
 javax.naming.Context cxt = new javax.naming.InitialContext();
 String jndiName = "java:comp/env/" + IPMApplication.DEFAULT_JNDI_ROOT
                 + "/" + localName;
 IPMApplicationHome home = (IPMApplicationHome) cxt.lookup( jndiName );
 IPMApplication app = home.create();

 // Initiate a new process instance
 //
 INodeElement entryNode = app.getProcessDefinition()
                             .getProcessMap()
                             .getNodeElement( "EntryPoint1" );
 IWorkitem wi = app.initiateProcessInstance( entryNode );

 // Fetch a handle to a process instance for update
 //
 IProcessInstancePK pk = ProcessInstancePKFactory.create( 100 );
 pk.setEditable( true );
 IProcessInstance pi = app.findProcessInstance( pk );

See Also:
IFinder, IPMApplication

Field Summary
static int DEFAULT_PRIORITY_VALUE
          The default priority value for an instance if none has been specified.
static int STATE_CLOSED_COMPLETED
          State value for an instance that has finished normally without manual intervention; the instance no longer contains any workitems.
static int STATE_CLOSED_TERMINATED
          State value for an instance that has been aborted before its normal completion.
static int STATE_OPEN_INITIATED
          State value for an instance that has just been created.
static int STATE_OPEN_RUNNING
          State value for an instance that has been created and is executing according to the process map.
static int STATE_OPEN_SUSPENDED
          State value for an instance that is unavailable.
 
Method Summary
 void addHistoryEvent(IHistoryEvent event)
          Add an event to the history/audit log of this process instance.
 void archive(java.io.OutputStream os)
          Archive the contents of the current process instance to an output stream.
 java.lang.String getApplicationName()
          Returns the common name of the application this instance belongs to.
 IParticipant getAuthenticatedUser()
          Returns the authenticated user id for this session.
 java.lang.String getClusterName()
          Returns the name of the cluster this instance belongs to.
 java.util.Date getCreationDate()
          Returns the creation date of this instance.
 IParticipant getCreatorUser()
          Returns the creator of this instance in the form of an IParticipant object.
 java.lang.Object getData(java.lang.String name)
          Returns the value of the specified data dictionary field.
 java.lang.String getEntityKey(java.lang.String name)
          Returns the primary key for the specified custom field.
 INodeElement getEntryNode()
          Returns the entry point node where the current process instance was initiated from.
 INodeElement getExitNode()
          Returns the exit node where this current process instance has completed at.
 java.util.Vector getHistoryEvents()
          Fetch all of the history events logged for this process instance.
 long getInstanceId()
          Returns the id (primary key) of this instance.
 java.util.Date getLastModifiedDate()
          Returns the date this instance was last modified.
 IWorkItemPK getParentPrimaryKey()
          Returns the primary key of the parent workitem from which this instance was spawned from.
 IProcessInstancePK getPrimaryKey()
          Returns the primary key for this instance.
 int getPriority()
          Returns the priority assigned to this instance.
 IParticipant getRoleUser(java.lang.String roleName)
          Returns the user that is contained in the defined role.
 int getState()
          Returns the state of the process instance.
 java.lang.String getTitle()
          Returns the title of this process instance.
 boolean hasBeenArchived()
          Returns true if this process instance has already been archived.
 boolean isEntityLoaded(java.lang.String name)
          Check if the specified custom field has been loaded.
 void release(boolean commit)
          Commit/rollback the process instance changes to the back-end store.
 void resume()
          Resumes the process instance; all workitems that belong to this instance are also resumed.
 void save()
          Save the process instance and its associated instance data; this method should be called when the desired effect is to just save the changes made to the process instance and not to the workitems associated with the process instance.
 void setAuthenticatedUser(IParticipant au)
          Sets the authenticated user id for this session.
 void setData(java.lang.String name, java.lang.Object value)
          Sets/updates the value of the specified data dictionary field with the specified Java value.
 void setEntityKey(java.lang.String name, java.lang.String value)
          Updates the primary key for the specified custom field.
 void setRoleUser(java.lang.String roleName, IParticipant roleUser)
          Sets the value of a role with the specified user.
 void suspend()
          Suspends the process instance; all workitems that belong to this instance are also suspended as a result of this operation.
 void terminate(INodeElement exitNode)
          Terminates the process instance at the given exit node.
 

Field Detail

STATE_OPEN_INITIATED

public static final int STATE_OPEN_INITIATED
State value for an instance that has just been created. The process instance will only have this value as its state after it has been initiated via initiateProcessInstance from the IPMApplication interface.
See Also:
IPMApplication.initiateProcessInstance(com.netscape.pm.model.INodeElement)
Since:
NPM 1.0

STATE_OPEN_RUNNING

public static final int STATE_OPEN_RUNNING
State value for an instance that has been created and is executing according to the process map. The instance is not in an exception or error condition.
Since:
NPM 1.0

STATE_OPEN_SUSPENDED

public static final int STATE_OPEN_SUSPENDED
State value for an instance that is unavailable. Assignees of any of the workitems that belong to this instance cannot take any action on their respective workitems until the process has returned to the running or active state.
See Also:
suspend(), resume()
Since:
NPM 1.0

STATE_CLOSED_COMPLETED

public static final int STATE_CLOSED_COMPLETED
State value for an instance that has finished normally without manual intervention; the instance no longer contains any workitems.
Since:
NPM 1.0

STATE_CLOSED_TERMINATED

public static final int STATE_CLOSED_TERMINATED
State value for an instance that has been aborted before its normal completion.
Since:
NPM 1.0

DEFAULT_PRIORITY_VALUE

public static final int DEFAULT_PRIORITY_VALUE
The default priority value for an instance if none has been specified.
See Also:
getPriority()
Since:
NPM 1.0
Method Detail

getInstanceId

public long getInstanceId()
Returns the id (primary key) of this instance.
Returns:
the instance id of this instance
Since:
NPM 1.0

getPrimaryKey

public IProcessInstancePK getPrimaryKey()
Returns the primary key for this instance. The primary key contains the instance id for the process instance and indicates whether the instance has been fetched for update or read-only.
Returns:
the primary key for this instance.
Since:
PM 6.0
See Also:
IProcessInstancePK

getCreationDate

public java.util.Date getCreationDate()
Returns the creation date of this instance.
Returns:
the creation date of this instance.
Since:
NPM 1.0

getCreatorUser

public IParticipant getCreatorUser()
                            throws PMException
Returns the creator of this instance in the form of an IParticipant object.
Returns:
an IParticipant object with the creator's corporate directory attributes.
Throws:
PMException - if there is a problem retrieving the creator's entry from the corporate directory.
Since:
NPM 1.0
See Also:
IParticipant

getRoleUser

public IParticipant getRoleUser(java.lang.String roleName)
                         throws PMException
Returns the user that is contained in the defined role. The user is returned as an IParticipant object.
Parameters:
roleName - the name of the role for which content needs to be returned. This role must be defined in the process definition as a field role
Returns:
the user
Throws:
PMException - if there is a problem loading the process instance data dictionary values.
Since:
NPM 1.0
See Also:
IParticipant

setRoleUser

public void setRoleUser(java.lang.String roleName,
                        IParticipant roleUser)
                 throws PMException
Sets the value of a role with the specified user.
Parameters:
roleName - the name of the role which is to be modified. This role must be defined in the process definition as a field role
roleUser - user to be set as the current role player
Throws:
PMException - if the field specified by roleName has not been defined as a role field in the process definition.
Since:
PM 6.0
See Also:
ICorporateDirectory, IParticipant

addHistoryEvent

public void addHistoryEvent(IHistoryEvent event)
Add an event to the history/audit log of this process instance. All events are placed on a queue, which is flushed to the database when the process instance is saved.
Parameters:
event - history event to be logged
Since:
PAE 4.0
See Also:
HistoryEventFactory, IHistoryEvent

getHistoryEvents

public java.util.Vector getHistoryEvents()
                                  throws PMException
Fetch all of the history events logged for this process instance. The history events are returned in a java.util.Vector. All of the elements in the Vector are IHistoryEvent.
Returns:
java.util.Vector containing IHistoryEvent objects.
Throws:
PMException - if unable to load all of the history events logged for this process instance.
Since:
PAE 4.0
See Also:
IHistoryEvent

getData

public java.lang.Object getData(java.lang.String name)
                         throws PMException
Returns the value of the specified data dictionary field. If the field has not been defined in the process definition for this application, null is returned. If name is null, null will be returned.

The value returned will depend upon the type of the data dictionary field. The values returned for built-in data fields are well-defined; the values returned for custom fields will depend entirely upon the field's implementation.

TEXT or LONGTEXT
java.lang.String
DATE or DATETIME
java.util.Date
BOOLEAN
java.lang.Boolean
FLOAT
java.lang.Double
INT
java.lang.Integer
ENTITY
depends upon field implementation
Parameters:
name - name of the field whose value is to be returned
Returns:
the current value associated with the specified data dictionary field.
Throws:
PMException - if there is a problem loading the process instance data dictionary values.
Since:
NPM 1.0
See Also:
IDataElement, IProcessMap

setData

public void setData(java.lang.String name,
                    java.lang.Object value)
             throws PMException
Sets/updates the value of the specified data dictionary field with the specified Java value. Unlike the corresponding JavaScript API version of this method, this version is intended to be called internally, that is from other Java objects. No conversion is performed to ensure the value matches the expected data type for the field.

The proper value to pass in will depend upon the type of the data dictionary field. The values required for built-in data fields are well-defined; the values required for custom fields will depend entirely upon the field's implementation.

TEXT or LONGTEXT
java.lang.String
DATE or DATETIME
java.util.Date
BOOLEAN
java.lang.Boolean
FLOAT
java.lang.Double
INT
java.lang.Integer
ENTITY
depends upon field implementation
Parameters:
name - name of the field whose value is to be modified
value - the value to associate with the field
Throws:
PMException - if there is a type mismatch between the expected data type for the field value and the actual data type for the passed value.
Since:
NPM 1.0
See Also:
IDataElement, IProcessMap

getEntityKey

public java.lang.String getEntityKey(java.lang.String name)
                              throws PMException
Returns the primary key for the specified custom field. The primary (also known as the entity key) key uniquely identifies this instance of the custom field from other instances of the same field. The primary key is always available from the process instance, and is in fact stored with the rest of the application data. If name is null null is returned.
Parameters:
name - the name of the custom field to fetch the entity key for
Returns:
the current value of the entity key for the specified custom field.
Throws:
PMException - if there is a problem loading the process instance data dictionary values.
Since:
PAE 4.0
See Also:
setEntityKey(java.lang.String, java.lang.String), IDataElement

setEntityKey

public void setEntityKey(java.lang.String name,
                         java.lang.String value)
Updates the primary key for the specified custom field. The primary (also known as the entity key) key uniquely identifies this instance of the custom field from other instances of the same field. The primary key is always available from the process instance, and is in fact stored with the rest of the application data. If name is null, nothing is done.
Parameters:
name - the name of the custom field to modify
value - the value to set as the custom field's entity key
Since:
PAE 4.0
See Also:
getEntityKey(java.lang.String), IDataElement

isEntityLoaded

public boolean isEntityLoaded(java.lang.String name)
Check if the specified custom field has been loaded. Custom fields are lazy-loaded by the process instance; that is, the load method on the custom field is called only when getData has been used to fetch the value of the field.

Note: if a custom field has been loaded during a request session, it must be re-loaded when starting another request session. After the handle to a process instance has been discarded, the handle to the custom field data value is lost as well.

Parameters:
name - the name of the custom field to check
Returns:
true if the custom field has been loaded; false otherwise.
Since:
PAE 4.0
See Also:
getData(java.lang.String), IDataElement

getState

public int getState()
Returns the state of the process instance.
Returns:
the current state of the process instance
Since:
NPM 1.0
See Also:
STATE_OPEN_INITIATED, STATE_OPEN_RUNNING, STATE_OPEN_SUSPENDED, STATE_CLOSED_COMPLETED, STATE_CLOSED_TERMINATED

suspend

public void suspend()
             throws PMException
Suspends the process instance; all workitems that belong to this instance are also suspended as a result of this operation. When a process instance has been suspended, assignees of any of the workitems that belong to the instance cannot take any action on their respective workitems until the process has returned to the running or active state.

There is no effect by calling this method if the process instance is already suspended.

Throws:
PMException - if there is a problem accessing the back-end database where the process instance is stored.
Since:
NPM 1.0
See Also:
STATE_OPEN_SUSPENDED, resume()

resume

public void resume()
            throws PMException
Resumes the process instance; all workitems that belong to this instance are also resumed.

There is no effect by calling this method if the process instance is not currently suspended.

Throws:
PMException - if there is a problem accessing the back-end database where the process instance is stored.
Since:
NPM 1.0
See Also:
STATE_OPEN_RUNNING, STATE_OPEN_SUSPENDED, suspend

terminate

public void terminate(INodeElement exitNode)
               throws PMException
Terminates the process instance at the given exit node. Calling this method will also terminate all the workitems for this particular process instance.
Parameters:
exitNode - the exit node to terminate this instance at
Throws:
PMException - if there is a problem accessing the back-end database where the process instance is stored; or if the specified node is not actually an exit node.
Since:
NPM 1.0
See Also:
STATE_CLOSED_TERMINATED, INodeElement, IProcessMap

save

public void save()
          throws PMException
Save the process instance and its associated instance data; this method should be called when the desired effect is to just save the changes made to the process instance and not to the workitems associated with the process instance. For example, saving a workitem from the UI involves just saving the instance data and does not require any changes to the workitem.
Throws:
PMException - if there is a problem accessing the back-end database where the process instance is stored
Since:
PAE 4.0
See Also:
IWorkItem.save()

release

public void release(boolean commit)
             throws PMException
Commit/rollback the process instance changes to the back-end store. This method must be called even if the process instance has been obtained for read-only, as this method will release any back-end database connection resources acquired during the life of this object. Failing to call this method at the close of a request could lead to a shortage in available database connections for future requests.

The effect this method will have on the process instance depends upon two factors: the value of the commit parameter and whether the process instance has been loaded for update or read-only.
commit
editable T F
T commit rollback
F noop noop

Note: this method cannot be called in lieu of the IWorkItem method commit. Calling release from IWorkItem will cause newly generated workitems to be routed internally in the engine, while this version of release will simply release database resources.

Parameters:
commit - set to true if want to commit instance changes; otherwise false to rollback changes
Throws:
PMException - is a problem accessing the back-end database where the process instance is stored
Since:
PAE 4.0
See Also:
IWorkItem.release(boolean)

getTitle

public java.lang.String getTitle()
Returns the title of this process instance. Since the title of a process instance is derived from the value of a data element, calling this method is similar to calling getData on the title data field itself and casting the value to a string. The title is always returned as a string, thus if the title data field has a type other than TEXT/LONGTEXT, the returned value will be the textual representation of the data element's value.
Returns:
the title of this process instance.
Since:
NPM 1.0
See Also:
getData(java.lang.String), IDataElement.getType(), IProcessDefinition.getTitleFieldName()

getPriority

public int getPriority()
Returns the priority assigned to this instance. The priority value can range from 1 (highest) to 5 (lowest). The priority value of a process instance is derived from the value of a data element. If this data element has type INT/FLOAT the priority value is fetched from the data element's value; otherwise the default value (3) is returned.
Returns:
the priority value of this process instance.
Since:
NPM 1.0
See Also:
getData(java.lang.String), IDataElement.getType(), IProcessDefinition.getPriorityFieldName()

getEntryNode

public INodeElement getEntryNode()
                          throws PMException
Returns the entry point node where the current process instance was initiated from. All process instances must start from a entry node, thus this method will never return null.
Returns:
the entry point node where the current instance was initiated from.
Since:
PAE 4.0
See Also:
INodeElement, IProcessMap

getExitNode

public INodeElement getExitNode()
                         throws PMException
Returns the exit node where this current process instance has completed at. If the current process instance has not been completed yet, this method will return null.
Returns:
the exit point node if the process instance is complete, null if the process instance is still active.
Since:
PAE 4.0
See Also:
INodeElement, IProcessMap

getClusterName

public java.lang.String getClusterName()
Returns the name of the cluster this instance belongs to.
Returns:
the name of the cluster this instance belongs to.
Since:
iPM 6.5
See Also:
IPMApplication

getApplicationName

public java.lang.String getApplicationName()
Returns the common name of the application this instance belongs to.
Returns:
the name of the application this instance belongs to.
Since:
PAE 4.0
See Also:
IPMApplication

getLastModifiedDate

public java.util.Date getLastModifiedDate()
Returns the date this instance was last modified.
Returns:
the date this instance was last modified.
Since:
PAE 4.0

getAuthenticatedUser

public IParticipant getAuthenticatedUser()
Returns the authenticated user id for this session. The authenticated user represents the corporate directory user that has successfully authenticated with the EJB container. Any access security checks performed on getData and setData are done using this user's identity.
Returns:
the authenticated user id for this session.
Since:
PAE 4.0
See Also:
IParticipant

setAuthenticatedUser

public void setAuthenticatedUser(IParticipant au)
Sets the authenticated user id for this session. This method is only being made available until the security framework for the engine has been completed. At that time, authentication credentials will be accessed from the container itself. This method is only being made public until that transition has finished.
Parameters:
au - the authenticated user for the current session
Since:
PAE 4.0
See Also:
IParticipant

hasBeenArchived

public boolean hasBeenArchived()
Returns true if this process instance has already been archived.
Returns:
true if this process instance has already been archived; false otherwise.
Since:
PAE 4.0
See Also:
archive(java.io.OutputStream)

archive

public void archive(java.io.OutputStream os)
             throws PMException
Archive the contents of the current process instance to an output stream. The archival process consists of three steps:
  1. writing the instance data for the process instance to the output stream; for instance, the creation date of the instance and the entry point node used to initiate the instance,
  2. writing the history data for all the events logged on behalf of this instance to the output stream,
  3. writing the application data (that is, the values of all the data dictionary fields for this instance) to the output stream.
Parameters:
os - the output stream to which the archived data should be written to
Throws:
PMException - if there is a problem writing to the output stream during the archival process; or if there is a problem accessing the back-end database where the process instance is stored
Since:
PAE 4.0

getParentPrimaryKey

public IWorkItemPK getParentPrimaryKey()
Returns the primary key of the parent workitem from which this instance was spawned from. This method is only relevant if this process instance is a subprocess instance. If this process instance does not have a parent work item, null is returned.
Returns:
the primary key of the parent workitem from which this instance was spawned from.
Since:
PM 6.0
See Also:
IWorkItemPK, IWorkItem.getChildPrimaryKey()
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD