Bug 779532

++ This bug is a clone of bug 779531 ++

Affects: Documentation (Ref Guide, User Guide, etc.)
project_key: SOA

This section should be rewritten in the DB and validated with tests:

"
4.1.1.  Relationship with the Configuration Framework 
Persistence API operations should be called from inside a jBPM context block. 
JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext();
try {
  // Invoke persistence operations here
} finally {
  jbpmContext.close();
}
"

The title should become something like "jBPM API basics".  I believe the user should be presented with the proper usage of the API on the SOA platform:

JbpmContext jbpmContext = JbpmConfiguration.getInstance().createJbpmContext();
try {
  // Invoke persistence operations here
} catch (Exception e) {
  jbpmContext.setRollbackOnly();
} finally {
  jbpmContext.close();
}

The invocation of setRollbackOnly should be validated in transactions where there is no ongoing JTA like e.g. in a web app  transaction, and in transactions where there is an ongoing JTA transaction like with a surrounding ejb that already requires a transaction.  Both situations should be tested with a successful jBPM operation and with a jBPM exception that throws an exception.