API first cut available for jBPM3

[thomas.diesler]

Folks,

following our team meeting in Antwerp I trimmed down the API+CTS that I had in the incubator project to the functionality and concepts that we agreed on.

http://www.jboss.org/community/docs/DOC-12945

In Antwerp we decided that the threading model that is native to jBPM (i.e. borrowing the client Thread) should be supported by the API, which actually makes a mapping to the jBPM3 code base possible.

How the API+CTS can be integrated in the Maven build is documented here

http://www.jboss.org/community/docs/DOC-12871

the Java Doc is here

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

Doing this work for jBPM3 has multiple benefits.

#1
It will be much easier to decide when jBPM3 functional equivalence is reached

#2
Projects that require a stable API but also have a dependency on jBPM3 can start to decouple from jBPM3 implementation detail and interface with the API. This is particularly true for the GWT-Console and to some extend to the GPD.

#3
The migration to jBPM4 will be seamless for projects that use the API as an integration point

#4
TomB who leads the API and provides an implementation for jBPM4 can reuse the jBPM3 integration and make good progress in jBPM4.

#5
Folks that know jBPM3 can start to provide qualified and meaningful feedback based on API signatures and CTS test implementations

Over the next couple of weeks I still expect to see some movement in the API+CTS snapshot artefacts until it becomes clear what will actually go into 3.3.1 and 4.0.0.Alpha1 respectively

[thomas.diesler]

Here a few notes on differences and limitations

ProcessInstance => Process

In Java an object instance is commonly called Foo not FooInstance. The standard talks about an "instance of a Process" rather than a ProcessInstance

Execution => Token

We agreed that an 'Execution' is not the same as a 'ProcessInstance' and should therefore exist as two separate entities in the API. Token is the concept that is known to jBPM3 users already and also appears under this name in the standards.

Tokens may have a parent child relationship, Process' do not.
A Process can be started, a Token cannot.
A Process has structure (i.e. child Nodes), a Token has not.

I didn't (yet) adapt the XML marshalling layer. Currently this is implementation detail of the dialect that is actually used in combination with the CTS and does neither effect CTS test cases nor API signatures. In other words, if the dialect is pluggable anyway it does not matter much what the actual XML will look like.

This becomes however important as soon as XML snippets enter the documentation. My mid Dec this should be settled so that we can start posting process definitions in XML

[thomas.diesler]

Ah ... forgot to say

Feedback on on individual API signature details and specific test cases is of course welcome.

The discussion around these details should start rather sooner than later to give folks the chance to work productively with snapshots that are reasonable stable.

[kukeltje]

Nice progress, I did not ecpect this. Will have a look at it, the comming days. You have some valid arguments for already having it available for jBPM 3.

[thomas.diesler]

Here is the current home of the CTS test classes

http://fisheye.jboss.com/browse/JbpmSvn/projects/spec/trunk/modules/cts/src/test/java/org/jbpm/test/cts?%40hideEmptyDirectories=Y

[kukeltje]

ProcessInstance => Process

In Java an object instance is commonly called Foo not FooInstance. The standard talks about an "instance of a Process" rather than a ProcessInstance

Hmm... semantics? imo this is not about the intstance of a Process (Java) object but of an instance of the Process as a business object as compared to the definition. Your argument is kind of still valid than (about removing the Instance part) just in another context. Otoh, it makes it kind of clear that it is *not* a definition.

Tokens may have a parent child relationship, Process' do not.
A Process can be started, a Token cannot.
A Process has structure (i.e. child Nodes), a Token has not.

What about the relation between processes and subprocesses? Are those only visible via the definition? It might make sense to have a method in the api that says Process.hasRunningChildProcesses() or something like that.

[thomas.diesler]

Otoh, it makes it kind of clear that it is *not* a definition.

The distinction to ProcessDefinition is still there.

The API would have ProcessDefinition

http://jbpm.dyndns.org/jbpm-spec/jbpm-spec-api/apidocs/org/jbpm/api/model/ProcessDefinition.html

and Process

http://jbpm.dyndns.org/jbpm-spec/jbpm-spec-api/apidocs/org/jbpm/api/model/Process.html

What about the relation between processes and subprocesses? Are those only visible via the definition?

They would be visible on both the ProcessDefinition and the Process. The ProcessDefinition is the immutable instance that defines the structure. The Process is the runtime copy of that structure that is mutable to some degree. (i.e. to associate state with individual Node instances)

A running Sub-Process would probably be a reference to a Process, but this definitely needs to be revisited when we come to the point when Sub-Processes appear on the API roadmap, which should be early next year.

Thanks for your feedback

[thomas.diesler]

Please also note, that both Process and ProcessDefinition share common functionality from ProcessStructure

http://jbpm.dyndns.org/jbpm-spec/jbpm-spec-api/apidocs/org/jbpm/api/model/ProcessStructure.html

ProcessStructure would however never appear in user code and can probably be moved to internal

[tom.baeyens]

i replied on the mailing list instead of the forum:

The scope of jBPM 3 work is already way beyond the resources we have for it. We should focus on the necessary work to put jBPM 3 in maintenance rather then introducing a new API on it.

We said in the meeting in the context of the migration debate that no API will be introduced in jBPM 3. A new API will be introduced in jBPM 4.

Apart from that, using the term process to indicate a process instance would be highly confusing.

[estaub]

Otoh, it makes it kind of clear that it is *not* a definition.

The distinction to ProcessDefinition is still there.

FWIW (bikeshed) - in my experience with business-analysts and other non-Java-heads, people informally use the term "Process" to refer to a Definition more often than they use it to refer to an Instance. When we talk about, say, "designing a business process", we're clearly talking about a definition, not an instance. This is an odd case where English has a word for the definition, but not for instances of that definition. So "Process" doesn't obviously mean "Process Instance".

-Ed Staub

[kukeltje]

The distinction to ProcessDefinition is still there.

I know that there is a Process and a ProcessDefinition, but to many people the difference might not be clear.

Apart from that, using the term process to indicate a process instance would be highly confusing.

This is indeed what I meant.

And reading Ed's comment he thinks the same. Might be the difference between the (up to now) more theoretical people and the ones with dirty hands ;-)

[thomas.diesler]

Thanks for your comments, but what should it actually be?

#1
ProcessDefinition + Process

#2
ProcessDefinition + ProcessInstance

#3
something else completely

Please also consider the usage of these artefacts

ProcessDefinitionService pdService = engine.getService(ProcessDefinitionService.class);

ProcessDefinition procDef = pdService.createProcessDefinition(XML);
Process proc = procDef.newProcess();

Token tok = proc.startProcess();

vs.

ProcessDefinitionService pdService = engine.getService(ProcessDefinitionService.class);

ProcessDefinition procDef = pdService.createProcessDefinition(XML);
ProcessInstance procInst = procDef.newProcessInstance();

Token tok = procInst.startProcessInstance();

Generally, please come up with an alternative suggestion if a given proposal is no good for some reason i.e. I don't like Foo because ... Instead I propose Bar

[benhu]

is this already included in jBPM 3.3.0 GA?

[benhu]

Thanks for your comments, but what should it actually be?

#1
ProcessDefinition + Process

#2
ProcessDefinition + ProcessInstance

#3
something else completely

Please also consider the usage of these artefacts

ProcessDefinitionService pdService = engine.getService(ProcessDefinitionService.class);

ProcessDefinition procDef = pdService.createProcessDefinition(XML);
Process proc = procDef.newProcess();

Token tok = proc.startProcess();

vs.

ProcessDefinitionService pdService = engine.getService(ProcessDefinitionService.class);

ProcessDefinition procDef = pdService.createProcessDefinition(XML);
ProcessInstance procInst = procDef.newProcessInstance();

Token tok = procInst.startProcessInstance();

Generally, please come up with an alternative suggestion if a given proposal is no good for some reason i.e. I don't like Foo because ... Instead I propose Bar

I think #1 works fine. From my point of view, even for business people when they mention "Process", they can mean both. Because for business people, they do not differentiate between definition and "instance". They think that they draw a diagram and the process is up like magic.

[kukeltje]

"benhu" wrote:
is this already included in jBPM 3.3.0 GA?

No, it is a separate package in alpha (or even pre-alpha) state. Lot's of changes can and probably will take place as you can see about the discussion (of which we had some very constructive ones during the team meeting). Reading Tom's arguments, it is currently there to get feedback on it, e.g. by using it in combination with jBPM 3.3 AS EXPERIMENT. So do not rely on it for production.