org.camunda.bpm.engine.context

Class ProcessEngineContext

java.lang.Object

org.camunda.bpm.engine.context.ProcessEngineContext

public class ProcessEngineContext
extends Object

When a Process Engine API call is performed, the engine will create a Process Engine Context. The context caches database entities, so that multiple operations on the same entity do not result in multiple database queries. This also means that the changes to these entities are accumulated and are flushed to the database as soon as the Process Engine API call returns (however, the current transaction might be committed at a later time).

If a Process Engine API call is nested into another call, the default behaviour is to reuse the existing Process Engine Context. This means that the nested call will have access to the same cached entities and the changes made to them.

When the nested call is to be executed in a new transaction, a new Process Engine Context needs to be created for its execution. In this case, the nested call will use a new cache for the database entities, independent of the previous (outer) call cache. This means that, the changes in the cache of one call are invisible to the other call and vice versa. When the nested call returns, the changes are flushed to the database independently of the Process Engine Context of the outer call.

The ProcessEngineContext is a utility class to declare to the Process Engine that a new Process Engine Context needs to be created in order for the database operations in a nested Process Engine API call to be separated in a new transaction.

Example on declaring a new Process Engine Context:

  try {
    ProcessEngineContext.requiresNew();
    runtimeService.startProcessInstanceByKey("EXAMPLE_INSTANCE");
  } finally {
    ProcessEngineContext.clear();
  }
 

Constructor Summary

Constructors

Constructor and Description
ProcessEngineContext()

Method Summary

Modifier and Type	Method and Description
static void	clear() Declares to the Process Engine that the new Context created by the requiresNew() method can be closed.
static void	requiresNew() Declares to the Process Engine that a new, separate context, bound to the current thread, needs to be created for all subsequent Process Engine database operations.
static <T> T	withNewProcessEngineContext(Callable<T> callable) Takes a callable and executes all engine API invocations within that callable in a new Process Engine Context.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessEngineContext

public ProcessEngineContext()

Method Detail

requiresNew

public static void requiresNew()

Declares to the Process Engine that a new, separate context, bound to the current thread, needs to be created for all subsequent Process Engine database operations. The method should always be used in a try-finally block to ensure that clear() is called under any circumstances. Please see the ProcessEngineContext class documentation for a more detailed description on the purpose of this method.

clear

public static void clear()

Declares to the Process Engine that the new Context created by the requiresNew() method can be closed. Please see the ProcessEngineContext class documentation for a more detailed description on the purpose of this method.

withNewProcessEngineContext

public static <T> T withNewProcessEngineContext(Callable<T> callable)
                                         throws Exception

Takes a callable and executes all engine API invocations within that callable in a new Process Engine Context. Please see the ProcessEngineContext class documentation for a more detailed description on the purpose of this method.

An alternative to calling: try { requiresNew(); callable.call(); } finally { clear(); }

Parameters:

callable - the callable to execute

Returns:

what is defined by the callable passed to the method

Throws:

Exception