<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">

<div>
        <table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
                <tbody>
                        <tr>

                                <td>

                                        <table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
                                                <tbody>
                                                        <tr>
                                                                <td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
                                                                        <h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
                                                                        <!-- To have a header image/logo replace the name below with your img tag -->
                                                                        <!-- Email clients will render the images when the message is read so any image -->
                                                                        <!-- must be made available on a public server, so that all recipients can load the image. -->
                                                                        <a href="https://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
                                                                </td>

                                                        </tr>
                                                        <tr>
                                                                <td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px;  -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
    Human Task Module Refactoring
</h3>
<span style="margin-bottom: 10px;">
    modified by <a href="https://community.jboss.org/people/salaboy21">Mauricio Salatino</a> in <i>jBPM</i> - <a href="https://community.jboss.org/docs/DOC-18789">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">

<div class="jive-rendered-content"><p>This document aims to explain how the human task module should look after applying some refactorings which were the results of several experiments.</p><p>You can more about this experiments here: <a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal">https://github.com/Salaboy/human-task-poc-proposal</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>The following sections describe how the module will look like after the refactorings</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h1>APIs and Service Structure</h1><p>All the Services Proposed by this refactoring are CDI managed beans. For the ones not familiar with CDI, you need to think about it as JPA for Dependency Injection frameworks. So we can say</p><p>that CDI is to Spring/Guice/Weld what JPA is to Hibernate/Top Link. CDI propose some very cool out of the box features that we definitely want to use to make our services more clear, robust, easy to maintain. Some of the things provided by CDI that I'm using in the experiments are:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><ul><li>Configuration based on annotations: We can inject services instances without needing to specify the implementation, so we keep it pluggable and decoupled all the time.<br/>Look at: <a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/impl/TaskInstanceServiceImpl.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/impl/TaskInstanceServiceImpl.java</a><br/>As you can see there, we can define at service level which characteristic the service implementation will need to be injected inside a service, but then we can provide several alternatives<br/>for that implementation and configure them for different environments. The CDI container will do the rest for us, it will choose wisely the implementation that fits with all the characteristic required and it will inject the services implementation when it's need.<br/><br/></li><li>Event Producers and Observers <br/>Look at: <a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/MVELLifeCycleManager.java#L246">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/MVELLifeCycleManager.java#L246</a><br/>and: <a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/lifecycle/listeners/JPATaskLifeCycleEventListener.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/lifecycle/listeners/JPATaskLifeCycleEventListener.java</a><br/>As you can see a simple and out of the box (and defined by an specification) Event mechanism is provided, allowing us to keep our Event Producers completely Decoupled from our Event Observers. We can also configure the obsevers to be instantiated by teh CDI container or we can decide how many instances of our observer do we need for a particular use case.<br/><br/></li><li>Decorators/Interceptors: <br/>We can use both to improve a specific technical or business policy should be applied to the execution of our service methods. <br/>Look at: <a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/UserGroupLifeCycleManagerDecorator.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/UserGroupLifeCycleManagerDecorator.java</a><br/>Decorators and Interceptors can be enabled and disabled based on configurations, which give us once again a great flexibility to add or remove things based on what we want to achieve.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>At the end of the day we have a set of services which can leverage the power of the CDI container. We can also hide that we are using CDI/Weld (weld is the implementation of the CDI interfaces/spec), look at: <a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/test/java/org/jboss/human/interactions/NewAPITest.java#L259">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/test/java/org/jboss/human/interactions/NewAPITest.java#L259</a></p><p>We can use it internally and if the user wants to get access to the container he/she can. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p><a href="https://community.jboss.org/servlet/JiveServlet/showImage/102-18789-3-19052/TaskServicesProposed.png"><span> https://community.jboss.org/servlet/JiveServlet/downloadImage/102-18789-3-19052/450-439/TaskServicesProposed.png </span></a></p><p>All the proposed services are simple POJOs which can contain references to all the other services. We can combine them to achive different functionality.</p><p>For a more detailed description about each service you can look at: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>The next section describe more advantages about using the CDI/Weld proposed programming model to keep our services simple and take out all the code that is not related with Human Interaction logic.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h1>Services Working Together</h1><p>The following image shows how the interactions with the human task module will happen. The diagram shows the interfaces and implementations required to interact with a TaskInstance</p><p><a href="https://community.jboss.org/servlet/JiveServlet/showImage/102-18789-3-19050/TaskInstanceServiceSimplified.png"><span> https://community.jboss.org/servlet/JiveServlet/downloadImage/102-18789-3-19050/450-252/TaskInstanceServiceSimplified.png </span></a></p><p>The previous figure shows all the components interacting when we want to interact with a task instance that was already created. </p><p>So let's say for example that we want to start a task. From the client perspective he/she can use the <span style="font-family: Consolas, 'Liberation Mono', Courier, monospace; font-size: 12px; text-align: -webkit-auto; background-color: #ffffff;">TaskServiceEntryPoint</span> to </p><p>start the task. This <span style="font-family: Consolas, 'Liberation Mono', Courier, monospace; font-size: 12px; text-align: -webkit-auto; background-color: #ffffff;">TaskServiceEntryPoint</span> will delegate the calls to the different service implementations. In this case if we are </p><p>starting a task the TaskInstanceService implementation will delegate the action to the LifeCycleManager. As you can see</p><p>the LifeCycleManager, no matter the implementation is being decorated by an UserGroupDecorator which in charge of handling the</p><p>resolution of the identities associated with the operation. The LifeCycleManager is also an Event Producer, which means that is in charge</p><p>of generating events to communicate to the external world the LifeCycle changes of each task. We can then attach external listeners to </p><p>Observer these events to audit what is happening or as callback mechanisms to execute actions when a task is completed for example.</p><p>Classes and Interfaces to look at this point:</p><p><a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/api/TaskServiceEntryPoint.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/api/TaskServiceEntryPoint.java</a></p><p><a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/impl/TaskInstanceServiceImpl.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/impl/TaskInstanceServiceImpl.java</a></p><p><a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/impl/TaskDefServiceImpl.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/impl/TaskDefServiceImpl.java</a></p><p><a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/MVELLifeCycleManager.java">https://github.com/Salaboy/human-task-poc-proposal/blob/master/human-task-core-cdi-experiment/src/main/java/org/jboss/human/interactions/internals/lifecycle/MVELLifeCycleManager.java</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>No magic, no complicated debug sessions, the services should be as straight forward as possible trying to following the sequence:</p><p><strong>TaskServiceEntryPoint ---(Delegate)--&gt; Task*ServiceImpl -&gt; Storage</strong></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h3>Shared Persistence Context and Transactional Behavior</h3><p>If you take a look at the previous links you will notice that all the Services, for example TaskInstanceServiceImpl and TaskDefServiceImpl are all using an Inject EntityManager.</p><p>And there is no code related with transactions or loading and merging detached entities (em.getTransaction(), ut.begin(), em.merge()). </p><p>The EntityManager that is being injected is being managed by Seam Persistence (ASL 2.0) (<a class="jive-link-external-small" href="http://docs.jboss.org/seam/3/persistence/latest/reference/en-US/html_single/">http://docs.jboss.org/seam/3/persistence/latest/reference/en-US/html_single/</a>) which give us a transparent</p><p>way of having all the advantages of the unified programming model of being in Managed and Transaction Persistence Context without the hassle of taking care of how to share different</p><p>instances of an EntityManager or demarcate the transactions based on what is available in our context. Seam Persistence provide us a declarative way to deal with all this topics, and take all the code</p><p>related with these tasks out of the Human Task Module. This also give us the possibility to integrate with Spring only configuring our environment and not changing our code </p><p>(<a class="jive-link-external-small" href="http://www.javaworld.com/javaworld/jw-05-2008/jw-05-spring-seam3.html">http://www.javaworld.com/javaworld/jw-05-2008/jw-05-spring-seam3.html</a>)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h1>Integration with the Outside World</h1><p>Using CDI for the integration perspective is just great. Most of the integration frameworks out there have CDI integration which make exposing our services extremely easy and natural.</p><p>I've created an experiment showing how we can do this with Switchyard/Camel, and most of this principles can be used for the Process/Rule engine as well:</p><p><a class="jive-link-external-small" href="https://github.com/Salaboy/human-task-poc-proposal/tree/master/human-task-switchard">https://github.com/Salaboy/human-task-poc-proposal/tree/master/human-task-switchard</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>The main focus of this project is to contain all the integration configuration required to expose our POJO services using different transports. I've being focused on JMS because it will allow</p><p>us to have asynchronous interactions transparently. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>The following figure shows us teh Switchyard Declarative configuration which is using our CDI POJO services to define the integration points:</p><p><a href="https://community.jboss.org/servlet/JiveServlet/showImage/102-18789-3-19053/subscribers.png"><span> https://community.jboss.org/servlet/JiveServlet/downloadImage/102-18789-3-19053/450-190/subscribers.png </span></a></p><p>The previous diagram is showing the following interaction and integration points:</p><ol><li>A client sending a JMS message wants to start a task</li><li>The Switchyard container is exposing a JMS queue which is expecting "Action" messages</li><li>As soon as we get one of this action messages, Switchyard picks the message and propagate it to the correspondant service</li><li>We can register a listener that will observe the events being fired by our components (i.e. TaskLifeCycleEvents)</li><li>As soon as one of these events is observed by our listener it will be redirected to a JMS topic which can contain multiple subscribers</li><li>Any number of subscribers can pick up the message and do what they want with it</li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>Cool Facts:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><ol><li>This experiment is just showing one of the possibilities of using Switchyard and the camel integration for handling async interactions in a very efficient way, without including code inside the Human Task Module. We are delegating all the interaction points to the Integration framework instead of adding complexity to the Human Task Logic.</li><li>We can integrate with any transport in the same way and we can mix and match what we want. For example, we can recieve a REST call and send notifications via JMS</li><li>Switchyard and all the services can run inside a SE or EE environment (because of CDI and its programming model)</li><li>Is all based on configuration, so we can provide a set of well known configurations and let the users to customize that if they want</li><li>Quartz for reminders, cron tasks and all of that comes for free</li><li>Push us to use a clean programming model, leverage all the CDI features</li></ol></div>

<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
    <p style="margin: 0;">Comment by <a href="https://community.jboss.org/docs/DOC-18789">going to Community</a></p>

        <p style="margin: 0;">Create a new document in jBPM at <a href="https://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2034">Community</a></p>
</div></td>
                        </tr>
                    </tbody>
                </table>


                </td>
            </tr>
        </tbody>
    </table>

</div>

</body>
</html>