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
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    Declares to the Process Engine that the new Context created by the requiresNew() method can be closed.
    static void
    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
    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 Details

    • ProcessEngineContext

      public ProcessEngineContext()
  • Method Details

    • 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