1 2 Previous Next 27 Replies Latest reply on Nov 21, 2008 5:00 AM by Thomas Diesler

    API first cut available for jBPM3

    Thomas Diesler Master

      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

        • 1. Re: API first cut available for jBPM3
          Thomas Diesler Master

          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

          • 2. Re: API first cut available for jBPM3
            Thomas Diesler Master

            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.

            • 3. Re: API first cut available for jBPM3
              Ronald van Kuijk Master

              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.

              • 5. Re: API first cut available for jBPM3
                Ronald van Kuijk Master

                 

                "thomas.diesler@jboss.com" wrote:
                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.

                "thomas.diesler@jboss.com" wrote:
                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.

                • 6. Re: API first cut available for jBPM3
                  Thomas Diesler Master

                   


                  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

                  • 7. Re: API first cut available for jBPM3
                    Thomas Diesler Master

                    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

                    • 8. Re: API first cut available for jBPM3
                      Tom Baeyens Master

                      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.

                      • 9. Re: API first cut available for jBPM3
                        Edward Staub Expert

                         

                        "thomas.diesler@jboss.com" wrote:

                        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


                        • 10. Re: API first cut available for jBPM3
                          Ronald van Kuijk Master

                           

                          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 ;-)


                          • 11. Re: API first cut available for jBPM3
                            Thomas Diesler Master

                            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


                            • 12. Re: API first cut available for jBPM3
                              Ben Hu Newbie

                              is this already included in jBPM 3.3.0 GA?

                              • 13. Re: API first cut available for jBPM3
                                Ben Hu Newbie

                                 

                                "thomas.diesler@jboss.com" wrote:
                                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.

                                • 14. Re: API first cut available for jBPM3
                                  Ronald van Kuijk Master

                                   

                                  "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.

                                  1 2 Previous Next