Author: jeff.yuchang Date: 2008-10-22 02:40:53 -0400 (Wed, 22 Oct 2008) New Revision: 412 Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/EPRWrapper.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/HibernateObject.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Identity.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/IdentityType.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/JoinState.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/ScheduleItem.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Session.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/SessionStatus.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ConversationAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/CreateSessionAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/IfAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/MessageRouterAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ParallelAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/PerformAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ReceiveMessageAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/RetrieveSessionAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ScheduleStateAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SendMessageAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/Service.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetMessageAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetStateAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SwitchAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhenAction.java cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhileAction.java Log: * [SOA-70] Add javadoc. Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/EPRWrapper.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/EPRWrapper.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/EPRWrapper.java 2008-10-22 06:40:53 UTC (rev 412) @@ -32,8 +32,8 @@ /** * + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> - * */ @Entity Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/HibernateObject.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/HibernateObject.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/HibernateObject.java 2008-10-22 06:40:53 UTC (rev 412) @@ -22,6 +22,8 @@ import java.io.Serializable; /** + * Any object that needs to be stored by using Hibernate, + * it needs to implement this interface. It is used internally. * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> * Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Identity.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Identity.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Identity.java 2008-10-22 06:40:53 UTC (rev 412) @@ -35,6 +35,27 @@ import javax.persistence.Table; /** + * A 'session' object, whether representing the top level (root) session, or a child session, + * should be identified by the following information: + * + * <ol> + * <li> + * Service description name - this name reflects the participant behaviour within a choreography, + * and provides the necessary link to enable conformance checking with the choreography description + * </li> + * <li> + * POJO class name - Each sub session needs to be distinguished, in case it uses common identity objects. + * Using the POJO class name in conjunction with the service description name, provides a unique way to reference a sub-session. + * So the POJO class name is effectively in place of the 'choreography unit' name. + * Combining it with the service description name, also enables the same POJO to be used within the behaviour description for different participants - + * i.e. it does not force the user to declare two separate classes, with the same properties, just to distinguish the different participants within the choreography. + * </li> + * <li> + * Set of 'primary' or 'alternate' business identities, detail see {@link IdentityType} - this list will contain identity details extracted from business messages, + * to correlate those messages to a particular session (or sub-session). + * </li> + * </ol> + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/IdentityType.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/IdentityType.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/IdentityType.java 2008-10-22 06:40:53 UTC (rev 412) @@ -20,7 +20,19 @@ package org.jboss.soa.overlord.jbossesb; /** + * According to WS-CDL specificatio, it has four types of identity. * + * <ul> + * <li><i>primary</i> - the primary identity field, used to associate a message with the session. </li> + * <li><i>alternate</i> - an alternative primary identity. </li> + * <li><i>associate</i> - link the message to a session based on an identity previously associated with the session (or parent session). + * However this identity will not be associated with the current session, + * it is usually only used to link a child session to a parent session. </li> + * <li><i>derived</i> - the extracted identity will be placed in reserve for use as the primary identity for a subsequent session. + * It is not directly associated with the session in which it is discovered.</li> + * </ul> + * + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/JoinState.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/JoinState.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/JoinState.java 2008-10-22 06:40:53 UTC (rev 412) @@ -28,6 +28,7 @@ import javax.persistence.Table; /** + * It represents the forked JBoss ESB service, which waits for other ESB services to converge. * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/ScheduleItem.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/ScheduleItem.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/ScheduleItem.java 2008-10-22 06:40:53 UTC (rev 412) @@ -28,6 +28,7 @@ import javax.persistence.Table; /** + * An item represent for JBoss ESB service. * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Session.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Session.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/Session.java 2008-10-22 06:40:53 UTC (rev 412) @@ -52,7 +52,35 @@ import org.jboss.soa.esb.message.Message; /** + * A Session represents the encapsulation of the current status of execution of an associated choreography instance, + * as well as variables containing business information relevant to the choreography. * + * <p> + * A Session represents a single choreography unit within a WS-CDL package. + * This means that a single choreography description (or package) will usually have multiple sessions, + * one associated with the root choreography unit, and zero or more associated with other non-root choreography units, + * that are directly or indirectly performed by the root choreography unit. + * </p> + + * <p> + * This Session class should not be visible outside the ESB conversational actions. + * There should be no reason for user custom actions to require access to this information. + * The only information they should be able to access is the business state information associated with the session. + * </p> + * + * <p> + * Sessions can be organized in a hierarchy, with the top session being associated with a root choreography unit, + * and the child sessions being the performed sub-choreographies. + * </p> + * + * <p> + * The session maintains a schedule of service descriptors to be processed (represented by the category and name of the service). + * This schedule indicates which service descriptors are expected to be invoked on behalf of the session. + * The execution of a service descriptor's action pipeline on a session will result in the service descriptor being removed from the schedule, + * but may result in other service descriptors being added to the schedule, depending upon the nature of the conversation actions within the pipeline. + * </p> + * + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/SessionStatus.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/SessionStatus.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/SessionStatus.java 2008-10-22 06:40:53 UTC (rev 412) @@ -23,7 +23,6 @@ /** * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> - * */ public enum SessionStatus { Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ConversationAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ConversationAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ConversationAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -46,19 +46,6 @@ /** * Base activity, all the ESB conversation aware actions extend from this one. * - * <pre> - * The procedure of processing a message is as following: - * 1. Get current session from the database. - * Include injecting context, such as injecting parent session business object if it exists - * 2. Unschedule current service, if it is first conversation action. - * 3. Handle Message. (This will be override by subclasses) - * 4. Save session object back to database. - * Update the parent session if it is necessary. - * 5. If it is the last conversation action in current service. - * And if it has no schedule items to invoke. Mark session status to 'Completed' - * 5.1 If it is sub-session, then invoke sub-session exit service. - * 6. Deliver message to services at last if it needs to. - * </pre> * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> @@ -95,19 +82,20 @@ /** - * <pre> * The procedure of processing a message is as following: - * 1. Get current session from the database. + * <ul> + * <li> Get current session from the database. * Include injecting context, such as injecting parent session business object if it exists - * 2. Unschedule current service, if it is first conversation action. - * 3. Handle Message. (This will be override by subclasses) - * 4. Save session object back to database. - * Update the parent session if it is necessary. - * 5. If it is the last conversation action in current service. - * And if it has no schedule items to invoke. Mark session status to 'Completed' - * 5.1 If it is sub-session, then invoke sub-session exit service. - * 6. Deliver message to services at last if it needs to. - * </pre> + * </li> + * <li> Unschedule current service, if it is first conversation action.</li> + * <li> Handle Message. (This will be override by subclasses) </li> + * <li> Save session object back to database. </li> + * <li> Update the parent session if it is necessary.</li> + * <li> If it is the last conversation action in current service.</li> + * And if it has no schedule items to invoke. Set session status as 'Completed' + * ** If it is sub-session, then invoke sub-session exit service. + * <li> Deliver message to services at last if it needs to.</li> + * </ul> * * @param message * @return Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/CreateSessionAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/CreateSessionAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/CreateSessionAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -26,8 +26,31 @@ import org.jboss.soa.overlord.jbossesb.SessionManager; /** - * This action creates a new session. * + * This action indicates the starting state associated with a session. + * + * <p> + * This can either be associated with a top level 'root' choreography, + * or a sub-choreography that is performed by an outer choreography. + * </p> + * + * <h4>Usage:</h4> + * <pre> + * {@literal + * <action class="org.jboss.soa.overlord.jbossesb.actions.CreateSessionAction" + * process="process" name="s1-1"> + * <property name="session" value="org.jboss.soa.overlord.samples.jbossesb.loan.broker.BrokerMain" /> + * </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li> + * <i>session </i> - stands for its associated business information class. + * </li> + * </ul> + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> * Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/IfAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/IfAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/IfAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -28,6 +28,26 @@ * This action represents a choice between a set of specified paths * based on the message that has occurred. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.IfAction" name="c3" process="process"> + <property name="paths"> + <if expression="isCreditValid()" immediate="true" service-category="PurchaseGoods.CreditAgency" service-name="CreditAgency.decision1"/> + <else immediate="true" service-category="PurchaseGoods.CreditAgency" service-name="CreditAgency.decision2"/> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>expression</i> - The decision method, the method result should be Boolean type, and it doesn't have any input parameters.</li> + * <li><i>serivce-category</i> - mapped to JBoss ESB service-category</li> + * <li><i>service-name</i> - mapped to JBossESB service-name<li> + * <li><i>immediate</i> - whether send message to the specified service-category and service-name immediately.</li> + * </ul> + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/MessageRouterAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/MessageRouterAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/MessageRouterAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -27,11 +27,42 @@ import org.jboss.soa.esb.listeners.message.MessageDeliverException; import org.jboss.soa.esb.message.Message; import org.jboss.soa.overlord.jbossesb.Identity; +import org.jboss.soa.overlord.jbossesb.IdentityType; import org.jboss.soa.overlord.jbossesb.ScheduleItem; /** * The action is used to perform routing of the inbound requests. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.MessageRouterAction" + process="process" name="s0-1"> + <property name="paths"> + <route service-category="ESBBroker.BrokerParticipant" + service-name="ESBBrokerProcess.main" + initiate="true"> + <message type="enquiry"> + <identity type="primary" > + <token name="id" locator="//@id" /> + </identity> + </message> + </route> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>serivceCategory</i> and <i>serviceName</i> - together represent a ESB service.</li> + * <li><i>initiate</i> - An optional 'initiate' boolean attribute. + * If the attribute is specified, and its value is 'true', then the route can only be selected if the service instance relevant for the inbound message does not yet exist, + * and this message will result in a {@link CreateSessionAction} being invoked to create the service instance. + * If the attribute value is 'false', or not specified, then a service instance must already exist that is capable of handling the inbound message.</li> + * <li><i>message.type</i> - Define the Message Type for routing.</li> + * <li><i>identity</i> - Detail refer to {@link IdentityType}</li> + * </ul> + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ public class MessageRouterAction extends ConversationAction { Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ParallelAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ParallelAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ParallelAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -24,8 +24,30 @@ import org.jboss.soa.esb.message.Message; /** - * This action represents a parallel construct. + * The ParallelAction is used to spawn two or more paths. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.ParallelAction" name="b5" process="process"> + <property name="paths"> + <path immediate="true" service-category="PurchaseGoods.Store" service-name="StoreBranch1"/> + <path immediate="true" service-category="PurchaseGoods.Store" service-name="StoreBranch2"/> + <join service-category="PurchaseGoods.Store" service-name="ReturnBuyerResponse"/> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>serivceCategory</i> and <i>serviceName</i> - together represent a ESB service.</li> + * <li><i>immediate</i> - Whether deliver the message to target service immediately or not.</li> + * <li><i>path</i> - This is used to define the service that is need to be invoked.</li> + * <li><i>join</i> - This is the converged point for spawned services</li> + * </ul> + * + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/PerformAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/PerformAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/PerformAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -29,7 +29,39 @@ import org.mvel.MVEL; /** + * PerformAction is used to invoke a child session. + * It doesn't create the sub-session, it just populated all needed information into Message Object, + * and then directed to the {@link CreateSessionAction} to create sub-session. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.PerformAction" + process="process" name="s3-1"> + <property name="serviceCategory" value="ESBBroker.BrokerParticipant" /> + <property name="serviceName" value="RequestForQuote.main" /> + <property name="returnServiceCategory" value="ESBBroker.BrokerParticipant" /> + <property name="returnServiceName" value="ESBBrokerProcess.main.9" /> + <property name="parentReference" value="quoteManager"/> + <property name="bindDetails" > + <bind from-expression="getCurrentSupplier()" + to-variable="supplier" /> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>serivceCategory</i> - Mapped to JBoss ESB service-category</li> + * <li><i>serviceName</i> - Mapped to JBossESB service-name<li> + * <li><i>returnServiceCategory</i> - The service-category of service, when sub-session has completed (it is optional).</li> + * <li><i>returnServiceName</i> - The service-name of service, when sub-session has completed. (it is optional)</li> + * <li><i>parentReference</i> - The property to set the parent session's business state object for sub-sesion's business state object.</li> + * <li><i>bind.from-expression</i> - the property or method of parent session's business state object.</li> + * <li><i>bind.to-variable</i> - the propert of sub-session's business state object</li> + * </ul> + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> * */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ReceiveMessageAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ReceiveMessageAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ReceiveMessageAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -26,11 +26,31 @@ import org.jboss.soa.overlord.jbossesb.Identity; /** - * <p> - * The ReceiveMessageAction is used to explicitly define the message type that should be received. - * If an RPC style has been used, then the optional operation name can also be defined. - * </p> + * The ReceiveMessageAction is used to explicitly define the message type that should be received and a set of identities. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.ReceiveMessageAction" name="c2" process="process"> + <property name="messageType" value="CreditCheckRequest"/> + <property name="clientEPR" value="broker"/> + <property name="identities"> + <identity type="primary"> + <token locator="//@id" name="id"/> + </identity> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>messageType </i> - Define the message type that should be received.</li> + * <li><i>clientEPR</i> - Define an EPR label that used to map to the 'reply-to' address.</li> + * <li><i>identities</i> - The CDL's identity, see {@link Identity}</li> + * </ul> + * + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/RetrieveSessionAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/RetrieveSessionAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/RetrieveSessionAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -27,8 +27,28 @@ import org.jboss.soa.overlord.jbossesb.Identity; /** - * This action gets an existed session. + * It retrieves existing sessions instead of creating new sessions. * + * <p> + * Its purpose is to identify an action pipeline as conversation based, + * and ensure that a suitable session exists. + * </p> + * + * The configuration would be like: + * + * <pre> + * <action class="org.jboss.soa.overlord.jbossesb.actions.RetrieveSessionAction" + * process="process" name="s11-1"> + * <property name="session" value="org.jboss.soa.overlord.samples.jbossesb.loan.broker.CompleteTransactionMain" /> + * <property name="serviceDescriptionName" value="{http://www.jboss.org/overlord/loanBroker}CompleteTransaction... /> + * <property name="identities" > + * <identity type="primary" > + * <token name="id" locator="//@id" /> + * </identity> + * </property> + * </action> + * </pre> + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ScheduleStateAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ScheduleStateAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/ScheduleStateAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -24,8 +24,27 @@ import org.jboss.soa.esb.message.Message; /** - * Schedule state activity. + * ScheduleStateAction enables an service descriptor's category and name to be added to the schedule for the session. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.ScheduleStateAction" + process="process" name="s1-3"> + <property name="serviceCategory" value="ESBBroker.BrokerParticipant" /> + <property name="serviceName" value="ESBBrokerProcess.main.1" /> + <property name="immediate" value="true" /> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>serviceCategory</i> - Mapped to JBossESB service-category.</li> + * <li><i>serviceName</i> - Mapped to JBossESB service-name.</li> + * <li><i>immediate</i> - Define whether send the message the to target service immediately or not.</li> + * </ul> + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SendMessageAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SendMessageAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SendMessageAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -37,8 +37,74 @@ /** - * Send message activity. + * Deliver message to the target service. * + * <p> + * This action enables a message, being processed by the action pipeline, to be sent to a nominated destination. + * The destination for the message being sent can be identified in two ways: + * </p> + * + * <ul> + * <li> + * <i>Explicitly</i><br/> + * A service category and name can be specified, to indicate the destination of the message to be sent. + * When this approach is used, it will be possible to optionally specify a 'reply to' service category and name, + * to which any subsequent response can be sent. In this case, the 'reply to' service category and name will be placed on the schedule for the session. + * </li> + * <li> + * <i>Implicitly</i>(Based on JBossESB EPR)<br/> + * If a previously received message had a 'reply to EPR', which was then associated with a label, + * then the message can be sent back to the originator of that previous message by specifying the label associated with the EPR. + * </li> + * </ul> + * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + process="process" name="s4-3"> + <property name="messageType" value="quoteList" /> + <property name="clientEPR" value="buyer" /> + <property name="identities" > + <identity type="primary" > + <token name="id" locator="//@id" /> + </identity> + </property> + </action> + * } + * </pre> + * OR: + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.SendMessageAction" + process="process" name="s8-4"> + <property name="messageType" value="requestForQuote" /> + <property name="serviceNameExpression" value="supplier.serviceName" /> + <property name="serviceCategoryExpression" value="supplier.serviceCategory" /> + <property name="responseServiceName" value="RequestForQuote.main.1" /> + <property name="responseServiceCategory" value="ESBBroker.BrokerParticipant" /> + <property name="identities" > + <identity type="primary" > + <token name="id" locator="//@id" /> + </identity> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>messageType </i> - Define the message type that is prepared to sent to.</li> + * <li><i>clientEPR</i> - This is JBossESB EPR Label, represents a JBossESB EPR that can be used to send a message to.</li> + * <li><i>serviceName</i> - Mapped to JBossESB service-name.</li> + * <li><i>serviceCategory</i> - Mapped to JBossESB service-category.</li> + * <li><i>servceNameExpression</i> - The EL expression against session's associated business state object to get the service-name value.</li> + * <li><i>serviceCategoryExpression</i> - The EL expression against session's associated business state object to get the service-category value.</li> + * <li><i>responseServiceName</i> - The service-name of the responded message.</li> + * <li><i>responseServiceCategory</i> - The service-category of the responded message.</li> + * </ul> + * + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/Service.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/Service.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/Service.java 2008-10-22 06:40:53 UTC (rev 412) @@ -21,7 +21,6 @@ /** * - * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetMessageAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetMessageAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetMessageAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -25,8 +25,25 @@ import org.mvel.MVEL; /** - * Set object into the 'ESB Message' Object. + * SetMessageAction enables the information contained within the ESB Message object, + * currently being passed through the action pipeline, to be updated based on information from the business state pojo. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.SetMessageAction" name="s8-2"> + <property name="headerProperty" value="serviceDescriptionName" /> + <property name="stateExpression" value="supplier.serviceDescription" /> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>headerProperty</i> - The key in ESB Message's header.</li> + * <li><i>stateExpression</i> - The property or method of session associated business state class.</li> + * </ul> + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> * */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetStateAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetStateAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SetStateAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -27,7 +27,35 @@ import org.w3c.dom.Element; /** + * SetStateAction is intended to enable business state, associated with the POJO for the session, + * to be set/updated based on information derived from either the business state or the current message object. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.SetStateAction" name="s7-2"> + <property name="variable" value="selectedQuoteValue" /> + <property name="messageExpression" value="//@quoteValue" /> + </action> + * } + * </pre> + * OR: + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.SetStateAction" name="s17-2"> + <property name="variable" value="supplierIndex" /> + <property name="stateExpression" value="nextSupplier()" /> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>variable</i> - The property in the session associated business state class.</li> + * <li><i>messageExpression</i> - The EL expression against ESB message Object.<li> + * <li><i>stateExpression</i> - The property or method of session associated business state class.</li> + * </ul> + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ public class SetStateAction extends ConversationAction { Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SwitchAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SwitchAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/SwitchAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -24,9 +24,34 @@ import org.jboss.soa.esb.message.Message; /** - * This action represents a choice between a set of specified paths - * based on the message that has occurred. + * SwitchAction provides a means to select the relevant path based on the type of a message being processed by the action. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.SwitchAction" + process="process" name="s11-2"> + <property name="paths"> + <case service-category="ESBBroker.BrokerParticipant" + service-name="CompleteTransaction.main.2" > + <message type="CreditCheckOk" /> + </case> + <case service-category="ESBBroker.BrokerParticipant" + service-name="CompleteTransaction.main.4" > + <message type="CreditCheckInvalid" /> + </case> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>serivce-category</i> - mapped to JBoss ESB service-category.</li> + * <li><i>service-name</i> - mapped to JBossESB service-name.<li> + * <li><i>type</i> - The message type that should be received.</li> + * </ul> + * * @author <a href="mailto:gary.brown@hattricksoftware.com">Gary Brown</a> * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhenAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhenAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhenAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -25,7 +25,29 @@ import org.mvel.MVEL; /** + * WhenAction will enable one or more specified states to be triggered when an associated expression evaluates to true. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.WhenAction" + process="process" name="s4-1"> + <property name="paths"> + <when expression="receivedAllQuotes()" + service-category="ESBBroker.BrokerParticipant" + service-name="ESBBrokerProcess.main.4" /> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>expression</i> - The decision method, the method result should be Boolean type, and it doesn't have any input parameters.</li> + * <li><i>serivce-category</i> - mapped to JBoss ESB service-category.</li> + * <li><i>service-name</i> - mapped to JBossESB service-name.<li> + * </ul> + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> * */ Modified: cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhileAction.java =================================================================== --- cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhileAction.java 2008-10-21 22:18:32 UTC (rev 411) +++ cdl/trunk/runtime/jbossesb/src/main/java/org/jboss/soa/overlord/jbossesb/actions/WhileAction.java 2008-10-22 06:40:53 UTC (rev 412) @@ -25,7 +25,34 @@ import org.mvel.MVEL; /** + * WhileAction will enable provide the traditional 'while' loop construct. * + * <h4>Usage:</h4> + * <pre> + * {@literal + <action class="org.jboss.soa.overlord.jbossesb.actions.WhileAction" + process="process" name="s2-1"> + <property name="paths"> + <while expression="hasSuppliers()" + service-category="ESBBroker.BrokerParticipant" + service-name="ESBBrokerProcess.main.2" + immediate="true" /> + <exit service-category="ESBBroker.BrokerParticipant" + service-name="ESBBrokerProcess.main.3" + immediate="true" /> + </property> + </action> + * } + * </pre> + * + * <h4>Description of configuration properties:</h4> + * <ul> + * <li><i>expression</i> - The decision method, the method result should be Boolean type, and it doesn't have any input parameters.</li> + * <li><i>serivce-category</i> - mapped to JBoss ESB service-category.</li> + * <li><i>service-name</i> - mapped to JBossESB service-name.<li> + * <li><i>immediate</i> - whether send message to the specified service-category and service-name immediately.</li> + * </ul> + * * @author <a href="mailto:cyu@redhat.com">Jeff Yu</a> */ public class WhileAction extends ConversationAction {