From overlord-commits at lists.jboss.org Thu Feb 19 10:59:56 2009 Content-Type: multipart/mixed; boundary="===============0679800401586750834==" MIME-Version: 1.0 From: overlord-commits at lists.jboss.org To: overlord-commits at lists.jboss.org Subject: [overlord-commits] Overlord SVN: r520 - in cdl/trunk/docs/docbook/userguide/src/main: module and 1 other directory. Date: Thu, 19 Feb 2009 10:59:56 -0500 Message-ID: --===============0679800401586750834== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 validat= ors in JBossESB. Added: cdl/trunk/docs/docbook/userguide/src/main/images/SVJBossESBAnnotatio= n.jpg =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D (Binary files differ) Property changes on: cdl/trunk/docs/docbook/userguide/src/main/images/SVJBo= ssESBAnnotation.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: cdl/trunk/docs/docbook/userguide/src/main/images/editvalidatorannp= arams.png =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D (Binary files differ) Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-val= idation-with-cdl.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validatio= n-with-cdl.xml 2009-02-19 13:52:57 UTC (rev 519) +++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-validatio= n-with-cdl.xml 2009-02-19 15:59:56 UTC (rev 520) @@ -5,8 +5,8 @@ Conversation Validation with CDL
Overview - - Conversation validation is a form of runtime governance concerned with = the dynamic behaviour of a system. + +Conversation validation is a form of runtime governance concerned with the= dynamic behaviour of a system. When coupled with a choreography description model of a system, this means= having the ability to ensure that the way a collection of services interac= t correctly adheres to a description of the business process being enacted. @@ -21,8 +21,15 @@
Configuration of Conversation Validation = + + This section explains how to configure the conversation validation mecha= nism 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 alterna= te ways that relevant endpoint + references can be configured for validation. + +
- Central Configuration + Installing the Conversation Validation Mechanism The principle mechanism used for validating conversations within an ESB is= through the use of a global filter registered with the jbossesb-= properties.xml. This file is located in the $JBossESB/= server/default/deploy/jbossesb.sar folder. @@ -31,7 +38,7 @@ ... + value=3D"org.jboss.soa.overlord.validator.jbossesb.ValidatorFilter"/> ]]> @@ -39,17 +46,23 @@ This filter is installed as part of the installation process for the Overl= ord-CDL distribution. +
+ +
+ Explicit Configuration + -The information concerning what destinations will be validated, and to whi= ch choreography/participant they relate, are contained within the validator-config.xml file, contained within the overl= ord-cdl-validator.esb bundle. +The information concerning which destinations will be validated, and to wh= ich model/role they relate, can be explicitly +defined within the validator-config.xml file, contain= ed within the overlord-cdl-validator.esb bundle. -An example of the contents of this file, as used by the TrailBlazer exampl= e, is: +An example of the contents of this file, that would related to the TrailBl= azer example, is: - + + @@ -58,20 +71,20 @@ - + - + - + @@ -79,59 +92,36 @@ = -The 'validator' element has a single boolean attribute called 'active', wh= ich determines whether active or passive validation is used. Active validat= ion means that any erronous messages, that conflict with the behaviour as d= escribed in the choreography, should be prevented from being received or se= nt. 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', w= ith 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, wit= h the errors only be reported for information purposes. If the mode is 'man= age', 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. - It is important to note that if 'active' validation is used, then the v= alidation mechanism will be an integral part of the message flow. This may = have a slight performance impact on the delivery of messages between servic= es. + 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 s= ervices. + -Within the 'validator' element is a list of 'service' elements, one per se= rvice being validated. The behaviour of the service being validated is iden= tified by specifying the choreography model and the participant type within= the choreography model. Therefore, within the above configuration, the fir= st set of destinations (eprs) are associated with the LoanBrokerP= articipant defined within the choreography description model fou= nd in the file model/TrailBlazer.cdm, which will be lo= cated within the overlord-cdl-validator.esb bundle. +The optional 'replyToTimeout' (defined in milliseconds) is used to determi= ne how long a dynamic reply-to destination should be monitored for validati= on purposes. In some message exchanges, the response destination will not a= lways be known in advance. Therefore the configuration can identify such si= tuations, and monitor the reply-to destination for the response. However, i= f a response is not delivered in a particular time period, we need to be ab= le to discontinue the validation of the dynamic endpoint. If this did not o= ccur, then over time too many endpoints would be monitored, which may resul= t in out-of-memory problems. The default timeout period is 10 seconds. +Within the 'validator' element is a list of 'service' elements, one per se= rvice being validated. The behaviour of the service being validated is iden= tified 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 th= e LoanBrokerParticipant defined within the choreograph= y description model found in the file models/TrailBlazer.cdm, which will be located within the overlord-cdl-validator.e= sb bundle. + + The elements contained within the 'service' element define the i= nput and output eprs (Endpoint References) = that are associated with the service. The input eprs a= re the destinations on which messages will be received and the ou= tput eprs are the destinations on which messages will be sent by= the service. The format of the 'epr' attribute will be specific to the type of transpor= t used for the ESB aware destination. Currently only JMS is supported, and = can be identified by the protocol prefix 'jms:'. + +Each 'input' and 'output' element can also define an optional 'dynamicRepl= yTo' boolean attribute. If defined, it will indicate to the Service Validat= or that the message on the specified endpoint (epr) will contain a dynamica= lly defined 'reply-to' destination that needs to be monitored for a respons= e. + =
=
- Local Configuration using <emphasis>ValidationAction</emphasis><= /title> - <para> -Although it is preferrable to validate an .esb bundle using the central co= nfiguration, there are times when it is not possible to know the specific d= estination 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 descri= ptor's action pipeline, to observe the message. - </para> - <para> -This can be achieved using the <emphasis>org.pi4soa.jbossesb.validator.Val= idationAction</emphasis>, which can be configured with the following proper= ties: - </para> + <title>Defining the Validator Configuration within a Choreography</titl= e> = - <informalexample> - <programlisting role=3D"XML" ><![CDATA[ - <action name=3D"LoanBrokerValidatorAction1" = - class=3D"org.pi4soa.jbossesb.validator.ValidationAction" = - process=3D"processMessage" > - <property name=3D"cdmFilePath" value=3D"models/TrailBlazer.cdm" /> - <property name=3D"participantType" value=3D"LoanBrokerParticipant" /> - <property name=3D"inbound" value=3D"true" /> - <property name=3D"request" value=3D"true" /> - </action> - ]]></programlisting> - </informalexample> - - <para> -The <emphasis>cdmFilePath</emphasis> references the choreography descripti= on model, which will usually be a relative path within the <emphasis>overlo= rd-cdl-validator.esb</emphasis> bundle. The <emphasis>participantType</emph= asis> property defines which participant the validator action is representi= ng. The optional <emphasis>inbound</emphasis> property indicates whether th= e 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 - -
- Defining the ESB Service endpoints - The first step to configuring the validator is to associate the endpoint= references (EPRs) against the relevant choreography interactions. This is achieved by defi= ning an @@ -169,14 +159,14 @@ = - + = To specify the EPR for a particular message exchange, enter the EPR into= the - Destination field. If however a temporary destinati= on is - used for a message exchange (usually when dealing with responses), then = the - temporary checkbox should be selected. + Destination field. If the exchange is a request, th= at + will result in a response being sent on a dynamically provided "reply-to" + destination, then the Dynamic Reply-To checkbox sho= uld be selected. = @@ -184,53 +174,16 @@ button to save the annotation against the interaction's exchange details. = -
- -
- Generating the <emphasis>validator-config.xml</emphasis> - - To generate the validator configuration details from a choreography desc= ription - into the format used by the central configuration mechanism (described p= reviously), - select the Overlord->JBossESB->Generate Validator m= enu item - associated with the popup menu for the choreography description. + When all of the relevant 'exchange details' components have been configu= red with + a jbossesb annotation, defining the EPR to be valid= ated, + then the choreography description file can be copied into the + overlord-cdl-validator.esb/models folder. This will= cause + the validation mechanism to derive the configuration information from th= e choreography + description model, and begin validating the defined destinations against= that + choreography description model. = - - - - - - When the dialog box is displayed, either enter the path to the validator-config.xml - in the text field, or use the Browse button to loca= te the file. - - - - - - - - If the selected file does not exist, then when the Ok button is pressed, - it will be created with the validator configuration associated with the = choreography - description. - - - - If the selected file already exists, then any 'service' entries associat= ed with the - choreography file will be updated with the new information from the chor= eography - description. All other entries in the selected validator configuration f= ile will be - retained. - - - - - If the validator-config.xml file within the JBoss s= erver environment - is directly updated, then the server will need to be restarted before th= e new configuration - will take effect. Tools to support hot reconfiguration of this file will= be provided - in the future. - - -
=
@@ -307,8 +260,8 @@ - + + @@ -317,17 +270,17 @@ - + - + - + @@ -336,7 +289,7 @@ = To define a Service Validator in record - only mode, the cdmFilePath attribute + only mode, the model attribute is not specified (because no choreography description exists to be validated against), and the optional validate attribute should be set to false (by = default --===============0679800401586750834==--