Author: objectiser Date: 2010-09-30 12:04:45 -0400 (Thu, 30 Sep 2010) New Revision: 425 Added: trunk/docs/userguide/src/main/en-US/images/monitorprefs.png Modified: trunk/docs/userguide/src/main/en-US/images/editvalidatorann.png trunk/docs/userguide/src/main/en-US/images/monitorui.png trunk/docs/userguide/src/main/en-US/images/validatorannotation.png trunk/docs/userguide/src/main/en-US/module/conversation-validation.xml Log: Update the user guide text and images. Modified: trunk/docs/userguide/src/main/en-US/images/editvalidatorann.png =================================================================== (Binary files differ) Added: trunk/docs/userguide/src/main/en-US/images/monitorprefs.png =================================================================== (Binary files differ) Property changes on: trunk/docs/userguide/src/main/en-US/images/monitorprefs.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: trunk/docs/userguide/src/main/en-US/images/monitorui.png =================================================================== (Binary files differ) Modified: trunk/docs/userguide/src/main/en-US/images/validatorannotation.png =================================================================== (Binary files differ) Modified: trunk/docs/userguide/src/main/en-US/module/conversation-validation.xml =================================================================== --- trunk/docs/userguide/src/main/en-US/module/conversation-validation.xml 2010-09-29 20:11:37 UTC (rev 424) +++ trunk/docs/userguide/src/main/en-US/module/conversation-validation.xml 2010-09-30 16:04:45 UTC (rev 425) @@ -22,39 +22,123 @@ <title>Configuration of Conversation Validation</title> <para> - This section explains how to configure the conversation validation mechanism to validate ESB services + This section explains how to configure the conversation validation mechanism to validate 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 + JBossESB and JBossWS-Native environments. The following two sub-sections explain two alternate ways that relevant endpoint references can be configured for validation. </para> <section> <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> - <informalexample> - <programlisting role="XML" ><![CDATA[ - <properties name="filters"> - ... - <property name="org.jboss.soa.esb.filter.10" - value="org.jboss.savara.validator.jbossesb.ValidatorFilter"/> - </properties> - ]]></programlisting> - </informalexample> + + <section> + <title>JBossWS-Native</title> + + <para> + The principle mechanism used for validating conversations within the JBossWS Native stack + is through the use of a global filter registered in the + <filename>standard-jaxws-client-config.xml</filename> and + <filename>standard-jaxws-endpoint-config.xml</filename> files. + These files are located in the <emphasis>$JBossAS/server/default/deployers/jbossws.deployter/META-INF</emphasis> + folder. + </para> + + <para> + The <filename>standard-jaxws-client-config.xml</filename> is updated to include a + <emphaiss>pre handler</emphaiss> implemented by a Savara client interceptor. + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <client-config> + <config-name>Standard Client</config-name> + <pre-handler-chains> + <javaee:handler-chain> + <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings> + <javaee:handler> + <javaee:handler-name>SAVARA JBossWS-Native Client Validator Interceptor</javaee:handler-name> + <javaee:handler-class>org.jboss.savara.validator.jbosswsnative.JBossWSNativeClientInterceptor</javaee:handler-class> + </javaee:handler> + </javaee:handler-chain> + </pre-handler-chains> + <feature>http://org.jboss.ws/dispatch/validate</feature> + <property> + <property-name>http://org.jboss.ws/http#chunksize</property-name> + <property-value>2048</property-value> + </property> + </client-config> + ]]></programlisting> + </informalexample> + + <para> + The <filename>standard-jaxws-endpoint-config.xml</filename> is updated to include a + <emphaiss>pre handler</emphaiss> implemented by a Savara server interceptor. + </para> + + <informalexample> + <programlisting role="XML" ><![CDATA[ + <endpoint-config> + <config-name>Standard Endpoint</config-name> + <pre-handler-chains> + <javaee:handler-chain> + <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings> + <javaee:handler> + <javaee:handler-name>Recording Handler</javaee:handler-name> + <javaee:handler-class>org.jboss.wsf.framework.invocation.RecordingServerHandler</javaee:handler-class> + </javaee:handler> + </javaee:handler-chain> + <javaee:handler-chain> + <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings> + <javaee:handler> + <javaee:handler-name>SAVARA JBossWS-Native Service Validator Interceptor</javaee:handler-name> + <javaee:handler-class>org.jboss.savara.validator.jbosswsnative.JBossWSNativeServerInterceptor</javaee:handler-class> + </javaee:handler> + </javaee:handler-chain> + </pre-handler-chains> + </endpoint-config> + ]]></programlisting> + </informalexample> + + <para> + These interceptors are installed as part of the installation process for the SAVARA + distribution. + </para> + </section> - <para> -This filter is installed as part of the installation process for the SAVARA distribution. - </para> + <section> + <title>JBossESB</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>$JBossAS/server/default/deployers/esb.deployer</emphasis> + folder. + </para> + <informalexample> + <programlisting role="XML" ><![CDATA[ + <properties name="filters"> + ... + <property name="org.jboss.soa.esb.filter.10" + value="org.jboss.savara.validator.jbossesb.ValidatorFilter"/> + </properties> + ]]></programlisting> + </informalexample> + + <para> + This filter is installed as part of the installation process for the SAVARA distribution. + </para> + </section> </section> <section> <title>Explicit Configuration</title> <para> -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>savara-validator-jbossesb.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>savara-validator-jbossesb.esb</emphasis> bundle. </para> + <para> An example of the contents of this file, that would related to the TrailBlazer example, is: </para> @@ -92,30 +176,58 @@ </informalexample> <para> -The 'validator' element has an optional 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. + The 'validator' element has an optional 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 '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. + 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> -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. + 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>TrailBlazer.cdm</filename>, which will be located within the <filename>models</filename> folder contained within the -<emphasis>savara-validator-jbossesb.esb</emphasis> bundle. + 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>TrailBlazer.cdm</filename>, which will be located within the + <filename>models</filename> folder contained within the + <emphasis>savara-validator-jboss.sar</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. + 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:'. + The format of the 'epr' attribute will be specific to the type of transport being validated. + Currently JMS is supported, and can be identified by the protocol prefix 'jms:', or a + Web Service endpoint using a service name with the QName style of '{namespace}localpart'. </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. + 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> @@ -164,10 +276,30 @@ </imageobject> <para> - To specify the EPR for a particular message exchange, enter the EPR into the - <emphasis>Destination</emphasis> field. If the exchange is a request, that + To specify the Endpoint Reference (EPR) for a particular message exchange, enter the EPR into the + <emphasis>Destination</emphasis> field. The value specified in this field will + be dependent upon the technology being validated. For example, if the JBossESB + is being monitored, then the value will be a physical address associated with the + ESB service endpoint (e.g. jms:queue/esb-quotes). If the technology being validated is a Web + Service (or BPEL process), then the field will represent the WSDL service name + specified using the QName style (e.g. {namespace}localpart). + </para> + + <para> + The <emphasis>Type</emphasis> field is used to define the style of endpoint being + validated. In the image above, the endpoint being validated is a Web Service (or + BPEL process), and therefore the type is specified as a 'service name'. However if + the technology being validated identifies a different endpoint address, for the request + and response (as in the case of JBossESB), then the type should be set to + 'endpoint address'. + </para> + + <para> + 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. + This situation may occur in the case of validating a JBossESB service, where a + well-defined endpoint address has not been defined for the response. </para> <para> @@ -179,7 +311,7 @@ When all of the relevant 'exchange details' components have been configured with a <emphasis>validator</emphasis> annotation, defining the EPR to be validated, then the choreography description file can be copied into the - <filename>savara-validator-jbossesb.esb/models</filename> folder. This will cause + <filename>savara-validator-jboss.sar/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. @@ -191,49 +323,48 @@ <section> <title>Monitoring the Choreography Description</title> -<para> -Once the JBossESB environment has been configured, to perform service validation of a set of ESB services against a choreography -description, and the server has been started, then the next step is to launch a tool to view the correlated information from -the service validators - and determine if the transactions are being correctly executed. -</para> -<para> -Within an Eclipse Java project, that contains the choreography description to be monitored, a configuration file called <emphasis>pi4soa.xml</emphasis> needs to be defined on the project's classpath. This file provides details of the JMS configuration parameters required to subscribe for the information generated by the service validators. The contents of this file is: -</para> - <informalexample> - <programlisting role="XML" ><![CDATA[ -<pi4soa> - <tracker> - <jndi> - <initialContextFactory>org.jnp.interfaces.NamingContextFactory</initialContextFactory> - <providerURL>jnp://localhost:1099</providerURL> - <factoryURLPackages>org.jboss.naming:org.jnp.interfaces</factoryURLPackages> - </jndi> - <jms> - <connectionFactory>ConnectionFactory</connectionFactory> - <connectionFactoryAlternate>ConnectionFactory</connectionFactoryAlternate> - <destination>topic/tracker</destination> - </jms> - </tracker> -</pi4soa> - ]]></programlisting> - </informalexample> + + <para> + Once the server environment has been configured, to perform service validation of a set of + services against a choreography description, and the server has been started, then the next + step is to configure the monitoring tool. This can be achieved by opening the + <emphasis>Window->Preferences->Savara->Monitor</emphasis> dialog, as shown in the following + image. + </para> -<para> -The destination defined in this file must match the one configured in the <emphasis>pi4soa.sar/pi4soa.xml</emphasis> file within the server. -</para> + <imageobject> + <imagedata fileref="en-US/images/monitorprefs.png" width="5in" /> + </imageobject> + <para> -The next step is to launch the monitoring tool. This is located on the popup menu, for the choreography description (i.e. .cdm) file, by selecting the Choreography->Monitor menu item. Once the tool has been launched, it will load the choreography description, subscribe to the relevant event destination, and then indicate via a message in the bottom status line that it is ready to monitor. + In general, the default values specified for the JNDI and JMS properties will be fine. + The only information that should need to be provided is a path to the JMS and JNDI + libraries. When using the JBossAS server, this path can be set to the top level + <filename>client</filename> folder. </para> + + <para> + The next step is to launch the monitoring tool. This is located on the popup menu, for + the choreography description (i.e. .cdm) file, by selecting the Savara->Monitor menu + item. Once the tool has been launched, it will load the choreography description, subscribe + to the relevant event destination, and then indicate via a message in the bottom status line + that it is ready to monitor. + </para> <imageobject> <imagedata fileref="en-US/images/monitorui.png" width="5in" /> </imageobject> <para> - When the information is received, from the service validators representing the different participants (services), it is correlated to show the global status of the business transaction. The list of correlated interactions is show in reverse time order in the image, so in this example a <emphasis>LoanBroker</emphasis> sends a <emphasis>creditCheck</emphasis> message to a <emphasis>CreditAgency</emphasis>, followed by a <emphasis>creditCheckResult</emphasis> being returned. + When the information is received, from the service validators representing the different + participants (services), it is correlated to show the global status of the business + transaction. The list of correlated interactions is shown in reverse time order in the + image. </para> + <para> -If any <emphasis>out of sequence</emphasis> or other error situations arise, these are displayed in red. + If any <emphasis>out of sequence</emphasis> or other error situations arise, these are + displayed in red. </para> </section>