Author: objectiser Date: 2009-02-19 10:59:56 -0500 (Thu, 19 Feb 2009) New Revision: 520 Added: cdl/trunk/docs/docbook/userguide/src/main/images/SVJBossESBAnnotation.jpg Removed: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannparams.png Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml Log: Updated user guide with the new approach to configuring the service validators in JBossESB. Added: cdl/trunk/docs/docbook/userguide/src/main/images/SVJBossESBAnnotation.jpg =================================================================== (Binary files differ) Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/SVJBossESBAnnotation.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannparams.png =================================================================== (Binary files differ) Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml =================================================================== --- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml 2009-02-19 13:52:57 UTC (rev 519) +++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validation-with-cdl.xml 2009-02-19 15:59:56 UTC (rev 520) @@ -5,8 +5,8 @@ <title>Conversation Validation with CDL</title> <section> <title>Overview</title> - <para> - Conversation validation is a form of runtime governance concerned with the dynamic behaviour of a system. + <para> +Conversation validation is a form of runtime governance concerned with the dynamic behaviour of a system. </para> <para> When coupled with a choreography description model of a system, this means having the ability to ensure that the way a collection of services interact correctly adheres to a description of the business process being enacted. @@ -21,8 +21,15 @@ <section> <title>Configuration of Conversation Validation</title> + <para> + This section explains how to configure the conversation validation mechanism to validate ESB services + against a choreography description. The first sub-section describes how the mechanism is hooked into the + JBossESB environment. The following two sub-sections explain two alternate ways that relevant endpoint + references can be configured for validation. + </para> + <section> - <title>Central Configuration</title> + <title>Installing the Conversation Validation Mechanism</title> <para> The principle mechanism used for validating conversations within an ESB is through the use of a global filter registered with the <emphasis>jbossesb-properties.xml</emphasis>. This file is located in the <emphasis>$JBossESB/server/default/deploy/jbossesb.sar</emphasis> folder. </para> @@ -31,7 +38,7 @@ <properties name="filters"> ... <property name="org.jboss.soa.esb.filter.10" - value="org.pi4soa.jbossesb.validator.ValidatorFilter"/> + value="org.jboss.soa.overlord.validator.jbossesb.ValidatorFilter"/> </properties> ]]></programlisting> </informalexample> @@ -39,17 +46,23 @@ <para> This filter is installed as part of the installation process for the Overlord-CDL distribution. </para> + </section> + + <section> + <title>Explicit Configuration</title> + <para> -The information concerning what destinations will be validated, and to which choreography/participant they relate, are contained within the <emphasis>validator-config.xml</emphasis> file, contained within the <emphasis>overlord-cdl-validator.esb</emphasis> bundle. +The information concerning which destinations will be validated, and to which model/role they relate, can be explicitly +defined within the <emphasis>validator-config.xml</emphasis> file, contained within the <emphasis>overlord-cdl-validator.esb</emphasis> bundle. </para> <para> -An example of the contents of this file, as used by the TrailBlazer example, is: +An example of the contents of this file, that would related to the TrailBlazer example, is: </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <validator active="true" > - <service cdmFilePath="models/TrailBlazer.cdm" - participantType="LoanBrokerParticipant" > + <validator mode="monitor" replyToTimeout="10000" > + <service model="TrailBlazer.cdm" + role="LoanBrokerParticipant" > <output epr="jms:queue/esb-tb-creditAgencyQueue" /> <input epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> <output epr="jms:queue/esb-tb-jmsBankRequestQueue" /> @@ -58,20 +71,20 @@ <output epr="jms:queue/esb-tb-customerNotifier" /> <input epr="jms:queue/esb-tb-fileBankResponseQueue" /> </service> - <service cdmFilePath="models/TrailBlazer.cdm" - participantType="CreditAgencyParticipant" > + <service model="TrailBlazer.cdm" + role="CreditAgencyParticipant" > <input epr="jms:queue/esb-tb-creditAgencyQueue" /> <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> </service> - <service cdmFilePath="models/TrailBlazer.cdm" - participantType="BankParticipant" > + <service model="TrailBlazer.cdm" + role="BankParticipant" > <input epr="jms:queue/esb-tb-jmsBankRequestQueue" /> <input epr="jms:queue/esb-tb-fileBankRequestQueue" /> <output epr="jms:queue/esb-tb-jmsBankResponseQueue" /> <output epr="jms:queue/esb-tb-fileBankResponseQueue" /> </service> - <service cdmFilePath="models/TrailBlazer.cdm" - participantType="NotifierParticipant" > + <service model="TrailBlazer.cdm" + role="NotifierParticipant" > <input epr="jms:queue/esb-tb-customerNotifier" /> </service> </validator> @@ -79,59 +92,36 @@ </informalexample> <para> -The 'validator' element has a single boolean attribute called 'active', which determines whether active or passive validation is used. Active validation means that any erronous messages, that conflict with the behaviour as described in the choreography, should be prevented from being received or sent. Passive validation means that the message will continue to be received or sent, and errors will only be reported for information purposes. +The 'validator' element has an optional boolean attribute called 'mode', with the possible values of 'monitor' or 'manage'. If the +mode is 'monitor' (which is the default), then any messages that result in validation errors being detected will continue to be received or sent, with the errors only be reported for information purposes. If the mode is 'manage', then any erronous messages detected during validation, that conflict with the behaviour as described in the choreography, will be prevented from being received or sent. </para> <note> <para> - It is important to note that if 'active' validation is used, then the validation mechanism will be an integral part of the message flow. This may have a slight performance impact on the delivery of messages between services. + It is important to note that if 'manage' validation mode is used, then the validation mechanism will be an integral part of the message flow. This may have a slight performance impact on the delivery of messages between services. </para> </note> + <para> -Within the 'validator' element is a list of 'service' elements, one per service being validated. The behaviour of the service being validated is identified by specifying the choreography model and the participant type within the choreography model. Therefore, within the above configuration, the first set of destinations (eprs) are associated with the <emphasis>LoanBrokerParticipant</emphasis> defined within the choreography description model found in the file <filename>model/TrailBlazer.cdm</filename>, which will be located within the <emphasis>overlord-cdl-validator.esb</emphasis> bundle. +The optional 'replyToTimeout' (defined in milliseconds) is used to determine how long a dynamic reply-to destination should be monitored for validation purposes. In some message exchanges, the response destination will not always be known in advance. Therefore the configuration can identify such situations, and monitor the reply-to destination for the response. However, if a response is not delivered in a particular time period, we need to be able to discontinue the validation of the dynamic endpoint. If this did not occur, then over time too many endpoints would be monitored, which may result in out-of-memory problems. The default timeout period is 10 seconds. </para> <para> +Within the 'validator' element is a list of 'service' elements, one per service being validated. The behaviour of the service being validated is identified by specifying the model (e.g. choreography description file) and the role (e.g. participant type) within the model. Therefore, within the above configuration, the first set of destinations (eprs) are associated with the <emphasis>LoanBrokerParticipant</emphasis> defined within the choreography description model found in the file <filename>models/TrailBlazer.cdm</filename>, which will be located within the <emphasis>overlord-cdl-validator.esb</emphasis> bundle. + </para> + <para> The elements contained within the 'service' element define the <emphasis>input</emphasis> and <emphasis>output</emphasis> eprs (Endpoint References) that are associated with the service. The <emphasis>input</emphasis> eprs are the destinations on which messages will be received and the <emphasis>output</emphasis> eprs are the destinations on which messages will be sent by the service. </para> <para> The format of the 'epr' attribute will be specific to the type of transport used for the ESB aware destination. Currently only JMS is supported, and can be identified by the protocol prefix 'jms:'. </para> + <para> +Each 'input' and 'output' element can also define an optional 'dynamicReplyTo' boolean attribute. If defined, it will indicate to the Service Validator that the message on the specified endpoint (epr) will contain a dynamically defined 'reply-to' destination that needs to be monitored for a response. + </para> </section> <section> - <title>Local Configuration using <emphasis>ValidationAction</emphasis></title> - <para> -Although it is preferrable to validate an .esb bundle using the central configuration, there are times when it is not possible to know the specific destination used to send a message to or from a service. In these situations, it will be necessary to explicitly insert an action into a service descriptor's action pipeline, to observe the message. - </para> - <para> -This can be achieved using the <emphasis>org.pi4soa.jbossesb.validator.ValidationAction</emphasis>, which can be configured with the following properties: - </para> + <title>Defining the Validator Configuration within a Choreography</title> - <informalexample> - <programlisting role="XML" ><![CDATA[ - <action name="LoanBrokerValidatorAction1" - class="org.pi4soa.jbossesb.validator.ValidationAction" - process="processMessage" > - <property name="cdmFilePath" value="models/TrailBlazer.cdm" /> - <property name="participantType" value="LoanBrokerParticipant" /> - <property name="inbound" value="true" /> - <property name="request" value="true" /> - </action> - ]]></programlisting> - </informalexample> - - <para> -The <emphasis>cdmFilePath</emphasis> references the choreography description model, which will usually be a relative path within the <emphasis>overlord-cdl-validator.esb</emphasis> bundle. The <emphasis>participantType</emphasis> property defines which participant the validator action is representing. The optional <emphasis>inbound</emphasis> property indicates whether the message on the action pipeline is being received (true) or sent (false). The optional <emphasis>request</emphasis> property can be used to determine whether the message on the action pipeline represents a request (true) or response/notification (false). - </para> - </section> - </section> - - <section> - <title>Generating the Validator Configuration from a Choreography</title> - - <section> - <title>Defining the ESB Service endpoints</title> - <para> The first step to configuring the validator is to associate the endpoint references (EPRs) against the relevant choreography interactions. This is achieved by defining an @@ -169,14 +159,14 @@ </para> <imageobject> - <imagedata fileref="images/editvalidatorannparams.png" width="5in" /> + <imagedata fileref="images/SVJBossESBAnnotation.jpg" width="5in" /> </imageobject> <para> To specify the EPR for a particular message exchange, enter the EPR into the - <emphasis>Destination</emphasis> field. If however a temporary destination is - used for a message exchange (usually when dealing with responses), then the - <emphasis>temporary</emphasis> checkbox should be selected. + <emphasis>Destination</emphasis> field. If the exchange is a request, that + will result in a response being sent on a dynamically provided "reply-to" + destination, then the <emphasis>Dynamic Reply-To</emphasis> checkbox should be selected. </para> <para> @@ -184,53 +174,16 @@ button to save the annotation against the interaction's exchange details. </para> - </section> - - <section> - <title>Generating the <emphasis>validator-config.xml</emphasis></title> - <para> - To generate the validator configuration details from a choreography description - into the format used by the central configuration mechanism (described previously), - select the <emphasis>Overlord->JBossESB->Generate Validator</emphasis> menu item - associated with the popup menu for the choreography description. + When all of the relevant 'exchange details' components have been configured with + a <emphasis>jbossesb</emphasis> annotation, defining the EPR to be validated, + then the choreography description file can be copied into the + <filename>overlord-cdl-validator.esb/models</filename> folder. This will cause + the validation mechanism to derive the configuration information from the choreography + description model, and begin validating the defined destinations against that + choreography description model. </para> - <imageobject> - <imagedata fileref="images/genvalidatormenu.png" width="5in" /> - </imageobject> - - <para> - When the dialog box is displayed, either enter the path to the <filename>validator-config.xml</filename> - in the text field, or use the <emphasis>Browse</emphasis> button to locate the file. - </para> - - <imageobject> - <imagedata fileref="images/genvalidatordialog.png" width="5in" /> - </imageobject> - - <para> - If the selected file does not exist, then when the <emphasis>Ok</emphasis> button is pressed, - it will be created with the validator configuration associated with the choreography - description. - </para> - - <para> - If the selected file already exists, then any 'service' entries associated with the - choreography file will be updated with the new information from the choreography - description. All other entries in the selected validator configuration file will be - retained. - </para> - - <note> - <para> - If the <emphasis>validator-config.xml</emphasis> file within the JBoss server environment - is directly updated, then the server will need to be restarted before the new configuration - will take effect. Tools to support hot reconfiguration of this file will be provided - in the future. - </para> - </note> - </section> </section> @@ -307,8 +260,8 @@ </para> <informalexample> <programlisting role="XML" ><![CDATA[ - <validator active="true" > - <service participantType="LoanBrokerParticipant" validate="false" > + <validator> + <service role="LoanBrokerParticipant" validate="false" > <output epr="jms:queue/esb-tb-creditAgencyQueue" /> <input epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> <output epr="jms:queue/esb-tb-jmsBankRequestQueue" /> @@ -317,17 +270,17 @@ <output epr="jms:queue/esb-tb-customerNotifier" /> <input epr="jms:queue/esb-tb-fileBankResponseQueue" /> </service> - <service participantType="CreditAgencyParticipant" validate="false" > + <service role="CreditAgencyParticipant" validate="false" > <input epr="jms:queue/esb-tb-creditAgencyQueue" /> <output epr="jms:queue/esb-tb-creditAgencyQueue_reply" /> </service> - <service participantType="BankParticipant" validate="false" > + <service role="BankParticipant" validate="false" > <input epr="jms:queue/esb-tb-jmsBankRequestQueue" /> <input epr="jms:queue/esb-tb-fileBankRequestQueue" /> <output epr="jms:queue/esb-tb-jmsBankResponseQueue" /> <output epr="jms:queue/esb-tb-fileBankResponseQueue" /> </service> - <service participantType="NotifierParticipant" validate="false" > + <service role="NotifierParticipant" validate="false" > <input epr="jms:queue/esb-tb-customerNotifier" /> </service> </validator> @@ -336,7 +289,7 @@ <para> To define a <emphasis>Service Validator</emphasis> in record - only mode, the <emphasis>cdmFilePath</emphasis> attribute + only mode, the <emphasis>model</emphasis> attribute is not specified (because no choreography description exists to be validated against), and the optional <emphasis>validate</emphasis> attribute should be set to <emphasis role="bold">false</emphasis> (by default