[jboss-svn-commits] JBL Code SVN: r34733 - in labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US: extras/configuring_the_registry and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Aug 15 19:37:23 EDT 2010
Author: dlesage
Date: 2010-08-15 19:37:23 -0400 (Sun, 15 Aug 2010)
New Revision: 34733
Added:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/generatedb.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/nodes2.xmlt
Modified:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_Examples.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Smooks.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Message_Transformation.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Registry_Troubleshooting.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_the_Registry.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_regex.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_xpath.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/jBPM_Integration.xml
Log:
JBESB 3460
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_Examples.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_Examples.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_Examples.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -12,28 +12,30 @@
</title>
<para>
- As mentioned before, by default the JBossESB is configured to use
- the JAXR API using Scout as its implementation and jUDDI as the
- registry. Here are some examples of how you can deploy this combo.
+ Study the examples in this section to learn about different registry
+ configuration options.
</para>
<section>
<title>
- Embedding
+ Embedding Components
</title>
<para>
- All ESB components (with components we really mean JVMs in
- this case) can embed the registry and they all can connect
- to the same database (or different once if that makes
- sense).
+ All of those server components, (including the Enterprise
+ Service Bus and Web Service) that have a relationship of
+ any kind with the <systemitem>registry</systemitem> can
+ share the latter between themselves. Indeed, multiple
+ instances of the <application>JBoss Enterprise SOA
+ Platform</application> can use the same
+ <systemitem>registry</systemitem> via a shared database.
</para>
<figure>
<title>Embedded jUDDI</title>
<mediaobject>
<imageobject id="image3">
- <imagedata fileref="images/configuring_examples/image3.png" width="100%" scalefit="1" contentdepth="100%"/>
+ <imagedata fileref="images/configuring_examples/image3.png"/>
</imageobject>
</mediaobject>
</figure>
@@ -49,52 +51,52 @@
<section>
<title>
- RMI using the jbossesb.sar
+ Remote Method Invocation Using the jbossesb.sar File
</title>
<para>
- Deploy a version of the jUDDI that brings up an RMI service.
- The JBossESB deploys the RMI service by default – it starts the
- registry within the jbossesb.sar.
+ This is a straightfoward process. Simply deploy a version of the
+ jUDDI Registry that brings up a Remote Method Invocation
+ service. (The JBoss Enterprise Service Bus deploys the Remote
+ Method Invocation service by default: it starts the registry
+ within the <filename>jbossesb.sar</filename> archive. This same
+ archive also registers an RMI service.)
</para>
- <para>
- The jbossesb.sar also registers a RMI service.
- </para>
-
- <figure>
+<figure>
<title>Remote Method Invocation</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/configuring_examples/chart17.png" width="100%" scalefit="1" contentdepth="100%"/>
+ <imagedata fileref="images/configuring_examples/chart17.png"/>
</imageobject>
</mediaobject>
</figure>
<para>
- Properties example:
+ Here are the properties:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/configuring_examples/reg1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The juddi.war is configured to bring up a RMI Service, which is
- triggered by the following setting in the web.xml
+ The <filename>juddi.war</filename> is configured to bring up a
+ RMI Service, this being triggered by the following setting in
+ the <filename>web.xml</filename> file:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/configuring_examples/reg2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Make sure to include, for example, the following JNDI
- settings in your juddi.properties:
+ Include the following JNDI settings in
+ <filename>juddi.properties</filename>:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/configuring_examples/reg3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<important>
<para>
- The RMI clients need to have the scout-client.jar in their
- classpath.
+ Remember to include <filename>scout-client.jar</filename> in the
+ RMI client's class-path.
</para>
</important>
@@ -103,27 +105,29 @@
<section>
<title>
- RMI using your own JNDI Registration of the RMI Service
+ Remote Method Invocation Using One's Own JNDI Registration of the
+ RMI Service
</title>
<para>
- If you don't want to deploy the juddi.war you can setup one of
- the ESB components that runs in the the same JVM as jUDDI to
- register the RMI service. While the other applications need to
- be configured to use RMI.
+ If, for some reason, one does not to deploy the
+ <filename>juddi.war</filename>, simply configure one of the
+ Enterprise Service components running in the same Java Virtual
+ Machine as <application>jUDDI</application> to register the RMI
+ service:
</para>
<figure><title>RMI Using One's Own JNDI Registration</title>
<mediaobject>
<imageobject id="image5">
- <imagedata fileref="images/configuring_examples/image5.png" width="100%" scalefit="1" contentdepth="100%"/>
+ <imagedata fileref="images/configuring_examples/image5.png"/>
</imageobject>
</mediaobject>
</figure>
<para>
- Properties example: For application 1 you need the Local settings:
+ For Application One, local settings are needed:
</para>
@@ -131,24 +135,37 @@
<para>
- while for application2 you need the RMI settings:
+ Application Two requires the Remote Method Invocation
+ settings:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/configuring_examples/webxml.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Where the hostname of the queryManagerURI and
- lifeCycleManagerURI need to point to the hostname on
- which jUDDI is running (which would be where
- application1 is running). Obviously application1 needs
- to have access to a naming service. To do the
- registration process you need to do something like:
+ Point the hostnames of the
+ <classname>queryManagerURI</classname> and
+ <classname>lifeCycleManagerURI</classname> classes to
+ the host on which jUDDI is running (this is also where
+ Application One is running.) Obviously, Application One
+ needs to have access to a naming service. To register
+ it, undertake the following process:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/configuring_examples/properties.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <para>
+ For example, make sure to include the following JNDI settings in the file
+ <filename>jbossesb-registry.sar/esb.juddi.xml</filename>:
+ </para>
+
+
+ <important>
+ <para>
+ Always include the <filename>scout-client.jar</filename> file in the classpath of the RMI clients.
+ </para>
+ </important>
</section>
@@ -156,22 +173,32 @@
<title>
SOAP
- </title>
+ </title>
<para>
- Finally, you can make the communication between Scout and
- jUDDI SOAP based. Again you need to deploy the juddi.war
- and configure the datasource. You probably want to shutdown
- the RMI service by commenting out the
- RegisterServicesWithJNDI servlet in the web.xml.
+ Read this section to learn how to configure
+ <application>Apache Scout</application> to use SOAP to
+ communicate with <application>jUDDI</application>.
+ </para>
+
+ <para>
+ Firstly, deploy the <filename>juddi.war</filename> and
+ configure the data-source.
</para>
-
+ <important>
+ <para>
+ It is best to also shut down the
+ RMI service by "commenting out"
+ <filename>web.xml</filename>'s
+ <systemitem>RegisterServicesWithJNDI</systemitem> servlet.
+ </para>
+ </important>
<figure><title>SOAP-based Communications</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/configuring_examples/chart18.png" width="100%" scalefit="1" contentdepth="100%"/>
+ <imagedata fileref="images/configuring_examples/chart18.png"/>
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Configuring_the_Registry.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -11,22 +11,61 @@
</title>
<para>
- The JBossESB Registry architecture allows for many ways to
- configure the ESB to use either a Registry or Repository. By
- default we use a JAXR implementation (Scout) and a UDDI (jUDDI), in
- an embedded way.
+ Read this section to learn how to configure the JBoss Enterprise
+ SOA Platform Registry.
</para>
+
<para>
- The following properties can be used to configure the JBossESB
- Registry. In the jbossesb-properties.xml there is section called
- 'registry':
+ The jUDDI registry is highly configurable. The
+ JBoss Enterprise Service Bus directs all
+ interaction with the registry through the Registry Interface, the
+ default configuration of which uses the
+ <application>Apache Scout</application>.
</para>
-
- <programlisting language="XML" role="XML"><xi:include href="extras/configuring_the_registry/properties1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
-
+
+ <variablelist>
+ <varlistentry>
+ <term>Apache Scout</term>
+ <listitem>
+ <para>
+ Apache Scout is a JAXR implementation
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term>Registry Interface </term>
+ <listitem>
+ <para>
+ The means by which the ESB communicates with the jUDDI Registry.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ </variablelist>
+
+
+
+ <procedure>
+ <title>Configuring the Registry</title>
+ <step>
+ <para>Edit the <property>registry</property> section of the
+ <filename><replaceable>$SOA_ROOT</replaceable>/server/<replaceable>$PROFILE</replaceable>/deployers/esb.deployer/jbossesb-properties.xml</filename>
+ file. Here is an example: </para>
+ <programlisting language="XML"><xi:include href="extras/configuring_the_registry/properties1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </step>
+ </procedure>
+
+
+ <para>
+ These are the properties that can be configured:
+ </para>
+
<table>
<title>Registry Properties</title>
<tgroup cols="2" colsep="1" rowsep="1">
@@ -43,9 +82,9 @@
</entry>
<entry>
<para>
- A class that implements the jbossesb Registry
- interface. We have provided one implementation
- (JAXRRegistry interface).
+ A class that implements the JBoss ESB Registry interface. One implementation,
+ <classname>JAXRRegistryImpl</classname>, that uses the
+ <interfacename>JAXRRegistry</interfacename> interface is included.
</para>
</entry>
</row>
@@ -56,7 +95,8 @@
</entry>
<entry>
<para>
- The class name of the JAXR ConnectionFactory implementation.
+ The class name of the JAXR <firstterm>ConnectionFactory</firstterm>
+ implementation.
</para>
</entry>
</row>
@@ -68,7 +108,7 @@
</entry>
<entry>
<para>
- The URI used by JAXR to query
+ The URI that JAXR uses to query services.
</para>
</entry>
</row>
@@ -80,46 +120,35 @@
</entry>
<entry>
<para>
- The URI used by JAXR to edit.
+ The URI that JAXR uses for editing.
</para>
</entry>
</row>
- <row>
- <entry>
- <property><classname>org.jboss.soa.esb.registry.securityManagerURI</classname></property>
- </entry>
- <entry>
- <para>
- The URI used to authenticate.
- </para>
- </entry>
- </row>
-
<row>
<entry>
<property><classname>org.jboss.soa.esb.registry.user</classname></property>
</entry>
<entry>
<para>
- The user used for edits.
+ The user-name utilised for editing.
</para>
</entry>
</row>
- <row>
+ <row>
<entry>
<property><classname>org.jboss.soa.esb.registry.password</classname></property>
</entry>
<entry>
<para>
- The password to go along with the user.
+ The password for the specified user.
</para>
</entry>
- </row>
+ </row>
<row>
@@ -151,8 +180,7 @@
</entry>
<entry>
<para>
- The name of the class used by scout to do the transport
- from scout to the UDDI.
+ The class used by Apache Scout to transport from itself to the UDDI Registry.
</para>
</entry>
</row>
@@ -164,14 +192,12 @@
</entry>
<entry>
<para>
- The list of interceptors that are applied to the
- configured registry. The codebase currently provides
- two interceptors, one for handling InVM registration
- and a second for applying a cache over the registry.
+ The list of <firstterm>interceptors</firstterm> that are applied to the configured
+ registry. The ESB provides two interceptors, one for handling
+ InVM registrations and one that is used to apply a cache to the registry.
</para>
<para>
- The default interceptor list consists solely the InVM
- interceptor.
+ The default interceptor list only contains one entry, the InVM interceptor.
</para>
</entry>
</row>
@@ -184,10 +210,9 @@
</entry>
<entry>
<para>
- The maximum number of server entries allowed in the
- cache. If this value is exceeded then entries will be
- evicted on a LRU basis. The default value is 100
- entries.
+ The maximum number of server entries allowed in the cache. If this value is
+ exceeded, entries will be removed on a "Least Recently Used" basis. The default
+ value is <code>100</code>.
</para>
</entry>
</row>
@@ -199,10 +224,9 @@
</entry>
<entry>
<para>
- The validity period of the caching interceptor. This is
- specified in milliseconds and defaults to 600000 (ten
- minutes). If this value is zero (or less) then there is
- no expiry specified on the cache.
+ The period of validity for the caching interceptor. This is specified in
+ milliseconds and defaults to <code>600000</code> (ten minutes).
+ Set this value to <code>0</code> to have no cache expiry.
</para>
</entry>
</row>
@@ -232,49 +256,93 @@
<para>
- The registry can be configured in many ways. Figure 1 shows a blue
- print of all the registry components. From the top down we can see
- that the JBossESB funnels all interaction with the registry through
- the Registry Interface. By default it then calls into a JAXR
- implementation of this interface. The JAXR API needs an
- implementation, which by default is Scout. The Scout JAXR
- implementation calls into a jUDDI registry. However there are many
- other configuration options.
- </para>
-
-
- <figure>
- <title>Blueprint of the Registry Component Architecture</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/configuring_the_registry/image2.png" width="100%" scalefit="1" contentdepth="100%"/>
- </imageobject>
- </mediaobject>
+ The registry can be configured in many
+ ways. The image below is a blue-print of all of the
+ registry's components.
+ </para>
+
+
+ <figure id="reg_comp_arch_blueprint">
+ <title>Blueprint of the Registry Component Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/configuring_the_registry/image2.png"/>
+ </imageobject>
+ </mediaobject>
</figure>
-
- </section>
+<!--
+ <figure>
+ <title>Registry Interceptors</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/configuring_the_registry/interceptors.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+-->
+<para>
+From the top down,
+ one can see that:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ The JBoss Enterprise Service Bus
+ funnels all interaction with the
+ registry through the
+ <interfacename>registry interface</interfacename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It then calls into a JAXR implementation of this interface.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The JAXR API needs an
+ implementation which, by default, is Scout.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Scout JAXR
+ implementation, in turn, calls into a jUDDI registry.
+ </para>
+ </listitem>
+ </orderedlist>
+
+<note>
+ <para>
+ Remember that these are just the defaults. There are many other
+ configuration options.
+ </para>
+</note>
- <section>
-
- <title>
- The Registry Implementation Class
- </title>
+
+
+
-
<para>
- Property: org.jboss.soa.esb.registry.implementationClass
- </para>
-
- <para>
- By default we use the JAXR API. The JAXR API is a
- convenient API since it allows us to connect any kind of
- XML based registry or repository. However, if for example
- you want to use Systinet's Java API you can do that by
- writing your own SystinetRegistryImplementation class and
- referencing it in this property.
- </para>
-
-
+ By default, this class uses the JAXR application programming
+ interface. The <interfacename>org.jboss.soa.esb.registry.implementationClass</interfacename> API
+ is convenient since it allows one to connect any kind of
+ XML-based registry or
+ repository. However, it is also
+ possible to use an alternative API.
+ </para>
+
+ <procedure>
+ <title>Using an Alternative API</title>
+ <step>
+ <para> Write a new
+ <classname>SystinetRegistryImplemtation</classname> class and
+ provide a reference to it from within this property.</para>
+ </step>
+ </procedure>
+
+
</section>
<section>
@@ -283,38 +351,33 @@
Using JAXR
</title>
- <para>
- Propery: org.jboss.soa.esb.registry.factoryClass
- </para>
-
- <orderedlist>
- <listitem>
-
- <para>
- If you decided to use JAXR then you will have to pick which
- JAXR implementation to use. This property is used to
- configure that class. By default we use Scout and therefore
- it is set to the scout factory
- org.apache.ws.scout.registry.ConnectionFactoryImpl.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The next step is to tell the JAXR implementation the location
- of the registry or repository for querying and updating, which
- is done by setting the
- org.jboss.soa.esb.registry.queryManagerURI,
- org.jboss.soa.esb.registry.lifeCycleManagerURI, and
- org.jboss.soa.esb.registry.securityManagerURI respectively,
- along with the username (org.jboss.soa.esb.registry.user) and
- password (org.jboss.soa.esb.registry.password) for the
- UDDI.
- </para>
- </listitem>
-
- </orderedlist>
+ <procedure>
+ <title>Using JAXR</title>
+ <step>
+ <para>Choose a specific JAXR implementation.</para>
+ </step>
+ <step>
+ <para>Use
+ this property to configure the class. (The JBoss Enterprise
+ SOA Platform uses Scout by
+ default and, hence, as one would expect this property is
+ set to the Scout factory class,
+ namely
+ <classname>org.apache.ws.scout.registry.ConnectionFactoryImpl</classname>.)</para>
+ </step>
+ <step>
+ <para> Configure the JAXR implementation by providing it with location of the
+ registry that is to be used for querying and
+ updating. Do so
+ by editing
+ <classname>org.jboss.soa.esb.registry.queryManagerURI</classname>,
+ <classname>org.jboss.soa.esb.registry.lifeCycleManagerURI</classname>
+ and
+ <classname>org.jboss.soa.esb.registry.securityManagerURI</classname>. </para>
+ </step>
+ </procedure>
+
</section>
@@ -323,41 +386,95 @@
Using jUDDI Transports
</title>
- <para>
- Property: org.jboss.soa.esb.scout.proxy.transportClass
- </para>
+ <para></para>
<para>
- When using Scout with a UDDI implementation there is an
- additional parameter that one can set - the transport class
- that is used for communication between Scout and the UDDI
- registry. If you are using Scout to communicate with jUDDI
- v3, we suggest leaving the transportClass as LocalTransport
- and using jUDDI's esb.juddi.client.xml to use jUDDI's
- transports (InVM, RMI, WS).
+ When using Scout, one can set an
+ additional parameter:
+ <classname>org.jboss.soa.esb.scout.proxy.transportClass</classname>. This
+ is the
+ <classname>transport</classname> class that facilitates
+ communications between Scout
+ and the jUDDI registry.
</para>
<para>
- jUDDI's esb.juddi.client.xml resides in the
- server/<config>/deploy/jbossesb.sar/META-INF directory and
- contain the concept of a “node”, which is a jUDDI registry
- location. Use the node settings to determine whether you
- want to use JAX-WS, InVM, or RMI as your transport:
- </para>
-
-
-
- <programlisting language="XML" role="XML"><xi:include href="extras/configuring_the_registry/nodes1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+ If one is using
+ Scout to communicate with
+ jUDDI v. 3 leave the transport
+ class as <classname>LocalTransport</classname> and
+ configure the <filename>server/config/deploy/jbossesb.sar/META-INF/esb.juddi.client.xml</filename>
+ file to make use of the jUDDI registry's
+ transports (InVM, RMI and WS).
+ This file defines the registry's <firstterm>nodes</firstterm>.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>node</term>
+ <listitem>
+ <para>
+ A node is a jUDDI registry location.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ </variablelist>
+
+
+ <procedure>
+ <title>Selecting a Transport</title>
+ <step>
+ <para> Use the
+ node settings to select which transport to
+ use:</para>
+ <programlisting language="XML" role="XML"><xi:include href="extras/configuring_the_registry/nodes1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </step>
+ <step>
+ <para>
+ By default, the RMI settings are enabled. To switch transports, simply
+ comment those ones out and enable whichever of the other transports
+ is to be used.
+ </para>
+ </step>
+ </procedure>
+
<para>
- As seen above, a transport should specify a proxyTransport, a
- URL for all of the supported UDDI API (inquiry, publish,
- security, subscription, subscription-listener,
- custodytransfer), and a jUDDI API URL. The RMI transport also
- includes JNDI settings. By default, the RMI settings are
- enabled – to switch transports you can comment them out and
- enable whichever of the transports you choose.
- </para>
+ A <classname>transport</classname> should specify:
+ </para>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ a <classname>proxyTransport</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a URL for all of the supported UDDI application programming interfaces
+ (<interfacename>inquiry</interfacename>,
+ <interfacename>publish</interfacename>,
+ <interfacename>security</interfacename>,
+ <interfacename>subscription</interfacename>,
+ <interfacename>subscription-listener</interfacename>
+ and <interfacename>custodytransfer</interfacename>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a jUDDI application programming interface URL.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the RMI transport also includes JNDI settings
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
</section>
@@ -366,120 +483,44 @@
Using Scout and jUDDI
</title>
- <para>
- Property: org.jboss.soa.esb.scout.proxy.transportClass
- </para>
+
<para>
- When using Scout with jUDDI there is an additional parameter that
- one can set. This is the transport class that should be used for
- communication between Scout and jUDDI. Thus far there are 4
- implementations of this class which are based on SOAP, SAAJ, RMI
- and Local (embedded java). If you are using Scout to communicate
- with jUDDI v3, we suggest leaving the transportClass as
- LocalTransport and using jUDDI's uddi.xml to use jUDDI's transports
- (InVM, RMI, WS).
+ There are currently
+ four implementations of the <classname>org.jboss.soa.esb.scout.proxy.transportClass</classname> class, these being based for SOAP,
+ SAAJ, RMI and Embedded Java (Local) respectively. When
+ communicating with the jUDDI registry, leave the
+ <classname>transportClass</classname> set to
+ <property>LocalTransport</property> and use the
+ <filename>uddi.xml</filename> file to utilise
+ the registry's transports (these being InVM,
+ RMI and WS, respectively.)
</para>
- <para>
- However, when communicating with another UDDI registry
- (Systinet, SOA Software, etc), it is preferable to use scout's
- JAXR transports. There are 4 implementations of this class which
- are based on SOAP, SAAJ, RMI and Local (embedded java). Note
- that when you change the transport, you will also have to change
- the query and lifecycle URIs. For example:
- </para>
-
- <table>
- <title>Registry URIs</title>
- <tgroup cols="2" colsep="1" rowsep="1">
- <colspec colwidth="1*"/>
- <colspec colwidth="2*"/>
- <thead>
- <row>
- <entry>SOAP</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>queryManagerURI</entry>
- <entry>http://localhost:8080/juddi/inquiry</entry>
- </row>
- <row>
- <entry>lifeCycleManagerURI</entry>
- <entry>http://localhost:8080/juddi/publish</entry>
- </row>
- <row>
- <entry>transportClass</entry>
- <entry>org.apache.ws.scout.transport.AxisTransport</entry>
- </row>
- </tbody>
- </tgroup>
- <tgroup cols="2" colsep="1" rowsep="1">
- <colspec colwidth="1*"/>
- <colspec colwidth="2*"/>
- <thead>
- <row>
- <entry>RMI</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>queryManagerURI</entry>
- <entry>jnp://localhost:1099/InquiryService?org.apache.juddi.registry.rmi.Inquiry#inquire</entry>
- </row>
- <row>
- <entry>lifeCycleManagerURI</entry>
- <entry>jnp://localhost:1099/PublishService?org.apache.juddi.registry.rmi.Publish#publish</entry>
- </row>
- <row>
- <entry>transportClass</entry>
- <entry>org.apache.ws.scout.transport.RMITransport</entry>
- </row>
- </tbody>
- </tgroup>
- <tgroup cols="2" colsep="1" rowsep="1">
- <colspec colwidth="1*"/>
- <colspec colwidth="2*"/>
- <thead>
- <row>
- <entry>local</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>queryManagerURI</entry>
- <entry>org.apache.juddi.registry.local.InquiryService#inquire</entry>
- </row>
- <row>
- <entry>lifeCycleManagerURI</entry>
- <entry>org.apache.juddi.registry.local.PublishService#publish</entry>
- </row>
- <row>
- <entry>transportClass</entry>
- <entry>org.apache.ws.scout.transport.LocalTransport</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
+
+
<para>
- For jUDDI we have two requirements that need to be fulfilled:
+ Ensure these two requirements are fulfiled when using jUDDI:
</para>
<orderedlist>
<listitem>
<para>
- access to the jUDDI database. You will need to create a
- schema in your database, and add the jbossesb publisher.
- The product/install/jUDDI-registry directory contains db
- create scripts for you favorite database.
+ one must be able to access the
+ <application>jUDDI</application> database. To achieve this,
+ create a schema in the database and add the
+ <systemitem>jbossesb publisher</systemitem>. (The
+ <filename>product/install/jUDDI-registry</filename>
+ directory contains <command>database-create</command>
+ scripts for most common databases.)
</para>
</listitem>
<listitem>
<para>
- esb.juddi.xml and esb.juddi.client.xml. The configuration
- of jUDDI itself.
+ <filename>esb.juddi.xml</filename> and
+ <filename>esb.juddi.client.xml</filename> must exist. These
+ contain the <application>jUDDI</application> configuration
+ itself.
</para>
</listitem>
</orderedlist>
@@ -487,35 +528,78 @@
<note>
<para>
- The database can be automatically created if the user you have
- created has enough rights to create tables. jUDDI should be
- able to create a database for any database that has a Hibernate
- dialect associated with it.
+ The database can be generated automatically if the user account
+ has been granted the right to create tables.
+ The jUDDI registry can create a database of any
+ type for which there is an associated
+ Hibernate dialect.
</para>
</note>
-</section>
+
+<para>
+ When communicating with another UDDI registry, use Scout's
+ JAXR transports. There are four implementations of this class, these also being
+ based on SOAP, SAAJ, RMI and Embedded Java (Local).
+</para>
+
+<para>
+ When changing the transport, always change the query and
+ lifecycle URIs as well. This example shows how to do
+ so:
+</para>
+
+<programlisting language="XML" role="XML"><xi:include href="extras/configuring_the_registry/nodes2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+
+</section>
+
+
<section>
<title>
Registry Interceptors
</title>
+
<para>
- The registry supports the ability to intercept requests to the registry
- using an interceptor stack. Each interceptor in the stack is provided
- with an opportunity to service the request, provide direct responses to
- the request or to augment the responses received from a lower interceptor
- or registry implementation as it wishes.
- </para>
- <para>
- The interceptor stack is configured using the org.jboss.soa.esb.registry.interceptors
- property within jbossesb-properties.xml
+ The registry has the ability to intercept requests. It does
+ so by
+ using an <firstterm>interceptor stack</firstterm>. Each interceptor in the stack is provided
+ with an opportunity to:
</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ service the request
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ provide direct responses to
+ the request
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ augment the responses received from a lower interceptor
+ or registry implementation
+ </para>
+ </listitem>
+</itemizedlist>
+
+<procedure>
+ <title>Configure the Interceptor Stack</title>
+ <step>
+ <para>Open the jbossesb-properties.xml file and modify the
+ org.jboss.soa.esb.registry.interceptors properties.</para>
+ </step>
+</procedure>
+
<figure>
<title>Registry Interceptors</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/configuring_the_registry/interceptors.png" width="100%" scalefit="1" contentdepth="100%"/>
+ <imagedata fileref="images/configuring_the_registry/interceptors.png"/>
</imageobject>
</mediaobject>
</figure>
@@ -523,29 +607,77 @@
<para>
There are two interceptors provided in the current implementation.
</para>
- <itemizedlist>
- <listitem>
- <para>org.jboss.internal.soa.esb.services.registry.InVMRegistryInterceptor</para>
- <para>
- The InVM registry interceptor is responsible for handling any InVMEprs which are
+
+ <table>
+ <title>Registry Properties</title>
+ <tgroup cols="2" colsep="1" rowsep="1">
+ <colspec colwidth="12*"/>
+ <colspec colwidth="5*"/>
+
+ <thead>
+ <row><entry>Property</entry><entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ org.jboss.internal.soa.esb.services.registry.InVMRegistryInterceptor
+ </entry>
+ <entry>
+ <para>
+ The InVM registry interceptor is responsible for
+ handling any InVM Eprs which are
registered by any of the services executing within the same server instance. The
information about the InVMEpr and its associated service will be cached within the
interceptor, will not be propagated to subsequent interceptors and will be returned
to the caller by augmenting results from subsequent interceptors/registry queries.
- </para>
- </listitem>
- <listitem>
- <para>org.jboss.internal.soa.esb.services.registry.CachingRegistryInterceptor</para>
- <para>
- The Caching registry interceptor retains a cache of Eprs and their associated services,
+ </para>
+ </entry>
+ </row>
+
+
+ <row>
+ <entry>
+ org.jboss.internal.soa.esb.services.registry.CachingRegistryInterceptor
+ </entry>
+
+ <entry><para>The Caching registry interceptor retains a cache of EPRs and their associated services,
evicting information from the cache on a LRU basis or after the information has expired.
</para>
<para>
The interceptor can be configured through the org.jboss.soa.esb.registry.cache.maxSize
and org.jboss.soa.esb.registry.cache.validityPeriod properties within jbossesb-properties.xml
</para>
- </listitem>
- </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+
+<note>
+ <para>
+ The database can be generated automatically if the user account
+ has been granted the right to create tables.
+ the jUDDI registry can create a database of any
+ type for which there is an associated
+ Hibernate dialect.
+ </para>
+</note>
+<note>
+ <para>
+ The JBoss Enterprise SOA Platform includes a tool that
+ automates jUDDI configuration. This
+ tool is found in the
+ <filename><replaceable>${SOA_ROOT}</replaceable>/tools/schema/</filename>
+ sub-directory. Find directions for using it in the
+ "Switching Databases" section of the <emphasis>Administration
+ Guide</emphasis>. Here is a code sample:
+ </para>
+
+ <programlisting language="XML"><xi:include href="extras/configuring_the_registry/generatedb.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+</note>
+
</section>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -15,45 +15,61 @@
</title>
<para>
- The Content Based Router (CBR) in the JBossESB uses
- Drools as its default rule provider engine. JBossESB
- integrates with Drools through three different routing action
- classes,
+ The <firstterm>content-based router</firstterm> used in the
+ JBoss Enterprise Service Bus utilises <application>Drools</application> as its default rule provider "engine." The
+ Enterprise Service Bus integrates with <application>JBoss
+ Rules</application> through three different routing <systemitem>action
+ classes</systemitem>. These are:
</para>
<itemizedlist>
- <listitem>
+ <listitem>
+
<para>
- a routing rule set, written in Drools drl (and
- optionally dsl) language.
- </para>
+ a routing rule set, written in
+ <application>Drools</application>' DRL (or,
+ optionally, the DSL) language;
+ </para>
+
</listitem>
+ <listitem>
- <listitem>
<para>
- The ESB Message content, either the serialized XML, or
- objects in the message, which is the data going into
- the rules engine.
- </para>
+ the Enterprise Service Bus message content, which is the data
+ that goes into the <systemitem>rule engine</systemitem> (it takes the form of
+ either XML or objects within the
+ message);
+ </para>
+
</listitem>
+ <listitem>
- <listitem>
<para>
- destination(s) which is the result coming out of the
- rules engine.
- </para>
+ the destination, (which is derived from the resultant
+ information coming out of the rules engine.)
+ </para>
+
</listitem>
</itemizedlist>
-
+ <important>
<para>
- When a message gets sent to the CBR, a certain rule set
- will evaluate the message content and return a set of
- Service destinations. We discuss how a target rule set can
- be targeted, how the message content is evaluated and what
- is done with the destination results.
+ There is no native support for
+ <application>Freemarker</application> inside the <application>Enterprise
+ Service Bus</application> and, hence, any use of this templating system
+ must come from within the context of
+ <application>Smooks</application>.
</para>
-
+ </important>
+
+ <para>
+ When a message is sent to the <systemitem>content-based
+ router</systemitem>, a certain <systemitem>rule
+ set</systemitem> will evaluate its content and return a set of
+ service destinations. This chapter will teach how a rule set
+ can be targeted, how the message content is evaluated and what
+ can be achieved with the resulting destinations.
+ </para>
</section>
@@ -63,11 +79,12 @@
</title>
<para>
- JBossESB ships with three slightly different routing action
- classes. Each of these action classes implements an Enterprise
- Integration Pattern. For more information of the Enterprise
- Integration Pattern you can check the JBossESB Wiki. The
- following actions are supported:
+ The JBoss Enterprise Service Bus ships with three slightly
+ different routing <firstterm>action classes</firstterm>. Each of
+ these implements an <firstterm>Enterprise Integration
+ Pattern</firstterm> (EIP). (The
+ <emphasis>JBossESB Wiki</emphasis> contains more information
+ about this subject.) These are the three supported action classes:
</para>
<orderedlist>
@@ -77,13 +94,15 @@
</para>
<para>
- Implements the Content Based Routing pattern. It routes a
- message to one or more destination services based on the
- message content and the rule set it is evaluating it
- against. The CBR throws an exception when no destinations
- are matched for a given rule set/message combination. This
- action will terminate any further pipeline processing, so
- it should be the last action of your pipeline.
+ This action class implements the content-based routing
+ pattern. It routes a message to one or more destination
+ services, based on the message content and the rule set
+ against which it is evaluating that content. The
+ content-based router throws an exception when no
+ destinations are matched for a given rule set or message
+ combination. This action will terminate any further pipeline
+ processing, so it should be positioned last in one's
+ pipeline.
</para>
</listitem>
@@ -93,12 +112,15 @@
</para>
<para>
- Implements the WireTap pattern. The WireTap is an
- Enterprise Integration Pattern (EIP) where a copy of the
- message is send to a control channel. The CBR-WT is
- identical in functionality to the ContentBasedRouter,
- however it does not terminate the pipeline which makes it
- suitable to be used as a WireTap.
+ This implements the <firstterm>WireTap</firstterm> pattern.
+ The <systemitem>WireTap</systemitem> is an Enterprise
+ Integration Pattern through which a copy of the message is
+ send to a control channel. The
+ <systemitem>WireTap</systemitem> is identical in
+ functionality to the standard content-based router, however
+ it does not terminate the pipeline. It is this latter
+ characteristic which makes it suitable to be used as a
+ wire-tap.
</para>
</listitem>
@@ -108,13 +130,14 @@
</para>
<para>
- Implements the Message-Filter pattern. The Message Filter
- pattern represents the case where messages can simply be
- dropped if certain content requirements are not met. The
- CBR-MF is identical in functionality to the
- ContentBasedRouter, but it does not throw an exception if
- the rule set does not match any destinations. In this case
- the message is simply filter out.
+ This implements the <firstterm>message filter
+ pattern</firstterm>. The message filter pattern represents
+ that case in which messages can simply be dropped if certain
+ content requirements are not met. It is identical in
+ functionality to the
+ Content-Based Router but it does not throw an exception if
+ the rule set does not match any destinations. If none are
+ met, the message is simply filtered out.
</para>
</listitem>
</orderedlist>
@@ -138,28 +161,26 @@
you need to make sure you remember two things:
</para>
- <itemizedlist>
- <listitem>
+<itemizedlist>
+ <listitem>
+
<para>
- your rule set imports the EsbMessage
+ firstly, ensure the rule set imports the ESB message
</para>
+
+<programlisting language="Java"><xi:include href="extras/cbr_drools/code2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/cbr_drools/code2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</listitem>
-
<listitem>
<para>
- and your rule set defines
+ secondly, ensure that the rule set defines the
+ following global variable which will create the list of
+ destinations available to the Enterprise Service Bus:
</para>
-
-<programlisting language="Java" role="JAVA"><xi:include href="extras/cbr_drools/code3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="Java"><xi:include href="extras/cbr_drools/code3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <para>
- which will make the list of destinations available to
- the ESB
- </para>
</listitem>
</itemizedlist>
@@ -174,12 +195,14 @@
</figure>
<para>
- The message will be asserted into the working memory of the
- rules engine. Figure 2 shows an example where the MessageType
- is used to determine to which destination the Message is going
- to be send. This particular ruleSet is shipped in the
- JBossESBRules.drl file and the rule checks if the type is XML
- or Serializable.
+ The message will now be added to the <systemitem>rule
+ engine</systemitem>'s <systemitem>working memory</systemitem>.
+ The figure shows an example in which the
+ <classname>MessageType</classname> is used to determine to
+ which destination the Message will be sent. This particular
+ rule-set is shipped in the
+ <filename>JBossESBRules.drl</filename> file. The rule also
+ checks if the format type is XML or of the serialized.
</para>
</section>
@@ -190,131 +213,150 @@
</title>
<para>
- For XML-based messages it is convenient to do XPath based
- evaluation. To support this we ship a “Domain Specific
- Language” implementation which allows us to use XPath
- expressions in the rule file. defined in the XPathLanguage.dsl.
- To use it you need to reference it in your ruleSet with:
+ It is convenient to undertake an
+ <firstterm>XPath</firstterm>-based evaluation of XML-based messages. Red Hat supports this by shipping a <firstterm>domain-specific
+ language</firstterm> implementation. Use this implementation to utilise
+ XPath expressions in the rule file.
</para>
-
+ <para>
+ These expressions are defined in the
+ <filename>XPathLanguage.dsl</filename> file. To use, simply
+ reference it in the rule-set with:
+ </para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/cbr_drools/code1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Currently the XPath Language makes sure the message is of the
- type JBOSS_XML and it defines
+ Currently, the XPath Language makes sure the message is of the
+ type <code>JBOSS_XML</code> and that it defines the following
+ items:
</para>
<orderedlist>
<listitem>
+
<para>
- xpathMatch “<element>”: yields true if an element
- by this name is matched.
+ <command>xpathMatch </command>
+ <replaceable><element></replaceable>: yields <code>true</code>
+ if an element by this name is matched.
</para>
</listitem>
<listitem>
<para>
- xpathEquals “<element>”, “<value>”: yields
- true if the element is found and it's value equals the
- value.
+ <command>xpathEquals </command>
+ <replaceable><element></replaceable>,
+ <replaceable><value></replaceable>: yields <code>true</code>
+ if the element is found and its value equals the value.
</para>
+
</listitem>
-
<listitem>
+
<para>
- xpathGreaterThan “<element>”, “<value>”:
- yields true if the element is found and it's value is
- greater than the value.
+ <command>xpathGreaterThan </command>
+ <replaceable><element></replaceable>,
+ <replaceable><value></replaceable>: yields <code>true</code>
+ if the element is found and its value is greater than
+ the value.
</para>
+
</listitem>
-
+
<listitem>
<para>
- xpathLowerThan “<element>”, “<value>”:
- yields true if the element is found and it's value is
- lower then the value.
+ <command>xpathLessThan </command>
+ <replaceable><element></replaceable>,
+ <replaceable><value></replaceable>: yields <code>true</code>
+ if the element is found and its value is lower then the
+ value.
</para>
</listitem>
</orderedlist>
-
- <section>
+ <para>
+ The XPath Language is defined in a file called
+ <filename>XPathLanguage.dsl</filename>. One can customise it if
+ the need arises. Alternatively, one can define an entirely
+ different domain-specific language.
+ </para>
+
+ <note>
+ <para>
+ The quick-start called <filename>fun_cbr</filename>
+ demonstrates this use of XPath.
+ </para>
+ </note>
+
+ <section id="sect-XPath_and_namespaces">
<title>
- XPath and namespaces
+ XPath and Name-Spaces
</title>
<para>
- To use namespaces with XPath, one needs to specify which
- namespace prefixes are to be used in the XPath expression.
- The namespace prefixes are specified as a comma separated
- list like this: “prefix=uri,prefix=uri”. This can be
- accomplished for all the above types of XPath expressions:
+ To use name-spaces with XPath, specify which
+ name-space prefixes are to be used in the XPath expression.
+ The name-space prefixes are specified in a comma-separated
+ list of the following format:
+ <code>"prefix=uri,prefix=uri"</code>. This same can done for
+ all of the different kinds of XPath expressions that were
+ mentioned above.
</para>
<orderedlist>
<listitem><para><command>xpathMatch expr "<expression>" use namespaces "<namepaces>"</command></para></listitem>
-
<listitem><para><command>xpathEquals expr "<expression>", "<value>" use namespaces "<namspaces>"</command></para></listitem>
-
<listitem><para><command>xpathGreaterThan "<expression>", "<value>" use namespaces "<namspaces>"</command></para></listitem>
-
<listitem><para><command>xpathLowerThan expr "<expression>", "<value>" use namespaces "<namespaces>"</command></para></listitem>
</orderedlist>
<para>
- Notice that the namespace aware statements differ in that
- they need the extra “expr” in front of the XPath
- expression. This is do avoid colliding with the non XPath
- aware statements in the dsl file.
+ The name-space-aware statements differ in that they all need the
+ extra <command>expr</command> keyword in front of the XPath
+ expression. This avoids collisions with the non-XPath aware
+ statements in the DSL file. The prefixes do not have to
+ match those used in the XML to be evaluated: it only
+ matters that the uniform resource identifier is the same.
</para>
- <note>
- <para>
- The prefixes do not have to match those used in the xml to
- be evaluated, it only matters that the URI is the same.
- </para>
- </note>
-
- <para>
- The XPathLanguage.dsl is defined in a file called
- XPathLanguage.dsl, and can be customized if needed, or you
- can define your own DSL altogether. The Quickstart called
- fun_cbr demonstrates this use of XPath.
- </para>
- </section>
+
+ </section>
- <section>
+ <section id="sect-SOA_ESB_Services_Guide-Content_Based_Routing_Using_Drools-Configuration">
<title>
Configuration
</title>
<para>
- Now that we have seen all the individual pieces how does it all
- tie together? It basically all comes down to configuration at
- this point, which is all done in your jboss-esb.xml. The image
+ These individual pieces are all connected via configuration,
+ which is undertaken in the <filename>jboss-esb.xml</filename>
+ file. The <systemitem>service configuration</systemitem> below
shows a service configuration fragment. In this fragment the
- service is listening on a JMS queue.
+ service is listening to a Java Message Service queue.
</para>
<para>
- Each EsbMessage is passed on to in this case the
- ContentBasedRouter action class which is loaded with a certain
- rule set. It sets the EsbMessage into Working Memory, fires the
- rules, obtains the list of destinations and routes copies of
- the EsbMessage to these services. It uses the rule set
- JbossESBRules.drl, which matches two destinations, name
- 'xml-destination' and 'serialized-destination'. These names are
- mapped to real service names in the 'route-to' section.
+ Each ESB message is passed to the
+ <classname>ContentBasedRouter</classname> action class, which
+ is loaded with a certain rule-set. It moves the ESB message
+ into working memory, "fires" the rules, obtains the list of
+ destinations and routes copies of the ESB message to the
+ services. It uses the <filename>JbossESBRules.drl</filename>
+ rule-set, which matches two destinations, namely
+ <systemitem>xml-destination</systemitem> and
+ <systemitem>serialized-destination</systemitem>. These names
+ are mapped to those of real services in the
+ <systemitem>route-to</systemitem> section.
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_drools/code4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The action attributes to the action tag are show in the table
- below. The attributes specify which action is to be used and
- which name this action is to be given.
+ This table shows <systemitem>action</systemitem> tag's
+ attributes. These attributes specify which
+ <systemitem>action</systemitem> is to be used and which name it
+ is to be given:
</para>
@@ -329,10 +371,9 @@
<tbody>
<row>
<entry><parameter>Class</parameter></entry>
- <entry>Action class, one of :
- org.jboss.soa.esb.actions.ContentBasedRouter
- org.jboss.soa.esb.actions.ContentBasedWireTap
- org.jboss.soa.esb.actions.MessageFilter
+ <entry>Action class, this being one of : <classname>org.jboss.soa.esb.actions.ContentBasedRouter</classname>,
+ <classname>org.jboss.soa.esb.actions.ContentBasedWireTap</classname>
+ or <classname>org.jboss.soa.esb.actions.MessageFilter</classname>
</entry>
</row>
<row>
@@ -344,9 +385,10 @@
</table>
<para>
- The action properties are shown in the next table. The
- properties specify the set of rules (ruleSet) to be used in
- this action.
+ This table depicts the action properties. The properties
+ specify which set of rules
+ (<systemitem>ruleSet</systemitem>) is to be used within the
+ action:
</para>
@@ -361,72 +403,78 @@
<tbody>
<row>
- <entry><property>ruleSet</property></entry>
+ <entry>ruleSet</entry>
<entry>
- Name of the filename containing the Drools ruleSet. The
- set of rules that is used to evaluate the content. Only
- 1 ruleSet can be given for each CBR instance.
+ Name of the filename containing the
+ <application>Drools</application> <systemitem>ruleSet</systemitem>, which is
+ the
+ set of rules used to evaluate content. Only
+ one <systemitem>ruleSet</systemitem> can be given for each CBR instance.
</entry>
</row>
<row>
- <entry><property>ruleLanguage</property></entry>
+ <entry>ruleLanguage</entry>
<entry>
- Optional reference to a file containing the definition
+ This is an optional reference to a file containing the definition
of a Domain Specific Language to be used for evaluating
the rule set.
</entry>
</row>
<row>
- <entry><property>ruleAgentProperties</property></entry>
+ <entry>ruleAgentProperties</entry>
<entry>
- This property points to a rule agent properties file
- located on the classpath. The properties file can
- contain a property that points to precompiled rules
- packages on the file system, in a directory, or
- identified by an URL for integration with the BRMS. See
- the “KnowledgeAgent” section below for more information.
+ This property points to a "rule agent properties" file
+ located on the class-path. The file can contain a
+ property that points to pre-compiled rules packages on
+ the file system, in a directory or identified by an
+ uniform resource locator for integration with the
+ <application>Business Rule Management
+ System</application>. See the “RuleAgent” section below
+ for more information.
</entry>
</row>
<row>
- <entry><property>ruleReload</property></entry>
+ <entry>ruleReload</entry>
<entry>
- Optional property which can be to true to enable 'hot'
- redeployment of rule sets. Note that this feature will
- cause some overhead on the rules processing. Note that
- rules will also reload if the .esb archive in which
- they live is redeployed.
+ This is an optional property which can be set to
+ <code>true</code> in order to enable "hot" redeployment
+ of rule sets. Note that this feature will cause some
+ overhead on the rules processing. Note also that the
+ rules will reload if the <filename>.esb</filename>
+ archive in which they reside is redeployed.
</entry>
</row>
<row>
- <entry><property>stateful</property></entry>
+ <entry>stateful</entry>
<entry>
- Optional property which tells the RuleService to use a
+ This is an optional property which tells the RuleService to use a
stateful session where facts will be remembered between
- invokations. See the “Stateful Rules” section for more
- information about stateful rules.
+ invocations. See the “Stateful Rules” section for more
+ information about this topic.
</entry>
</row>
<row>
- <entry><property>destinations</property></entry>
+ <entry>destinations</entry>
<entry>
- A set of route-to properties each containing the
- logical name of the destination along with the Service
- category and name as referenced in the registry. The
- logical name is the name which should be used in the
- rule set.
+ This is a set of route-to properties, each of which
+ contains the logical name of the destination, along
+ with the Service category and name as referenced in the
+ registry. The logical name is the name which should be
+ used in the rule set.
</entry>
</row>
<row>
- <entry><property>object-paths</property></entry>
+ <entry>object-paths</entry>
<entry>
- Optional property to pass Message objects into Drools
- WorkingMemory.
+ This is an optional property to pass
+ <systemitem>message</systemitem> objects into
+ <systemitem>working memory</systemitem>.
</entry>
</row>
@@ -461,6 +509,9 @@
</table>
+
+
+
</section>
<section>
@@ -470,13 +521,14 @@
<note>
<para>
- Drools treats objects as shallow objects to achieve highly
- optimized performance, so what if you want to evaluate an
- object deeper in the object tree? An optional 'object-paths'
- property can be used, which results in the extraction of
- objects from the message, using an “ESB Message Object Path”.
+ Note that <application>Drools</application> treats objects
+ as though they were "shallow" in order to achieve
+ highly-optimised performance. To evaluate an object that
+ resides in a location deeper than the "object tree," use the
+ optional <property>object-paths</property> property to extract
+ objects from the message, via an “ESB Message Object Path”.
MVEL is used to extract the object and the path used should
- follow the syntax:
+ therefore use the following syntax:
</para>
</note>
@@ -510,54 +562,61 @@
</itemizedlist>
<para>
- examples:
+ Here are some examples:
</para>
<itemizedlist>
<listitem>
<para>
- properties.Order, gets the property object named "Order"
+ <command>properties.Order</command> - obtains the property object named <literal>Order</literal>
</para>
</listitem>
<listitem>
<para>
- attachment.1, gets the first attachment Object
+ <command>attachment.1</command> - obtains the first attachment Object
</para>
</listitem>
<listitem>
<para>
- attachment.FirstAttachment, gets the attachment named
- 'FirstAttachment'
+ <command>attachment.FirstAttachment</command> - obtains the
+ attachment named <literal>FirstAttachment</literal>
</para>
</listitem>
<listitem>
<para>
- attachment.1.Order, gets getOrder() return object on
- the attached Object.
+ <command>attachment.1.Order</command> - obtains
+ <function>getOrder()</function> return object on the
+ attached Object.
</para>
</listitem>
<listitem>
<para>
- body.Order1.lineitem, obtains the object named "Order1"
- from the body of the message. Next it will call
- getLineitem() on this object. More elements can be
- added to the query to traverse the bean graph.
+ <command>body.Order1.lineitem</command> - obtains the
+ object named <literal>Order1</literal> from the body of
+ the message. Next it will call
+ <function>getLineitem()</function> on this object. More
+ elements can be added to the query in order to traverse the bean
+ graph.
</para>
</listitem>
</itemizedlist>
-
-<important>
+<important>
<para>
- Remember that you have to add java import statements on the
- objects you import into your rule set. Finally, the Object
- Mapper cannot flatten out entire collections, so if you need to
- do that you have to perform a (Smooks-) transformation on the
- message first, to unroll the collection..
+ It is important to remember that you have to add <command>java
+ import</command> statements onto the objects you import into your
+ rule-set.
</para>
+
+ <para>
+ Finally, the Object Mapper cannot flatten out entire
+ collections, so if you have need to do that you firstly have to undertake
+ a (<literal>Smooks-</literal>) transformation of the message. This is in order to unroll the
+ collection.
+ </para>
</important>
@@ -571,36 +630,35 @@
<para>
Using stateful sessions means that facts will be remembered
- across invocations. When stateful is set to true the working
- memory will not be disposed.
+ across invocations. When stateful is set to <code>true</code>, the working
+ memory will not be cleared.
</para>
<para>
- Stateful rule services must be told via message properties when
- to continue with a current stateful session and when to dispose
- of it. To signal that you want to continue an existing stateful
- session two message properties must be set:
+ Tell stateful rule services when to continue with a current
+ stateful session and when to dispose of it via message
+ properties . To signal that the existing stateful session is to
+ be continued, set these two message properties:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/cbr_drools/mess_prop1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
When one invokes the rules for the last time, one must set
- “dispose” to "true" so that the working memory is disposed:
+ “dispose” to "<code>true</code>" so that the working memory is disposed:
</para>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/cbr_drools/mess_prop2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+<programlisting language="Java"><xi:include href="extras/cbr_drools/mess_prop2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
- For more details about the RuleService please see RuleService
- chapter.
+ For more details about the RuleService please see the Rule Service chapter.
</para>
</note>
<para>
- For an example of using stateful rules take a look at the
- business_ruleservice_stateful quickstart.
+ For an example showing how to use stateful rules, please refer to the
+ <code>business_ruleservice_stateful</code> Quick Start.
</para>
<note>
@@ -637,106 +695,77 @@
<section>
<title>
- KnowledgeAgent
+ RuleAgent
</title>
<para>
- By using the ruleAgentProperty property, you can use precompiled rules
- packages that can be located on the local file system, in a
- local directory, or point to an URL. For information about the
- configuration options that exist for the properties file please
- refer to the KnowledgeAgent section of the Drools manual.
+ By using the <literal>RuleAgent</literal> property, one can utilise pre-compiled rules
+ packages. These packages can be located on the local file system, in a
+ local directory or pointing to an URL. For information about the
+ configuration options that exist for the properties file, please
+ refer to section <ulink
+ url="http://downloads.jboss.com/drools/docs/4.0.7.19894.GA/html/ch09s04.html#d0e5889">9.4.4.1.
+ The Rule Agent</ulink> of the <literal>Drools</literal> manual.
</para>
-
- <note>
- <para>
- For more details about the RuleService please see RuleService
- chapter.
- </para>
- </note>
-
- <note>
- <para>
- For an example of using a rule agent take a look at the
- business_ruleservice_ruleAgent quickstart.
- </para>
- </note>
-
-</section>
-
-<section>
- <title>
- KnowledgeAgent and Business Rule Management System
- </title>
-
+<note>
<para>
- By using the ruleAgentProperties property, you can effectively integrate
- your service with a Business Rule Management System (BRMS).
- This can be accomplished by specifying a URL in the rule agent
- properties file. For information about the how to configure the
- URL and the other properties please refer to the KnowledgeAgent
- section of the Drools manual.
+ For more details about the RuleService, please see the Rule Service chapter
</para>
+</note>
- <note>
- <para>
- For more details about the RuleService please see RuleService
- chapter.
- </para>
- </note>
<note>
<para>
For information about the how to install and configure the BRMS
- please refer to the Drools manual.
+ please refer to the the <emphasis>JBoss Rules Guide</emphasis>.
</para>
</note>
</section>
- <section>
+ <section>
<title>
Executing Business Rules
</title>
<para>
- Related to rule execution for routing is the rule execution to
- simply modifying data in the message according to business
- rules. An example Quickstart called business_rule_service
- demonstrates this use case. This quickstart uses the action
- class org.jboss.soa.esb.actions.BusinessRulesProcessor
- </para>
+ There is a close relationship between rule execution for
+ modifying data in the message according to business processes and
+ rule execution for routing. An example quick start called
+ <filename>business_rule_service</filename>
+ demonstrates this use case. This quick start uses the <classname>org.jboss.soa.esb.actions.BusinessRulesProcessor</classname> action class. </para>
<para>
- The functionality of the Business Rule Processor (BRP) is
- identical to the Content Based Router, but it does not do any
- routing, instead it returns the modified EsbMessage for further
- action pipeline processing. You may mix business and routing
- rules in one rule set if you wish to do so, but routing will
- only occur if you use one of the three routing action classes
- mentioned earlier.
+ The functionality of the <firstterm>Business Rule
+ Processor</firstterm> (BRP) is similar to
+ that of a content-based router. However, it is not a router.
+ It returns the modified
+ ESB message for further <systemitem>action pipeline</systemitem>
+ processing. One can mix business and routing rules in
+ a single rule set if one so wishes. However, routing will only occur if one
+ of those three routing <classname>action</classname> classes mentioned previously is
+ used.
</para>
</section>
<section>
<title>
- Changing RuleService implementations
+ Changing Rule Service Implementations
</title>
<para>
- If you would like to use a different RuleService then the
- default one that is shipped with JBossESB, then this is
- possible by specifying the class you would like to use in the
+ To use a different rule service than that
+ which is shipped with the JBoss Enterprise Service
+ Bus, specify the preferred class in the
action configuration:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_drools/changeruleservice.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The requirement is that your rule service implements the
- interface: org.jboss.soa.esb.services.rules.RuleService.
+ The rule service is required to implement the <interfacename>org.jboss.soa.esb.services.rules.RuleService</interfacename> interface.
</para>
</section>
@@ -747,18 +776,21 @@
</title>
<para>
- It is recommended that you package up your code into units of
- functionality, using .esb packages. The idea is to package up
- your routing rules alongside the rule services that use the
- rule sets. The example below shows a layout of the simple_cbr
- quickstart to demonstrate a typical package.
+ Note that one should package one's code by grouping it into
+ units of functionality, using <filename>.esb</filename>
+ packages. The idea of this is to collate the routing rules
+ alongside the services that use those rule sets. The diagram
+ below below shows the layout of the
+ <filename>simple_cbr</filename> Quick Start in order to depict
+ that which is typical of a package:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_drools/code6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Finally make sure to deploy and reference the jbrules.esb in
- your deployment.xml.
+ Finally, deploy and reference the
+ <filename>jbrules.esb</filename> in the
+ <filename>deployment.xml</filename> file, as per this example:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_drools/deployment.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Smooks.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Smooks.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Smooks.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -14,14 +14,13 @@
</title>
<para>
- The SmooksAction can be used for splitting HUGE messages into
- split fragments and performing Content-Based Routing on these
- split fragments.
+ Use the SmooksAction to split huge messages into
+ fragments and perform content-based routing upon these.
</para>
<para>
- An example of this might be a huge order message with
- thousands/millions of order items per message. You might need
+ For example, one might have a huge order message with
+ thousands/millions of order items per message. In order
to split the order up by order item and route each order item
split fragment to one or more destinations based on the
fragment content. This example can be illustrated as follows:
@@ -32,7 +31,7 @@
<title>Huge Message</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/cbr_smooks/smooks_example.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/cbr_smooks/smooks_example.png" />
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Message_Transformation.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Message_Transformation.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Message_Transformation.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -10,122 +10,96 @@
Message Transformation
</title>
- <section>
- <title>
- Overview
- </title>
+
<para>
- JBoss ESB supports message data transformation through a number of
- mechanisms:
+ One can use several different mechanisms to transform messages
+ from one format to another. These are the three choices:
</para>
- <itemizedlist>
- <listitem>
- <para>
- Smooks: Smooks is, among other things, a Fragment based
- Data Transformation and Analysis tool (XML, EID, CSV,
- Java etc). It supports a wide range of data processing
- and manipulation features
- </para>
- </listitem>
+ <variablelist>
- <listitem>
- <para>
- XSLT: JBoss ESB supports message transformation through
- the standard XSLT usage model, as well as through the
- Smooks.
- </para>
- </listitem>
+ <varlistentry>
+ <term>Smooks</term>
+ <listitem>
- <listitem>
- <para>
- ActionProcessor Data Transformation: Where Smooks can
- not handle a specific transformation usecase, you can
- implement a custom transformation solution through
- implementation of the
- org.jboss.soa.esb.actions.ActionProcessor interface.
- </para>
- </listitem>
- </itemizedlist>
-
- </section>
+ <para>
+ Smooks is a
+ fragment-based data transformation and analysis
+ tool. It can "understand" a wide range of source and
+ target data formats, including XML, EID, CSV and Java. It
+ features a wide range of data processing and manipulation
+ functionality.
+ </para>
- <section>
-
- <title>
- Smooks
- </title>
-
- <para>
- Message Transformation on JBossESB is supported by the
- SmooksAction component. This is an ESB Action component that
- allows the Smooks Data Transformation/Processing Framework to
- be plugged into an ESB Action Processing Pipeline.
- </para>
+ </listitem>
+ </varlistentry>
- <para>
- A wide range of source (XML, CSV, EDI, Java etc) and target
- (XML, Java, CSV, EDI etc) data formats are supported by the
- SmooksAction component. A wide range of Transformation
- Technologies are also supported, all within a single framework.
- See the Message Action Guide for more details.
- </para>
+ <varlistentry>
+ <term>XSLT</term>
+ <listitem>
+ <para>
+ This is an alternative to Smooks.
+ </para>
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>ActionProcessor Data Transformation</term>
+ <listitem>
+ <para>
+ If Smooks cannot handle a specific type of transformation,
+ use the
+ <interfacename>org.jboss.soa.esb.actions.ActionProcessor</interfacename>
+ interface to implement a custom solution.
+ </para>
+
+ </listitem>
+
+ </varlistentry>
+ </variablelist>
+
+
+
+ <procedure>
+ <title>Using Smooks</title>
+ <step>
+ <para> Use the <classname>SmooksAction</classname> component to
+ "plug" the Smooks framework into
+ an ESB action processing pipeline.</para>
+ </step>
+ </procedure>
+
<section>
<title>
Samples and Tutorials
</title>
- <orderedlist>
- <listitem>
+
<para>
- A number of Transformation Quickstart samples accompany
- the JBossESB distribution (<ulink
- url="http://community.jboss.org/wiki/jbossesb" />).
- Check out the "transform_*" Quickstarts
- <footnote>
- <para>
- Note that some of the ESB Quickstarts are still
- using the older “SmooksTransformer” action
- class. The SmooksAction is a more flexible and
- easier to use alternative to the
- SmooksTransformer. The SmooksTransformer will
- be deprecated in a future release (and removed
- later again).
- </para>
- </footnote>
+ Find quick starts that demonstrate
+ transformations
+ in
+ the <filename>samples/quickstarts</filename> directory. (The
+ name of each transformation Quick Start sub-directory is
+ prefixed with the word <filename>transform_</filename>.)
</para>
- </listitem>
-
- <listitem>
+
+
<para>
- A number of tutorials are available online on the
- Smooks website (<ulink
- url="http://www.smooks.org/mediawiki/index.php?title=Main_Page"
- />). Any of these samples can be easily ported to
- JBossESB (<ulink
- url="http://community.jboss.org/wiki/jbossesb" />).
- </para>
- </listitem>
- </orderedlist>
-
- </section>
-</section>
+ The <emphasis>JBoss SOA Platform Programmers'
+ Guide</emphasis> contains further information about
+ transformations.
+ </para>
-<section>
-
- <title>
- XSL Transformations
- </title>
- <note>
+<note>
<para>
- XSLT transformation are supported by the XstlAction. Please
- see the section “XSLTAction” in the ProgrammersGuide for
- more information.
+ To learn more about XSLT
+ transformations, read the section of the <emphasis>Programmers' Guide</emphasis> entitled “XSLTAction”.
</para>
- </note>
+</note>
</section>
</chapter>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Registry_Troubleshooting.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Registry_Troubleshooting.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Registry_Troubleshooting.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -21,30 +21,35 @@
<listitem>
<para>
- If you use RMI you need the juddi-client.jar, which can be
- found as part of the jUDDI distribution.
+ If using RMI, be sure to obtain the
+ <filename>juddi-client.jar</filename>, (found in the
+ <application>jUDDI</application> distribution.)
</para>
</listitem>
<listitem>
<para>
- Make sure the jbossesb-properties.xml file is on the
- classpath and read or else the registry will try to
- instantiate classes with the name of 'null'.
+ Ensure that the
+ <filename>jbossesb-properties.xml</filename> file is on the
+ class-path and being read correctly. If not, the
+ <systemitem>registry</systemitem> will try to instantiate
+ classes using "null" as the name.
</para>
<itemizedlist>
<listitem>
<para>
- Make sure you have META-INF/esb.juddi.client.xml that
+ Make sure that
+ <filename>META-INF/esb.juddi.client.xml</filename>
specifies a valid transport.
</para>
</listitem>
<listitem>
<para>
- Make sure the settings of your persistence.xml file are
- valid and that you are using the Hibernate dialect that
- matches your database.
+ Make sure that the <filename>persistence.xml</filename>
+ file's settings are valid and that the chosen
+ <application>Hibernate</application> dialect matches that
+ for the database in use.
</para>
</listitem>
</itemizedlist>
@@ -53,16 +58,17 @@
<listitem>
<para>
- Make sure you have a esb.juddi.xml file on your classpath
- for jUDDI to configure itself with.
+ Ensure that the <filename>esb.juddi.xml</filename> file is
+ on the class-path. The <application>jUDDI</application>
+ registry requires this so that it can configure itself.
</para>
</listitem>
<listitem>
<para>
- In the event that a service fails or does not shut down
- cleanly, it is possible that stale entries may persist
- within a registry. You will have to remove these manually.
+ In the event that a service fails or otherwise fails to
+ shut down cleanly, old entries may possibly "persist" in the
+ registry. Remove these manually.
</para>
</listitem>
</itemizedlist>
@@ -74,17 +80,20 @@
More Information
</title>
+ <para>
+ Learn more about troubleshooting the registry at these locations:
+ </para>
<itemizedlist>
<listitem>
<para>
- For more information see the wiki:
+ The JBoss jUDDI Wiki:
<ulink url="http://www.jboss.org/community/docs/DOC-11217" />
</para>
</listitem>
<listitem>
<para>
- JBossESB user forum:
+ The JBoss ESB User Forum:
<ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=246" />.
</para>
</listitem>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -17,22 +17,32 @@
</title>
<para>
- The Rule Service support in the JBossESB uses Drools
- as its rule engine. JBossESB integrates with Drools through
+ <application>Drools</application> is the name of the
+ engine that provides the <application>SOA
+ Platform</application> with <firstterm>rule service</firstterm>
+ support. Read this section to learn more about it.
+ </para>
+
+ <para>
+ <application>Drools</application> is integrated through
+ the following components:
</para>
<itemizedlist>
<listitem>
- <para>The BusinessRulesProcessor action class</para>
+ <para>the <classname>BusinessRulesProcessor</classname> action class</para>
</listitem>
<listitem>
<para>
- Rules written in Drools drl, dsl, decision table, or business rule editor.
+ rules written in any one of <application>JBoss
+ Rules</application>, DRL, DSL, decision tables or the
+ <application>Business Rule Editor</application>.
</para>
</listitem>
<listitem>
<para>
- The ESB Message
+ the Enterprise Service Bus Message. (This is inserted
+ into the Rules Engine's working memory.)
</para>
</listitem>
<listitem>
@@ -46,58 +56,60 @@
<para>
- When a message is sent to the BusinessRulesProcessor, a certain
- rule set will execute over the objects in the message, and update
- those objects and / or the message.
+ When a message is sent to the
+ <classname>BusinessRulesProcessor</classname>, a <firstterm>rule
+ set</firstterm> executes over the objects contained therein. The
+ rule set will update either one of those objects or the message
+ itself.
</para>
</section>
<section>
<title>
- Rule Set Creation
+ Rule-Set Creation
</title>
<para>
- A rule set can be created using the JBoss Developer Studio which
- includes a plug-in for Drools, or with Eclispe 3.5 and the
- plugin installed (see Drools download site for the plugin). Since
- the message is added as a global, you need to add
- jbossesb-rosetta.jar to your Drools project.
+ Create a rule-set by using <application>JBoss Developer
+ Studio</application>. Since the message is added as a global, there
+ is a needs to add the <filename>jbossesb-rosetta.jar</filename> file
+ to the <application>Drools</application> project.
</para>
-
- <para>
- You can also write your rules using the <application>Drools
- BRMS</application> Business Rule Editor. When using the Drools
- BRMS, it is not necessary to add the ESB Message class to the
- imports, as long as <filename>jbossesb-rosetta.jar</filename> is
- somewhere on the classpath of the BRMS web application.
- </para>
<note>
<para>
- For a detailed discussion on rule creation and the Drools language
- itself please see the Drools documention.
+ For a detailed study of rule creation and the
+ Drools language itself, please refer to the
+ included <emphasis>Drools Reference Guide</emphasis>.
</para>
</note>
-
+
+
<para>
- For the most part, rules can be written without regard to their
- deployment on the ESB as a service. There are a few caveats
- however:
+ One must adhere to three requirements when writing rules for
+ deployment as services on the <application>JBoss Enterprise SOA
+ Platform</application>:
</para>
- <orderedlist>
- <listitem>
- <para>
- All rules deployed as a rule service must define the
- ESB Message as a global, i.e.,
- </para>
-
- <programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/declareglobals.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <orderedlist>
+ <listitem>
+ <para>
+ all rules deployed as <systemitem>rule services</systemitem>
+ must define the ESB Message as a global.
+ </para>
+ <para>
+ (Most rule services will want to communicate
+ results to other services in the flow. They do so by way of
+ updating the message, so the
+ <classname>BusinessRulesProcessor</classname> or
+ <classname>DroolsRuleService</classname>
+ will always set the ESB Message as a global.)
+ </para>
+ <programlisting language="Java"><xi:include href="extras/rule_service/declareglobals.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
@@ -122,19 +134,30 @@
<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/declareglobalssalience.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</listitem>
-
- <listitem>
- <para>
- The DroolsRuleService does not provide a means to start a
- RuleFlow from the rule service. This also would have made for
- additional configuration support in the jboss-esb.xml, and
- could be supported in the future. For now, if a RuleFlow needs
- to be started, this can be done in higher salience rule. E.g.,
- </para>
+ <listitem>
+ <para>
+ The <classname>DroolsRuleService</classname> does not provide a
+ means by which to start a <firstterm>RuleFlow</firstterm> from the
+ <systemitem>rule service</systemitem> itself. (This functionality
+ may be added in the future.) For now, this can be achieved in a
+ rule with higher salience, as per this sample code:
+ </para>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/ruleflowsalience.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+<programlisting language="Java"><xi:include href="extras/rule_service/declareglobalssalience.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</listitem>
+ <listitem>
+ <para>
+ The <classname>DroolsRuleService</classname> does not provide a
+ means by which to start a <firstterm>RuleFlow</firstterm> from the
+ <systemitem>rule service</systemitem> itself. (This functionality
+ may be added in the future.) For now, this can be achieved in a
+ rule with higher salience, as per this sample code:
+ </para>
+
+<programlisting language="Java"><xi:include href="extras/rule_service/ruleflowsalience.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+ </listitem>
</orderedlist>
</section>
@@ -145,43 +168,52 @@
</title>
<para>
- The consumer of a rule service has little to worry about. In a rule
- service environment there is no need for the consumer to worry
- about creating rulebases, creating working memories, inserting
- facts, or firing the rules. Instead the consumer just has to worry
- about adding facts to the message, and possibly some properties to
- the message.
+ A <firstterm>rule service consumer</firstterm> has little to do.
+ There is no need for it to create <firstterm>rule-bases</firstterm>
+ or <firstterm>working memories</firstterm>, to insert facts or to
+ execute the rules. It only has to add facts and, on occassions,
+ properties, to the message.
</para>
<para>
- In some cases the client is ESB aware, and will add the objects
- to the message directly:
+ In some cases, the client is <firstterm>ESB-aware</firstterm>
+ meaning that it can add objects directly to the message, as per
+ this example:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/objecttomessage.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <para>
+ In other cases, the data may be in an Extensible Mark-Up Language
+ (XML) message. If so, a <firstterm>transformation
+ service</firstterm> will be added to the message flow. As its name
+ implies, its purpose is to transform the XML into <firstterm>Plain
+ Old Java Object</firstterm> (POJO) files prior to the invocation of
+ the <systemitem>rule service</systemitem>.
+ </para>
- <para>
- In other cases the data may be in an XML message, and a
- transformation service will be added to the message flow to
- transform the XML to POJOs before the rule service is invoked.
- </para>
-
+
+
<para>
- Using stateful rule execution requires a few properties to be added
- the messages. For the first message,
+ One must add a few properties to the message so that stateful
+ rule execution can occur.
</para>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/mess1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <para>
- For all the subsequest messages but the final message,
+ <para>
+ For the first message:
</para>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/mess2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+<programlisting language="Java"><xi:include href="extras/rule_service/mess1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+ <para>
+ For all the subsequent messages bar the final one:
+ </para>
+<programlisting language="Java"><xi:include href="extras/rule_service/mess2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
<para>
For the final message:
</para>
@@ -190,16 +222,44 @@
<para>
- These can be added directly by an ESB aware client. A
- non-ESB aware client would have to communicate the position
- of the message (first, ongoing, last) in the data, and an
- action class would need to be added to the pipeline to add
- the properties to the ESB message (see
- quickstarts/business_ruleservice_stateful for an example of
- this type of service).
+ An ESB-aware client can add these directly. However
+ a client that is not ESB-aware will have to communicate the
+ position of the message (whether it is first, ongoing or last) within the
+ data. Also, an action class must be added to the
+ pipeline so that the properties of the
+ Enterprise Service Bus message are included.
+ </para>
+
+ <important>
+ <para>
+ Note that the <filename>quickstarts/business_ruleservice_stateful</filename>
+ file is an example of this type of service.
+ </para>
+
+ </important>
+
+ <note>
+ <para>
+ In the releases up to, and including,
+ <application>Enterprise Service Bus 4.6</application>, the
+ <systemitem>continue</systemitem> functionality for the
+ stateful rule execution did not dispose of the working
+ memory if the value of the property was either
+ <code>false</code> or completely absent. This has now been
+ fixed through the work for <literal>JBESB-2900</literal>.
+ </para>
+
+ <para>
+ If there is a need to re-enable the previous behaviour, do
+ so by changing the value of the configuration property
+ called
+ <property>org.jboss.soa.esb.services.rules.continueState</property>
+ to <code>true</code>. This property is found in the
+ <filename>jbossesb-properties.xml</filename> file.
</para>
-
- <note>
+ </note>
+
+ <note>
<para>
In ESB 4.6 and prior releases, the “continue” functionality for
stateful rule execution did not dispose of working memories if
@@ -210,8 +270,7 @@
“org.jboss.soa.esb.services.rules.continueState”, found within
jbossesb-properties.xml, to true.
</para>
- </note>
-
+ </note>
</section>
<section>
@@ -220,13 +279,12 @@
</title>
<para>
- Configuration of a rule service is in the jboss-esb action element
- for the service. Several configuration parameters are required or
- optional
+ Configure a <systemitem>rule service</systemitem> via its
+ <systemitem>jboss-esb</systemitem> action element.
</para>
<para>
- The action class and name is required:
+ To do this, the name and action class are both required
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/actionclass.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -240,36 +298,46 @@
One of the following is also required:
</para>
-
+ <itemizedlist>
+ <listitem>
+ <para>
+ a <filename>DRL</filename> file
+ </para>
+
<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/dri.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </listitem>
+ <listitem>
<para>
- for specifying a drl file, or
- </para>
-
-<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/dsl.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+ <filename>DSL</filename> and <filename>DSLR</filename>
+ (<firstterm>Domain Specific Language</firstterm>) files
+ </para>
+<programlisting language="XML"><xi:include href="extras/rule_service/dsl.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </listitem>
+ <listitem>
<para>
- for specifying a dsl and dslr (domain specific language) files , or
+ a <code>decisionTable</code> on the classpath
</para>
-<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/dectable.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+<programlisting language="XML"><xi:include href="extras/rule_service/dectable.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </listitem>
+ <listitem>
<para>
- or specifying a decisionTable on the classpath, or
+ a "properties" file on the classpath, the purpose of which is to
+ tell the <systemitem>rule agent</systemitem> how to find the rules
+ package. It can do so by specifying either an URL or a local file.
</para>
- <programlisting language="XML" role="XML"><xi:include href="extras/rule_service/rulesagent.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/rule_service/rulesagent.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+ </listitem>
- <para>
- for specifying a properties file on the classpath that tells the
- rule agent how to find the rule package. This could specify a url or
- a local file system.
- </para>
-
+ </itemizedlist>
+
+
<para>
- Several example configurations follow.
+ Several example configurations follow:
</para>
<orderedlist>
@@ -289,11 +357,13 @@
</para>
<para>
- In this scenario, a service may receive multiple messages over time
- and wish to use rules to accumulate data across this message set.
- Each time a message is received, the rules will be fired within the
- context of a single Stateful Session. The active Session can be
- disposed of (reset) via the “dispose” property.
+ In this scenario, the client can, over time, send multiple messages
+ to the rule service. The first message might contain a customer
+ object, with the subsequent ones each containing orders for that
+ customer. Every time a message is received, the rules will be
+ "fired." The client can add a property to the final message that
+ tells the rule service to dispose of the contents of the <systemitem>working
+ memory</systemitem>.
</para>
@@ -433,38 +503,41 @@
<segtitle>Description</segtitle>
<seglistitem>
- <seg><property>ruleSet</property></seg>
+ <seg><systemitem>ruleSet</systemitem></seg>
- <seg>Optional reference to a file containing the Drools
- ruleSet. The set of rules that is used to evaluate the
- content. Only 1 ruleSet can be given for each rule service
- instance.</seg>
+ <seg>This is an optional reference to a file containing the
+ <systemitem>ruleSet</systemitem>, which is the set of
+ rules used to evaluate the content. Only one
+ <systemitem>ruleSet</systemitem> can be given for each
+ <systemitem>rule service</systemitem> instance.</seg>
</seglistitem>
<seglistitem>
- <seg><property>ruleLanguage</property></seg>
+ <seg><systemitem>ruleLanguage</systemitem></seg>
- <seg>Optional reference to a file containing the definition
- of a Domain Specific Language to be used for evaluating the
- rule set. If this is used, the file in ruleSet should be a
- dslr file.</seg>
+ <seg>This is an optional reference to a file containing the
+ definition of a Domain Specific Language. This
+ definition can be used for evaluating the rule set. If
+ it is used, ensure that the file in the
+ <systemitem>ruleSet</systemitem> is a
+ <filename>dslr</filename>.</seg>
</seglistitem>
<seglistitem>
- <seg><property>ruleReload</property></seg>
-
- <seg>Optional property which can be to true to enable 'hot'
- redeployment of rule sets. Note that this feature will
- cause some overhead on the rules processing. Note that
- rules will also reload if the .esb archive in which they
- live is redeployed.</seg>
+ <seg><systemitem>ruleReload</systemitem></seg> <seg>Set this
+ optional property to <code>true</code> in order to enable
+ the <firstterm>hot redeployment</firstterm> of
+ <systemitem>rule sets</systemitem>. (However, enabling this feature
+ will increase the overhead on the rules processing.) Note
+ that rules will also reload if the <filename>.esb</filename>
+ archive in which they live is redeployed.</seg>
</seglistitem>
<seglistitem>
- <seg><property>decisionTable</property></seg>
+ <seg><systemitem>decisionTable</systemitem></seg>
<seg>This is an optional reference to a file containing the
definition of a rule-specification spreadsheet. </seg>
@@ -472,24 +545,26 @@
</seglistitem>
<seglistitem>
- <seg><property>ruleAgentProperties</property></seg>
+ <seg><systemitem>ruleAgentProperties</systemitem></seg>
- <seg>Optional reference to a properties file containing the
- location (URL or file path) to the compiled rule
- package(s). Note there is no need to specify ruleReload
- with a KnowledgeAgent, since this is controlled through the
- Drools resource scanning/notification system.</seg>
+ <seg>This is an optional reference to a properties file
+ containing the location (either a URL or file path) of the
+ compiled rule packages. Note there is no need to specify
+ <systemitem>ruleReload</systemitem> with a
+ <systemitem>ruleAgent</systemitem>, as it is controlled
+ through the properties file.</seg>
</seglistitem>
<seglistitem>
<seg><property>stateful</property></seg>
- <seg>Optional property which can be to true to specify that
- the rule service will receive multiple messages over time
- that will add fact to the rule engine working memory and
- re-execute the rules. NOTE: A single shared session is
- shared across all Service executions.</seg>
+ <seg>Set this optional property to <code>true</code> to
+ specify that the <systemitem>rule service</systemitem> will
+ be receiving multiple messages over time. (The new facts
+ will be added to the <systemitem>rule engine</systemitem>'s
+ <systemitem>working memory</systemitem> and the rules will
+ be re-executed each time.)</seg>
</seglistitem>
<seglistitem>
@@ -579,22 +654,30 @@
<title>
Object Paths
</title>
-
-<note>
+
+
<para>
- Drools treats objects as shallow objects to achieve highly
- optimized performance, so what if you want to evaluate an object
- deeper in the object tree? An the optional 'object-paths' property
- can be used, which results in the extraction of objects from the
- message, using an “ESB Message Object Path”. MVEL is used to
- extract the object and the path used should follow the syntax:
+ Note that <application>Droolss</application> treats objects as
+ though they are <firstterm>shallow</firstterm>. This is in order to achieve highly-optimized
+ performance. Use the optional <property>object-paths</property>
+ property to evaluate an object residing in a location that is "deeper" down
+ than the <systemitem>object tree</systemitem>. (Set this property
+ to extract those objects with an <literal>ESB Message Object
+ Path</literal>.)
</para>
-</note>
+
+
+ <para>
+ The <firstterm>MVFLEX Expression Language</firstterm> (MVEL) is
+ used to extract the object. The path to be used must abide by the
+ following syntax:
+ </para>
+
-<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/mvel.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+<programlisting language="Java"><xi:include href="extras/rule_service/mvel.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- where,
+ Understand that, in the above sample:
</para>
<itemizedlist>
@@ -628,56 +711,66 @@
</para>
<segmentedlist>
- <title>MVEL Expressions</title>
+ <title>Example MVEL Expressions</title>
<segtitle>Expression</segtitle><segtitle>Result</segtitle>
-
- <seglistitem>
+ <seglistitem>
+
<seg><command>properties.Order</command></seg>
- <seg>gets the property object named "Order" </seg>
+ <seg>Use this to obtain the property object named
+ <systemitem>Order</systemitem></seg>
+
</seglistitem>
-
<seglistitem>
+
<seg><command>attachment.1</command></seg>
- <seg>gets the first attachment Object</seg>
+ <seg>obtains the first attachment object</seg>
+
</seglistitem>
<seglistitem>
<seg><command>attachment.AttachmentOne</command></seg>
- <seg>gets the attachment named 'FirstAttachment'</seg>
+ <seg>obtains the attachment named <literal>AttachmentOne</literal></seg>
+
</seglistitem>
-
<seglistitem>
+
<seg><command>attachment.1.Order</command></seg>
- <seg>gets getOrder() return object on the attached Object.</seg>
+ <seg>obtains <function>getOrder()</function>
+ <firstterm>return object</firstterm> on the attached
+ object.</seg>
+
</seglistitem>
<seglistitem>
<seg><command>body.Order1.lineitem</command></seg>
- <seg>obtains the object named "Order1" from the body of the
- message. Next it will call getLineitem() on this object.
- More elements can be added to the query to traverse the
- bean graph. </seg>
+ <seg>obtains the object named <literal>Order1</literal> from
+ the body of the message. Next, it will call
+ <function>getLineitem()</function> on this object. More
+ elements can be added to the query in order to traverse the
+ bean graph.</seg>
+
</seglistitem>
-
</segmentedlist>
<important>
<para>
- Remember that you have to add java import statements on the objects
- you import into your rule set.
+ Remember to add the <command>java import</command> statements to any
+ objects that one imports into one's <systemitem>rule
+ set</systemitem>.
</para>
</important>
<para>
- Finally, the Object Mapper can flatten out entire collections. For
- example a collectoin Orders will be unrolled, and each order object
- inserted into working memory.
+ The <firstterm>Object Mapper</firstterm> cannot "flatten out" entire
+ collections. If one has a requirement to do that, run a
+ "transformation" on the message first. (This will "unroll" the
+ collection.)
</para>
@@ -753,19 +846,22 @@
</title>
<para>
- It is recommended that you package up your code into units of
- functionality, using .esb packages. The idea is to package up
- your routing rules alongside the rule services that use the
- rule sets. The below shows a layout of the
- business_rules_service quickstart to demonstrate a typical
- package.
+ JBoss recommends that one packages one's code into "units of
+ functionality." Use <filename>.esb</filename> packages to do so.
+ Conceptually, the aim is to package routing rules alongside the
+ <systemitem>rule services</systemitem> that use <systemitem>the
+ rule sets</systemitem>. The figure below shows the layout of the
+ <code>business_rules_service</code> Quick Start and, in doing
+ so, depicts a "typical" package.
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/esbarchive.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Finally make sure to deploy and reference the jbrules.esb in
- your deployment.xml.
+ Finally, deploy and reference the
+ <filename>jbrules.esb</filename> archive in the
+ <filename>deployment.xml</filename> file. Here is an example of
+ how to do this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/jbrules.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Security.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -15,34 +15,61 @@
</title>
<para>
- Services in JBossESB can be configured to be secure which means
- that the service will only be executed if authentication succeeds
- and if the caller is authorized to execute the service.
+ JBoss ESB services can be made secure, in
+ the sense that one can configure the platform so that
+ they will only be executed if authentication succeeds and
+ the caller also has the suitable level of authority.
</para>
<para>
- A service can be invoked by using a gateway or by using the
- ServiceInvoker to directly invoke the ESB service. When calling a
- service via a gateway, the gateway is responsible for extracting
- the security information needed to authenticate the caller. It does
- this by extracting the information from the transport that the
- gateway handles. Using this information the gateway creates an
- authentication request that is encrypted and then passed to the
- ESB.
+ There are two ways in which to invoke a service:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ through a gateway
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ directly via the <application>Enterprise Service
+ Bus</application> via the
+ <firstterm>ServiceInvoker</firstterm>.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ When one uses the first option, the gateway is responsible for
+ obtaining the security information needed to authenticate the
+ caller. It does this by extracting the information from the
+ transport that it handles. Once it has obtained this information, it
+ creates an authentication request that is encrypted and then
+ passed to the <application>Enterprise Service Bus</application>.
</para>
-
+
+
<para>
- When using the ServiceInvoker a gateway is not involved and it is
- the responsibility of the client to create the authentication
- request prior to invoking the service. Both of these situations
- will be looked at in the following sections.
+ If one uses the <classname>ServiceInvoker</classname> instead, the
+ gateway is not utilised. Instead, it becomes the client's responsibility
+ to create the authentication request prior to invoking
+ the service.
</para>
+ <para>
+ Both of these options will be discussed in more detail
+ the following sections.
+ </para>
+
+
<para>
- The default security implementation is JAAS based but this is a
- configurable feature. The following sections describe the security
- components and how they can be configured.
+ The default security implementation is based on the <firstterm>Java
+ Authentication and Authorization Service</firstterm> (JAAS). (It
+ can be reconfigured if one wishes to use an alternative system.)
+ The following sections describe how to set the JAAS security
+ components.
</para>
</section>
@@ -78,9 +105,8 @@
</entry>
<entry>
<para>
- This is the concrete SecurityService implementation
- that should be used. Required. Default is
- JaasSecurityService.
+ This is the "concrete" <firstterm>SecurityService</firstterm> implementation that should be
+ used. The default setting is <code>JaasSecurityService</code>.
</para>
</entry>
<entry>
@@ -96,10 +122,11 @@
</entry>
<entry>
<para>
- A default CallbackHandler implementation when a JAAS
- based SecurityService is being used. See “Customizing
- security” for more information about the
- callbackHandler property.
+ This is a default
+ <classname>CallbackHandler</classname> implementation, utilised when
+ a <abbrev>JAAS</abbrev>-based <classname>SecurityService</classname>
+ is employed. See “Customizing Security” for more information about
+ the <classname>CallbackHandler</classname> property.
</para>
</entry>
<entry>
@@ -115,7 +142,8 @@
</entry>
<entry>
<para>
- The algorithm to use for sealing the SecurityContext.
+ This is the algorithm to use when "sealing" the
+ <classname>SecurityContext</classname>.
</para>
</entry>
<entry>
@@ -131,8 +159,8 @@
</entry>
<entry>
<para>
- The size of the secret/symmetric key used to
- encrypt/decrypt the SecurityContext.
+ This is the size of the secret/symmetric key used to encrypt/decrypt the
+ <classname>SecurityContext</classname>.
</para>
</entry>
<entry>
@@ -148,11 +176,11 @@
</entry>
<entry>
<para>
- The amount of time in milliseconds that a security
- context is valid for. This is a global setting that may
- be overridden on a per service basis by specifying this
- same property name on the security element in
- jboss-esb.xml.
+ This is the amount of time (in milliseconds) for which a security
+ context is valid. A global setting, this may be over-ridden on a
+ per-service basis. To do so, specify the property of the same name that
+ exists on the security element in the
+ <filename>jboss-esb.xml</filename> file.
</para>
</entry>
<entry>
@@ -169,9 +197,11 @@
</entry>
<entry>
<para>
- Configures a global SecurityContextPropagator. For
- more details on the SecurityContextPropagator please
- refer to the “Security Context Propagation”.
+ Use this to configure a global
+ <classname>SecurityContextPropagator</classname>.
+ (For more details on the
+ <classname>SecurityContextPropagator</classname>, please refer to the section on
+ “Security Context Propagation.”
</para>
</entry>
<entry>
@@ -187,9 +217,10 @@
</entry>
<entry>
<para>
- Path to the keystore that holds a keys used for
- encrypting and decrypting data external to the ESB.
- This is used to encrypt the AuthenticationRequest.
+ This is the path to the <firstterm>Keystore</firstterm> which
+ holds the keys used to encrypt and decrypt that data which is
+ external to the Enterprise Service Bus. The Keystore is used to
+ encrypt the <classname>AuthenticationRequest</classname>.
</para>
</entry>
<entry>
@@ -237,7 +268,7 @@
</entry>
<entry>
<para>
- Password for the alias if one was specified upon creation.
+ This is the password for the alias if one was specified upon creation.
</para>
</entry>
<entry>
@@ -253,9 +284,9 @@
</entry>
<entry>
<para>
- Cipher transformation in the format:
- “algorithm/mode/padding”. If not specified this will
- default to the keys algorithm.
+ This is a cipher transformation. It is in this format:
+ <code>algorithm/mode/padding</code>. If this is not specified, the
+ "keys" algorithm will be used by default.
</para>
</entry>
<entry>
@@ -273,23 +304,27 @@
<para>
- The JAAS login modules are configured in the way you would
- except using the login-config.xml file located in the conf
- directory of your JBoss Application Server. So you can use the
- ones that come pre-configured but also add your own login
- modules.
+ Configure the JAAS log-in modules via the
+ <filename><replaceable>$SOA_ROOT</replaceable>/server/<replaceable>$PROFILE</replaceable>/conf/login-config.xml</filename>
+ file. Use either a pre-configured one or create a custom solution.
</para>
<warning>
<para>
- By default JBossESB ships with an example keystore which should
- not be used in production. It is only provided as a sample to
- help users get security working “out of the box”. The sample
- keystore can be updated with custom generate key pairs.
+ The <application>JBoss Enterprise Service Bus</application>
+ ships with an example key-store. Do not be use this in a
+ production environment. It is only provided as a sample to help
+ users achieve a working security configuration
+ “out-of-the-box.”
</para>
</warning>
-
+ <note>
+ <para>
+ One can update the sample key-store with a custom-generated
+ pairs of keys.
+ </para>
+ </note>
<section>
<title>
@@ -297,13 +332,17 @@
</title>
<para>
- Security is configured per-service. A service in JBossESB can
- be declared as being secured and that it requires
- authentication. Services are configured by adding a “security”
- element to the service in jbossesb.xml:
+ Security is configured on a per-service basis. An ESB service can be
+ declared secure and requiring authentication.
</para>
-
+ <para>
+ To configure a service, find it in the
+ <filename>jbossesb.xml</filename> file and add a
+ <property>security</property> element there. This code sample
+ demonstrates this:
+ </para>
+
<programlisting language="XML" role="XML"><xi:include href="extras/security/securityservice.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -324,7 +363,8 @@
</entry>
<entry>
<para>
- A named module that exist in conf/login-config.xml
+ This is a named module that exists in the
+ <filename>conf/login-config.xml</filename> file.
</para>
</entry>
<entry>No</entry>
@@ -349,13 +389,12 @@
</entry>
<entry>
<para>
- An optional comma separated list of roles that are
- allowed to execute the service. This is a check that
- is performed after a caller has been authenticated, to
- verfiy that the caller in a member of the roles
- specified. The roles will have been assigned after a
- successful authentication by the underlying security
- mechanism.
+ This is an comma-separated list of those roles that have
+ been granted the ability to execute the service. This is used as a
+ check that is performed after a caller has been authenticated, in
+ order to verify that they are indeed belonging to one of the roles
+ specified. The roles will have been assigned after a successful
+ authentication by the underlying security mechanism.
</para>
</entry>
<entry>No</entry>
@@ -368,8 +407,9 @@
</entry>
<entry>
<para>
- An optional CallbackHandler that will override the one
- defined in jbossesb-properties.xml.
+ This is the <classname>CallbackHandler</classname>
+ that will override that which was defined in the
+ <filename>jbossesb-properties.xml</filename> file.
</para>
</entry>
<entry>No</entry>
@@ -423,9 +463,9 @@
</entry>
<entry>
<para>
- Optional property that lets the service override the
- global security context propagator class
- implementation specified in jbossesb-properties.xml.
+ This property lets the service to override the
+ "global security context propagator" class implementation, that is
+ specified in the <filename>jbossesb-properties.xml</filename> file.
</para>
</entry>
<entry>No</entry>
@@ -436,7 +476,8 @@
<para>
- Example of overriding global configuration settings:
+ This example demonstrates how to override global configuration
+ settings:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/security/jbossesb-properties_security_example.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -450,26 +491,30 @@
</title>
<para>
- To authenticate a caller, security information needs to be
- provided. If the call to the service is coming through a gateway,
- then the gateway will extract the required information from the
- transport that the gateway works with. For a web service call this
- would entail extracting either the UsernameToken or the
- BinarySecurityToken from the security element in the SOAP header.
+ Security information needs to be provided in order to authenticate a
+ caller. If the call to the service is coming through a gateway, then
+ that gateway will extract the required information from the
+ transport with which it works. For a web service call, this would
+ entail extracting either the <classname>UsernameToken</classname> or
+ the <classname>BinarySecurityToken</classname>
+ from the security element in the SOAP header.
</para>
<para>
- When a service needs to call another services and that service
- requires authentication, another authentication process will be
- performed. So having a chain of services that are all configured
- for authentication will cause multiple authentications to be
- performed. To minimize such overhead the ESB will store an
- encrypted SecurityContext which will be propagated with the ESB
- Message object between services. If the ESB detects that a Message
- has a SecurityContext, it checks that the SecurityContext is still
- valid, and if so, re-authentication is not performed. Note that the
- SecurityContext is only valid on a single ESB node. If the message
- is routed to a different ESB node, re-authentication will be
+ An authentication process will run if one service requiring
+ authentication needs to call upon another. Therefore, having a chain
+ of services that are all configured for authentication will cause
+ multiple authentications to be performed. In order to minimize the
+ overhead, the Enterprise Service Bus will store an encrypted
+ <classname>SecurityContext</classname>. This
+ <classname>SecurityContext</classname> will be passed on to
+ the ESB message object between services. If the
+ ESB detects that a Message has a
+ <classname>SecurityContext</classname>, it will check that it is
+ still valid and, if so, re-authentication is not performed. Note
+ that the <classname>SecurityContext</classname> is only valid for a
+ single Enterprise Service Bus node. If the message is routed to a
+ different ESB node, a re-authentication will be
required.
</para>
@@ -479,16 +524,17 @@
</title>
<para>
- An AuthenticationRequest is intended to carry security
- information needed for authentication between a gateway and a
- service, or between two services.
+ An <classname>AuthenticationRequest</classname> is designed to
+ carry the security information needed for authentication between
+ either a gateway and a service or between two services.
</para>
<para>
An instance of this class should be set on the message object
- before calling the service configured for authentication:
+ prior to that service which has been configured for
+ authentication being called:
</para>
@@ -496,21 +542,25 @@
<note>
<para>
- The authentication context is encrypted and then set in the
- message context. This will be decrypted by the ESB to perform
- authentication. See the “SecurityService Configuration”
- section for information on how to configure the public
- keystore for this purpose.
+ Note that the authentication context is encrypted and then set
+ within the message context. It will later be de-crypted by the
+ Enterprise Service Bus in order to perform the authentication.
+ See Section on Security Service Configuration for
+ information on how to configure the <firstterm>public keystore</firstterm> for this
+ purpose.
</para>
</note>
<para>
- The “security_basic” quickstart shows an example of using a
- external client and how to prepare the Message before using the
- ServiceInvoker, see the SendEsbMessage class for more
- information. This quickstart also shows how you can configure
- jbossesb-properties.xml for client usage.
+ The <filename>security_basic</filename> Quick Start shows an
+ example of an external client in use. The Quick Start explains
+ shows how to prepare the message before using the
+ <classname>ServiceInvoker</classname>. (See the
+ <classname>SendEsbMessage</classname> class for more
+ information.) It also demonstrates how one can configure the
+ <filename>jbossesb-properties.xml</filename> file for client
+ usage.
</para>
</section>
@@ -519,24 +569,30 @@
<section>
<title>
- JBossESB SecurityContext
+ The JBoss Enterprise Service Bus Security Context
</title>
+
<para>
- A SecurityContext in JBossESB is an object that is local to a
- specific ESB node, or really to the JVM of the node. The
- SecurityContext is created after a successful authentication has be
- performed and it will be used locally in the ESB where it was
- created to save having to re-authenticate with every call.
+ In the JBoss Enterprise Service Bus, a
+ <classname>SecurityContext</classname> is an object that is local to
+ a specific <abbrev>ESB</abbrev> node or to the Java Virtual Machine
+ of that node. The <classname>SecurityContext</classname> is created
+ after a successful authentication has be performed. It will be used
+ locally in the Enterprise Service Bus in which it was created. This
+ is in order to avoid having to re-authenticate with every call.
</para>
-
+
+
+
<para>
- A timeout is specified for the context which is the time, in
- milliseconds, that the context is valid for. This value can be
- specified globally in jbossesb-properties.xml of overridden
- per-service by specifying the value in jboss-esb.xml. Please see
- “Configuring Secuirtyon a Service” and “SecurityService
- Configuration” to see how this is done.
+ A time-out (in milliseconds) is specified for the context in which
+ it is valid. This time value can be either specified globally (by
+ editing the <filename>jbossesb-properties.xml</filename> file) or it
+ can be over-ridden on a per-service basis. This latter is achieved by
+ specifying it in the <filename>jboss-esb.xml</filename> file.
+ Additional information about this topic can be found in elsewhere in
+ this chapter.
</para>
</section>
@@ -607,29 +663,33 @@
<section>
<title>
- Customising security
+ Customising Security
</title>
<para>
- The default security implementation in JBossESB is based on JAAS
- and named JaasSecurityService. Custom login modules can be added in
- conf/login-config.xml of an JBoss Application Server.
+ The default security implementation in the JBoss Enterprise Service
+ Bus is based on <abbrev>JAAS</abbrev>. It is named
+ <classname>JaasSecurityService</classname>. Custom log-in modules
+ can be added to the <filename>conf/login-config.xml</filename> file
+ of a JBoss Application Server.
</para>
<para>
- Since different login modules will require different information,
+ Since different log-in modules will require different information,
the callback handler to be used can be specified in the security
- configuration for that Service. This can be accomplished by
- specifying the 'callbackHandler' attribute belonging to the
- security element defined on the service.
+ configuration for that service. This can be accomplished by
+ specifying the <emphasis>callbackHandler</emphasis> attribute
+ belonging to the security element defined on the service.
</para>
<para>
- The callbackHandler should specify a fully qualified class name of
- a class that implements the EsbCallbackHandler interface:
+ The <classname>callbackHandler</classname> should specify a "fully
+ qualified" classname for that class
+ which implements the <classname>EsbCallbackHandler</classname>
+ interface:
</para>
@@ -637,55 +697,60 @@
<para>
- The AuthenticationRequest will contain the principal and
- credentials needed authenticate a caller.
+ The <classname>AuthenticationRequest</classname> class will contain
+ both the principal and the credentials needed to authenticate a
+ caller.
</para>
<para>
- The SecurityConfig will give access to the security configuration
- in jboss-esb.xml.
+ The <classname>SecurityConfig</classname> class will grant access to
+ the security configuration specified in the
+ <filename>jboss-esb.xml</filename> file.
</para>
<para>
- Both of these are made available to the CallbackHandler which it
- can use to populate the Callback instances required by the login
- module.
+ Both of these are made available to the
+ <classname>CallbackHandler</classname>. It can use them to populate
+ the callback instances that are required by the log-in module.
</para>
</section>
<section>
<title>
- Provided Login Modules
+ Provided Log-in Modules
</title>
<para>
- This section lists the login modules provided with JBossESB. Please
- note that all login modules available with JBoss AS are available
- as well and custom login modules should be easy to add.
+ This section lists the log-in modules provided with JBoss Enterprise
+ Service Bus. Please note that all of the log-in modules available
+ with JBoss Application Server are also available here. Custom log-in
+ modules should also be easy to add.
</para>
<section>
<title>
- CertificateLoginModule
+ Certificate Log-in Module
</title>
<para>
- This login module performs authentication by verifiying that a
- certificate passed with the call to the ESB, can be verified
- against a certificate in a local keystore.
+ This log-in module performs authentication by verifying the
+ certificate that is passed with the call to the Enterprise Service
+ Bus against a certificate held in a local keystore.
</para>
<para>
- Upon successful authentication the certificates Common Name(CN)
- will be used to create a principal. If role mapping is in use then
- it is the CN that will be used in the role mapping. See “Role
- Mapping” for details on the role mapping functionality.
+ Upon successful authentication, the certificate's <firstterm>Common
+ Name</firstterm> (CN) creates a
+ <firstterm>principal</firstterm>. If role-mapping is in use, then it is the Common Name
+ that will be used for this. Please refer to the Section on Role
+ Mapping for details about the role-mapping
+ functionality.
</para>
@@ -753,7 +818,8 @@
<para>
- Example of fragment from login-config.xml
+ Here is a portion of the
+ <filename>login-config.xml</filename> file:
</para>
@@ -827,10 +893,12 @@
</title>
<para>
- This file is can be optionally specified in login-config.xml by
- using the 'rolesPropertiesFile'. This can point to a file on the
- local file system or to a file on the classpath. This file contains
- a mapping of users to roles:
+ This file is optional. It can be specified in
+ <filename>login-config.xml</filename> by using the
+ <property>rolesPropertiesFile</property> property. This property can
+ point to a file located either on the local file system or on the
+ classpath. The file contains a mapping of users to roles, as shown
+ in the following example:
</para>
@@ -838,7 +906,8 @@
<note>
<para>
- For an example please look at the security_cert quickstart.
+ For an example, please look at the <filename>security_cert</filename>
+ Quick Start.
</para>
</note>
@@ -849,40 +918,34 @@
<title>
Password Encryption
</title>
+<para>
+ <application>JBoss Enterprise Service Bus</application> configuration files sometimes require
+ passwords. In the past, these had been stored in clear text in
+ the configuration files themselves. This was obviously a security risk. There is now the option to
+ specify a path to a file that contains an encrypted password that can be
+ read whenever it is required.
+</para>
- <para>
- Configuration files in JBossESB sometimes require passwords which
- up until now have been specified in clear text in the configuration
- files. This is a security risk and something that should be
- avoided. In JBossESB you have the ability to specify a path to a
- file that contains an encrypted password wherever a password is
- required.
- </para>
+<section>
+<title>
+Creating an Encrypted Password File
+</title>
- <section>
- <title>
- Creating an Encrypted Password File
- </title>
+<para>
+Follow these steps to create an encrypted password file:
+</para>
- <para>
- This can be achived by performing the following steps:
- </para>
-
<orderedlist>
- <listitem>
- <para>
- Go to the conf directory of your jboss server instance
- (eg: default/conf)
- </para>
- </listitem>
-
- <listitem>
- <para>
- <command>java -cp ../lib/jbosssx.jar
- org.jboss.security.plugins.FilePassword welcometojboss 13
- testpass esb.password </command>
- </para>
- </listitem>
+<listitem>
+<para>
+Go to the JBoss Server instance's <filename>default/conf</filename> directory.
+</para>
+</listitem>
+<listitem>
+<para>
+<command>java -cp ../lib/jbosssx.jar org.jboss.security.plugins.FilePassword welcometojboss 13 testpass esb.password </command>
+</para>
+</listitem>
</orderedlist>
<table>
@@ -890,50 +953,38 @@
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colwidth="2*"/>
<colspec colwidth="5*"/>
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
+<thead>
- <tbody>
+<row>
+<entry>Option</entry>
+<entry>Description</entry>
+</row>
+</thead>
- <row>
- <entry>
- <property>Salt</property>
- </entry>
- <entry>
- <para>
- The salt used for the encryption. This is the
- “welcometojboss” string in the example above.
- </para>
- </entry>
- </row>
+<tbody>
- <row>
- <entry>
- <property>Iteration</property>
- </entry>
- <entry>
- <para>
- The number of iterations. This is the number 13 in the
- example above.
- </para>
- </entry>
- </row>
+<row>
+<entry>
+<property>Salt</property>
+</entry>
+<entry>
+<para>
+ The "salt" used to encrypt. (In the example above, this is the
+ <code>welcometojboss</code> string .)
+</para>
+</entry>
+</row>
- <row>
- <entry>
- <property>Clear Text Password</property>
- </entry>
- <entry>
- <para>
- The password you wish to encrypt. This is the string
- “testpass” in the example above.
- </para>
- </entry>
- </row>
+<row>
+<entry>
+<property>Iteration</property>
+</entry>
+<entry>
+<para>
+The number of iterations. (In the example above, this is the number <code>13</code>.)
+</para>
+</entry>
+</row>
<row>
<entry>
@@ -956,40 +1007,40 @@
<section>
- <title>
- Configuring Encrypted Password Files
- </title>
-
- <para>
- Configuration is done by simply substituting the clear text
- password in your configuration file(s) with the path to the
- encrypted password file.
- </para>
-
- </section>
+<title>
+ Configuring Encrypted Password Files
+</title>
+<para>
+ To configure encrypted passwords files, simply replace the existing clear-text password
+ with the path to the other file containing the
+ encrypted password.
+</para>
</section>
+</section>
<section>
<title>
- SecurityService
+ Security Service
</title>
- <para>
The Security Service interface is the
- central component in JBossESB security. This
- interface is shown below:
+ <para>
The <interfacename>SecurityService</interfacename> interface is the
+ Enterprise Service Bus central security component. Here it is:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/security/security_service_interface.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
<para>
- The default implementation is based on JAAS, but this can
- be customized by implementing the above interface and
- configuring the custom SecurityService to be used in
- jbossesb-properties.xml. For more details of the
- SecurityService interface methods, please refer to the
- javadocs.
+ The default implementation is based on JAAS
+ but it can be customised if one implements the above
+ interface and configures the
+ <filename>jbossesb-properties.xml</filename> file to use a
+ custom <interfacename>SecurityService</interfacename>. For more
+ information relating to the
+ <classname>SecurityService</classname> interface, please
+ refer to the Java documentation.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/Service_Orchestration.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -14,12 +14,19 @@
</title>
<para>
- Service Orchestration is the arrangement of business processes.
- Traditionally BPEL is used to execute SOAP based WebServices. If
- you want to orchestrate JBossESB regardless of their end point
- type, then it makes more sense to use jBPM. This chapter explains
- how to use the integration discussed earlier to do Service
- Orchestration using jBPM.
+ Read this chapter to gain an understanding of how to use the
+ integration functionality discussed earlier to perform Service
+ Orchestration with the <application>Business Process Manager</application>.
+ </para>
+
+ <para>
+ The term, <firstterm>service orchestration</firstterm>, refers to the
+ arrangement of business processes. Traditionally, the
+ <firstterm>Business Process Execution Language</firstterm> (BPEL)
+ has been used to execute SOAP-based web services. Red Hat recommends
+ using jBPM to orchestrate processes, regardless of their end-point
+ type, within the <application>JBoss Enterprise SOA
+ Platform</application>.
</para>
</section>
@@ -30,9 +37,12 @@
</title>
<para>
- JBossESB provides WS-BPEL support via its Web Service
- components. For details on these components and how to configure
- and use them, see the Message Action Guide.
+ Read the <emphasis>Message Action Guide</emphasis> to gain an
+ understanding of how the <application>JBoss Enterprise Service
+ Bus</application> provides <firstterm>Web
+ Service-BPEL</firstterm> (WS-BPEL) support. This
+ <emphasis>Guide</emphasis> also provides information about how
+ to configure the main components of this.
</para>
@@ -48,27 +58,31 @@
<note>
<para>
- JBoss and JBossESB also have a special support agreement with
- ActiveEndpoints (<ulink url="http://www.active-endpoints.com/"
- />) for their award wining ActiveBPEL WS-BPEL Engine. In
- support of this, JBossESB ships with a Quickstart dedicated to
- demonstrating how JBossESB and ActiveBPEL can collaborate
- effectively to provide a WS-BPEL based orchestration layer on
- top of a set of Services that don't expose Webservice
- Interfaces (the “webservice_bpel” Quickstart). JBossESB
- provides the Webservice Integration and ActiveBPEL provides the
- Process Orchestration. A number of flash based walk-thrus of
- this Quickstart are also available online: <ulink
- url="http://labs.jboss.com/jbossesb/resources/tutorials/bpel-demos/bpel-demos.html"
- />.
+ The JBoss Enterprise Service
+ Bus software includes <!-- the <filename>webservice_bpel</filename>
+ Quick Start, which demonstrates how the <abbrev>ESB</abbrev> and -->
+ <ulink url="http://www.active-endpoints.com/">ActiveBPEL
+ </ulink> which can be used to collaborate effectively to provide a
+ WS-BPEL-based orchestration layer on top of a
+ set of services that do not expose Webservice Interfaces. The
+ JBoss Enterprise Service Bus provides the web service
+ integration and <application>ActiveBPEL</application>
+ provides the <firstterm>Process Orchestration</firstterm>. A
+ number of <application>Flash</application>- based
+ "walk-throughs" of this Quick Start are also
+ available online here: <ulink
+ url="http://labs.jboss.com/jbossesb/resources/tutorials/bpel-demos/bpel-demos.html" />.
</para>
</note>
<note>
<para>
- ActiveEndpoints WS-BPEL engine does not run on versions of
- JBossAS since 4.0.5. However, it can be deployed and run
- successfully on Tomcat as our examples illustrate.
+ The <application>ActiveEndpoints WS-BPEL
+ Engine</application> has been incompatible with the
+ <application>JBoss Application Server</application> since
+ Release 4.0.5. However, it can be deployed and run
+ successfully on <application>Tomcat</application>, as demonstrated in the
+ examples below.
</para>
</note>
@@ -80,12 +94,15 @@
</title>
<para>
- A key component of Service Orchestration is to use a flow-chart
- like design tool to design and deploy processes. The jBPM IDE
- can be used for just this. Figure 6 shows an example of such a
- flow-chart, which represents a simplified order process. This
- example is taken from the bpm_orchestration4 quick start
- [JBESB-QS] which ships with JBossESB.
+ A flow chart-like design tool must be used to plan and deploy
+ Service Orchestration processes. The <application>jBPM
+ Integrated Development Environment</application> (IDE) can be
+ utilised for this purpose. The following shows an example of just such
+ a flow-chart, representing a simplified ordering process. (This
+ example is taken from the
+ <filename>bpm_orchestration4</filename> Quick Start which ships
+ with the <application>JBoss Enterprise Service
+ Bus</application>.)
</para>
<figure id="Orchestration_diagram">
@@ -94,40 +111,49 @@
</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/so/Service_Orchestration_Order_Process_jBPM.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/so/Service_Orchestration_Order_Process_jBPM.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- In the “Order Process” Diagram three of the nodes are JBossESB
- Services, the “Intake Order”, “Calculate Discount” and the
- “Ship It” nodes. For these nodes the regular “Node” type was
- used, which is why these are labeled with
- “<<Node>>”. Each of these nodes have the
- EsbActionHandler attached to the node itself. This means that
- the jBPM node will send a request to the Service and then it
- will remain in a wait state, waiting for the ESB to call back
- into the node with the response of the Service. The response of
- the service can then be used within jBPM context. For example
- when the Service of the “Intake Order” responds, the response
- is then used to populate the “Review Order” form. The “Review
- Order” node is a “Task Node”. Task Nodes are designed for human
- interaction. In this case someone is required to review the
- order before the Order Process can process.
+ The classnames of the <xref linkend="Orchestration_diagram"/>
+ nodes are JBoss ESB Services. They are called <classname>Intake
+ Order</classname>, <classname>Calculate Discount</classname> and
+ <classname>Ship It</classname>. The regular type of
+ <systemitem>Node</systemitem> was used for them, which is why
+ they are labeled with <emphasis><<Node>></emphasis>.
+ Each of these nodes has the
+ <classname>EsbActionHandler</classname> attached to itself. This
+ means that the <application>Business Process
+ Manager</application> node will send a request to the service
+ and then it will remain in a "wait" state, until the Enterprise
+ Service Bus calls back with the response from the service. This
+ response can then be used within a <application>Business Process
+ Manager</application> context.
</para>
<para>
- To create the diagram above, select File > New > Other,
- and from the Selection wizard select “JBoss jBPM “Process
- Definition” as shown in below. The wizard will direct you to
- save the process definition. From an organizational point of
- view it is recommended use one directory per process
- definition, as you will typically end up with multiple files
- per process design.
- </para>
-
-
+ For example, when the <classname>Intake Order</classname>
+ Service responds, that response is used to populate the
+ <classname>Review Order</classname> form. The <classname>Review
+ Order</classname> node is a <firstterm>task node</firstterm>,
+ which means that it was designed for human interaction. (In this
+ case, someone is required to review the order before the Order
+ Process can occur.)
+ </para>
+ <para>
+ To create the diagram in <xref
+ linkend="Orchestration_diagram"/>, select <guimenu>File > New
+ > Other</guimenu> and, from the
+ <systemitem>Selection</systemitem> wizard, choose
+ <guilabel>JBoss jBPM Process Definition</guilabel>. The wizard
+ will direct one to save the process definition. Red Hat
+ recommends that a single directory be used for each process
+ definition, as this makes the most sense from an organisational
+ point of view. This is because one will usually end up with
+ multiple files associated with each process design.
+ </para>
<figure id="process_defintion">
<title>Select the New JBoss jBPM Process Definition
@@ -162,149 +188,194 @@
<para>
- Before building the “Order Process” diagram of Figure 6, we'd
- need to create and test the three Services. These services are
- 'ordinary' ESB services and are defined in the jboss-esb.xml.
- Check the jboss-esb.xml of the bpm_orchestration4 quick start
- [JBESB-QS] if you want details on them, but they only thing of
- importance to the Service Orchestration are the Services names
- and categories as shown in the following jboss-esb.xml
- fragment:
+ Before building the order process diagram depicted in <xref
+ linkend="Orchestration_diagram"/>, create and test the three
+ services. These are ordinary ESB services and they are defined
+ in the <filename>jboss-esb.xml</filename> file. Study the
+ <filename>jboss-esb.xml</filename> file in the
+ <filename>bpm_orchestration4</filename> Quick Start to learn
+ more about them but the only essential things to know in
+ relation to Service Orchestration are the names and categories
+ of the services themselves. These are as shown in the following
+ sample <filename>jboss-esb.xml</filename> file fragment:
</para>
- <programlisting language="XML" role="XML">
+ <programlisting language="XML">
<xi:include href="extras//so/jbossesb-properties_service_orchestration_fragment.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude">
</xi:include>
</programlisting>
<para>
- These Service can be referenced using the EsbActionHandler or
- EsbNotifier Action Handlers as discussed in Chapter 1. The
- EsbActionHandler is used when jBPM expects a response, while
- the EsbNotifier can be used if no response back to jBPM is
- needed.
+ Reference these services by using the
+ <classname>EsbActionHandler</classname> or
+ <classname>EsbNotifier</classname> action handlers. (The
+ <classname>EsbActionHandler</classname> should be used when the
+ <application>Business Process Manager</application> expects a
+ response, whilst the <classname>EsbNotifier</classname> is to be
+ utilised when none is needed.)
</para>
<para>
- Now that the ESB services are known we drag the “Start” state
- node into the design view. A new process instance will start a
- process at this node. Next we drag in a “Node” (or “ESB Service
- “if available). Name this Node “Intake Order”. We can connect
- the Start and the Intake Order Node by selecting “Transition”
- from the menu and by subsequently clicking on the Start and
- Intake Order Node. You should now see an arrow connecting these
- two nodes, pointing to the Intake Order Node.
+ Now that the <abbrev>ESB</abbrev> services are known, drag the
+ <systemitem>Start</systemitem> state node into the design view.
+ A new process instance will begin at this node. Next, drag in a
+ <systemitem>node</systemitem> (or ESB Service, if one is
+ available.) Name this node <systemitem>Intake
+ Order</systemitem>. It is possible to connect the
+ <systemitem>Start</systemitem> and the <systemitem>Intake
+ Order</systemitem> nodes by selecting
+ <guimenuitem>Transition</guimenuitem> from the menu and then
+ clicking on them both. (An arrow connecting them should appear.
+ It will be pointing towards the first <systemitem>Intake
+ Order</systemitem>.)
</para>
<para>
- Next we need to add the Service and Category names to the
- Intake Node. Select the “Source” view. The “Intake Order Node
- should look like
+ Now add the Service and Category names to the Intake Node.
+ Select the <guilabel>Source</guilabel> view. The source code of
+ the <systemitem>Intake Order</systemitem> node should look like
+ this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/intake.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- and we add the EsbHandlerAction class reference and the
- subelement configuration for the Service Category and Name,
- BPM_Orchestration4 and“IntakeService” respectively
+ Next, add the <classname>EsbHandlerAction</classname> class
+ reference, then the sub-element configurations for the Service
+ Category and Name, the
+ <systemitem>BPM_Orchestration4</systemitem> and the
+ <systemitem>IntakeService</systemitem>, as per this example
+ code:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/intakeorder.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Next we want to send the some jBPM context variables along with
- the Service call. In this example we have a variable named
- “entireOrderAsXML” which we want to set in the default position
- on the EsbMessage body. For this to happen we add
+ Having done that, send some <application>Business Process
+ Manager</application> context variables along with the service
+ call. In this example, there is a variable named
+ <property>entireOrderAsXML</property>, which is to be set in the
+ default position on the body of the Enterprise Service Bus
+ message. To do this, simply add the following code:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/setvariable.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- which will cause the XML content of the variable
- “entireOrderAsXML” to end up in the body of the EsbMessage, so
- the IntakeService will have access to it, and the Service can
- work on it, by letting it flow through each action in the
- Action Pipeline. When the last action is reached it the replyTo
- is checked and the EsbMessage is send to the JBpmCallBack
- Service, which will make a call back into jBPM signaling the
- “Intake Order” node to transition to the next node (“Review
- Order”). This time we will want to send some variables from the
- EsbMessage to jBPM. Note that you can send entire objects as
- long both contexts can load the object's class. For the mapping
- back to jBPM we add an “esbToEsbVars” element. Putting it all
- together we end up with:
+ This will cause the XML-based contents of the
+ <property>entireOrderAsXML</property> variable to end up in the
+ body of the Enterprise Service Bus message. This, in turn, means
+ that the <classname>IntakeService</classname> can now access the
+ message and can process it, by letting it flow through each
+ action in the <systemitem>Pipeline</systemitem>. When the last
+ action is reached, the <property>replyTo</property> property is
+ checked and the Enterprise Service Bus message is sent to the
+ <classname>JBpmCallBack</classname> service. The latter makes a
+ call back into the <application>Business Process
+ Manager</application>, signaling the transition from the
+ <systemitem>Intake Order</systemitem> node to the next one
+ (<systemitem>Review Order</systemitem>.) This time, one will
+ want to send some variables from the Enterprise Service Bus
+ message to the <application>Business Process
+ Manager</application>. Note that entire objects can be sent, as
+ long both contexts can load the object's class. In order to
+ retain the ability to "map back" to the <application>Business
+ Process Manager</application>, add an
+ <property>esbToEsbVars</property> element.
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/combined.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- So after this Service returns we have the following variables
- in the jBPM context for this process: entireOrderAsXML,
- entireOrderAsObject, entireCustomerAsObject, and for demo
- purposes we also added some flattened variables: order_orderid,
- order_totalAmount, order_priority, customer_firstName,
- customer_lastName and customer_status.
+ When this service returns, the following variables will be
+ stored in the <application>Business Process
+ Manager</application> context:
</para>
+ <itemizedlist>
+ <listitem><para><systemitem>entireOrderAsXML</systemitem>,</para></listitem>
+ <listitem><para> <systemitem>entireOrderAsObject</systemitem> and</para></listitem>
+ <listitem><para> <systemitem>entireCustomerAsObject</systemitem>. </para></listitem>
+ </itemizedlist>
+
+ <para>
+ In addition, for demonstration purposes, there are also some
+ flattened variables:
+ </para>
+
+ <itemizedlist>
+ <listitem><para> <systemitem>order_orderid</systemitem>,</para></listitem>
+ <listitem><para> <systemitem>order_totalAmount</systemitem>,</para></listitem>
+ <listitem><para> <systemitem>order_priority</systemitem>,</para></listitem>
+ <listitem><para> <systemitem>customer_firstName</systemitem>,</para></listitem>
+ <listitem><para> <systemitem>customer_lastName</systemitem> and</para></listitem>
+ <listitem><para> <systemitem>customer_status</systemitem>.</para></listitem>
+
+ </itemizedlist>
+
<figure id="The_Order_process">
<title>The Order Process Has Reached the “Review Order” Node</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/so/order.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/so/order.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- In our Order process we require a human to review the order. We
- therefore add a “Task Node” and add the task “Order Review”,
- which needs to be performed by someone with actor_id “user”.
- The XML-fragment looks like
+ A human will be required to review the order process. Therefore,
+ add a <systemitem>Task Node</systemitem> and the task
+ <systemitem>Order Review</systemitem>. These need to be
+ performed by someone with the <property>actor_id</property>
+ <code>user</code>. The XML fragment should look like this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/orderprocess.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- In order to display these variables in a form in the
- jbpm-console we need to create an xhtml dataform (see the
- Review_Order.xhtml file in the bpm_orchestration4 quick start
- [JBESB-QS] and tie this for this TaskNode using the forms.xml
- file:
+ Create an XHTML data-form. Do this so that these variables can
+ display in a form in the <guilabel>jbpm-console</guilabel> (see
+ the <filename>Review_Order.xhtml</filename> file in the
+ <emphasis>bpm_orchestration4</emphasis> Quick Start [JBESB-QS]
+ for more information about this.) "Tie" this data-form to the
+ <property>TaskNode</property> via the
+ <filename>forms.xml</filename> file:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/createxhtml.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Note that in this case the same form is used in two task nodes.
- The variables are referenced in the Review Order form like
+ Note that, in this case, the same form is applied to two task
+ nodes. The variables are referenced in the <guilabel>Review
+ Order</guilabel> form as shown in the following sample code.
+ (This, in turn, references the variables that are set in the
+ <application>Business Process Manager</application> context.)
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/revieworderform.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- which references the variables set in the jBPM context.
- </para>
-
- <para>
- When the process reaches the “Review Node”, as shown in Figure
- 9. When the 'user' user logs into the jbpm-console the user can
- click on 'Tasks” to see a list of tasks, as shown in below.
- The user can 'examine' the task by clicking on it and the user
- will be presented with a form as shown below. The user
- can update some of the values and click “Save and Close” to let
- the process move to the next Node.
+ When the process reaches the <systemitem>Review
+ Node</systemitem>, (depicted in <xref
+ linkend="The_Order_process" />), the user can log into the
+ <guilabel>jbpm-console</guilabel> and click on "Tasks” to see a
+ list of items, (as shown in <xref linkend="task_list_for_user"
+ />.) He or she can examine the task by clicking on it. A form
+ will appear, (as seen in <xref
+ linkend="The_Order_Review_form"/>.) He or she can then update
+ some of the values and conclude by clicking <guibutton>Save and
+ Close</guibutton>, at which point the process will move on to
+ the next node.
</para>
<figure id="task_list_for_user">
<title>The Task List for User "User"</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/so/task_list_for_user.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/so/task_list_for_user.png" />
</imageobject>
</mediaobject>
</figure>
@@ -313,24 +384,29 @@
<title>The "Order Review" form</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/so/orderreview.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/so/orderreview.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- The next node is the “Calculate Discount” node. This is an ESB
- Service node again and the configuration looks like
+ The next one is the <systemitem>Calculate Discount</systemitem>
+ node. This is, once again, an ESB service node, the
+ configuration file for which looks like this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/calculatediscount.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The Service receives the customer and orderHeader objects as
- well as the entireOrderAsXML, and computes a discount. The
- response maps the body.order_orderDiscount value onto a jBPM
- context variable called “order_-discount”, and the process is
- signaled to move to the “Review Discount” task node.
+ The service receives both the <classname>customer</classname>
+ and the <classname>orderHeader</classname> objects, as well as
+ the <classname>entireOrderAsXML</classname> data. It then
+ computes a discount. The response maps the
+ <classname>body.order_orderDiscount</classname> value onto a
+ <application>Business Process Manager</application> context
+ variable called <property>order_-discount</property>. The
+ process is then signaled, which tells it to move to the
+ <systemitem>Review Discount</systemitem> node:
</para>
<figure id="The_Discount_Review_form">
@@ -343,22 +419,27 @@
</figure>
<para>
- The user is asked to review the discount, which is set to 8.5.
- On “Save and Close” the process moves to the “Ship It” node,
- which again is an ESB Service. If you don't want the Order
- process to wait for the Ship It Service to be finished you can
- use the EsbNotifier action handler and attach it to the
- outgoing transition:
+ Here, the user is asked to review the discount, which is set to
+ a value of 8.5 (see <xref linkend="The_Discount_Review_form"
+ />.) When he or she clicks <guibutton>Save and
+ Close</guibutton>, the process moves to the <systemitem>Ship
+ It</systemitem> node, which is, once again, an ESB service. To
+ circumvent the Order process before the <systemitem>Ship
+ It</systemitem> service completes, use the
+ <classname>EsbNotifier</classname> action handler by attaching
+ it to the outgoing transition:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/shipit.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- After notifying the ShippingService the Order process moves to
- the 'end' state and terminates. The ShippingService itself may
- still be finishing up. In bpm_orchestration4 [JBESB-QS] it uses
- drools to determine whether this order should be shipped
- 'normal' or 'express'.
+ After notifying the <classname>ShippingService</classname>, the
+ order process moves to the "end" state and terminates. (The
+ <classname>ShippingService</classname> itself may still be
+ finishing.) <application>JBoss Rules</application> is used in
+ the <filename>bpm_orchestration4</filename> file to determine
+ whether this order should be shipped via the "normal" or
+ "express" method.
</para>
</section>
@@ -366,64 +447,98 @@
<section>
<title>
- Process Deployment and Instantiation
+ Process Deployment and "Instantiation"
</title>
<para>
- In the previous paragraph we create the process definition and
- we quietly assumed we had an instance of it to explain the
- process flow. But now that we have created the
- processdefinition.xml, we can deploy it to jBPM using the IDE,
- ant or the jbpm-console (as explained in Chapter 1). In this
- example we use the IDE and deployed the files:
- Review_Order.xhtml, forms.xml, gpd.xml, processdefinition.xml
- and the processimage.jpg. On deployment the IDE creates a par
- achive and deploys this to the jBPM database. We do not
- recommend deploying Java code in par archives as it may cause
- class loading issues. Instead we recommend deploying classes in
- jar or esb archives.
+ In the previous section, an assumption was made that an instance
+ of the process definition was running. This was in order to
+ explain the process flow. However, now that the
+ <filename>processdefinition.xml</filename> file has been
+ created, it can be deployed to the <application>Business Process
+ Manager</application>, by using any one of the following: the
+ integrated development environment, <application>ant</application> or the
+ <guilabel>jbpm-console</guilabel>. (The integrated development
+ environment will be used in the following example.)
</para>
+
+
+ <para>
+ The following files will be deployed:
+ </para>
+
<figure id="Deployment">
<title>Deployment of the Order Process</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/so/instantiation.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/so/instantiation.png" />
</imageobject>
</mediaobject>
- </figure>
-
+ </figure>
+
+ <itemizedlist>
+ <listitem><para><filename>Review_Order.xhtml</filename>,</para></listitem>
+ <listitem><para><filename>forms.xml</filename>, </para></listitem>
+ <listitem><para><filename>gpd.xml</filename>,</para></listitem>
+ <listitem><para><filename>processdefinition.xml</filename> and</para></listitem>
+ <listitem><para><filename>processimage.jpg</filename>. </para></listitem>
+ </itemizedlist>
+
<para>
- When the process definition is deployed a new process
- instance can be created. It is interesting to note that we
- can use the 'StartProcessInstanceCommand” which allows us
- to create a process instance with some initial values
- already set. Take a look at
+ The integrated development environment creates a
+ <filename>PAR</filename> archive and deploys it to the
+ <application>Business Process Manager</application>'s
+ database.
+ </para>
+
+ <warning>
+ <para>
+ Red Hat recommends against deploying Java code in
+ <filename>PAR</filename> archives as it may cause
+ class-loading issues. Instead, use either
+ <filename>JAR</filename> or <filename>ESB</filename>
+ archives to deploy classes.
+ </para>
+ </warning>
+
+ <para>
+ Create a new process instance once the process definition is
+ deployed. (Note that
+ <command>StartProcessInstanceCommand</command> can be used. The
+ allows one to create a process instance with some pre-set
+ initial values.) Study this code sample:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/procdef.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- where new process instance is invoked and using some groovy
- script, and the jBPM key is set to the value of 'OrderId' from
- an incoming order XML, and the same XML is subsequently put in
- jBPM context using the esbToBpmVars mapping. In the
- bpm_orchestration4 quickstart [JBESB-QS] the XML came from the
- Seam DVD Store and the “SampleOrder.xml” looks like
+ The new process instance is now invoked and using a script. The
+ jBPM key is set to the value of
+ <property>OrderId</property> from an incoming order
+ XML file. This same XML is
+ subsequently put into a <application>Business Process
+ Manager</application> context, through use of the
+ the <classname>esbToBpmVars</classname> mapping. In the
+ <filename>bpm_orchestration4</filename> Quick Start, the
+ XML came from the <literal>Seam DVD
+ Store</literal> and the <filename>SampleOrder.xml</filename>
+ looks like this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/so/sampleorder.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
- <note>
+
+<note>
<para>
- Both ESB as well as jBPM deployments are hot. An extra feature
- of jBPM is that process deployments are versioned. Newly
- created process instances will use the latest version while
- existing process instances will finish using the process
- deployment on which they where started.
+ Both the Enterprise Service Bus and the Business
+ Process Manager deployments are "hot." The jBPM has a special
+ feature that results in process deployments being "versioned":
+ newly created process instances will use the latest version,
+ whilst existing ones will finish using the process deployment on
+ which they were started.
</para>
- </note>
+</note>
</section>
@@ -433,11 +548,15 @@
</title>
<para>
- We have demonstrated how jBPM can be used to orchestrate
- Services as well as do Human Task Management. Note that you are
- free to use any jBPM feature. For instance look at the quick
- start bpm_orchestration2 [JBESB-QS] how to use the jBPM fork
- and join concepts.
+ From studying the examples in this chapter, you have learned how
+ the <application>Business Process Manager</application> can be
+ used to orchestrate services and, in addition, perform "Human
+ Task Management." Note that you are free to use any jBPM
+ feature. For instance, look at the Quick Start entitled
+ <filename>bpm_orchestration2</filename>, in order to learn how
+ to use the Business Process Manager's
+ <systemitem>fork</systemitem> and <systemitem>join</systemitem>
+ functionality.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/The_Message_Store.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -15,32 +15,33 @@
</title>
<para>
- The message store mechanism in JBossESB is designed with audit
- tracking purposes in mind. As with other ESB services, it is a
- pluggable service, which allows for you, the developer to plug in
- your own persistence mechanism should you have special needs. The
- implementation supplied with JBossESB is a database persistence
- mechanism. If you require say, a file persistence mechanism, then
- it’s just a matter of you writing your own service to do this, and
- override the default behaviour with a configuration change.
+ The Enterprise Service Bus' <firstterm>MessageStore</firstterm>
+ mechanism has been designed for the purpose of audit-tracking. As
+ with other ESB services, it is <firstterm>pluggable</firstterm>,
+ which means that the developer can plug in his or her own
+ persistence mechanism should there be the need to do so. (A database
+ persistence mechanism is supplied.) For instance, to create a file
+ persistence mechanism, simply code a service to create it, then
+ over-ride the default behavior with a configuration change.
</para>
<note>
<para>
- One thing to point out with the Message Store – this is a base
- implementation. We will be working with the community and partners
- to drive the feature functionality set of the message store to
- support advanced audit and management requirements. This is meant
- to be a starting point.
+ Note that this <classname>MessageStore</classname> is a base
+ implementation only. Red Hat will be working with the community and
+ partners to improve the functionality of this software to the point
+ where, at a future point in time, it will support advanced auditing
+ and management requirements. At present, this program is solely intended
+ as a starting point.
</para>
</note>
<important>
<para>
- In JBossESB 4.2 the Message Store is also used for storing
- messages that need to be redelivered in the event of failures.
- See the Programmers Guide around the ServiceInvoker for further
- details.
+ The <classname>MessageStore</classname> is
+ also used for holding messages that need to be re-delivered in
+ the event of a failure. Additional information on this topic si
+ found in the <emphasis>Programmers' Guide</emphasis>.
</para>
</important>
@@ -52,8 +53,13 @@
</title>
<para>
- The org.jboss.soa.esb.services.persistence.MessageStore
- interface is defined as follows:
+ The <classname>MessageStore</classname> is responsible for
+ reading and writing messages upon request. Each message must be
+ uniquely identified within the context of the store. (Each
+ <classname>MessageStore</classname> implementation uses a
+ uniform resource identifier to accomplish this. The
+ URI acts as the “key” for messages in the
+ database.)
</para>
@@ -70,53 +76,57 @@
<important>
<para>
- MessageStore implementations may use different formats for
- their URIs.
+ Each <classname>MessageStore</classname> implementation uses
+ a different format for uniform resource identifiers.
</para>
</important>
<para>
- Messages can be stored within the store based upon
- classification using addMessage. If the classification is not
- defined then it is up to the implementation of the MessageStore
- how it will store the Message. Furthermore, the classification
- is only a hint: implementations are free to ignore this field
- if necessary.
+ Messages can be stored using a classification derived from
+ <classname>addMessage</classname>. If the classification is not
+ defined, then it is up to the individual implementation of the
+ <classname>MessageStore</classname> to determine for itself
+ how it will store the message. Furthermore, the classification
+ is only a guide: one's implementation can ignore this field if
+ necessary.
</para>
<note>
<para>
- It is implementation dependent as to whether or not the
- MessageStore imposes any kind of concurrency control on
- individual Messages. As such, you should use the removeMessage
- operation with care.
+ It is dependent on the implementation as to whether or not the
+ <classname>MessageStore</classname> imposes any kind of
+ concurrency control on individual messages. Therefore, use the
+ <classname>removeMessage</classname> operation with care.
</para>
</note>
<warning>
<para>
- Because the current MessageStore interface is designed to
- support both audit trail and redelivery scenarios, you should
- not use the setUndelivered/setDelivered and associated
- operations unless they are applicable!
+ Do not use the <command>setUndelivered/setDelivered</command>
+ commands or other associated operations unless they are
+ applicable. This is because the current
+ <classname>MessageStore</classname> interface is designed to
+ support both audit trail and re-delivery functionality.
</para>
</warning>
<para>
- The default implementation of the MessageStore is provided by
- the
- org.jboss.internal.soa.esb.persistence.format.db.DBMessageStoreImpl
- class. The methods in this implementation make the required DB
- connections (using a pooled Database Manager
- DBConnectionManager).
+ The
+ <classname>org.jboss.internal.soa.esb.persistence.format.db.DBMessageStoreImpl</classname>
+ class provides the default implementation of the
+ <classname>MessageStore</classname>. . The methods in this
+ implementation make the required database connections via a
+ pooled database manager, called
+ <classname>DBConnectionManager</classname>.
</para>
<para>
- To override the MessageStore implementation you should look at
- the MessageActionGuide and the MessagePersister Action.
+ Use the <classname>MessageActionGuide</classname> and the
+ <classname>MessagePersister</classname> actions to override the
+ <classname>MessageStore</classname> implementation.
</para>
- <note>
+ <note>
<para>
The <classname>MessageStore</classname> interface does not
currently support transactions. Any use of the
@@ -156,29 +166,32 @@
</title>
<para>
- To configure your Message Store, you can change and override
- the default service implementation through the following
- settings found in the jbossesb-properties.xml:
+ To configure the <classname>MessageStore</classname>, firstly
+ over-ride the default service implementation. Do this by editing
+ the settings found in the
+ <filename>jbossesb-properties.xml</filename> file:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/ms/jbossesb-properties.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The section in the property file called “dbstore” has all the
- settings required by the database implementation of the message
- store. The standard settings, like URL, db user, password, pool
- sizes can all be modified here.
+ In this file, there is a section entitled
+ “<property>dbstore</property>.” It is here that all of the
+ settings required by the <classname>Message Store</classname>'s
+ database implementation are located. Modify the standard
+ settings, like URL, db user, password, pool size and so forth
+ here.
</para>
<para>
- The scripts for the required database schema, are again, very
- simple. They can be found under
- lib/jbossesb.esb/message-store-sql/<db_type>/create_database.sql
- of your JBossESB installation.
+ The scripts for the "required database" schema are found in the
+ <filename>lib/jbossesb.esb/message-store-sql/<db_type>/create_database.sql</filename>
+ file in the <application>JBoss Enterprise Service
+ Bus</application> installation.
</para>
<para>
- The structure of the table can be seen from the sample SQL:
+ The SQL code in the following sample shows the structure of this file:
</para>
@@ -186,44 +199,50 @@
<para>
- The uuid column is used to store a unique key for this message,
- in the format of a standard URI. A key for a message would look
- like:
+ The <systemitem>UUID</systemitem> column is used to store a
+ unique key for the message. It takes the form of a standard
+ uniform resource identifier. Message keys look like this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/ms/key.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- This logic uses the new UUID random number generator in jdk
- 1.5. the type will be the type of the stored message. JBossESB
- ships with JBOSS_XML and JAVA_SERIALIZED currently.
+ This logic exploits the UUID's random number generator. The
+ <systemitem>type</systemitem> will be equal to that of the
+ stored message. The <application>JBoss Enterprise Service
+ Bus</application> currently ships with two different
+ <systemitem>type</systemitem>, these being
+ <systemitem>JBOSS_XML</systemitem> and
+ <systemitem>JAVA_SERIALIZED</systemitem>, respectively.
</para>
<para>
- The “message” column will contain the actual message content.
+ The <systemitem>message</systemitem> column contains the
+ contents of the actual message itself.
</para>
<para>
- The supplied database message store implementation works by
- invoking a connection manager to your configured database.
- Supplied with JBoss ESB is a standalone connection manager, and
- another for using a JNDI datasource.
+ The database message store implementation supplied with the Enterprise Service Bus works by invoking a
+ connection to one's already-configured database. Both a
+ stand-alone connection manager, and another for using a <abbrev>JNDI</abbrev>
+ data-source, are also supplied with the <abbrev>ESB</abbrev>.
</para>
<para>
- To configure the database connection manager, you need to
- provide the connection manager implementation in the
- jbossesb-properties.xml. The properties that you would need to
- change are:
+ To configure the database connection manager, add its
+ implementation details to the
+ <filename>jbossesb-properties.xml</filename> file. The
+ properties to change are as follows:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/ms/jbossesb-properties_dbconnection.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The two supplied connection managers for managing the database pool are
+ The two pre-supplied connection managers for the database pool
+ are:
</para>
-<itemizedlist>
+ <itemizedlist>
<listitem>
<para>
org.jboss.soa.esb.persistence.manager.J2eeConnectionManager
@@ -238,12 +257,14 @@
<para>
- The Standalone manager uses C3PO to manage the connection
- pooling logic, and the J2eeConnectionManager uses a datasource
- to manage it's connection pool. This is intended for use when
- deploying your ESB endpoints inside a container such as JBoss
- AS or Tomcat, etc. You can plug in your own connection pool
- manager by implementing the interface:
+ The <firstterm>Stand-Alone Manager</firstterm> uses
+ <firstterm>C3PO</firstterm> to manage the connection pooling
+ logic whilst the <firstterm>J2eeConnectionManager</firstterm>,
+ by contrast, employs a data-source. Use this when deploying
+ Enterprise Service Bus end points inside a container such as the
+ <application>JBoss Application Server</application> or
+ <application>Tomcat</application>. To plug ina custom connection manager,
+ use this interface:
</para>
@@ -256,9 +277,13 @@
</itemizedlist>
<para>
- Once you have implemented this interface, you update the
- properties file with your new class, and the connection manager
- factory will now use your implementation.
+ Another option is to "plug in" a custom connection pool manager.
+ Firstly, implement this interface:
+ <classname>org.jboss.internal.soa.esb.persistence.manager.ConnectionManager</classname>.
+ Next, update the <filename>Properties</filename> file with the
+ name of the new class. Having done so, the <firstterm>Connection
+ Manager Factory</firstterm> will now be able to utilize the new
+ implementation.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_Content-Based_Routing.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -13,52 +13,70 @@
Introduction
</title>
+ <section>
+ <title>
+ Some Questions
+ </title>
<para>
- Typically, information within the ESB is conveniently packaged,
- transferred, and stored in the form of a message. Messages are
- addressed to Endpoint References (services or clients), that
- identify the machine/process/object that will ultimately deal
- with the content of the message. However, what happens if the
- specified address is no longer valid? For example, the service
- has failed or been removed from service? It is also possible
- that the service no longer deals with messages of that
- particular type; in which case, presumably some other service
- still handles the original function, but how should the message
- be handled? What if other services besides the intended
- recipient are interested in the message's content? What if no
- destination is specified?
+ In normal situations, information within the Enterprise Service
+ Bus is conveniently packaged, transferred and stored all in the
+ form of a <emphasis>message</emphasis>. Messages are addressed
+ to <firstterm>End Point References</firstterm> (which are either
+ services or clients.) An <abbrev>EPR</abbrev>'s role is to
+ identify the machine or process or object that will ultimately
+ deal with the content of the message. However, what happen will
+ if the specified address is no longer valid? Situations that may
+ lead to this scenario include those in which the service has
+ failed or been removed. It is also possible that the service no
+ longer deals with messages of that particular type, in which
+ case presumably some other service will still deal with the
+ original function, but that still leaves the question of "How
+ should the message be handled?" What if other services besides
+ that which is the intended recipient are interested in the
+ message's contents? What if no destination is specified?
</para>
+ </section>
+
+ <section>
+ <title>
+ Introducing Content-Based Routing
+ </title>
+
+ <para>
+ One possible answer to all of these problems is
+ <firstterm>Content-Based Routing</firstterm>
+ (<abbrev>CBR</abbrev>). Content-Based Routing seeks to route
+ messages, not by a specified destination, but by the actual
+ content of the message itself. In a typical application, a
+ message is routed by being opened and then having a set of rules
+ applied to its content. These rules are used to ascertain which
+ parties are interested in it.
+ </para>
- <para>
- One possible solution to these problems is Content-Based
- Routing. Content-based routing seeks to route messages, not by
- a specified destination, but by the actual content of the
- message itself. In a typical application, a message is routed
- by opening it up and applying a set of rules to its content to
- determine the parties interested in its content.
- </para>
+ <para>
+ The Enterprise Service Bus can determine the destination of a
+ given message based upon its content. This relieves the sending
+ application of the onus of needing to know where the message
+ should go.
+ </para>
- <para>
- The ESB can determine the destination of a given message based
- on the content of that message, freeing the sending application
- from having to know anything about where a message is going to
- end up.
- </para>
+ <para>
+ Content-based routing and filtering networks are both extremely
+ flexible and very powerful. When built upon established
+ technologies such as <abbrev>MOM</abbrev> (<firstterm>Message
+ Oriented Middleware</firstterm>), <abbrev>JMS</abbrev>
+ (<firstterm>Java Message Services</firstterm>), and
+ <abbrev>XML</abbrev> (Extensible Markup Language), they are also
+ reasonably easy to implement.
+ </para>
- <para>
- Content-based routing and filtering networks are extremely
- flexible and very powerful. When built upon established
- technologies such as MOM (Message Oriented Middleware), JMS
- (Java Message Services), and XML (Extensible Markup Language)
- they are also reasonably easy to implement.
- </para>
-
</section>
+ </section>
<section>
<title>
- Simple example
+ Simple Example
</title>
<para>
@@ -74,27 +92,30 @@
</para>
<para>
- Routers, as their name suggests, route messages. They examine
- the content of the messages they receive, apply rules to that
- content, and forward the messages as the rules dictate.
+ <firstterm>Routers</firstterm>, as their name suggests, "route"
+ messages. They examine the content of messages as they receive
+ them, apply rules to that content and then forward the messages
+ as the rules dictate.
</para>
<para>
In addition to routers and services, some systems may also
- include harvesters, which specialize in finding interesting
- information, packaging it up as a formatted message before
- sending it to a router. Harvesters mine many sources of
- information including mail transfer agent message stores, news
+ include <firstterm>harvesters</firstterm>. These tools
+ specialise in finding interesting information, packaging it up
+ in the guise of a formatted message and then sending it to a
+ router. Harvesters "mine" many sources of information, including
+ <firstterm>mail transfer agent</firstterm> message stores, news
servers, databases and other legacy systems.
</para>
<para>
- The diagram below illustrates a typical CBR architecture using
- an ESB. At the heart of the system, represented by the cloud,
- is the ESB. Messages are sent from the client into the ESB,
- which directs them to the Router. This is then responsible for
- sending the messages to their ultimate destination (or
- destinations, as shown in this example).
+ The diagram below depicts a typical Content-Based Routing
+ architecture that is using an Enterprise Service Bus. At the
+ heart of the system, represented by the cloud, is the
+ <abbrev>ESB</abbrev>. Messages are sent into it from the client,
+ and it then directs them onwards to the router. The router is
+ then responsible for sending the messages to their ultimate
+ destination(s).
</para>
<mediaobject>
@@ -105,5 +126,7 @@
</section>
+
+
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -10,43 +10,87 @@
What is a Rule Service?
</title>
-<section>
+
+ <para>
+ Study this section to learn about <firstterm>rule services</firstterm> and ways in which to
+ utilize them. An understanding of the <application>JBoss Business
+ Rules Management System</application> (BRMS) will aid the reader in
+ understanding these types of services.
+ </para>
+
+ <section>
<title>
Introduction
</title>
-
- <para>
- The JBossESB Rule Service allows you to deploy rules created in
- Drools as services on the ESB. This is beneficial, because it
- means you don't have to develop as much client code to integrate
- rules into your application environment, and rules can be accessed
- as part of an action chain or orchestrated business process. To
- understand these types of services, you should first learn about
- Drools.
- </para>
-
+
+
<para>
- Rule Services are supported by the BusinessRulesProcessor
- action class and the DroolsRuleService, which implement the
- RuleService interface. While it is possible to use rule engines
- other than Drools, only Drools is supported out the
- the box. The BusinessRulesProcessor supports rules loaded from
- the classpath that are defined in .drl files, .dsl files
- (domain specific language support), and .xls (decision table
- support) files. These are primarily for testing, prototypes,
- and very simple rule services. There is no way to specify
- multiple rule files in the jboss-esb.xml file, so complex rule
- services need to use the Drools KnowledgeAgent.
+ As its name implies, the <application>JBoss Enterprise SOA
+ Platform</application>'s rule service
+ allows one to deploy <firstterm>rules</firstterm> that have been created in
+ <application>JBoss Rules</application> as
+ <firstterm>services</firstterm> on the ESB. This has two major benefits:
</para>
-
+
+
+ <orderedlist>
+ <listitem>
+ <para>
+ The amount of client code required to integrate the
+ rules into one's application environment is dramatically
+ reduced.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rules can be accessed either as part of an
+ <firstterm>action chain</firstterm> or from within an
+ <firstterm>orchestrated business process</firstterm>.
+ </para>
+</listitem>
+</orderedlist>
+ <note>
+ <para>
+ The <application>JBoss Business Rules Management
+ System</application> is supported but one can also use a
+ <systemitem>rule engine</systemitem> if need be.
+ </para>
+ </note>
+
+ <para>
+ Rule Services are supported by the
+ <classname>BusinessRuleProcessor</classname> and the
+ <classname>DroolsRuleService</classname> action classes, the
+ latter of which implements the
+ <interfacename>RuleService</interfacename> interface.
+ </para>
+
<para>
- The RuleService uses the KnowledgeAgent to access rule packages from
- the Drools BRMS or local file system. These rule packages can
- contain thousands of rules, the source of which can be:
- </para>
+ The <classname>BusinessRuleProcessor</classname> supports rules
+ loaded from the class-path. These rules are defined in
+ <filename>.drl</filename> and <filename>.dsl</filename> files,
+ and also in decision tables (which use
+ <filename>.xls</filename> files.) However, there is no way to
+ specify multiple rule files for a single
+ <classname>BusinessRuleProcessor</classname> action. (One can,
+ in general, have multiple rule files, though.) These file-based
+ rules exist primarily for the purpose of testing prototypes and
+ very simple rule services. More complex rule services need to
+ use the <application>JBoss Rules</application>
+ <systemitem>RuleAgent</systemitem>, because there is no way to
+ specify multiple rule files in
+ <filename>jboss-esb.xml</filename>.
+ </para>
+
+ <para>
+ The <systemitem>RuleService</systemitem> uses the
+ <systemitem>RuleAgent</systemitem> to access rule packages from
+ either the <application>Business Rules Management
+ System</application> or the local file system. These rule
+ packages can contain thousands of rules, originating in
+ different ways. These files can originate from the following sources:
+ </para>
-
-
<orderedlist>
<listitem>
<para>
@@ -55,26 +99,27 @@
</listitem>
<listitem>
<para>
- Imported DRL files.
+ imported <filename>DRL</filename> files
</para>
</listitem>
<listitem>
<para>
- Rules written in a Domain Specific Language.
- </para>
+ domain-specific language files
+ </para>
</listitem>
<listitem>
<para>
- Rules from Decision Tables.
- </para>
+ decision tables
+ </para>
</listitem>
</orderedlist>
<important>
<para>
- Use of the Drools KnowledgeAgent is the recommended approach for
- production systems.
+ the JBoss developers recommend using the <application>JBoss
+ Rules</application> <systemitem>RuleAgent</systemitem> approach
+ on production systems.
</para>
</important>
@@ -110,7 +155,33 @@
means every 60 seconds, check for resource changes - across ALL
KnowledgeAgents.
</para>
- </note>
+</note>
+
+ <para>
+ Most rule services will be "stateless." In the stateless
+ model, a message is sent to the <systemitem>rule
+ service</systemitem>. Every fact to be inserted into the
+ <systemitem>rule engine</systemitem> is included in the
+ body of the message. The rules execute and update either
+ the message or the facts.
+ </para>
+
+ <para>
+ "Stateful" execution takes place over time. In this scenario, several
+ messages are sent to the <systemitem>rule
+ service</systemitem>. Each time the rules are executed,
+ either the message or the facts are updated. This continues until
+ the service receives a final message that tells it to dispose
+ of the stateful session.
+ </para>
+ <note>
+ <para>
+ This configuration model is currently limited, in the sense
+ that there can only be a single stateful <systemitem>rule
+ service</systemitem> in the message flow.
+ </para>
+ </note>
+
</section>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_the_Registry.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_the_Registry.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/What_is_the_Registry.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -17,59 +17,76 @@
</title>
<para>
- In the context of SOA, a registry provides applications and
- businesses a central point to store information about their
- services. It is expected to provide the same level of
- information and the same breadth of services to its clients as
- that of a conventional market place. Ideally a registry should
- also facilitate the automated discovery and execution of
- e-commerce transactions and enabling a dynamic environment for
- business transactions. Therefore, a registry is more than an
- “e-business directory”. It is an inherent component of the SOA
- infrastructure.
+ Read this section to learn both some general theory about SOA
+ Platform registries and also some specific information about
+ JBoss' implementation.
</para>
+
+ <para>
+ In the context of a Service Oriented Architecture, a registry
+ provides applications and businesses with a central point within
+ which information about services can be stored. A registry is
+ expected to provide both the same level of information and the
+ same breadth of services as a conventional "marketplace."
+ Ideally, a registry should also facilitate the automatic
+ discovery and execution of electronic commerce to take place by
+ providing a dynamic environment for business transactions.
+ Therefore, a registry is more than a mere “e. business
+ directory”. It is a fundamental component of a Service Oriented
+ Architecture's infrastructure.
+ </para>
</section>
<section>
<title>
- Why do I need it?
+ Why Does One Need It?
</title>
<para>
- It is not difficult to discover, manage and interface with
- business partners on a small scale, using manual or ad hoc
- techniques. However, this approach does not scale as the
- number of services, the frequency of interactions, the
- physical distributed nature of the environment, increases.
- A registry solution based on agreed upon standards provides
- a common way to publish and discover services. It offers a
- central place where you query whether a partner has a
- service that is compatible with in-house technologies or to
- find a list of companies that support shipping services on
- the other side of the globe.
+ It is easy to discover and manage business partners and
+ interface with them on a small scale using either manual or
+ ad hoc techniques. However, this approach does not scale
+ well when the number of services and frequency of
+ interactions increase and the physical distribution of the
+ environment expands. A registry provides a solution based
+ upon agreed standards by providing a common, ubiquitous way
+ to discover and "publish" services. It offers a central
+ place in which one can query whether or not a partner has a
+ service that is compatible with in-house technologies. It
+ also allows one to find a list of companies that, for
+ instance, support shipping services on the other side of the
+ globe.
</para>
- <para>
- Service registries are central to most service oriented
- architectures and at runtime act as a contact point to
- correlate service requests to concrete behaviors. A service
- registry has meta-data entries for all artifacts within the
- SOA that are used at both runtime and design time. Items
- inside a service registry may include service description
- artifacts (e.g., WSDL), Service Policy descriptions,
- various XML schema used by services, artifacts representing
- different versions of services, governance and security
- artifacts (e.g., certificates, audit trails), etc. During
- the design phase, business process designers may use the
- registry to link together calls to several services to
- create a workflow or business process.
+ <para>
+ Hence, service registries are central to service-oriented
+ architectures. At the time of execution, they act as contact
+ points at which service requests can be correlated with
+ actual behaviors. A service registry will hold meta-data
+ entries for all of the <firstterm>artifacts</firstterm>
+ within the Service Oriented Architecture that are used at
+ both run-time and design time.
+ </para>
+
+ <para>
+ Items held within a service registry may include service
+ description <firstterm>artifacts</firstterm> such as
+ <firstterm>Service Policy</firstterm> descriptions, various
+ <firstterm>Extensible Mark-Up Language</firstterm> (XML)
+ schema used by services, artifacts representing different
+ versions of services, governance and security artifacts
+ (such as certificates and audit trail data) and so forth.
+ During the design phase, business process architects may use
+ the Registry to link calls to several different services
+ together. In doing so, they create a work-flow or business
+ process.
</para>
<note>
<para>
- The registry may be replicated or federated to improve
- performance and reliability. It need not be a single
- point of failure.
+ Replicate or federate the registry in order to
+ improve performance and reliability. This will prevent
+ it from being a single point of failure.
</para>
</note>
@@ -77,32 +94,33 @@
<section>
<title>
- How do I use it?
- </title>
+ How Does One Use It?
+ </title>
<para>
- From a business analyst’s perspective, it is similar to an
- Internet search engine for business processes. From a
- developers perspective, they use the registry to publish
- services and query the registry to discover services
- matching various criteria.
+ From a business analyst’s perspective, the registry is
+ similar to an Internet search engine, albeit one designed to
+ find business processes. From a developer's perspective, the
+ registry is used to discover and publish services that match
+ various criteria.
</para>
</section>
<section>
<title>
- Registry Vs Repository
- </title>
+ Registries versus Repositories
+ </title>
<para>
- A registry allows for the registration of services,
- discovery of metadata and classification of entities into
- predefined categories. Unlike a respository, it does not
- have the ability to store business process definitions or
- WSDL or any other documents that are required for trading
- agreements. A registry is essentially a catalogue of items,
- whereas a repository maintaines those items.
+ The purpose of the registry to record services, discover
+ meta-data and classify entities into pre-defined categories.
+ Unlike a repository, it does not have the ability to store
+ business process definitions, WSDLs or any other documents
+ required for trade agreements. A registry is essentially a
+ <emphasis>catalogue</emphasis> of items, whereas a
+ repository is the storage area that actually contains those
+ items.
</para>
</section>
@@ -110,26 +128,47 @@
<section>
<title>
- SOA components
+ Service-Oriented Architecture Components
</title>
<para>
- As the W3C puts it: An SOA is a specific type of
- distributed system in which the agents are "services":
- <ulink
+ "A Service Oriented Architecture is a specific type of
+ distributed system in which the agents are
+ 'services'."<footnote><para>Refer to the W3C
+ Working Draft on <ulink
url="http://www.w3.org/TR/2003/WD-ws-arch-20030808/#id2617708"
- />.
+ /> for a more detailed definition.</para></footnote>.
</para>
<para>
- The key components of a Service Oriented Architecture are
- the messages that are exchanged, agents that act as service
- requesters and service providers, and shared transport
- mechanisms that allow the flow of messages. A description
- of a service that exists within an SOA is essentially just
- a description of the message exchange patter between itself
- and its users. Within an SOA there are thus three critical
- roles: requester, provider, and broker.
+ The key components of a Service-Oriented Architecture are:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ the exchanged messages
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the agents that act as service requesters and providers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the shared transport mechanisms that allow the
+ messages to flow.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ A "service" is essentially the messages exchanged between
+ the system and its users. Within an Service Oriented
+ Architecture, there are three critical roles: the service
+ provider, the broker and the requester. Each shall now be
+ defined in turn.
</para>
<variablelist>
@@ -138,9 +177,10 @@
<listitem>
<para>
- allows access to services, creates a
- description of a service and publishes it to
- the service broker.
+ A <firstterm>service provider</firstterm>
+ facilitates access to services, creates
+ descriptions of them and publishes them to the
+ service broker.
</para>
</listitem>
</varlistentry>
@@ -148,8 +188,9 @@
<term>Service Broker</term>
<listitem>
<para>
- hosts a registry of service descriptions. It is
- responsible for linking a requestor to a
+ A <firstterm>service broker</firstterm> hosts a
+ registry of service descriptions. It is
+ responsible for linking a service requester to a
service provider.
</para>
</listitem>
@@ -158,11 +199,12 @@
<term>Service Requester</term>
<listitem>
<para>
- is responsible for discovering a service by
- searching through the service descriptions
- given by the service broker. A requestor is
- also responsible for binding to services
- provided by the service provider.
+ A <firstterm>service requester</firstterm> is
+ responsible for discovering a service. It does
+ so by searching through the service descriptions
+ given by the service broker. A requester is also
+ responsible for binding to services obtained from
+ the service provider.
</para>
</listitem>
</varlistentry>
@@ -178,41 +220,44 @@
<section>
<title>
- UDDI
+ Universal Description, Discovery and Integration Registry
</title>
<para>
- The Universal Description, Discovery and Integration
- registry is a directory service for Web Services. It
- enables service discovery through queries to the UDDI
- registry at design time or at run time. It also allows
- providers to publish descriptions of their services to the
- registry. The registry typically contains a URL that
- locates the WSDL document for the web services and contact
- information for the service provider. Within UDDI
- information is classified into the following categories.
+ The <firstterm>Universal Description, Discovery and
+ Integration</firstterm> (UDDI) Registry is a directory for
+ <firstterm>web services</firstterm>. Use it to discover
+ services through queries at design- or run-time. It also
+ allows providers to publish descriptions of their services.
+ The typical UDDI Registry will contain a <firstterm>uniform
+ resource locator</firstterm> (URL) that points to both the
+ WSDL document for the web services and the contact
+ information for the service provider. Within the UDDI
+ Registry, information is categorised in the following ways:
</para>
<itemizedlist>
<listitem>
<para>
- White pages: contain general information such as
- the name, address and other contact information
- about the company providing the service.
+ <firstterm>White Pages</firstterm> contain
+ general information, such as the name, address and
+ other contact details for the company providing
+ the service.
</para>
</listitem>
<listitem>
<para>
- Yellow pages: categorize businesses based on the
- industry their services cater to.
+ <firstterm>Yellow Pages</firstterm> are used to categorize
+ businesses based upon the industries to which they
+ belong.
</para>
</listitem>
<listitem>
<para>
- Green pages: provide information that will enable a
- client to bind to the service that is being
- provided.
+ <firstterm>Green Pages</firstterm> provide
+ information that will enable a client to bind to the
+ service that is being provided.
</para>
</listitem>
@@ -221,33 +266,49 @@
<section>
<title>
- The Registry and JBossESB
+ The Registry and the JBoss Service-Oriented Architecture Platform
</title>
<para>
- The registry plays a central role within JBossESB. It is
- used to store endpoint references (EPRs) for the services
- deployed within the ESB. It may be updated dynamically when
- services first start-up, or statically by an external
- administrator.
+ The registry plays a central role within the
+ <application>JBoss Enterprise Service-Oriented Architecture
+ Platform</application>. It is used to store the
+ <firstterm>End Point References</firstterm> (EPRs) for the
+ services that have been deployed. It may either be updated
+ dynamically (when services first start) or statically (by an
+ external administrator.)
</para>
<para>
- As with all environments within which registries reside, it
- is not possible for the registry to determine the liveness
- of the entities its data represents, e.g., if an EPR is
- registered with the registry then there can be no guarantee
- that the EPR is valid (it may be malformed) or it may
- represent a services that is no longer active. At present
- JBossESB does not perform life-cycle monitoring of the
- services that are deployed within it. As such, if services
- fail or move elsewhere, their EPRs that may reside within
- the registry will remain until they are explicitly updated
- or removed by an administrator. Therefore, if you get
- warnings or errors related to EPRs obtained from the
- registry, you should consider removing any out-of-date
- items.
+ The registry cannot determine the status of those entities
+ represented by the data it contains. Hence, an end-point
+ reference might be in the Registry but there can be no
+ guarantee that it is valid (as it may be malformed or it may
+ represent a service that is no longer active.)
+ </para>
+
+ <para>
+ The <application>JBoss Enterprise SOA Platform</application>
+ does not currently perform life-cycle monitoring of deployed
+ services. The administrator must explicitly update or remove
+ end-point references associated with services that have been
+ moved elsewhere or have failed, otherwise they will simply
+ remain in the Registry.
+ </para>
+
+ <para>
+ Upon receipt of any warning or error messages from the
+ Registry related to end-point references, one should inform those
+ responsible for the services with which they are associated.
</para>
-
+
+ <important>
+ <para>
+ ESB services create their own end-point references
+ automatically. These end-points are internal
+ implementations and, hence, modification of
+ them is not supported.
+ </para>
+ </important>
</section>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_regex.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_regex.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_regex.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -17,12 +17,10 @@
</title>
<para>
- An easy way of performing content based routing in JBoss ESB is is
- via the Regex rules provider on the ContentBasedRouter action.
- </para>
-
- <para>
- This provider is very easy to use and supports both inline and
+ An easy way to perform content-based routing in JBoss Enterprise
+ Service Bus is via the <firstterm>Regex rules provider</firstterm>
+ on the <classname>ContentBasedRouter</classname> action. One will
+ find this provider very easy to use and it supports both inline and
external rule definitions.
</para>
</section>
@@ -34,10 +32,11 @@
</title>
<para>
- Defining inline Regex routing rules is trivial. You just need to
- configure the “cbrAlias” property to “Regex” and then define the
- routing rules in the <route-to> configurations in the container
- destinations property.
+ Defining inline Regex routing rules is very straightforward. One
+ merely needs to set the <property>cbrAlias</property> property to
+ <code>Regex</code> and then define the routing rules in the
+ <property>route-to</property> configurations, found in the
+ <property>container destinations</property> property.
</para>
@@ -47,47 +46,47 @@
</section>
<section>
-
- <title>
+<title>
External Rule Definitions
- </title>
+</title>
+<para>
+ Defining external XPath routing rules is also quite simple. Again, one
+ merely needs to set the <property>cbrAlias</property> property to
+ <code>Regex</code> and then:
+</para>
- <para>
- Defining external XPath routing rules is also trivial. Again,
- you configure the “cbrAlias” property to “Regex” and then
- </para>
-
<orderedlist>
- <listitem>
- <para>
- Define the routing expressions in a .properties file, where the
- property keys are the destination names and the property values
- are the Regex expressions for routing to the destination in
- question.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Define the routing rules in the <route-to> configurations in
- the container destinations property, with the
- “destination-name” attribute referring to the Regex rule key as
- defined in the external .properties file.
- </para>
- </listitem>
+<listitem>
+<para>
+ define the routing expressions in a <filename>.properties</filename>
+ file, where the property keys are the destination names and the property
+ values are the Regex expressions for routing to the destination in
+ question.
+</para>
+</listitem>
+<listitem>
+<para>
+ define the routing rules in the <code>route-to</code> configurations in the
+ container destinations property, with the
+ <property>destination-name</property> attribute set to refer to the
+ Regex rule key as defined in the external
+ <filename>.properties</filename> file.
+</para>
+</listitem>
</orderedlist>
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_regex/external2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <para>
- The XPath rules file is a simple .properties file as follows:
- </para>
+<para>
+ The XPath rules are in a <filename>.properties</filename> file. They are
+ represented in this simple format:
+</para>
+
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_regex/xpathrules2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_xpath.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_xpath.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/content-based_routing_using_xpath.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -17,8 +17,9 @@
<para>
- An easy way of performing content based routing in JBoss ESB is is via
- the XPath rules provider on the ContentBasedRouter action.
+ An easy way of performing content based routing in the JBoss Enterprise
+ Service Bus is via the <firstterm>XPath Rules Provider</firstterm> on
+ the <classname>ContentBasedRouter</classname> action.
</para>
<para>
@@ -34,10 +35,11 @@
</title>
<para>
- Defining inline XPath routing rules is trivial. You just need to
- configure the “cbrAlias” property to “XPath” and then define the routing
- rules in the <route-to> configurations in the container
- destinations property.
+ It is very simple to define inline routing rules using XPath. One merely
+ needs to set the <property>cbrAlias</property> property to
+ <code>XPath</code> and then define the routing rules in the
+ <code>route-to</code> configurations that are found in the container
+ destinations property.
</para>
@@ -52,26 +54,26 @@
</title>
<para>
- Defining external XPath routing rules is also trivial. Again, you
- configure the “cbrAlias” property to “XPath” and then
+ It is also very straightforward to define external XPath routing
+ rules. Again, one must set the <property>cbrAlias</property>
+ property to <code>XPath</code> and then:
</para>
<orderedlist>
<listitem>
<para>
- Define the routing expressions in a .properties file, where the
- property keys are the destination names and the property values are the
- Xpath expressions for routing to the destination in question.
+define the routing expressions in a .properties file, in which the property
+keys are equal to the destination names and the property values are the XPath
+expressions for routing to the destination in question.
</para>
</listitem>
<listitem>
<para>
- Define the routing rules in the <route-to> configurations in the
- container destinations property, with the “destination-name” attribute
- referring to the XPath rule key as defined in the external .properties
- file.
+define the routing rules in the <code>route-to</code> configurations via the container
+destinations property, whereby the <property>destination-name</property> attribute will refer to
+the XPath rule key as defined in the external .properties file.
</para>
</listitem>
</orderedlist>
@@ -81,7 +83,8 @@
<para>
- The XPath rules file is a simple .properties file as follows:
+ The XPath rules are in a <filename>.properties</filename> file. They are
+ represented in this simple format:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/cbr_xpath/xpathrules.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -96,10 +99,11 @@
</title>
<para>
- XML namespace prefix-to-uri mappings are defined in the <namespace>
- elements, contained within the “namespaces” container property.
- Namespaces prefix-to-uri mappings are define in exactly the same
- way for both inline and external rule definitions.
+ <abbrev>XML</abbrev> name-space prefix-to-URI mappings are defined
+ in the <property>namespace</property> elements. These are contained
+ within the <literal>namespaces</literal> container property. Name-space
+ prefix-to-URI mappings are defined in exactly the same way for both
+ inline and external rule definitions.
</para>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/generatedb.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/generatedb.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/generatedb.xmlt 2010-08-15 23:37:23 UTC (rev 34733)
@@ -0,0 +1,8 @@
+!-- <entry key="juddi.tablePrefix">JUDDI_</entry> -->
+ <entry key="juddi.isCreateDatabase">true</entry>
+ <entry key="juddi.databaseExistsSql">select * from ${prefix}BUSINESS_ENTITY
+ </entry>
+ <entry key="juddi.sqlFiles">
+ juddi-sql/mysql/create_database.sql,
+ juddi sql/mysql/insert_publishers.sql
+ </entry>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/nodes2.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/nodes2.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/extras/configuring_the_registry/nodes2.xmlt 2010-08-15 23:37:23 UTC (rev 34733)
@@ -0,0 +1,14 @@
+SOAP
+queryManagerURI http://localhost:8080/juddi/inquiry
+lifeCycleManagerURI http://localhost:8080/juddi/publish
+transportClass org.apache.ws.scout.transport.AxisTransport
+
+RMI
+queryManagerURI jnp://localhost:1099/InquiryService?org.apache.juddi.registry.rmi.Inquiry#inquire
+lifeCycleManagerURI jnp://localhost:1099/PublishService?org.apache.juddi.registry.rmi.Publish#publish
+transportClass org.apache.ws.scout.transport.RMITransport
+
+Local
+queryManagerURI org.apache.juddi.registry.local.InquiryService#inquire
+lifeCycleManagerURI org.apache.juddi.registry.local.PublishService#publish
+transportClass org.apache.ws.scout.transport.LocalTransport
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/jBPM_Integration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/jBPM_Integration.xml 2010-08-15 23:29:06 UTC (rev 34732)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Services_Guide/en-US/jBPM_Integration.xml 2010-08-15 23:37:23 UTC (rev 34733)
@@ -10,37 +10,56 @@
jBPM Integration
</title>
-
- <section>
+<section>
<title>
Introduction
</title>
<para>
- JBoss jBPM is a powerful workflow and BPM (Business Process
- Management) engine. It enables the creation of business processes
- that coordinate between people, applications and services. With its
- modular architecture, JBoss jBPM combines easy development of
- workflow applications with a flexible and scalable process engine.
- The JBoss jBPM process designer graphically represents the business
- process steps to facilitate a strong link between the business
- analyst and the technical developer. This document assumes that you
- are familiar with jBPM. If you are not you should read the jBPM
- documentation [TB-JBPM-USER] first. JBossESB integrates the jBPM so
- that it can be used for two purposes:
+ This section of the book examines the <application>JBoss Business
+ Process Manager</application>. Read on to learn about the features
+ of this powerful tool. (This document assumes that the readership
+ is familiar with the basics of jBPM. If this is not the case, read the
+ <emphasis>jBPM Reference Guide</emphasis> included with this
+ software first.)
</para>
+ <para>
+ The <application>JBoss Business Process Manager</application> is a
+ powerful workflow and <firstterm>business process
+ management</firstterm> (BPM) engine. Use it to create business
+ processes when there is a need to co-ordinate people, applications
+ and services. The <application>jBPM</application> uses a
+ modular architecture which combines easy development of work-flow
+ applications with a process engine that is both flexible and
+ scalable.
+ </para>
+
+ <para>
+ To represent the steps in a business procedure
+ graphically, use the accompanying <application>jBPM Process
+ Designer</application>. This can facilitate the formation of a
+ strong working relationship between the business analyst
+ and the technical developer.
+ </para>
+ <para>
+ The <application>JBoss Enterprise Service Bus</application>
+ integrates with the <application>jBPM</application> for two reasons, these being:
+ </para>
-<orderedlist>
- <listitem>
- <para>
- Service Orchestration
- </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Service Orchestration
+ </para>
+
<para>
- ESB services can be orchestrated using jBPM. You can create a
- jBPM process definition which makes calls into ESB services.
+ ESB services can be "orchestrated" using the
+ <application>Business Process Manager</application>. To do so,
+ create a <firstterm>process definition</firstterm> which
+ calls upon them.
</para>
</listitem>
@@ -50,8 +69,9 @@
</para>
<para>
- jBPM allows you to incorporate human task management integrated
- with machine based services.
+ The <application>Business Process Manager</application> allows
+ one to integrate machine-based services with the management of
+ tasks undertaken by people.
</para>
</listitem>
</orderedlist>
@@ -64,11 +84,15 @@
</title>
<para>
- The jbpm.esb deployment that ships with the ESB includes the full
- jBPM runtime and the jBPM console. The runtime and the console
- share a common jBPM database. The ESB DatabaseInitializer mbean
- creates this database on startup. The configuration for this mbean
- is found in the file jbpm.esb/jbpm-service.xml.
+ The full jBPM run-time and console are included with the
+ <filename>jbpm.esb</filename> deployment that ships with the
+ <application>JBoss Enterprise Service Bus</application>. The runtime
+ and the console share a common database. To create the database,
+ start the Enterprise Service Bus
+ <classname>DatabaseInitializer</classname>
+ <firstterm>M-Bean</firstterm>. (The configuration settings for this
+ M-Bean are found in the
+ <filename>jbpm.esb/jbpm-service.xml</filename> file.)
</para>
@@ -77,9 +101,8 @@
<para>
- The first Mbean configuration element contains the configuration
- for the DatabaseInitializer. By default the attributes are
- configured as follows:
+ The first MBean configuration element contains the settings for the
+ <classname>DatabaseInitializer</classname>.
</para>
<table>
@@ -114,51 +137,73 @@
<para>
- The DatabaseInitializer mbean is configured in jbpm-service.xml
- to wait for the JbpmDS to be deployed, before deploying itself.
- The second mbean “JbpmService” ties the lifecycle of the jBPM
- job executor to the jbpm.esb lifecycle - it starts a job
- executor instance on startup and stops it on shutdown. The
- JbpmDS datasource is defined in the jbpm-ds.xml and by default
- it uses a HSQL database. In production you will want change to
- a production strength database. All jbpm.esb deployments should
- share the same database instance so that the various ESB nodes
- have access to the same processes definitions and instances.
- </para>
+ The <classname>DatabaseInitializer</classname> MBean is
+ configured (via the <filename>jbpm-service.xml</filename> file)
+ to wait for the <classname>JbpmDS</classname> to be deployed,
+ before it then deploys itself. The second MBean,
+ <classname>JbpmService</classname>, ties the lifecycle of the
+ <application>Business Process Manager</application>'s
+ <firstterm>job executor</firstterm> to that of the
+ <filename>jbpm.esb</filename>. It does so by launching a
+ <systemitem>job executor</systemitem> instance on start-up. (It,
+ of course, stops it on shutdown.)
+ </para>
+ <para>
+ The <classname>JbpmDS</classname> data source is defined in the
+ <filename>jbpm-ds.xml</filename> file. By default, it uses a
+ <application>Hypersonic</application> database. (Always change this to a production-quality
+ database in a live environment.) Note that all
+ <filename>jbpm.esb</filename> deployments should share the same
+ database instance. This is so that the various Enterprise
+ Service Bus nodes have access to the same <firstterm>processes
+ definitions</firstterm>.
+ </para>
+
<para>
- The jBPM console is a web application accessible at <ulink
- url="http://localhost:8080/jbpm-console" />, when you start the
- server. The login screen is shown below.
+ The <application>jBPM Console</application> is a web application.
+ Access it from this address: <ulink
+ url="http://localhost:8080/jbpm-console" />, after the server has
+ been started.
</para>
<figure><title>jBPM Console Log In</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/jbpm/jbpmconsole.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/jbpm/jbpmconsole.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- Please check the jBPM documentation [TB-JBPM-USER] to change the
- security settings for this application, which will involve change
- some settings in the conf/login-config.xml. The console can be used
- for deploying and monitoring jBPM processes, but is can also be
- used for human task management. For the different users a
- customized task list will be shown and they can work on these
- tasks. The quickstart bpm_orchestration4 [JBESB-QS] demonstrates
- this feature.
+ Please refer to the <emphasis>jBPM Reference Guide</emphasis> in
+ order to learn how to change the security settings for this
+ application. The process involves changing some settings in the
+ <filename>conf/login-config.xml</filename> file. Use the console to
+ deploy and monitor both jBPM processes and human task management
+ procedures. (A customised tasklist will be shown for each user of
+ the software, allowing them to work on their own tasks) The Quick
+ Start entitled <filename>bpm_orchestration4</filename> demonstrates
+ this feature.)
</para>
<para>
- The jbpm.esb/META-INF directory contains the deployment.xml and the
- jboss-esb.xml. The deployment.xml specifies the resources this esb
- archive depends on:
+ The <filename>jbpm.esb/META-INF</filename> directory
+ contains the <filename>deployment.xml</filename> and
+ <filename>jboss-esb.xml</filename> files.
</para>
-
-<programlisting language="XML" role="XML"><xi:include href="extras/jbpm/jbpm_deployment.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <para>
+ The <filename>deployment.xml</filename> file specifies the two
+ resources upon which the ESB archive will depend. (They are the
+ <filename>jbossesb.esb</filename> and the
+ <classname>JbpmDS</classname> data source files. The information in
+ these files is used to determine the order of deployment.)
+ </para>
+
+
+<programlisting language="XML"><xi:include href="extras/jbpm/jbpm_deployment.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
<para>
The <filename>jboss-esb.xml</filename> file deploys one internal
@@ -170,41 +215,42 @@
<para>
- This service listens to the jBPMCallbackBus, which by default is a
- JMS Queue on either a JBossMQ (jbmq-queue-service.xml) or a
- JBossMessaging (jbm-queue-service.xml) messaging provider. Make
- sure only one of these files gets deployed in your jbpm.esb
- archive. If you want to use your own provider simple modify the
- provider section in the jboss-esb.xml to reference your JMS
- provider. shown in this example:
+ This internal service listens to the
+ <classname>jBPMCallbackBus</classname>, which, by default, is set as
+ either a <classname>JBossMQ</classname> (the
+ <filename>jbmq-queue-service.xml</filename> file) or a
+ <classname>JBossMessaging</classname> (the
+ <filename>jbm-queue-service.xml</filename> file.) It is a messaging
+ provider for the <firstterm>Java Message Service Queue</firstterm>.
+ Ensure that only one of these files is deployed in the
+ <filename>jbpm.esb</filename> archive. If one wants to use one's own
+ messaging provider, simply modify the corresponding section in the
+ <filename>jboss-esb.xml</filename> file to refer to it, in the way
+ shown in this example:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/jbpm/jBPM_provider_section_in_jboss_esb.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <note>
- <para>
- For more details on what the JbpmCallbackService does, please
- see the “jBPM to ESB” section later on in this chapter.
- </para>
- </note>
+
</section>
<section>
<title>
- jBPM configuration
+ Configuring the jBPM
</title>
<para>
- The configuration of jBPM itself is managed by three files, the
- jbpm.cfg.xml and the hibernate.cfg.xml and the
- jbpm.mail.templates.xml.
+ The configuration of Business Process Manager itself is managed by
+ three files, namely <filename>jbpm.cfg.xml</filename>,
+ <filename>hibernate.cfg.xml</filename> and
+ <filename>jbpm.mail.templates.xml</filename>.
</para>
<para>
- By default the jbpm.cfg.xml is set to use the JTA transacion
- manager, as defined in the section:
+ The <filename>jbpm.cfg.xml</filename> file is programmed, to use
+ the <firstterm>JTA Transaction Manager</firstterm> by default.
</para>
@@ -212,12 +258,13 @@
<para>
- Other settings are left to the default jBPM settings.
+ Other settings are left as the jBPM defaults.
</para>
<para>
- The hibernate.cfg.xml is also slightly modified to use the JTA
- transaction manager
+ The <filename>hibernate.cfg.xml</filename> file is also
+ modified to use the <systemitem>JTA Transaction
+ Manager</systemitem>.
</para>
@@ -225,39 +272,48 @@
<para>
- Hibernate is not used to create the database schema, instead we
- use our own DatabaseInitiazer mbean, as mentioned in the
- previous section.
+ <application>Hibernate</application> is not used to create the
+ database schema. Rather, the
+ <systemitem>DatabaseInitializer</systemitem> M-Bean referred to
+ in Configuration section is utilised.
</para>
<para>
- The jbpm.mail.templates.xml is left empty by default. For each
- more details on each of these configuration files please see
- the jBPM documentation.
+ The <filename>jbpm.mail.templates.xml</filename> file is empty
+ by default.
</para>
+<note>
+ <para>
+ For more details on each of these configuration files, please
+ see the <emphasis>jBPM Guide</emphasis>.
+ </para>
+</note>
<important>
<para>
- The configuration files that usually ship with the
- jbpm-console.war have been removed so that all
- configuration is centralized in the configuration files in
- the root of the jbpm.esb archive.
+ The configuration files that formerly shipped with the
+ <filename>jbpm-console.war</filename> have been removed.
+ This was done to centralized all of the configuration files
+ in the root of the <filename>jbpm.esb</filename> archive.
</para>
</important>
</section>
<section>
- <title>
- Creation and Deployment of a Process Definition
+ <title>
+
+ Creating and Deploying a Process Definition
</title>
<para>
- To create a Process Definition we recommend using the eclipse based
- jBPM Process Designer Plugin [KA-JBPM-GPD]. You can either download
- and install it to eclipse yourself, or use JBoss Developer Studio.
- The image below shows the graphical editor.
+ We recommend using the
+ <application>Eclipse</application>-based <firstterm>jBPM Process
+ Designer Plug-in</firstterm> (KA-JBPM-GPD) to create
+ <firstterm>process definitions</firstterm>. Either download and
+ install it in <application>Eclipse</application> manually or use the
+ <application>JBoss Developer Studio</application> to do so.
</para>
<figure><title>JBoss Developer Studio - jBPM Graphical Editor</title>
@@ -269,22 +325,22 @@
</figure>
<para>
- The graphical editor allows you to create a process definition
- visually. Nodes and transitions between nodes can be added,
- modified or removed. The process definition saves as an XML
- document which can be stored on a file system and deployed to a
- jBPM instance (database). Each time you deploy the process instance
- jBPM will version it and will keep the older copies. This allows
- processes that are in flight to complete using the process instance
- they were started on. New process instances will use the latest
- version of the process definition.
+ Use the <application>jBPM Graphical Editor</application> to create a
+ process definition visually. Nodes, (and transitions between nodes),
+ can be added, modified and removed. Each process definition is saved
+ in XML format. The saved file can then be stored in a directory and
+ deployed to a jBPM instance (that is, a database.) Each time one
+ deploys the process instance, the jBPM will "version" it and retain
+ the older copies. This allows processes that are already underway to
+ complete on the instance upon which they were started. New instances
+ will use the latest version of the process definition.
</para>
<para>
- To deploy a process definition the server needs to be up and
- running. Only then can you go to the 'Deployment' tab in the
- graphical designer to deploy a process archive (par). Figure 3
- shows the “Deployment” tab view.
+ In order to deploy a process definition, first check that the server
+ is running. Next, activate a <firstterm>Process Archive</firstterm>
+ (PAR) by going to the <guilabel>Deployment</guilabel> tab in the
+ <application>Graphical Editor</application>:
</para>
<figure><title>JBoss Developer Studio - jBPM Deployment View</title>
@@ -296,36 +352,56 @@
</figure>
<para>
- In some cases it would suffice to deploy just the
- processdefinition.xml, but in most cases you will be deploying
- other type of artifacts as well, such as task forms. It is also
- possible to deploy Java classes in a par, which means that they end
- up in the database where they will be stored and versioned. However
- it is strongly discouraged to do this in the ESB environment as you
- will risk running into class loading issues. Instead we recommend
- deploying your classes in the lib directory of the server. You can
- deploy a process definition
+ Sometimes it is sufficient to just deploy the
+ <filename>processdefinition.xml</filename> file but, in most cases,
+ one will be deploying other kinds of
+ <systemitem>artifacts</systemitem> as well, such as <firstterm>task
+ forms</firstterm>.
</para>
+<warning>
+ <para>
+ It is also possible to deploy Java classes into a <filename>process
+ archive</filename>. This means that they will end up in the
+ database, where they will be stored and versioned. Red Hat does not
+ recommend doing this in the Enterprise Service Bus environment, the
+ reason being that it can lead to class-loading issues. The
+ recommended practice is to instead deploys the classes into the
+ server's <filename>lib</filename> directory.
+ </para>
+</warning>
+ <para>
+ Use one of the following three mechanisms to deploy a process
+ definition:
+ </para>
+
<orderedlist>
<listitem>
<para>
- straight from the eclipse plugin, by clicking on the
- “Test Connection..” button and, on success, by clicking
- on the “Deploy Process Archive” button,
+ through <application>JBoss Developer
+ Studio</application>, by clicking on the
+ <guibutton>Deploy Process Archive</guibutton> button
+ (having first configured the upload servlet used by the
+ deployer.) This is visible in the
+ <guilabel>Deployment</guilabel> view;
</para>
</listitem>
<listitem>
<para>
- by saving the deployment to a par file and using the
- jBPM console to deploy the archive, see Figure 4, or
- finally,
+ by saving the deployment to a local
+ <filename>.par</filename> file from the
+ <guilabel>Deployment</guilabel> view and then using
+ the jBPM Console to activate the
+ archive. (In order to do this, one needs to be able to
+ log in to the console with the privileges of an
+ administrator.)
</para>
</listitem>
<listitem>
<para>
- by using the DeployProcessToServer jBPM ant task.
+ by using the <classname>DeployProcessToServer</classname>
+ jBPM <command>ant</command> task.
</para>
</listitem>
</orderedlist>
@@ -344,13 +420,15 @@
<section>
<title>
- JBossESB to jBPM
+ From the Enterprise Service Bus to the jBPM
</title>
<para>
- JBossESB can make calls into jBPM using the BpmProcessor action.
- This action uses the jBPM command API to make calls into jBPM. The
- following jBPM commands have been implemented:
+ The <application>JBoss Enterprise Service Bus</application> can
+ make calls into the Business Process Manager by using the
+ <classname>BpmProcessor</classname> action. This action utilises
+ the <interfacename>jBPM Command</interfacename> API. The following jBPM
+ commands have been implemented at this stage:
</para>
<table>
@@ -369,14 +447,17 @@
</entry>
<entry>
<para>
- Start a new ProcessInstance given a process definition
- that was already deployed to jBPM. This command leaves
- the Process Instance in the start state, which would be
- needed if there is an task associated to the Start node
- (i.e. some task on some actor's tasklist). In most cases
- however you would like the new Process Instance to move
- to the first node, which is where the next command comes
- in.
+ This command starts a new
+ <classname>ProcessInstance</classname>, the
+ associated process definition of which has already
+ been deployed to the jBPM. The
+ <classname>NewProcessInstanceCommand</classname>
+ leaves the process instance in the
+ <literal>start</literal> state. This is needed in
+ the case of a task being associated with the
+ <systemitem>Start node</systemitem>, an example
+ being when there is one on an
+ <firstterm>actor</firstterm>'s task-list.
</para>
</entry>
</row>
@@ -387,9 +468,11 @@
</entry>
<entry>
<para>
- Identical to the NewProcessInstanceCommand, but
- additionally the new Process Instance is moved from the
- Start position into the first Node.
+ This is identical to the
+ <command>NewProcessInstanceCommand</command> except
+ that the new process instance is automatically
+ moved from the <literal>start</literal> position to
+ the first node.
</para>
</entry>
</row>
@@ -400,8 +483,9 @@
</entry>
<entry>
<para>
- The the root node variables for a process instance,
- using the process instance ID.
+ This command takes the root node variables for a
+ process instance, by using the process instance
+ identifier.
</para>
</entry>
</row>
@@ -413,11 +497,15 @@
</entry>
<entry>
<para>
- Cancel a ProcessInstance. i.e. when an event comes in
- which should result in the cancellation of the entire
- ProcessInstance. This action requires some jBPM context
- variables to be set on the message, in particular the
- ProcessInstance Id. Details on that are discussed later.
+ This command cancels a
+ <classname>ProcessInstance</classname>. Use it in
+ situations such as that which occurs when an event
+ is received that should result in the cancellation
+ of the entire
+ <classname>ProcessInstance</classname>. (This action
+ requires some <abbrev>jBPM</abbrev> context
+ variables to be set on the message, most notably the
+ <classname>ProcessInstance</classname> identifier.)
</para>
</entry>
</row>
@@ -437,7 +525,7 @@
<para>
- There are two required action attributes:
+ Two action attributes are required:
</para>
<orderedlist>
@@ -446,11 +534,11 @@
name
</para>
- <para>
- Required attribute. You are free to use any value for
- the name attribute as long as it is unique in the
- action pipeline.
- </para>
+ <para>
+ Use any value for this <property>name</property> attribute,
+ as long as it is unique in the <systemitem>action
+ pipeline</systemitem>.
+ </para>
</listitem>
<listitem>
@@ -458,15 +546,15 @@
class
</para>
- <para>
- Required attribute. This attributes needs to be set to
- “org.jboss.soa.esb.services.jbpm.actions.BpmProcessor”
- </para>
+ <para>
+ Always set this attribute to
+ <classname>org.jboss.soa.esb.services.jbpm.actions.BpmProcessor</classname>.
+ </para>
</listitem>
</orderedlist>
<para>
- Furthermore one can configure the following configuration properties:
+ One can also set these configuration properties:
</para>
<table>
@@ -485,10 +573,11 @@
</entry>
<entry>
<para>
- Needs to be one of:
- NewProcessInstanceCommand, StartProcessInstanceCommand,
- GetProcessInstanceVariablesCommand or
- CancelProcessInstanceCommand.
+ This must be one of:
+ <classname>NewProcessInstanceCommand</classname>,
+ <classname>StartProcessInstanceCommand</classname>,
+ <classname>GetProcessInstanceVariablesCommand</classname> or
+ <classname>CancelProcessInstanceCommand</classname>.
</para>
</entry>
<entry>
@@ -498,19 +587,21 @@
</entry>
</row>
- <row>
+ <row>
<entry>
<property>process-definition-name</property>
</entry>
<entry>
<para>
- required property for the NewProcessInstanceCommand and
- StartProcessInstanceCommand if the
- process-definition-id property is not used. The value
- of this property should reference a process definition
- that is already deployed to jBPM and of which you want
- to create a new instance. This property does not apply
- to the CancelProcessInstanceCommand.
+ This property is required for the
+ <command>NewProcessInstanceCommands</command> and
+ <command>StartProcessInstanceCommands</command> if the
+ <property>process-definition-id</property> property is
+ not used. The value of this property should reference
+ the already-deployed process definition for which one wishes
+ to create a new instance. (This property does not
+ apply to the
+ <command>CancelProcessInstanceCommand</command>.)
</para>
</entry>
<entry>
@@ -527,13 +618,15 @@
</entry>
<entry>
<para>
- required property for the NewProcessInstanceCommand
- and StartProcessInstanceCommand if the
- process-definition-name property is not used. The
- value of this property should reference a process
- definition id in jBPM of which you want to create a
- new instance. This property does not apply to the
- CancelProcessInstanceCommand.
+ This is a required property for the
+ <command>NewProcessInstanceCommands</command> and
+ <command>StartProcessInstanceCommands</command> if
+ the <property>process-definition-name</property> property is
+ not used. The value of this property should refer to
+ the already-deployed process definition for which
+ a new instance is to be created. (This property does not
+ apply to the
+ <command>CancelProcessInstanceCommand</command>.)
</para>
</entry>
<entry>
@@ -550,9 +643,10 @@
</entry>
<entry>
<para>
- specifies the jBPM actor id, which applies to the
- NewProcessInstanceCommand and
- StartProcessInstanceCommand only.
+ Use this property to specify the <classname>jBPM
+ actor</classname> identifier. (It only applies to the
+ <command>NewProcessInstanceCommand</command> and the
+ <command>StartProcessInstanceCommand</command>.)
</para>
</entry>
<entry>
@@ -560,28 +654,27 @@
No
</para>
</entry>
- </row>
+ </row>
- <row>
+ <row>
<entry>
<property>key</property>
</entry>
<entry>
<para>
- optional property to specify the value of the jBPM
- key. For example one can pass a unique invoice id as
- the value for this key. On the jBPM side this key is
- as the “business” key id field. The key is a string
- based business key property on the process instance.
- The combination of business key + process definition
- must be unique if a business key is supplied. The key
- value can hold an MVEL expression to extract the
- desired value from the EsbMessage. For example if you
- have a named parameter called “businessKey” in the
- body of your message you would use
- “body.businessKey”. Note that this property is used
- for the NewProcessInstanceCommand and
- StartProcessInstanceCommand only.
+ Use this property to specify the value of the
+ jBPM key. The key is a string based business key
+ property on the process instance. The combination of
+ business key and process definition must be unique if a
+ business key is supplied. The key value can hold an
+ MVEL expression to extract the desired value from the
+ EsbMessage. For example, if one were to have a named
+ parameter called <systemitem>businessKey</systemitem>
+ in the body of a message,
+ <property>body.businessKey</property> would be used.
+ (This property only applies to
+ <command>NewProcessInstanceCommand</command> and
+ <command>StartProcessInstanceCommands</command>.)
</para>
</entry>
<entry>
@@ -589,23 +682,23 @@
No
</para>
</entry>
- </row>
+ </row>
- <row>
+ <row>
<entry>
<property>transition-name</property>
</entry>
<entry>
<para>
- This property only applies to the
- StartProcessInstanceCommand, and is of use only if
- there are more then one transition out of the current
- node. If this property is not specified the default
- transition out of the node is taken. The default
- transition is the first transition in the list of
- transition defined for that node in the jBPM
- processdefinition.xml.
+ This only applies to
+ <command>StartProcessInstanceCommand</command>. Use it only if there is more
+ than one transition out of the current node. If this
+ property is not specified, then the default transition
+ out of the node is taken. The default transition is the
+ first transition in the list of transitions defined for
+ that node in the jBPM
+ <filename>processdefinition.xml</filename>.
</para>
</entry>
<entry>
@@ -624,93 +717,75 @@
<entry>
- <para>
- optional property for the NewProcessInstanceCommand and
- StartProcessInstanceCommand. This property defines a list of
- variables that need to be extracted from the EsbMessage and set
- into jBPM context for the particular process instance. The list
- consists of mapping elements. Each mapping element can have the
- following attributes:
- </para>
+ <para>
+ This is a optional property for the <command>New-</command> and
+ <command>StartProcessInstanceCommand</command>s. It defines a list
+ of variables which need to be extracted from the
+ ESB Message and set into the
+ jBPM context for that particular process instance.
+ The list consists of mapping elements, each of which can have the
+ following attributes:
+ </para>
<itemizedlist>
<listitem>
- <para>
- esb
- </para>
-
- <para>
- required attribute which can contain an
- MVEL expression to extract a value anywhere
- from the EsbMessage.
- </para>
+ <para>
+ esb
+ </para>
+
+ <para>
+ This is a required attribute. Place an MVEL expression in it and
+ use it to extract a value from anywhere in the ESB message.
+ </para>
- </listitem>
- <listitem>
- <para>bpm</para>
- <para>
- optional attribute
- containing the name
- which be used on the
- jBPM side. If omitted
- the esb name is used.
- </para>
- </listitem>
- <listitem>
- <para>default</para>
- <para>
- optional attribute
- which can hold a
- default value if the
- esb MVEL expression
- does not find a value
- set in the EsbMessage.
- </para>
- </listitem>
- <listitem>
- <para>bpmToEsbVars</para>
- <para>
- structurally identical
- to the “esbToBpmVars”
- property (above). Used
- with the
- GetProcessInstanceVariablesCommand
- for mapping jBPM
- process instance
- variables (root token
- variables) onto the ESB
- message.
- </para>
- </listitem>
-
- <listitem>
- <para>reply-to-originator</para>
- <para>
- Optional property for
- the
- NewProcessInstanceCommand
- and
- StartProcessInstanceCommand.
- If this property is
- specified, with a value
- of true, then the
- creation of the process
- instance will store the
- ReplyTo/FaultTo EPRs of
- the invoking message
- within the process
- instance. These values
- can then be used within
- subsequent
- EsbNotifier/EsbActionHandler
- invocations to deliver
- a message to the
- ReplyTo/FaultTo
- addresses.
- </para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>bpm</para>
+ <para>
+ This is a optional attribute containing the
+ name to use on the jBPM side. (If it is
+ omitted, the Enterprise Service Bus name is
+ used instead.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>default</para>
+ <para>
+ This is a optional attribute which can hold a
+ default value if the ESB's MVEL expression does
+ not find a value set in the ESB message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>bpmToEsbVars</para>
+ <para>
+ This is structurally identical to the
+ <property>esbToBpmVars</property> property
+ above. Use it in conjuction with the
+ <classname>GetProcessInstanceVariablesCommand</classname>
+ to map jBPM <systemitem>process instance variables</systemitem>
+ (<systemitem>root token</systemitem> variables)
+ to the ESB message.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>reply-to-originator</para>
+ <para>
+ This is an optional property for the
+ <command>New</command>- and
+ <command>StartProcessInstanceCommands</command>.
+ Specify a value of <code>true</code>, to make
+ the process instance store the <systemitem>ReplyTo</systemitem>/<systemitem>FaultTo</systemitem> values
+ of the invoking message's end-point references '
+ within the process instance. These values can
+ then be used within subsequent
+ <systemitem>EsbNotifier</systemitem>/<systemitem>EsbActionHandler</systemitem> invocations to
+ deliver a message to the <systemitem>ReplyTo</systemitem>/<systemitem>FaultTo</systemitem> addresses.
+ </para>
+ </listitem>
+ </itemizedlist>
</entry>
<entry>
@@ -767,58 +842,68 @@
<section>
<title>
- Exception Handling JBossESB to jBPM
+ ESB to jBPM Exception Handling
</title>
<para>
- For ESB calls into jBPM an exception of the type
- JbpmException can be thrown from the jBPM Command API. This
- exception is not handled by the integration and we let it
- propagate into the ESB Action Pipeline code. The action
- pipeline will log the error, send the message to the
- DeadLetterService (DLS), and send the an error message to
- the faultTo EPR, if a faultTo EPR is set on the message.
+ A <exceptionname>JbpmException</exceptionname> can be
+ thrown from the jBPM Command API when ESB calls are made.
+ This exception is not handled by the integration. Instead,
+ it is passed through to the <systemitem>action
+ pipeline</systemitem>'s code. The action pipeline will log
+ the error, send the message to the
+ <classname>DeadLetterService</classname>, and send an error
+ message to the <systemitem>faultTo</systemitem> end-point
+ reference, if this has been set.
</para>
</section>
</section>
<section>
<title>
- jBPM to JBossESB
+ jBPM-to-JBoss ESB
</title>
<para>
- The JBossESB to jBPM maybe interesting but the other way around is
- probably far more interesting jBPM to JBossESB communication
- provides us with the capability to use jBPM for service
- orchestration. Service Orchestration itself will be discussed in
- more detail in the next chapter and here we're focusing on the
- details of the integration first. The integration implements two
- jBPM action handler classes. The classes are “EsbActionHandler” and
- “EsbNotifier”. The EsbActionHandler is a request-reply type action,
- which drops a message on a Service and then waits for a response
- while the EsbNotifier only drops a message on a Service and
- continues its processing. The interaction with JBossESB is
- asynchronous in nature and does not block the process instance
- while the Service executes. First we'll discuss the EsbNotifier as
- it implements a subset of the configuration of EsbActionHandler
- class.
+ <firstterm>jBPM-to-JBossESB</firstterm> communication provides one
+ with the capability to use jBPM for <firstterm>service
+ orchestration</firstterm>. (Service Orchestration itself is
+ discussed in more detail in the next chapter. Firstly, though, one
+ must learn about the details of this integration.)
</para>
-
+ <para>
+ The integration implements two jBPM action handler
+ classes, namely<classname>EsbActionHandler</classname> and
+ <classname>EsbNotifier</classname>. The
+ <classname>EsbActionHandler</classname> is a request-reply type
+ action, which sends a message to a service and then awaits a
+ response. The <classname>EsbNotifier</classname>, by contrast, does
+ not wait for such a response. The interaction with the Enterprise
+ Service Bus is asynchronous in nature and, therefore, does not block
+ the process instance whilst the service executes.
+ </para>
+
+ <para>
+ The <classname>EsbNotifier</classname> will be examined first, as it
+ implements a subset of the configuration of the
+ <classname>EsbActionHandler</classname>.
+ </para>
+
<section>
<title>
- EsbNotifier
+ ESBNotifier
</title>
<para>
- The EsbNotifier action should be attached to an outgoing
- transition. This way the jBPM processing can move along while the
- request to the ESB service is processed in the background. In the
- jBPM processdefinition.xml we would need attach the EsbNotifier to
- the outgoing transition. For example the configuration for a “Ship
- It” node could look like:
+ The <classname>EsbNotifier</classname> action should be attached to
+ an outgoing transition. This is so that the <abbrev>jBPM</abbrev>
+ processing can continue whilst the request to the
+ <abbrev>ESB</abbrev> service is processed in the background. One
+ needs to attach the <classname>EsbNotifier</classname> to the
+ outgoing transition in the <abbrev>jBPM</abbrev>
+ <filename>processdefinition.xml</filename> file.
</para>
@@ -881,28 +966,79 @@
</para>
</listitem>
-<listitem>
+ <listitem>
<para>
- globalProcessScope - optional element. This boolean valued
- parameter sets the default scope in which the bpmToEsbVars are
- looked up. If the globalProcessScope is set to true the variables
- are looked for up the token hierarchy (= process-instance scope).
- If set to false it retrieves the variables in the scope of the
- token. If the given token does not have a variable for the given
- name, the variable is searched for up the token hierarchy. If
- omitted the globalProcessScope is set to false for retrieving
- variables.
+ The category name of the ESB service. This is required if the
+ <classname>reply-to-originator</classname> functionality is not in
+ use.
</para>
</listitem>
-<listitem>
+
+ <listitem>
+
<para>
- bpmToEsbVars – optional element. This element takes a list of
- mapping subelements to map a jBPM context variable to a location in
- the EsbMessage. Each mapping element can have the following
- attributes:
+ <classname>esbServiceName</classname>
</para>
+
+ <para>
+ This is the name of the ESB service. It is required
+ if the <classname>reply-to-originator</classname>
+ functionality is not in use.
+ </para>
+
+ </listitem>
+ <listitem>
+
+ <para>
+ <classname>replyToOriginator</classname>
+ </para>
+
+
+ <para>
+ This specifies the <emphasis>reply</emphasis> or
+ <emphasis>fault</emphasis> originator address. Upon its creation, this address was
+ stored in the process instance.
+ </para>
+
+ </listitem>
+ <listitem>
+
+ <para>
+ <classname>globalProcessScope</classname>
+ </para>
+
+
+ <para>
+ This element is an optional Boolean-valued parameter. Use it to
+ set the default scope within which the
+ <classname>bpmToEsbVars</classname> variables are to be found. If
+ the <classname>globalProcessScope</classname> is set to
+ <code>true</code>, it searches for the variables within the
+ <firstterm>token hierarchy</firstterm> (that is, the
+ <classname>process-instance</classname> scope.) If, by contrast, it
+ is set to <code>false</code>, it retrieves the variables in the
+ scope of the token. If the token itself does not possess a variable
+ for a given name, then the token hierarchy is used to search for
+ that variable. If the element is omitted altogether, the
+ <classname>globalProcessScope</classname> defaults to
+ <code>false</code>.
+ </para>
+
+ </listitem>
+ <listitem>
+
+ <para>
+ <classname>bpmToEsbVars</classname>
+ </para>
+
+ <para>
+ This element is optional. It takes a list of sub-elements and uses
+ them to map a jBPM context variable to an ESB Message location. Each
+ of these mapping sub-elements can have the following attributes:
+ </para>
+
<itemizedlist>
<listitem>
<para>
@@ -915,48 +1051,66 @@
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/jbpm/esb_jBPM_mapping.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+
<para>
- and one can reference jBPM context variable names directly.
+ The jBPM context-variable names can also be referenced directly.
</para>
</listitem>
-
- <listitem>
+ <listitem>
+
<para>
- esb – optional attribute. The name of the variable on the
- EsbMessage. The name can be a MVEL type expression. By default the
- variable is set as a named parameter on the body of the EsbMessage.
- If you decide to omit the esb attribute, the value of the bpm
- attribute is used.
+ <classname>esb</classname>
</para>
- </listitem>
-
- <listitem>
+
<para>
- default – optional attribute. If the variable is not found in jBPM
- context the value of this field is taken instead.
+ This attribute is optional. It is the name of the variable in the
+ Enterprise Service Bus Message. It can be an MVEL-type expression.
+ (In other words, the attribute value <property>TokenName</property>
+ in the example above is equal to
+ <classname>body.TokenName</classname>. A special value called
+ <code>BODY_CONTENT</code> "addresses" the body directly.) By
+ default, the variable is set as a named parameter on the body of the
+ ESB Message. In order to omit the <classname>esb</classname>
+ attribute, replace it with the value of the
+ <classname>bpm</classname> attribute.
</para>
- </listitem>
-
- <listitem>
+ </listitem>
+ <listitem>
+
<para>
- process-scope – optional attribute. This boolean valued parameter
- can override the setting of the setting of the globalProcessScope
- for this mapping.
+ default
</para>
-</listitem>
+
+ <para>
+ This attribute is optional. If the variable is not found within the
+ jBPM context, the value of this field is taken
+ instead.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>process-scope</classname>
+ </para>
+
+ <para>
+ This attribute is optional. It is a parameter that can contain a
+ Boolean value used to override the setting of the
+ <classname>globalProcessScope</classname> for this mapping.
+ </para>
-</itemizedlist>
+ </listitem>
+ </itemizedlist>
- </listitem>
-</itemizedlist>
+ </listitem>
+ </itemizedlist>
<important>
<para>
- When working on variable mapping configuration it is recommended
- to turn on debug level logging.
+ Always activate
+ <systemitem>debug</systemitem>-level logging when working
+ on the variable mapping configuration.
</para>
</important>
@@ -964,18 +1118,18 @@
<section>
<title>
- EsbActionHandler
+ ESB Action Handler
</title>
<para>
- The EsbActionHandler is designed to work as a reply-response type
- call into JBossESB. The EsbActionHandler should be attached to the
- node. When this node is entered this action will be called. The
- EsbActionHandler executes and leaves the node waiting for a
- transition signal. The signal can come from any other thread of
- execution, but under normal processing the signal will be sent by
- the JBossESB callback Service. An example configuration for the
- EsbActionHandler could look like:
+ The <classname>EsbActionHandler</classname> is designed to work as a
+ reply-response type call into the Enterprise Service Bus. Attach it
+ to the node. This is so that the action is called when the node is
+ entered. The <classname>EsbActionHandler</classname>
+ executes, leaving the node waiting for a transition signal, (which
+ can come from any other thread of execution but will normally be
+ sent by the <classname>JBossESB
+ callback</classname> service.)
</para>
@@ -983,9 +1137,9 @@
<para>
- The configuration for the EsbActionHandler action extends the
- EsbNotifier configuration. The extensions are the following
- subelements:
+ The <classname>EsbActionHandler</classname> action's configuration
+ extends to the settings for the <classname>EsbNotifier</classname>.
+ The extensions consist of the following sub-elements:
</para>
@@ -1006,83 +1160,112 @@
</entry>
<entry>
<para>
- This subelement is identical to the esbToBpmVars
- property mention in the previous section “JBossESB to
- jBPM” for the BpmProcessor configuration. The element
- defines a list of variables that need to be extracted
- from the EsbMessage and set into jBPM context for the
- particular process instance, however, it should be
- noted that the effect of the globalProcessScope value,
- if not specified, will default to true when setting
- variables. The list consists of mapping elements. Each
- mapping element can have the following attributes:
- </para>
+ This identical to the
+ <classname>esbToBpmVars</classname> property for the
+ <classname>BpmProcessor</classname> configuration. The sub-element
+ defines a list of variables that need to be extracted from the ESB
+ message and set in the Business Process Manager context for that
+ particular process instance. If left unspecified, the
+ <classname>globalProcessScope</classname> value defaults to
+ <code>true</code> when the variables are set.
+ </para>
-
+ <para>
+ The list consists of mapping elements, each of which can have the
+ following attributes:
+ </para>
<itemizedlist>
- <listitem>
- <para>
- esb – required attribute which can contain an MVEL
- expression to extract a value anywhere from the
- EsbMessage.
- </para>
+ <listitem>
+
+ <para>
+ <classname>esb</classname>
+ </para>
+
+ <para>
+ This is a required attribute which can contain an MVEL expression.
+ Use it to extract a value and put it into the ESB Message from
+ anywhere.
+ </para>
</listitem>
+ <listitem>
+
+ <para>
+ <classname>bpm</classname>
+ </para>
+
+ <para>
+ This is an optional attribute containing the name which is to be
+ used by the jBPM. If it is not supplied, then the
+ name in <classname>esb</classname> is used instead.
+ </para>
- <listitem>
- <para>
- bpm – optional attribute containing the name which be used
- on the jBPM side. If omitted the esb name is used.
- </para>
</listitem>
-
- <listitem>
- <para>
- default – optional attribute which can hold a default value
- if the esb MVEL expression does not find a value set in the
- EsbMessage.
- </para>
- </listitem>
+ <listitem>
+
+ <para>
+ default
+ </para>
+
+ <para>
+ Use this is an optional attribute to hold a default
+ value if the <classname>esb</classname> MVEL
+ expression cannot find one that is set in the
+ Enterprise Service Bus message.
+ </para>
- <listitem>
- <para>
- process-scope – optional attribute. This boolean valued
- parameter can override the setting of the setting of
- the globalProcessScope for this mapping.
- </para>
+ </listitem>
+ <listitem>
+
+ <para>
+ <classname>process-scope</classname>
+ </para>
+
+ <para>
+ This is an optional parameter consisting of a Boolean value. Use it
+ to override the setting of this mapping's e
+ <classname>globalProcessScope</classname>.
+ </para>
- </listitem>
-</itemizedlist>
+ </listitem>
+ </itemizedlist>
</entry>
<entry>No</entry>
- </row>
+ </row>
- <row>
+ <row>
<entry>
<property>exceptionTransition</property>
</entry>
<entry>
<para>
- The name of the transition that should be taken if an
- exception occurs while processing the Service. This
- requires the current node to have more then one
- outgoing transition where one of the transition
- handles “exception processing”.
+ This the name of the transition
+ to utilize if an exception occurs whilst the
+ service is being processed. This element requires the current
+ node to have more than one outgoing transition and for one of
+ those transitions to handle <firstterm>exception
+ processing</firstterm>.
</para>
</entry>
<entry>No</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
+ </row>
+
+
+ </tbody></tgroup>
+ </table>
+
+
+
+
<para>
- Optionally you may want to specify a timeout value for this
- action. For this you can use a jBPM native Timer on the node.
- If for example you only want to wait 10 seconds for the Service
- to complete you could add
+ A time-out value can be specified for this action (it is
+ optional.) To do so, use a jBPM-native
+ <firstterm>timer</firstterm> on the node. The next example
+ demonstrates how to add a time-out value so that, if no signal
+ is received within ten seconds of entering this node, a
+ transition called <classname>time-out</classname> is triggered:
</para>
@@ -1099,52 +1282,53 @@
<section>
<title>
- Exception Handling jBPM -> JBossESB
+ jBPM-to-ESB Exception Handling
</title>
<para>
- There are two types of scenarios where exceptions can arise.
+ There are two scenarios in which exceptions can arise:
</para>
<orderedlist>
<listitem>
- <para>
- The first type of exception is a
- MessageDeliveryException which is thrown by the
- ServiceInvoker. If this occurs it means that
- delivery of the message to the ESB failed. If this
- happens things are pretty bad and you have probably
- misspelled the name of the Service you are trying
- to reach. This type of exception can be thrown from
- both the EsbNotifier as well as the
- EsbActionHandler. In the jBPM node one can add an
- <ulink
- url="http://docs.jboss.com/jbpm/v3/userguide/processmodelling.html"
- /> [TB-JBPM-USER] to handle this exception.
- </para>
- </listitem>
+ <para>
+ The <classname>ServiceInvoker</classname> will throw a
+ <exceptionname>MessageDeliveryException</exceptionname> when
+ delivery of the message to the <application>Enterprise
+ Service Bus</application> fails. This happens when the user
+ has mis-spells the name of the service that he or she is
+ trying to reach. This type of exception can be thrown from
+ both the <classname>EsbNotifier</classname> and the
+ <classname>EsbActionHandler</classname>. It is possible to
+ add an <classname>ExceptionHandler</classname>
+ (<classname>TB-JBPM-USER</classname> ) that can deal with
+ this situation to the jBPM node. (See <ulink
+ url="http://docs.jboss.com/jbpm/v3/userguide/processmodelling.html"
+ /> for more information.)
+ </para>
+ </listitem>
- <listitem>
- <para>
- The second type of exception is when the Service
- received the request, but something goes wrong
- during processing. Only if the call was made from
- the EsbActionHandler does it makes sense to report
- back the exception to jBPM. If the call was made
- from the EsbNotifier jBPM processing has already
- moved on, and it is of little value to notify the
- process instance of the exception. This is why the
- exception-transition can only be specified for
- EsbAction-Handler.
- </para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>
+ The second type of exception occurs when the service
+ receives a request successfully only for something to go
+ wrong during subsequent processing. Only if the call was
+ made from the <classname>EsbActionHandler</classname> does
+ it makes sense to report the exception back to
+ <application>Business Process Manager</application>. This is
+ due to the fact that, if the call was made from the
+ <classname>EsbNotifier</classname>, then jBPM processing has
+ already moved on, and it would, therefore, be of little
+ value to notify the process instance of the problem.
+ </para>
+ </listitem>
+ </orderedlist>
<para>
- To illustrate the type of error handling that is now possible
- using standard jBPM features we will discuss some scenarios
- illustrated below:
+ The following scenarios illustrate the kind of error
+ handling that it is now possible to achieve using standard
+ jBPM features.
</para>
@@ -1154,39 +1338,40 @@
<section>
<title>
- Scenerio One: Time-out
+ Scenario One: Time-out
</title>
+
+
<para>
- When using the EsbActionHandler action and the node is waiting
- for a callback, it maybe that you want to limit how long you
- want to wait for. For this scenario you can add a timer to the
- node. This is how Service1 is setup in Figure 5. The timer can
- be set to a certain due date. In this case it is set to 10
- seconds. The process definition configuration would look like
+ If one is using the <classname>EsbActionHandler</classname>
+ action and the node is awaiting a callback, then it may be
+ advantageous to limit the waiting period. To do so,
+ add a timer to the node. That is how <literal>Service1</literal>
+ is configured in the diagram. The timer can be set for a certain
+ period, which, in this case, is ten seconds:
</para>
+<programlisting language="XML"><xi:include href="extras/jbpm/scenario_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-<programlisting language="XML" role="XML"><xi:include href="extras/jbpm/scenario_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
-
-
-
-
+
<para>
- Node “Service1” has 2 outgoing transitions. The first one is
- called “ok” while the second one is called
- “time-out-transition”. Under normal processing the call back
- would signal the default transition, which is the “ok”
- transition since it is defined first. However if the execution
- of the service takes more then 10 seconds the timer will fire.
- The transition attribute of the timer is set to
- “time-out-transition”,so this transition will be taken on
- time-out. In Figure 5 this means that the processing ends up in
- the “ExceptionHandling” node in which one can perform
- compensating work.
+ <literal>Service1</literal> has two outgoing transitions. The
+ first of these is called <classname>ok</classname> whilst the
+ second one is named
+ <classname>time-out-transition</classname>. Under normal
+ processing conditions, the call-back would signal the default
+ transition, which is the <classname>ok</classname>, since it
+ is defined as the first. However, if the processing of the
+ service takes more then ten seconds, the timer will execute. The
+ <property>transition</property> attribute of the timer is set to
+ <classname>time-out-transition</classname>, meaning that this
+ transition will be taken on time-out. Look at the diagram and
+ observe that the processing ends up in the
+ <classname>ExceptionHandling</classname> node. From here, one can
+ perform compensatory work.
</para>
- <figure id="fig5"><title>Three Exception Handling Scenarios:
+ <figure id="fig5"><title>Three Exception Handling Scenarios:
Time-Out, Exception-Transition and Exception-Decision.</title>
<mediaobject>
<imageobject>
@@ -1197,31 +1382,38 @@
</section>
- <section>
+
+</section>
+
+<section>
<title>
Scenario Two: Exception Transition
</title>
- <para>
- To handle exception that may occur during processing of the
- Service, one can define an exceptionTransition. When doing so
- the faultTo EPR is set on the message such that the ESB will
- make a callback to this node, signaling it with the
- exceptionTransition. Service2 has two outgoing transitions.
- Transition “ok” will be taken under normal processing, while
- the “exception” transition will be taken when the Service
- processing throws an exception. The definition of Service2
- looks like
- </para>
+ <para>
+ One can define an <classname>exceptionTransition</classname> to handle
+ any exceptions that may occur whilst the service is being
+ processed. Doing so results in the <classname>faultTo</classname>
+ end point reference being set on the message, meaning that the
+ Enterprise Service Bus will make a call-back to this node. It is
+ this call-back that signals the
+ <classname>exceptionTransition</classname>.
+ <literal>Service2</literal> has two outgoing transitions:
+ Transition <classname>ok</classname> will be taken under normal
+ processing, whilst the <classname>exception</classname>
+ transition will be taken when the service has, as its name
+ inidcates, thrown an exception during processing.
+ </para>
<programlisting language="XML" role="XML"><xi:include href="extras/jbpm/scenario_2_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- where in the action, the exceptionTransition is set to “exception”.
- In this scenario the process also ends in the “ExceptionHandling”
- node.
+ In the preceding definition of <literal>Service2</literal>, the
+ action's <property>exceptionTransition</property> is set to
+ “exception.” Note that, in this scenario the process
+ also ends up in the <classname>ExceptionHandling</classname> node.
</para>
</section>
@@ -1233,13 +1425,15 @@
</title>
<para>
- Scenario 3 is illustrated in the configuration of Service3 and the
- “exceptionDecision” node that follows it. The idea is that
- processing of Service3 completes normally and the default
- transition out of node Service3 is taken. However, somewhere during
- the Service execution an errorCode was set, and the
- “exceptionDecision” node checks if a variable called “errorCode”
- was set. The configuration would look like
+ In order to understand this final scenario, study the configuration
+ of <literal>Service3</literal> and the
+ <classname>exceptionDecision</classname> node that follows it. As
+ can be seen <literal>Service3</literal> processes and completes
+ normally and the default transition out of its node occurs as one
+ would expect. However, at some point during the service execution,
+ an <classname>errorCode</classname> was set, and the
+ <classname>exceptionDecision</classname> node checks if a variable
+ of the same name has been called here:
</para>
@@ -1247,26 +1441,28 @@
<para>
- where the esbToBpmVars mapping element extracts the errorCode
- called “Some-ExceptionCode” from the EsbMessage body and sets in
- the jBPM context, if this “SomeExceptionCode” is set that is. In
- the next node “exceptionDecision” the “ok” transition is taken
- under normal processing, but if a variable called “errorCode” is
- found in the jBPM context, the “exceptionCondition” transition is
- taken. This is using the decision node feature of jBPM where
- transition can nest a condition. Here we check for the existence
- of the “errorCode” variable using the condition
+ In the above example, the <classname>esbToBpmVars</classname>
+ mapping element extracts the <classname>errorCode</classname>
+ called <classname>SomeExceptionCode</classname> from the Enterprise
+ Service Bus message body and sets in the jBPM context. (This is
+ provided that the <classname>SomeExceptionCode</classname> is set.)
+ In the next node, named <classname>exceptionDecision</classname>,
+ the <code>ok</code> transition is taken if processing is normal,
+ but if a variable called <classname>errorCode</classname> is found
+ in the jBPM context, the <classname>exceptionCondition</classname>
+ transition is taken instead. This is achieved by using the jBPM's
+ <firstterm>decision node</firstterm> feature, by means of
+ which transitions can nest within a condition.
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/jbpm/scenario_3_b.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
- For more details on conditional transitions please see the
- jBPM documentation [TB-JBPM-USER].
+ To learn more about conditional transitions, please
+ refer to the <emphasis>jBPM Reference Guide</emphasis>.
</para>
</note>
-
- </section>
+
</section>
</chapter>
More information about the jboss-svn-commits
mailing list