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