6 Replies Latest reply on Oct 6, 2009 4:03 PM by kukeltje

    making references to usercode more consistent in jpdl

    tom.baeyens

      hi, i wonder if we can make the usage of expressions in jpdl more consistent. currently we have following usages attributes expr and class to refer to user code

      <custom class="..."
      <custom class="..." method="..."
      <custom expr="..."
      <custom expr="..." method="..."
      
      <event-listener class="..."
      
      <decision expr="..."
      <decision handler-ref="..."
      <decision ...><handler class="..."
      <decision ...><handler class="..." method="..."
      <decision ...><handler expr="..."
      <decision ...><handler expr="..." method="..."
      
      <task ...><assignment-handler class="..."
      <task ...><assignment-handler class="..." method="..."
      <task ...><assignment-handler expr="..."
      <task ...><assignment-handler expr="..." method="..."
      
      <java class="..." method="..."
      <java expr="..."
      
      <script expr="..."
      
      <object class="..."
      <object class="..." method="..."
      <object expr="..."
      <object expr="..." method="..."
      
      <condition expr="..."
      <condition ref="..."
      <condition class="..."
      <condition class="..." method="..."
      


      The general usage of attributes expr, class and method is like this:
      * attributes class and expr are mutually exclusive
      * class specifies an object that is obtained by instantiating the class name
      * expr specifies an object that is obtained as the result of evaluating the expression
      * if together with class or expr a method attribute is specified, then the method will be invoked on the object (or on the class if it is a static method) and the return value of the method will be used instead of the original object

      Here are the combinations that don't fall into the description given above. After each set of exceptions, I describe a proposal of how I think it should be done.

      <decision expr="..."
      <decision handler-ref="..."


      The result of evaluating expr on a decision is assumed to be a String and indicate a outgoing transition name. So <decision expr="..." is a special interpretation of the expression in the context of a decision.

      The handler-ref is a name of an object that is searched for in the environment and that will act as the DecisionHandler. The exact same semantics could be expressed with an expression on the handler element: <decision handler-ref="xxx" is exactly the same as <decision ...><handler expr="#{xxx}"

      <java expr="..."


      The expression will just be executed. Optionally the result will be captured and stored in a variable.

      This is the same as <script expr="..." so I think it should be removed.

      <script expr="..."


      Evaluates the expression. Script is mostly used for multi-line scripting languages like bsh or groovy.

      I think that this usage of <script expr="..." is in fact an assignment. And hence I think we should consider to add an assign activity. Where var represents the left hand side and expr represents the right hand side of an assignment statement.

      <condition expr="..."
      <condition ref="..."
      <condition class="..."
      <condition class="..." method="..."


      This is the most tricky one. The syntax <condition expr="..." is expected to resolve to a Boolean. Where as <condition ref="..." and <condition class="..." are expected to result in an object that implements Condition.

      In order to get this consistent I think we should look at decision and sync the condition syntax and classname accordingly:

      <condition expr="..." would stay as is. This is similar to <decision expr="...". In both cases the result of evaluating expr is used in the specific context. In case of a decision a String is expected indicating the outgoing transition. In case of a condition a boolean is expected.

      I think the interface class Condition should be refactored to ConditionHandler. In that case we can make it consistent with decision. And we can do that as Condition is still in the internal classes.

      Then we can rename ref to handler-ref and introduce a sub-element handler, similar to decision:
      <condition handler-ref
      <condition ...><handler class="..."
      <condition ...><handler class="..." method="..."
      <condition ...><handler expr="..."
      <condition ...><handler expr="..." method="..."


        • 1. Re: making references to usercode more consistent in jpdl
          tom.baeyens

          And with these changes, the question comes about upgrades.

          So when users apply the upgrade to the next version, their old process xml will still be in the db.

          What should be included in our automatic upgrade?


          For now, I forsee that we must add a deployment property 'langid' for all processes deployed in the repository. That should be set jpdl-4.0 for all existing processes in the automatic upgrade. And we also include a mechanism that will add this property and set it to the current library version if we insert a process into the repository. That way, when we parse a process file from the repository we know exactly in what schema version it was deployed. So we just need to make sure that our parser produces the backwards compatible behaviour for it.

          In more general terms, we could discuss:

          What exactly are our stability promises when it comes to jPDL?


          • 2. Re: making references to usercode more consistent in jpdl
            tom.baeyens

            another question that pops up is the following: in the documentation, we make a split between userguide (supported) and devguide (not supported).

            so advanced jpdl properties are not documented in the userguide until they are stable.

            but the xsd schema *must* contain all those details. as otherwise the jpdl file won't parse in advanced users use unsupported properties.

            i don't see any other (practical) way then to explicitely document that the xsd might declare more properties. and that only the properties and constructs described in the userguide are supported/stable.

            is that a reasonable way forward ?

            • 3. Re: making references to usercode more consistent in jpdl
              kukeltje

              and add that to the annotations in the XSD as well. You'll see those when working with sourcecompletion in e.g. eclipse.

              Detailed comment on the previous posts follow

              • 4. Re: making references to usercode more consistent in jpdl
                tom.baeyens

                Guys, a question: Does it make sense to combine an expr with injections when specifying user code ?

                imo it does not. if you specify an event-listener or custom activity behaviour. if you obtain the user code object by resolving an expression, i think it would be highly unlikely for users to want to inject things in it after resolution. since it is resolved as an expression, it doesn't live in the process or the deployment scope. and hence the object lives in another scope like the process instance, process engine, some web beans context maybe. if your object is resolved from these other contexts, it would seem very strange if the process execution would inject values in it.

                so my conclusion is that we'll have more robust software if we explicitely remove injections in case an expr attribute is used to refer to user code.

                wdyt ?

                • 5. Re: making references to usercode more consistent in jpdl
                  tom.baeyens

                  about combining expr with injections:

                  actually, the only use case i can think of where an expression would be useful to instantiate usercode is to have SEAM prepare an object for you. then you could have a seam/webbeans object that declares a number of injections though annotations. those injections could be transactional resources.

                  in that scenario, we explicitely leverage seam to do the injections. so we shouldn't be injecting then.

                  • 6. Re: making references to usercode more consistent in jpdl
                    kukeltje

                    Some small remarks:
                    - I agree with your latest two posts
                    - What is the advantage of having a method attribute with a class on decision, condition etc... There should be well defined interfaces like execute and decide that need to return the correct type. Adding methods is not needed there imo.
                    - With expr I'd ditch the method completely in favour of the normal EL notations for it.
                    - <decision handler-ref="xxx" is exactly the same as <decision ...><handler expr="#{xxx}" would not be my choice. I'd give the handler a name and have the handler-ref point to that name. Unless that is what you mean if xxx is the name of the handler in the jbpm context. Then what you state is what I mean as well.
                    - What is the '' element?
                    - The ref on condition should also be handler-ref like on decision, or the other way around, just be concise