Package org.camunda.bpm.engine.context

Class ProcessEngineContext

  • public class ProcessEngineContext
extends java.lang.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();
  }

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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​(java.util.concurrent.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​(java.util.concurrent.Callable<T> callable)
                                         throws java.lang.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:
        java.lang.Exception