Transactions - redhat-consulting/jbpm-ee GitHub Wiki

The following sections discuss transactional considerations when integrating an application with jBPM-EE via REST, SOAP, JMS, and EJB services.

Distributed Transactions with Local and Remote EJBs

The following diagram describes that when using the EJB interfaces (Local and Remote), the JTA transaction started by your application will be assumed and continued by jBPM. jBPM will participate in that transaction. If jBPM encounters an exception, the calling transaction will be rolled back. If the application encounters an exception after calling jBPM, the jBPM transaction will subsequently be rolled back.

height=400px|align=center

Transactions with SOAP and RESTful Interface

The following diagram describes that when using REST and SOAP interfaces, the transaction started by your application will be a separate transaction from the jBPM transaction. This means, if the jBPM layer throws an exception, you will manually need to handle this in your code in terms of coordination with your application transaction. Once the call to jBPM-EE SOAP/REST interfaces is successful, the jBPM-EE transaction is committed.
height=400px|align=center

Failure Scenarios

The following diagram describes the transactions required to complete the workflow. Note that in the example, there are three transactions, each moving the process forward.

align=center

####The Process####

  • The "Start Process Instance" transaction (Transaction 1) will start the process and move it to the Human Task "String Input". The caller to ProcessService.startProcess(...) will block until the process instance moves to the first point in which it can no longer move forward, which in this example is the "Human Task".
  • The "Human Task" transaction (Transaction 2) occurs when the user completes the task, moving the process forward, crossing over the custom work item handler and script nodes, and to the timer. The caller to TaskService.complete(...) will block until the process moves to the first point in which it can no longer move forward, in this case the "Timer" node.
  • The "Timer" transaction (Transaction 3) occurs when the timer executes after a delay. The "Timer" thread will control execution until the process moves to the first point in which it can no longer move forward, in this case the end node.

####Process State####

  • In between the transactions, the process state is "dehydrated", written to the database.
  • The application server memory during the "dehydrated" periods do not contain the process instance data.

##Failure Case - External Signals## The following diagram describes what happens when an exception occurs while execution is being triggered by an external application. In this example, the Customer Application calls into the TaskService.complete(...) method, completing a task and moving it forward. align=center

###The Process###

  1. The Customer Application calls into the JBPM-EE Services executing the TaskService.complete(...) method, completing the Task Instance.
  2. The process instance moves forward to the Custom Handler.
  3. An exception occurs in Custom Handler.

###Process State###

  • When the exception occurs, "Transaction 2" is marked for Rollback.
  • The calling thread which executed TaskService.complete(...) will be thrown an exception by the jBPM-EE Services.
  • If the calling thread is utilizing the jBPM-EE EJB Local or Remote interfaces and its calls participated in a transaction, the main transaction will be rolled back.
  • If the calling thread is utilizing the jBPM-EE REST or SOAP interfaces and it's calls participated in a transaction, the calling application will need to handle the thrown exception and coordination with it's own transaction.
  • After the transactions are rolled back due to the exception, the process instance will no longer be in memory, and the state of the process will be waiting, again, on the "Human Task" node. Moving the process forward would require another call to TaskService.complete(...).

##Failure Case - Timers## The following diagram helps to illustrate the case in which an exception occurs while the calling thread is started by a jBPM Timer. align=center

###The Process###

  1. The jBPM timer service identifies a timer is ready to fire.
  2. The jBPM timer service begins a Transaction.
  3. The jBPM timer service hydrates the process instance from the database.
  4. The jBPM timer service signals the process instance to leave the timer node.
  5. The process instance moves to the Script tag, and then forward to the Custom Handler.
  6. The Custom Handler Throws an Exception.

###Process State###

  • The Transaction started by the Timer Service is marked for rollback.
  • After the transaction is rolled back due to the exception, the process instance will no longer be in memory. The state of the process instance will be waiting at the Timer node. The timer service will immediately see that the Timer needs to be executed, and retry execution.
  • The Timer Service will retry the process 5 times by default before marking the Timer as invalid.

##Failure Scenario - Calling Application## The following diagrams describe the failure scenario when an application first makes calls into jBPM and then has a failure in its own application code.

####Step 1#### The Customer Application starts a JTA transaction, then persists data to its own database.

height=100px

####Step 2#### The Customer Application calls ProcessService.startProcess(...), starting a process instance.

https://github.com/redhat-consulting/jbpm-ee/wiki/images/transactions/process1.png

####Step 3#### The Customer Application makes a call to its own internal API, which throws a Runtime Exception.

height=100px

###Local and Remote EJB Interfaces### With the Local and Remote EJB interfaces, the jBPM-EE Services execute in the same transaction as the calling thread. In this case, that calling thread is within Customer Application, which already has a JTA transaction. When the Customer Application, therefore, experiences an exception after calling the jBPM-EE Services, the Customer Application persistence in Step 1 and the jBPM Process Instance state change (moving from Start State to Human Task) in Step 2 are both rolled back when the exception occurs in Step 3.

###REST and SOAP Interfaces### In this case, the jBPM Process is not rolled back, because the jBPM-EE Services execute in a separate transaction from the calling application, Customer Application. While the Customer Application's transaction is rolled back, the jBPM Process Instance has moved forward from the Start state to the Human Task.