jbpm-api first draft

[thomas.diesler]

Folks,

The first draft of the API is available here

http://jbpm.dyndns.org/jbpm-site/jbpm-api/apidocs/index.html

The associated test case is here

http://fisheye.jboss.com/browse/JbpmSvn/tempranillo/jpdl/branches/jbpm3/modules/testsuite/src/test/java/org/jbpm/test/samples/basic/BasicSequenceTest.java

I implemented a mapping to the current jBPM3 code base for this basic test.
On purpose, the API leaves out everything that is not covered by this usecase.

The issue that deals with API design is http://jira.jboss.org/jira/browse/JBPM-1250

Please provide feedback.

[kukeltje]

Thomas,

I assume (without checking first, I know) this is the 'backport' of the public api that will be in PVM?

[thomas.diesler]

Hi Ronald,

conceptually, yes. On our way to jBPM4 we promise backward compatibility of API and process descriptors. Necessary changes in configuration will be documented. Database structure and content may change in an incompatible way.

If you care, please add subtasks to JBPM-1250 that addresses functionality you would like to see covered through the API. Ideally, with a pointer to an equivalent test case in the jBPM3 code base.

Our goal is that user code will only ever have to work with the API and does not have direct dependencies on either the jBPM3 nor jBPM4 code base

cheers
-thomas

[thomas.diesler]

This seems a bit long winded

 // Locate the ProcessEngine
 ProcessEngine engine = ProcessEngineLocator.locateProcessEngine();

 // Create a ProcessDefinition through the ProcessDefinitionManager
 ProcessDefinitionManager pdm = engine.getProcessDefinitionManager();
 ProcessDefinition pd = pdm.createProcessDefinition(jpdl);

 // Create a ProcessInstance through the ProcessInstanceManager
 ProcessInstanceManager pim = engine.getProcessInstanceManager();
 ProcessInstance pi = pim.createProcessInstance(pd);

 // Create an Execution through the ExecutionManager
 ExecutionManager pem = engine.getExecutionManager();
 Execution ex = pem.createExecution(pi);

and could probably be done much shorter - like this

 // Create a ProcessDefinition through the ProcessDefinitionManager
 ProcessDefinitionManager pdm = ProcessDefinitionManager.locateProcessDefinitionManager();
 ProcessDefinition pd = pdm.createProcessDefinition(jpdl);

 // Create an Execution through the ProcessDefinition
 Execution ex = pd.createExecution();

Note however, that this would only introduce convenience access and not change the first approach conceptually.

The API is designed such that objects can be navigated bi-directional. In other words, the ProcessDefinition can get the ProcessInstanceManager and the ExecutionManager and invoke createExecution that way.

I'd like to introduce convenience short cuts when it becomes clear what the most frequent use cases are.

[thomas.diesler]

This is now in place

 // Create a ProcessDefinition through the ProcessDefinitionManager
 ProcessDefinitionManager pdm = ProcessDefinitionManager.locateProcessDefinitionManager();
 ProcessDefinition pd = pdm.createProcessDefinition(jpdl);

 // Create an Execution through the ProcessDefinition
 Execution ex = pd.createExecution();

[tom.baeyens]

i would like to see how in this proposal we're going to implement cross cutting concerns like authorization, transactions, retry upon optimistic locking failure and make it configurable for different environments like plain java, servlet, ee, seam, spring,...

not all the details are necessary, just the interception points.

as far as i got it, your proposal seems to reflect the pattern of a statefull session bean, while i can only see it work with a stateless session bean approach.

[thomas.diesler]

Currently, we are in the process of defining the basic API and getting that right.

Please add this functionality to http://jira.jboss.org/jira/browse/JBPM-1250

We will surely cross that bridge when we come to it.

Does the above API proposal cover the use case that it is intended for appropriately?

[tom.baeyens]

Related side discussion: 3 distinct interfaces or 1 unified interface

http://www.jboss.com/index.html?module=bb&op=viewtopic&p=4159896