org.jbpm
Class JbpmContext

java.lang.Object
  org.jbpm.JbpmContext

All Implemented Interfaces:

java.io.Serializable

public class JbpmContext
extends java.lang.Object
implements java.io.Serializable

is used to surround persistent operations to processes.

Obtain JbpmContext's via JbpmConfiguration.createJbpmContext() and put it in a try-finally block like this:

 JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext();
 try {
   TaskInstance taskInstance = ...
   
   ...do your process operations...
   
   // in case you update a process object that was not fetched
   // with a ...ForUpdate method, you have to save it.
   jbpmContext.save(processInstance);
 finally {
   jbpmContext.close();
 }
 

A JbpmContext separates jBPM from a sprecific environment. For each service that jBPM uses, there is an interface specified in the jBPM codebase. jBPM also includes implementations that implement these services by using services in a specific environment. e.g. a hibernate session, a JMS asynchronous messaging system, ...

A JbpmContext can demarcate a transaction. When a PersistenceService is fetched from the JbpmContext, the default implementation for the persistence service will create a hibernate session and start a transaction. So that transactions can be configured in the hibernate configuration.

A JbpmContext allows the user to overwrite (or make complete) the configuration by injecting objects programmatically. like e.g. a hibernate session factory or a hibernate session or any other resource that can be fetched or created from the configuration.

Last but not least, JbpmContext provides convenient access to the most common operations such as getTaskList(String), newProcessInstance(String) loadTaskInstanceForUpdate(long) and save(ProcessInstance).

All the ...ForUpdate(...) methods will automatically save the loaded objects at jbpmContext.close();

See Also:

Serialized Form

Field Summary

static java.lang.String

DEFAULT_JBPM_CONTEXT_NAME

Constructor Summary

JbpmContext(Services services, ObjectFactory objectFactory)
normally, JbpmContext object are created via a JbpmConfiguration.

Method Summary

void	addAutoSaveProcessInstance(ProcessInstance processInstance)
void	addAutoSaveTaskInstance(TaskInstance taskInstance)
void	addAutoSaveToken(Token token)
void	close() make sure you close your JbpmContext in a finally block.
void	deployProcessDefinition(ProcessDefinition processDefinition) deploys a process definition.
java.lang.String	getActorId() retrieves the current authenticated actor from the authentication service.
java.sql.Connection	getConnection() gets the jdbc connection from the default configured persistence service.
ContextSession	getContextSession() more variables related database access.
static JbpmContext	getCurrentJbpmContext() obtains the current JbpmContext from a thread local.
GraphSession	getGraphSession() more graph (process) related database access.
java.util.List	getGroupTaskList(java.util.List actorIds) fetches all the task instances for which at least one of the given actorIds is a candidate (pooled actor).
JbpmConfiguration	getJbpmConfiguration()
JobSession	getJobSession() more job related database access.
LoggingSession	getLoggingSession() more logging related database access.
ObjectFactory	getObjectFactory() gives access to the object factory containing the configuration for creating the service factories.
ProcessInstance	getProcessInstance(long processInstanceId) gets a process instance from the db.
ProcessInstance	getProcessInstance(ProcessDefinition processDefinition, java.lang.String key) returns the process instance with the given key or null if no such instance exists.
ProcessInstance	getProcessInstanceForUpdate(long processInstanceId) gets a process instances from the db and registers it for auto-save.
ProcessInstance	getProcessInstanceForUpdate(ProcessDefinition processDefinition, java.lang.String key) returns the process instance with the given key or null if no such instance exists.
ServiceFactory	getServiceFactory(java.lang.String name)
Services	getServices() gives access to the services and service factories.
org.hibernate.Session	getSession() gets the hibernate session from the default configured persistence service.
org.hibernate.SessionFactory	getSessionFactory() gets the hibernate session factory from the default configured persistence service.
TaskInstance	getTaskInstance(long taskInstanceId) gets a task instance from the db.
TaskInstance	getTaskInstanceForUpdate(long taskInstanceId) gets a task instance from the db and registers it for auto-save.
java.util.List	getTaskList() fetches the tasklist for the current authenticated actor.
java.util.List	getTaskList(java.lang.String actorId) fetches the tasklist for the given actor.
TaskMgmtSession	getTaskMgmtSession() more task related database access.
Token	getToken(long tokenId) gets a token from the db.
Token	getTokenForUpdate(long tokenId) get a token from the db and registers it for auto-save.
ProcessInstance	loadProcessInstance(long processInstanceId) loads a process instance from the db.
ProcessInstance	loadProcessInstance(ProcessDefinition processDefinition, java.lang.String key) returns the process instance with the given key or throws an exception if no such instance exists.
ProcessInstance	loadProcessInstanceForUpdate(long processInstanceId) loads a process instances from the db and registers it for auto-save.
ProcessInstance	loadProcessInstanceForUpdate(ProcessDefinition processDefinition, java.lang.String key) returns the process instance with the given key or throws an exception if no such instance exists.
TaskInstance	loadTaskInstance(long taskInstanceId) loads a task instance from the db.
TaskInstance	loadTaskInstanceForUpdate(long taskInstanceId) loads a task instance from the db and registers it for auto-save.
Token	loadToken(long tokenId) loads a token from the db.
Token	loadTokenForUpdate(long tokenId) loads a token from the db and registers it for auto-save.
ProcessInstance	newProcessInstance(java.lang.String processDefinitionName) creates a new process instance for the latest version of the process definition with the given name.
ProcessInstance	newProcessInstanceForUpdate(java.lang.String processDefinitionName) creates a new process instance for the latest version of the process definition with the given name and registers it for auto-save.
void	save(ProcessInstance processInstance) saves the process instance.
void	save(TaskInstance taskInstance) saves the complete process instance for this task instance.
void	save(Token token) saves the complete process instance for this token.
void	setActorId(java.lang.String actorId) sets the currently authenticated actorId.
void	setConnection(java.sql.Connection connection) allows users to provide a jdbc connection to be used when the hibernate session is created. if a nonstandard persistence service is configured, then this call has no effect.
void	setRollbackOnly() mark this transaction for rollback only in the persistence service.
void	setSession(org.hibernate.Session session) sets the hibernate session into the default configured persistence service, preventing the creation of a session from the configured session factory (if there is one configured). if a nonstandard persistence service is configured, then this call has no effect.
void	setSessionFactory(org.hibernate.SessionFactory sessionFactory) sets the hibernate session factory into the default configured persistence service, overwriting the configured session factory (if there is one configured). if a nonstandard persistence service is configured, then this call has no effect.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_JBPM_CONTEXT_NAME

public static final java.lang.String DEFAULT_JBPM_CONTEXT_NAME

See Also:

Constant Field Values

Constructor Detail

JbpmContext

public JbpmContext(Services services,
                   ObjectFactory objectFactory)

normally, JbpmContext object are created via a JbpmConfiguration.

Method Detail

close

public void close()

make sure you close your JbpmContext in a finally block.

getCurrentJbpmContext

public static JbpmContext getCurrentJbpmContext()

obtains the current JbpmContext from a thread local. The current contexts are maintained in a stack so that you can do nested context operations for different jbpm configurations.

it is strongly recommended that client code invokes JbpmConfiguration.getCurrentJbpmContext() in preference to this method.

deployProcessDefinition

public void deployProcessDefinition(ProcessDefinition processDefinition)

deploys a process definition. For parsing process definitions from archives, see the static parseXxx methods on ProcessDefinition.

getTaskList

public java.util.List getTaskList()

fetches the tasklist for the current authenticated actor. With the default configured authentication service, you can set the authenticated user with setActorId(String), then all the subsequent operations will be performed on behalf of that actor.

getTaskList

public java.util.List getTaskList(java.lang.String actorId)

fetches the tasklist for the given actor.

getGroupTaskList

public java.util.List getGroupTaskList(java.util.List actorIds)

fetches all the task instances for which at least one of the given actorIds is a candidate (pooled actor). Typically, for an actor, his/her personal actorId plus all the actorIds representing the groups that person belongs to form the actorIds. Then the user interface should show only the option to take these tasks to the actor's personal task list (with TaskInstance.setActorId(String)). Only task instances that are assigned to the actor directly should be offered the possibility for performing the actual task.

loadTaskInstance

public TaskInstance loadTaskInstance(long taskInstanceId)

loads a task instance from the db.

Throws:

JbpmException - in case no such task instance exists

See Also:

getTaskInstance(long), loadTaskInstanceForUpdate(long), getTaskInstanceForUpdate(long)

getTaskInstance

public TaskInstance getTaskInstance(long taskInstanceId)

gets a task instance from the db.

Returns:

the task instance or null in case no such task instance exists.

See Also:

loadTaskInstance(long), loadTaskInstanceForUpdate(long), getTaskInstanceForUpdate(long)

loadTaskInstanceForUpdate

public TaskInstance loadTaskInstanceForUpdate(long taskInstanceId)

loads a task instance from the db and registers it for auto-save. The loaded task instance will be save automatically at the close(). This is a convenience method in case you plan to do update operations on this task instance.

Throws:

JbpmException - in case no such task instance exists

See Also:

loadTaskInstance(long), getTaskInstance(long), getTaskInstanceForUpdate(long)

getTaskInstanceForUpdate

public TaskInstance getTaskInstanceForUpdate(long taskInstanceId)

gets a task instance from the db and registers it for auto-save. The loaded task instance will be save automatically at the close(). This is a convenience method in case you plan to do update operations on this task instance.

Returns:

the task instance or null in case no such task instance exists.

See Also:

loadTaskInstance(long), getTaskInstance(long), loadTaskInstanceForUpdate(long)

loadToken

public Token loadToken(long tokenId)

loads a token from the db.

Throws:

JbpmException - in case no such token exists.

See Also:

getToken(long), loadTokenForUpdate(long), getTokenForUpdate(long)

getToken

public Token getToken(long tokenId)

gets a token from the db.

Returns:

the token or null in case no such token exists.

See Also:

loadToken(long), loadTokenForUpdate(long), getTokenForUpdate(long)

loadTokenForUpdate

public Token loadTokenForUpdate(long tokenId)

loads a token from the db and registers it for auto-save. The loaded token will be save(Token)d automatically at the close(). This is a convenience method in case you plan to do update operations on this token.

Throws:

JbpmException - in case no such token exists.

See Also:

getToken(long), loadToken(long), getTokenForUpdate(long)

getTokenForUpdate

public Token getTokenForUpdate(long tokenId)

get a token from the db and registers it for auto-save. The loaded token will be save(Token)d automatically at the close(). This is a convenience method in case you plan to do update operations on this token.

Returns:

the token or null in case no such token exists.

See Also:

getToken(long), loadToken(long), loadTokenForUpdate(long)

loadProcessInstance

public ProcessInstance loadProcessInstance(long processInstanceId)

loads a process instance from the db. Consider using loadProcessInstanceForUpdate(long) if you plan to perform an update operation on the process instance.

Throws:

JbpmException - in case no such process instance exists.

See Also:

getProcessInstance(long), loadProcessInstanceForUpdate(long), getProcessInstanceForUpdate(long)

getProcessInstance

public ProcessInstance getProcessInstance(long processInstanceId)

gets a process instance from the db. Consider using loadProcessInstanceForUpdate(long) if you plan to perform an update operation on the process instance.

Returns:

the token or null in case no such token exists.

See Also:

loadProcessInstance(long), loadProcessInstanceForUpdate(long), getProcessInstanceForUpdate(long)

loadProcessInstanceForUpdate

public ProcessInstance loadProcessInstanceForUpdate(long processInstanceId)

loads a process instances from the db and registers it for auto-save. The loaded process instance will be save(ProcessInstance)d automatically at the close(). This is a convenience method in case you plan to do update operations on this process instance.

Throws:

JbpmException - in case no such process instance exists.

See Also:

loadProcessInstance(long), getProcessInstance(long), getProcessInstanceForUpdate(long)

getProcessInstanceForUpdate

public ProcessInstance getProcessInstanceForUpdate(long processInstanceId)

gets a process instances from the db and registers it for auto-save. The loaded process instance will be save(ProcessInstance)d automatically at the close(). This is a convenience method in case you plan to do update operations on this process instance.

Returns:

the token or null in case no such token exists.

See Also:

loadProcessInstance(long), getProcessInstance(long), loadProcessInstanceForUpdate(long)

getProcessInstance

public ProcessInstance getProcessInstance(ProcessDefinition processDefinition,
                                          java.lang.String key)

returns the process instance with the given key or null if no such instance exists.

loadProcessInstance

public ProcessInstance loadProcessInstance(ProcessDefinition processDefinition,
                                           java.lang.String key)

returns the process instance with the given key or throws an exception if no such instance exists.

getProcessInstanceForUpdate

public ProcessInstance getProcessInstanceForUpdate(ProcessDefinition processDefinition,
                                                   java.lang.String key)

returns the process instance with the given key or null if no such instance exists. Upon close of this jbpmContext, the fetched process instance will be automatically saved.

loadProcessInstanceForUpdate

public ProcessInstance loadProcessInstanceForUpdate(ProcessDefinition processDefinition,
                                                    java.lang.String key)

returns the process instance with the given key or throws an exception if no such instance exists. Upon close of this jbpmContext, the fetched process instance will be automatically saved.

newProcessInstance

public ProcessInstance newProcessInstance(java.lang.String processDefinitionName)

creates a new process instance for the latest version of the process definition with the given name.

Throws:

JbpmException - when no processDefinition with the given name is deployed.

newProcessInstanceForUpdate

public ProcessInstance newProcessInstanceForUpdate(java.lang.String processDefinitionName)

creates a new process instance for the latest version of the process definition with the given name and registers it for auto-save.

Throws:

JbpmException - when no processDefinition with the given name is deployed.

save

public void save(ProcessInstance processInstance)

saves the process instance.

save

public void save(Token token)

saves the complete process instance for this token.

save

public void save(TaskInstance taskInstance)

saves the complete process instance for this task instance.

setRollbackOnly

public void setRollbackOnly()

mark this transaction for rollback only in the persistence service. The close() operation will then perform a rollback.

getServices

public Services getServices()

gives access to the services and service factories.

getServiceFactory

public ServiceFactory getServiceFactory(java.lang.String name)

getObjectFactory

public ObjectFactory getObjectFactory()

gives access to the object factory containing the configuration for creating the service factories.

getSessionFactory

public org.hibernate.SessionFactory getSessionFactory()

gets the hibernate session factory from the default configured persistence service.

Returns:

the hibernate session factory, or null if a nonstandard persistence service is configured

setSessionFactory

public void setSessionFactory(org.hibernate.SessionFactory sessionFactory)

sets the hibernate session factory into the default configured persistence service, overwriting the configured session factory (if there is one configured). if a nonstandard persistence service is configured, then this call has no effect.

getSession

public org.hibernate.Session getSession()

gets the hibernate session from the default configured persistence service.

Returns:

the hibernate session, or null if a nonstandard persistence service is configured.

setSession

public void setSession(org.hibernate.Session session)

sets the hibernate session into the default configured persistence service, preventing the creation of a session from the configured session factory (if there is one configured). if a nonstandard persistence service is configured, then this call has no effect.

getConnection

public java.sql.Connection getConnection()

gets the jdbc connection from the default configured persistence service.

Returns:

the jdbc connectoin, or null if a nonstandard persistence service is configured.

setConnection

public void setConnection(java.sql.Connection connection)

allows users to provide a jdbc connection to be used when the hibernate session is created. if a nonstandard persistence service is configured, then this call has no effect.

getContextSession

public ContextSession getContextSession()

more variables related database access.

getLoggingSession

public LoggingSession getLoggingSession()

more logging related database access.

getJobSession

public JobSession getJobSession()

more job related database access.

getGraphSession

public GraphSession getGraphSession()

more graph (process) related database access.

getTaskMgmtSession

public TaskMgmtSession getTaskMgmtSession()

more task related database access.

getActorId

public java.lang.String getActorId()

retrieves the current authenticated actor from the authentication service.

setActorId

public void setActorId(java.lang.String actorId)

sets the currently authenticated actorId.

addAutoSaveProcessInstance

public void addAutoSaveProcessInstance(ProcessInstance processInstance)

addAutoSaveToken

public void addAutoSaveToken(Token token)

addAutoSaveTaskInstance

public void addAutoSaveTaskInstance(TaskInstance taskInstance)

getJbpmConfiguration

public JbpmConfiguration getJbpmConfiguration()