[jboss-svn-commits] JBL Code SVN: r34732 - in labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US: extras/advanced and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Aug 15 19:29:07 EDT 2010
Author: dlesage
Date: 2010-08-15 19:29:06 -0400 (Sun, 15 Aug 2010)
New Revision: 34732
Added:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway2.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway3.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway4.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway5.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway6.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway7.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway8.xmlt
Modified:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Advanced_Topics.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Building_and_Using_Services.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Configuration.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Connectors_and_Adapters.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Example.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Fault-tolerance_and_Reliability.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/JBossESB.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Other_Components.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Service_Orientated_Architecture_Overview.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Services_and_Messages.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/The_Enterprise_Service_Bus.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Web_Services_Support.xml
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Writing_JAXB_Annotation_Introduction_Configurations.xml
Log:
JBESB 3460
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Advanced_Topics.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Advanced_Topics.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Advanced_Topics.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -12,81 +12,81 @@
<para>
- In this Chapter we shall look at some more advanced concepts within
- JBossESB.
+ Read this chapter to learn about some of the more advanced concepts related to
+ the <application>JBoss Enterprise Service Bus</application>.
</para>
<section>
<title>
- Fail-over and load-balancing support
+ Fail-Over and Load-Balancing Support
</title>
<para>
- In mission critical systems it is important to design with
- redundancy in mind. JBossESB 4.2.GA is the first version with
- built-in fail-over, load balancing and delayed message
- redelivery to help you build a robust architecture. When you
- use SOA it is implied that the Service has become the building
- unit. JBossESB allows you to replicate identical services
- across many nodes. Where each node can be a virtual or physical
- machine running an instance of JBossESB. The collective of all
- these JBossESB instances is called "The Bus". Services within
- the bus use different delivery channels to exchange messages.
- In ESB terminology one such channel maybe JMS, FTP, HTTP, etc.
- These different "protocols" are provided by systems external to
- the ESB; the JMS-provider, the FTP server, etc. Services can be
+ Design mission-critical systems with redundancy in mind. The
+ <application>JBoss Enterprise Service Bus</application>
+ includes built-in fail-over support, load-balancing and delayed
+ message re-delivery. Take advantage of thse features to build a
+ robust infrastructure. (It is assumed that the service is, by
+ now, the basic building unit.) The JBoss Enterprise Service Bus
+ allows one to replicate identical services across many nodes,
+ whereby each node can be a virtual or physical machine running
+ an instance of the ESB. The collective term for all of these
+ ESB instances is the <firstterm> bus</firstterm>. Services
+ within the bus use different delivery channels to exchange
+ messages. In the ESB, such a channel may use any of these
+ protocols: JMS, FTP or HTTP. These different protocols are
+ provided by systems external to the ESB, such as the
+ JMS-provider, the FTP server and so forth. Services can be
configured to listen to one or more protocols. For each
- protocol that it is configured to listen on, it creates an End
- Point Reference (EPR) in the Registry.
+ protocol for which it is configured to listen, the ESB creates
+ an end-point reference in the
+ <systemitem>registry</systemitem>.
</para>
<section>
<title>
- Services, EPRs, listeners and actions
+ Services, End-Point References, Listeners and Actions
</title>
<para>
- As we have discussed previously, within the jboss-esb.xml
- each service element consists of one or more listeners and
- one or more actions. Let's take a look at the
- JBossESBHelloworld example. The configuration fragment
- below is loosely based on the configuration of the
- JBossESBHelloworld example. When the service initializes it
- registers the category, name and description to the UDDI
- registry. Also for each listener element it will register a
- ServiceBinding to UDDI, in which it stores an EPR. In this
- case it will register a JMSEPR for this service, as it is a
- jms-listener. The jms specific like queue name etc are not
- shown, but appeared at the top of the jboss-esb.xml where
- you can find the 'provider' section. In the jms-listener we
- can simply reference the "quickstartEsbChannel" in the
- busidref attribute.
- </para>
+ Within the <filename>jboss-esb.xml</filename> file, each
+ service element consists of one or more listeners and
+ actions. The configuration fragment below is loosely based
+ upon that for the <filename>JBossESBHelloworld</filename>
+ example. When the service is initialised, it registers the
+ category, name and description in the <systemitem>UDDI
+ registry</systemitem>. Also, it
+ will register a <classname>ServiceBinding</classname> to the
+ UDDI for each listener element. It stores these in an end-point reference.
+ </para>
<programlisting language="XML" role="XML"><xi:include href="extras/advanced/Code_Example10.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Given the category and service name, another service can
- send a message to our Hello World Service by looking up the
- Service in the Registry. It will receive the JMSEPR and it
- can use that to send a message to. All this heavy lifting
- is done in the ServiceInvoker class. When our HelloWorld
- Service receives a message over the quickstartEsbChannel,
- it will hand this message to the process method of the
- first action in the ActionPipeline, which is the
- SystemPrintln action.
+ If it is given the category and service names, another
+ service can find the <literal>Hello World</literal>
+ <systemitem>registry</systemitem> and send it a message.
+ The service will then receive the <code>JMSEPR</code> use
+ it to send the message. All of this "heavy lifting" is
+ undertaken by the <classname>ServiceInvoker</classname>
+ class. When one's "Hello World" service receives a message
+ over the <classname>quickstartEsbChannel</classname>, it
+ passes it to the process method belonging to
+ <classname>SystemPrintln</classname>, which is the first
+ action in the <systemitem>pipeline</systemitem>.
</para>
<note>
<para>
- Because ServiceInvoker hides much of the fail-over
- complexity from users, it necessarily only works with
- native ESB Messages. Furthermore, in JBossESB 4.2.1 not
- all gateways have been modified to use the
- ServiceInvoker, so incoming ESB-unaware messages to
- those gateway implementations may not always be able to
- take advantage of service fail-over.
+ Because the <classname>ServiceInvoker</classname> hides
+ much of the fail-over complexity from users, it only
+ works with native ESB messages. In addition, not every
+ gateway has been modified to use the
+ <classname>ServiceInvoker</classname>. Therefore,
+ incoming ESB-unaware messages for those gateway
+ implementations are sometimes unable to take advantage
+ of service fail-over.
</para>
</note>
@@ -98,62 +98,62 @@
</title>
<para>
- In our example we have this service running on let's say
- Node1. What happens if we simply take the helloworld.esb
- and deploy it to Node2 as well (see figure 7-2)? Let's say
- we're using jUDDI for our Registry and we have configured
- all our nodes to access one central jUDDI database (it is
- recommended to use a clustered database for that). Node2
- will find that the FirstServiceESB - SimpleListener Service
- is already registered! It will simply add a second
- ServiceBinding to this service. So now we have 2
- ServiceBindings for this Service. We now have our first
- replicated Service! If Node1 goes down, Node2 will keep on
- working.
+ In the example, the service is running on
+ <literal>Node1</literal>. If one simply takes the
+ <filename>helloworld.esb</filename> file and deploy it on
+ <literal>Node2</literal> as well (see the illustration
+ below), then <literal>Node2</literal> will find that the
+ <literal>FirstServiceESB - SimpleListener</literal> service
+ is already registered. Therefore, it adds a second
+ <systemitem>ServiceBinding</systemitem> to this service,
+ replicating it. If <literal>Node1</literal> fails,
+ <literal>Node2</literal> will still continue to function.
</para>
- <figure id="figu-SOA_ESB_Programmers_Guide-Advanced_Topics-Service_Instances">
+ <figure>
<title>Two service instances each on a different node.</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/advanced/chapter7_helloworld_qs_example_2_instance_4_node.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/advanced/chapter7_helloworld_qs_example_2_instance_4_node.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- You will get load balancing as both service instances
- listen to the same queue. However this means that we still
- have a single point of failure in our setup. This is where
- Protocol Clustering maybe an option, which we shall
- describe in the next section.
+ Load balancing has been achieved because both service
+ instances listen to the same queue. However, this means that
+ one will still have a single point of failure in one's
+ configuration. This is where <firstterm>protocol
+ clustering</firstterm> may be an option. It will be
+ described in the next section.
</para>
<para>
- This type of replication can be used to increase the
+ This type of replication can be used to either increase the
availability of a service or to provide load balancing. To
- further illustrate, consider the diagram below which has a
- logical service (Application Service) that is actually
- comprised of 4 individual services, each of which provides
- the same capabilities and conforms to the same service
- contract. They differ only in that they do not need to
- share the same transport protocol. However, as far as the
- users of Application Service are concerned they see only a
- single service, which is identified by the service name and
- category. The ServiceInvoker hides the fact that
- Application Service is actually composed of 4 other
- services from the clients. It masks failures of the
- individual services and will allow clients to make forward
- progress as long as at least one instance of the replicated
- service group remains available.
+ understand more fully, consider the diagram below, which has
+ a logical service (an application service.) This logical
+ service is actually comprised of four individual services,
+ each of which provides the same capabilities and conforms to
+ the same service contract. They differ only in that they do
+ not need to share the same transport protocol. However, as
+ far as the users of the application service are concerned,
+ they see only a single service, which is identified by the
+ service name and category. The
+ <classname>ServiceInvoker</classname> hides the fact that
+ the application service is actually composed of these four
+ other services from the clients by masking their failures It
+ will allow clients to "make forward progress" as long as at
+ least one instance of the replicated service group remains
+ available.
</para>
- <note>
+ <important>
<para>
- This type of replication should only be used for
+ Only use this type of replication for
stateless services.
</para>
- </note>
+ </important>
<mediaobject>
<imageobject>
@@ -162,17 +162,19 @@
</mediaobject>
<para>
- Replication of services may be defined by service providers
- outside of the control of service consumers. As such, there
- may be times when the sender of a message does not want to
- silently fail-over to using an alternative service if one
- is mentioned within the Registry. As such, if the Message
- property org.jboss.soa.esb.exceptionOnDeliverFailure is set
- to true then no retry attempt will be made by the
- ServiceInvoker and MessageDeliverException will be thrown.
- If you want to specify this approach for all Messages then
- the same property can be defined within the Core section of
- the JBossESB property file.
+ Although providers can replicate services independently of
+ their consumers, in some circumstances the sender of a
+ message will not want silent fail-over to occur. One needs
+ to set a message property called
+ <property>org.jboss.soa.esb.exceptionOnDeliverFailure</property>
+ to <code>true</code> in order to prevent automatic, silent
+ fail-over. When this property has been set, the
+ <classname>ServiceInvoker</classname> throws an
+ <classname>MessageDeliverException</classname> instead of
+ attempting to re-send the message. This property can be
+ specified for all Messages by setting it in the
+ <property>Core</property> section of the JBoss Enterprise
+ Service Bus <filename>property</filename> file.
</para>
</section>
@@ -183,40 +185,42 @@
</title>
<para>
- Some JMS providers can be clustered. JBossMessaging (<ulink
- url="http://community.jboss.org/wiki/JBossMessaging" />)is
- one of these providers, which is why we use this as our
- default JMS provider in JBossESB (<ulink
- url="http://community.jboss.org/wiki/jbossesb" />). When
- you cluster JMS you remove a single point of failure from
- your architecture.
+ Some Java Message Service providers can be clustered.
+ <classname>JBossMessaging</classname> is one of these, which
+ is why it was chosen as the JMS provider
+ for the Enterprise Service Bus. When this
+ JMS is clustered, a single point of failure is removed
+ from the architecture (see the next diagram.)
</para>
- <figure><title>Example of Protocol Clustering Using <abbrev>JMS</abbrev></title>
+ <figure><title>Example of Protocol Clustering Using JMS</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/advanced/chapter7_protocol_clustering_1.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/advanced/chapter7_protocol_clustering_1.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- Please read the documentation on Clustering for
- JBossMessaging (<ulink
- url="http://community.jboss.org/wiki/JBossMessaging" />) if
- you want to enable JMS clustering. Both JBossESB
- replication and JMS clustering can be used together, as
- illustrated in the following figure. In this example,
- Service A is identified in the registry by a single JMSEpr.
- However, opaquely to the client, that JMSEpr points to a
- clustered JMS queue, which has been separately configured
- (in an implementation manner) to support 3 services. This
- is a federated approach to availability and load balancing.
- In fact masking the replication of services from users (the
- client in the case of the JBossESB replication approach,
- and JBossESB in the case of the JMS clustering) is in line
- with SOA principles: hiding these implementation details
- behind the service endpoint and not exposing them at the
- contract level.
+ One should read the documentation on "Clustering for
+ JBossMessaging," if one wants to enable this functionality.
+ Both JBoss ESB replication and
+ JMS clustering can be used together, as
+ shown in the following illustration. In this example, Service
+ A is identified in the registry by a single
+ JMS end-point reference. However, the
+ EPR points to a clustered
+ JMS queue, which has been separately
+ configured to support three services. The client cannot see
+ this. This is known as a "federated" approach to
+ availability and load balancing. In fact, masking the
+ replication of services from users is in accordance with
+ SOA principles, which dictate that one
+ should hide the implementation details behind the service
+ end-point and not expose them at the contract level. (This
+ masking of replication is done to the client in the case of
+ the JBoss ESB replication approach, and to
+ the JBoss ESB itself in the case of the
+ Java Message Service clustering.)
</para>
<mediaobject>
@@ -227,21 +231,22 @@
<note>
<para>
- If using JMS clustering in this way you will obviously
- need to ensure that your configuration is correctly
- configured. For instance, if you place all of your ESB
- services within a JMS cluster then you cannot expect to
- benefit from ESB replication.
+ If one is using JMS clustering in this
+ way, ensure that the
+ configuration is correct. For instance, if all
+ of one's ESB services are placed within a
+ JMS cluster, no
+ benefit from replication could be expected.
</para>
</note>
<para>
- Other examples of Protocol Clustering would be a NAS for
- the FileSystem protocol, but what if your provider simply
- cannot provide any clustering? Well in that case you can
- add multiple listeners to your service, and use multiple
- (JMS) providers. However this will require fail-over and
- load-balancing across providers which leads us to the next
+ Another examples of Protocol Clustering is a NAS (<firstterm>Network Attached Storage</firstterm>) for
+ the <literal>FileSystem</literal> protocol, but what if one's provider simply
+ cannot provide any clustering? In that case, you can
+ add multiple listeners to your service and use multiple
+ (JMS) providers. However, this will require fail-over and
+ load-balancing across providers. This is discussed in the next
section.
</para>
@@ -253,12 +258,10 @@
</title>
<para>
- If you would like to run the same service on more than one
- node in a cluster you have to wait for service registry
- cache revalidation before the service is fully working in
- the clustered environment. You can setup this cache
- revalidation timeout in
- deploy/jbossesb.sar/jbossesb-properties.xml:
+ If you would like to run the same service on more than one node in a cluster, you
+ have to wait for service registry cache re-validation. This must occur before the service is fully working
+ in the clustered environment. You can setup this cache re-validation timeout in
+ <filename>deploy/jbossesb.sar/jbossesb-properties.xml</filename>:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/advanced/clustering.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -276,19 +279,19 @@
</title>
<para>
- Our HelloWorld Service can listen to more then 1 protocol.
- Here we have added a JMS channel.
+ The <classname>HelloWorld</classname> Service can listen to
+ more than one protocol. An extra JMS channel has been added here:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/advanced/Code_Example11.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Now our Service is simultaneously listening to two JMS
- queues. Now these queues can be provided by JMS providers
- on different physical boxes! So we now have a made a
- redundant JMS connection between two services. We can even
- mix protocols in this setup, so we can also add and
- ftp-listener to the mix.
+ Now your Service is simultaneously listening to two JMS
+ queues. These queues can be provided by JMS providers on
+ different physical boxes. Therefore, you now have a redundant
+ JMS connection between two services. You can even mix
+ protocols in this setup, so you can also add an ftp-listener
+ to the mix.
</para>
<figure id="figu-SOA_ESB_Programmers_Guide-Advanced_Topics-Adding_two_FTP_Servers">
@@ -298,7 +301,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/advanced/chapter7_load_balancing_ftp.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata align="center" fileref="images/advanced/chapter7_load_balancing_ftp.png" />
</imageobject>
</mediaobject>
</figure>
@@ -307,20 +310,21 @@
<para>
- When the ServiceInvoker tries to deliver a message to our
- Service it will get a choice of 8 EPRs now (4 EPRs from
- Node1 and 4 EPRs from Node2). How will it decide which one
- to use? For that you can configure a Policy. In the
- jbossesb-properties.xml you can set the
+ When the <classname>ServiceInvoker</classname> tries to
+ deliver a message to our Service, it will receive a choice of eight
+ EPRs now (four each from Node1 and Node2.) How will
+ it decide which one to use? For that, you can configure a
+ Policy. In the <filename>jbossesb-properties.xml</filename>, you can set the
'org.jboss.soa.esb.loadbalancer.policy'. Right now three
- Policies are provided, or you can create your own.
+ Policies are provided. You can also create your own. Here are the
+ three provided policies:
</para>
<itemizedlist>
<listitem>
<para>
First Available. If a healthy ServiceBinding is
- found it will be used unless it dies, and it will
+ found, then it will be used unless it dies. It will
move to the next EPR in the list. This Policy does
not provide any load balancing between the two
service instances.
@@ -328,27 +332,28 @@
</listitem>
<listitem>
<para>
- Round Robin. Typical Load Balance Policy where each
+ Round Robin. This is typical Load Balance Policy where each
EPR is hit in order of the list.
</para>
</listitem>
<listitem>
<para>
- Random Robin. Like the other Robin but then random.
+ Random Robin. Like the Round Robin but then random.
</para>
</listitem>
</itemizedlist>
<para>
- The EPR list the Policy works with may get smaller over
- time as dead EPRs will be removed from the (cached) list.
- When the list is exhausted or the time-to-live of the list
- cache is exceeded, the ServiceInvoker will obtain a fresh
- list of EPRs from the Registry. The
- 'org.jboss.soa.esb.registry.cache.life' can be set in the
- jbossesb-properties file, and is defaulted to 60,000
- milliseconds. What if none of the EPRs work at the moment?
- This is where we may use Message Redelivery Service.
+ The EPR list with which the Policy works may become smaller
+ over time
+ as dead EPRs are removed from the (cached) list. When the
+ list is emptied or the "time-to-live" of the cache is
+ exceeded, the ServiceInvoker will obtain a fresh list of
+ EPRs from the Registry. The
+ <classname>org.jboss.soa.esb.registry.cache.life</classname> can be set
+ in the jbossesb-properties file. Its default is 60,000
+ milliseconds. If you find that none of the EPRs work,
+ you may use the Message Redelivery Service.
</para>
</section>
@@ -358,35 +363,34 @@
</title>
<para>
- If the list of EPRs contains nothing but dead EPRs the
+ If the list contains nothing but dead EPRs, the
ServiceInvoker can do one of two things:
</para>
<itemizedlist>
<listitem>
<para>
- If you are trying to deliver the message
- synchronously it will send the message to the
- DeadLetterService, which by default will store to
- the DLQ MessageStore, and it will send a failure
- back to the caller. Processing will stop. Note that
- you can configure the DeadLetterService in the
- jbossesb.esb if for instance you want it to go to a
- JMS queue, or if you want to receive a
- notification.
- </para>
+ If you are trying to deliver the message
+ synchronously, it will be sent to the
+ DeadLetterService, which, by default, will store to
+ the DLQ MessageStore. It will then send a failure
+ back to the caller and processing will stop. Note that
+ you can configure the DeadLetterService in the
+ jbossesb.esb if, for instance, you want it to go to a
+ JMS queue or if you want to receive a notification.
+ </para>
</listitem>
<listitem>
<para>
- If you are trying to deliver the message
- asynchronously (recommended), it too will send the
- message to the DeadLetterService, but the message
- will get stored to the RDLVR MessageStore. The
- Redeliver Service (jbossesb.esb) will retry sending
- the message until the maximum number of redelivery
- attempts is exceeded. In that case the message will
- get stored to the DLQ MessageStore and processing
+ If you are trying to deliver the message
+ asynchronously (as is recommended), it, too, will send the
+ message to the DeadLetterService but the message
+ will be stored in the RDLVR MessageStore. The
+ Redeliver Service (jbossesb.esb) will keep retrying to send
+ the message until the maximum number of redelivery
+ attempts is exceeded. In that case, the message will
+ be stored in the DLQ MessageStore and processing
will stop.
</para>
</listitem>
@@ -395,7 +399,7 @@
<figure><title>Message Re-delivery</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/advanced/chapter7_mesage_redelivery.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/advanced/chapter7_mesage_redelivery.png" />
</imageobject>
</mediaobject>
</figure>
@@ -404,15 +408,17 @@
<note>
<para>
- The DeadLetterService is turned on by default, however
- in the jbossesb-properties.xml you could set
- org.jboss.soa.esb.dls.redeliver to false to turn off
- its use. If you want to control this on a per message
- basis then set the org.jboss.soa.esb.dls.redeliver
- property in the specific Message properties
- accordingly. The Message property will be used in
- preference to any global setting. The default is to use
- the value set in the configuration file.
+ The <literal>DeadLetterService</literal> is turned on
+ by default. However in the
+ <filename>jbossesb-properties.xml</filename>, you can
+ set <classname>org.jboss.soa.esb.dls.redeliver</classname>
+ to "false" to turn it off. If you want to control
+ this on a per-message basis, set the
+ <classname>org.jboss.soa.esb.dls.redeliver</classname>
+ property in the specific Message's properties accordingly.
+ The Message property will be used in preference to
+ any global setting. The default is to use the value set
+ in the configuration file.
</para>
</note>
@@ -425,29 +431,31 @@
</title>
<para>
- JBossESB 4.8 supports 2 types of providers:
+ JBoss supports 2 types of providers:
</para>
<orderedlist>
<listitem>
<para>
- Bus Providers, which supply messages to action
- processing pipelines via messaging protocols such as
- JMS and HTTP. This provider type is “triggered” by the
- underlying messaging provider.
- </para>
+ Bus Providers, which supply messages to action
+ processing pipelines via messaging protocols such as JMS and HTTP.
+ This type is “triggered” by the underlying
+ messaging provider.
+ </para>
+
</listitem>
<listitem>
<para>
- Schedule Providers, which supply messages to action
- processing pipelines based on a schedule driven model
- i.e. where the underlying message delivery mechanism
- (e.g. the file system) offers no support for triggering
- the ESB when messages are available for processing, a
- scheduler periodically triggers the listener to check
- for new messages.
- </para>
+ Schedule Providers, which supply messages to action
+ processing pipelines based on a schedule-driven model.
+ (In other words, where the underlying message delivery mechanism, such as
+ the file system, offers no support for triggering
+ the ESB when messages are available for processing, a
+ scheduler periodically triggers the listener to check
+ for new messages.)
+ </para>
+
</listitem>
</orderedlist>
@@ -457,13 +465,10 @@
</para>
<para>
- JBossESB 4.8 offers a <schedule-listener> as well as 2
- <schedule-provider> types - <simple-schedule> and
- <cron-schedule>. The <schedule-listener> is
- configured with a “composer” class, which is an implementation
- of the
- org.jboss.soa.esb.listeners.ScheduledEventMessageComposer
- interface..
+ JBoss ESB offers a <schedule-listener> as well as 2 <schedule-provider>
+ types: <simple-schedule> and <cron-schedule>. The <schedule-listener> is
+ configured with a “composer” class, which is an implementation of the
+ <classname>org.jboss.soa.esb.listeners.ScheduledEventMessageComposer</classname> interface.
</para>
<section>
@@ -472,8 +477,8 @@
</title>
<para>
- This schedule type provides a simple scheduling
- capability based on a the following attributes:
+ This schedule type provides a simple capability
+ based on the following attributes:
</para>
<variablelist>
@@ -507,21 +512,20 @@
<term>startDate</term>
<listitem>
<para>
- The schedule start date and time. The format of
- this attribute value is that of the XML Schema
- type “dateTime”. See <ulink
- url="http://books.xmlschemata.org/relaxng/ch19-77049.html" />.
+
+ The schedule start date and time. The format
+ of this attribute value is that of the XML
+ Schema type “dateTime”. See dateTime.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term> endDate </term>
+ <term>endDate</term>
<listitem>
<para>
- The schedule end date and time. The format of
- this attribute value is that of the XML Schema
- type “dateTime”. See <ulink
- url="http://books.xmlschemata.org/relaxng/ch19-77049.html" />.
+ The schedule end date and time. The
+ format of this attribute value is that of the
+ XML Schema type “dateTime”. See dateTime.
</para>
</listitem>
</varlistentry>
@@ -530,61 +534,67 @@
<para>
Example:
</para>
-<programlisting language="XML" role="XML"><xi:include href="extras/advanced/Code_Example12.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+<programlisting language="XML">
+<xi:include href="extras/advanced/Code_Example12.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+</programlisting>
</section>
- <section>
+ <section id="sect-SOA_ESB_Programmers_Guide-Scheduling_of_Services-Cron_Schedule">
<title>
Cron Schedule
</title>
<para>
- This schedule type provides scheduling capability based on
- a CRON expression. The attributes for this schedule type
+ This schedule type provides scheduling capability based on
+ a CRON expression. The attributes for this schedule type
are as follows:
</para>
-
+
<variablelist>
<varlistentry>
- <term>scheduleid</term>
- <listitem>
+ <term> scheduleid </term>
+ <listitem>
+
<para>
A unique identifier string for the schedule.
Used to reference a schedule from a listener
- </para>
+ </para>
+
</listitem>
</varlistentry>
-
<varlistentry>
- <term>cronExpression</term>
- <listitem>
+ <term> cronExpression </term>
+ <listitem>
+
<para>
CRON expression
- </para>
+ </para>
+
</listitem>
</varlistentry>
-
<varlistentry>
- <term>startDate</term>
- <listitem>
+ <term> startDate </term>
+ <listitem>
+
<para>
The schedule start date and time. The format
of this attribute value is that of the XML
- Schema type “dateTime”. See <ulink
- url="http://books.xmlschemata.org/relaxng/ch19-77049.html"/>.
- </para>
+ Schema type “dateTime”. See dateTime.
+ </para>
+
</listitem>
</varlistentry>
<varlistentry>
- <term>endDate</term>
+ <term> endDate </term>
<listitem>
+
<para>
The schedule end date and time. The format of
this attribute value is that of the XML Schema
- type “dateTime”. See <ulink
- url="http://books.xmlschemata.org/relaxng/ch19-77049.html"/>.
+ type “dateTime”. See dateTime.
</para>
</listitem>
</varlistentry>
@@ -710,34 +720,170 @@
</section>
-<section>
- <title>
- Quartz Scheduler Property Configuration
- </title>
-
- <para>
- The Scheduling functionality in JBossESB is built on top of
- the Quartz Scheduler (<ulink
- url="http://www.quartz-scheduler.org/" />). The default
- Quartz Scheduler instance configuration used by JBossESB is
- as follows:
- </para>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/advanced/quartz1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <!-- The information in this section is based on https://jira.jboss.org/jira/browse/SOA-1382 and http://community.jboss.org/wiki/WritingCustomListenersforJBossESB4x -->
- <para>
- Any of these Scheduler configurations can be overridden,
- or/and new ones can be added. You can do this by simply
- specifying the configuration directly on the
- <schedule-provider> configuration as a
- <property> element. For example, if you wish to
- increase the thread pool size to 5:
- </para>
+ <section>
+ <title>
+
+ Creating Custom Gateways</title>
+ <para>
+ This section outlines three methods that can be used to construct custom listeners for the Enterprise Service Bus.
+ </para>
+
+
+ <orderedlist>
+ <listitem><para>AbstractThreadedManagedLifecycle/AbstractManagedLifecycle Listener: A Listener that uses the base Listener API to create a Threaded/Non-Threaded listener, executing based on the managed lifecycle.</para></listitem>
+ <listitem><para>Schedule Driven Listener: A listener uses the ScheduledEventListener to "wake up" based on a configured schedule and generates a message for the Service Action Pipeline.</para></listitem>
+ <listitem><para>Groovy Scripted Event Driven Listener: A listener that "wakes up" based on an event triggered by an external process (e.g. a message received on a JMS Queue) and generates a message for the Service Action Pipeline.</para></listitem>
+
+
+ </orderedlist>
+ <section>
+ <title>AbstractThreadedManagedLifecycle/AbstractManagedLifecycle Listener</title>
+
+ <para>
+ Every ESB Listener is implemented using either the
+ AbstractThreadedManagedLifecycle or the AbstractManagedLifecycle
+ class. Extending one of these classes is straightforward:
+ </para>
+ <programlisting language="XML">
+<xi:include href="extras/advanced/customgateway.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+</programlisting>
+
+ <para>
+ This Gateway extends the AbstractThreadedManagedLifecycle class and implements the doRun method (the Thread method). Note how the doRun method checks the running state of the listener on each iteration of its run loop.
+ </para>
+ <para>
+Your listener should extend AbstractManagedLifecycle if you don't require a threaded listener.
+ </para>
+ <para>
+To configure a custom gateway such as this, you need to use the base configuration types bus-provider. bus and listener as follows:
+ </para>
+
+ <programlisting language="XML">
+<xi:include href="extras/advanced/customgateway2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+</programlisting>
+</section>
-<programlisting language="Java" role="JAVA"><xi:include href="extras/advanced/quartz2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+<section>
+
+ <title>Schedule-Driven Listener</title>
+
+<para>
+scheduled-listener can be used to perform scheduled tasks based on simple-schedule or cron-schedule provider configurations.
+</para>
+<para>
+scheduled-listener is configured with an “event-processor” class, which can be an implementation of one of the following interfaces:
+</para>
+<itemizedlist>
+<listitem><para></para></listitem>
+<listitem><para>ScheduledEventListener: Event Processors that implement this interface are simply triggered through the “onSchedule” method. No action processing pipeline is executed.</para></listitem>
+<listitem><para>ScheduledEventMessageComposer: Event Processors that implement this interface are capable of “composing” a message for the action processing pipeline associated with the listener.</para></listitem>
+
+</itemizedlist>
+
+<para>
+The attributes of this listener are:
+</para>
+
+<orderedlist>
+<listitem><para>name: the name of the listener instance.</para></listitem>
+<listitem><para>event-processor: the event processor class that's called on every schedule trigger. See above for implementation details.</para></listitem>
+<listitem><para>One of:</para></listitem>
+
+
+
+
+</orderedlist>
+<itemizedlist>
+<listitem><para>scheduleidref: the scheduleid of the schedule to use for triggering this listener (configured in the providers).</para></listitem>
+<listitem><para>schedule-frequency: schedule frequency (in seconds). A convenient way of specifying a simple schedule directly on the listener.</para></listitem>
+
+</itemizedlist>
+<para>
+ In this example, imagine that one needs to process "order" files and the
+ File Listener component that ships with the ESB does not quite meet
+ your requirements. In this situation, you can always write your own
+ custom file listener by implementing the ScheduledEventMessageComposer
+ interface:
+</para>
+<programlisting language="XML">
+<xi:include href="extras/advanced/customgateway3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+</programlisting>
+
+<para>
+ To turn it into an ESB Service, use this code:
+ </para>
+
+<programlisting language="XML"><xi:include href="extras/advanced/customgateway4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+</section>
+
+<section>
+ <title>Groovy-Scripted Event-Driven Listener</title>
+
+<para>
+One of the easier ways of implementing an Event Driven Listener in JBoss ESB is by hooking in the listener via a Groovy script and the groovy-listener configuration.
+</para>
+
+<para>
+The groovy-listener is very easy to configure. It takes the following configuration attributes:
+</para>
+
+<orderedlist>
+<listitem><para>name: the name of the listener instance.</para></listitem>
+<listitem><para>script: the path (on the classpath) to the Groovy Script.</para></listitem>
+
+</orderedlist>
+
+<para>
+The Groovy script effectively becomes the gateway. It has access to the following script variable bindings:
+</para>
+
+<orderedlist>
+<listitem><para>config: the listener configuration (type ConfigTree) i.e. the nested property element values. This is also required for construction of the Action Pipeline.</para></listitem>
+<listitem><para>gateway: a reference to the underlying GroovyGateway listener (Java). This provides access to the lsitener lifecycle. More no lifecycle later.</para></listitem>
+</orderedlist>
+
+<para>
+If the JMS Listener implemention provided with JBoss ESB does not meet your requirements you could hook in your own custom JMS Listener via a Groovy script and the groovy-listener.
+</para>
+<para>
+start by implementing a javax.jms.MessagListener:
+</para>
+
+
+<programlisting language="XML"><xi:include href="extras/advanced/customgateway5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+<para>
+Now we need to add the hooks for making this work in the ESB. We need to create "start" and "stop" methods for managing the listener's lifecycle, creating the Action Pipeline instance (and other resources):
+</para>
+
+<programlisting language="XML"><xi:include href="extras/advanced/customgateway6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+<note>
+<para>
+You could also used the ServiceInvoker in place of executing the Action
+Pipeline directly via the ActionProcessingPipeline class, just as with the
+AbstractThreadedManagedLifecycle example earlier in this document. This
+would require a message aware listener to be installed on the service (an
+InVM listener would be fine) and would also mean that the pipeline is
+executed asynchronously from the implemented listeners thread of execution.
+</para>
+</note>
+
+<para>
+Now we need to implement the Groovy Script that will hook in the OrderListener into the ESB, as well as manage it's lifecycle (starting and stopping):
+</para>
+
+<programlisting language="XML"><xi:include href="extras/advanced/customgateway7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+<para>
+Finally, to configure the Groovy script into your ESB Service, use this code:
+</para>
+
+<programlisting language="XML"><xi:include href="extras/advanced/customgateway8.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</section>
-
+ </section>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Building_and_Using_Services.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Building_and_Using_Services.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Building_and_Using_Services.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -11,174 +11,212 @@
</title>
- <section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-ListenersNotifiersRouters_and_Actions">
+ <section>
<title>
- Listeners, Routers/Notifiers and Actions
+ Listeners, Routers, Notifiers and Actions
</title>
- <section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-Listeners">
+ <section>
<title>
Listeners
</title>
<para>
- Listeners encapsulate the endpoints for ESB-aware message
- reception. Upon receipt of a message, a Listener feeds that
- message into a “pipeline” of message processors that
- process the message before routing the result to the
- “replyTo” endpoint. The action processing that takes place
- in the pipeline may consist of steps wherein the message
- gets transformed in one processor, some business logic is
- applied in the next processor, before the result gets
- routed to the next step in the pipeline, or to another
- endpoint.
+ <firstterm>Listeners</firstterm> encapsulate the end-points
+ needed for the reception of ESB-aware messages. Upon
+ receiving a message, a <systemitem>listener</systemitem>
+ then feeds it into a “pipeline” of message processors.
+ These modify the message before routing the result to the
+ <systemitem>replyTo</systemitem> end-point. The action
+ processing that takes place in the
+ <systemitem>pipeline</systemitem> may consist of steps in
+ which the message is transformed by one processor, before
+ being passed to the next, which may then apply some
+ business logic to it and so on, before the result is routed
+ to either the next step in the
+ <systemitem>pipeline</systemitem>, or to another end-point.
</para>
<note>
<para>
- Various parameters can be configured for listeners,
- such as the number of active worker threads. See the
- chapter on Defining Service Configurations for a full
- range of these options.
+ One can configure various parameters for listeners. An
+ example is that of the number of active worker threads.
+ See the "Configuration" section for a full range of
+ these options.
</para>
</note>
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-Routers">
+<section>
<title>
Routers
</title>
<para>
- Routers are the way in which either the ESB Message itself
- of its payload can be routed to an endpoint. Some routers
- support the 'unwrap' property. If this property is true
- then the ESB Message payload will be extracted and only the
- payload will be sent to the ESB-unaware endpoint. Setting
- 'unwrap' to false will pass the ESB Message as is and the
- receiving endpoint must be ESB-aware so that it can deal
- with the message.
+ <firstterm>Routers</firstterm> are used to direct either
+ the message or its payload to an end-point. Some
+ <systemitem>routers</systemitem> support the
+ <property>unwrap</property> property. Set this property to
+ <code>true</code>, to automatically extract message payload
+ and send it to the next ESB-unaware end-point by itself.
+ Setting the option to <code>false</code> will pass the ESB
+ Message in its entirety, without extracting the payload. (In
+ this latter case, the receiving end-point must be ESB-aware
+ so that it can handle the message.)
</para>
<para>
- No further processing of the action pipeline will occur
- after the router action even if you there are action after
- it in the configuration. If this sort of splitting is
- required you should use the StaticWiretap action.
+ The <systemitem>action pipeline</systemitem> will not
+ process the message any further after the
+ <systemitem>router</systemitem> operation has run, even if
+ there are further actions waiting in the configuration. If
+ one does require this kind of
+ <firstterm>splitting</firstterm>, one should use the
+ <systemitem>StaticWiretap</systemitem> action.
</para>
<para>
- Other routers like StaticWiretap, StaticRouter are only for
- routing to other services. There are also router that can
- be used for dynamic routing based on the message content.
- Please see the section “What is Content Based Routing” in
- the ServicesGuide for more formation on content based
- routers.
+ Tools like the <systemitem>StaticWiretap</systemitem> and
+ the <systemitem>StaticRouter</systemitem> can only be used
+ for routing to other services. There are also programs
+ available that can route dynamically, basing their actions
+ on the message's content. Please see the section entitled
+ "What is Content Based Routing?" in the <emphasis>Services
+ Guide</emphasis> to learn more about
+ <firstterm>content-based routers</firstterm>.
</para>
<note>
<para>
- For information about the usage of different routers please
- see the routers section in the “Out-of-the-box Actions”
- chapter.
+ To learn more about using different types of routers,
+ please see the "Routers" section the "Out-of-the-Box
+ Actions" chapter.
</para>
</note>
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-Notifiers">
+<section>
<title>
Notifiers
</title>
<para>
- Notifiers are the way in which success or error information
- may be propagated to ESB-unaware endpoints. You should not
- use Notifiers for communicating with ESB-aware endpoints.
- This may mean that you cannot have ESB-aware and
- ESB-unaware endpoints listening on the same channel.
- Consider using Couriers or the ServiceInvoker within your
- Actions if you want to communicate with ESB-aware
- endpoints.
+ Use <firstterm>notifiers</firstterm> to pass on success and
+ error messages to ESB-unaware end-points. Do not use
+ <systemitem>notifiers</systemitem> to communicate with
+ ESB-aware end-points. (This may mean that one cannot have
+ ESB-aware and -unaware end-points listening to the same
+ channel. If this is the case, consider using either
+ <firstterm>couriers</firstterm> or the
+ <classname>ServiceInvoker</classname> within actions to
+ communicate with ESB-aware end-points.)
</para>
<para>
- Not all ESB-aware transports are supported for Notifiers
- (and vice versa). Notifiers are deliberately simple in
- what they allow to be transported: either a byte[] or a
- String (obtained by calling toString() on the payload).
+ Not every ESB-aware transport is supported by
+ <systemitem>notifiers</systemitem> and, by the same token,
+ not every transport supports
+ <systemitem>notifiers</systemitem> either. The developers
+ have deliberately kept the
+ <systemitem>notifiers</systemitem> very simple. As a
+ result, they only allow one to transport either a
+ <type>byte[]</type> or a <type>String</type> (the latter
+ of which is obtained by calling
+ <methodname>toString()</methodname> on the payload.)
</para>
<note>
<para>
- JMSNotifier was sending the type of JMS message
- (TextMessage or ObjectMessage) depending upon the type
- of ESB Message (XML or Serializable, respectively).
- This was wrong, as the type of ESB Message should not
- affect the way in which the Notifier sends responses.
- As of JBossESB 4.2.1CP02, the message type to be used
- by the Notifier can be set as a property
- (org.jboss.soa.esb.message.transport.jms.nativeMessageType)
+ The <classname>JMSNotifier</classname> previously sent
+ different types of JMS message
+ (<classname>TextMessage</classname> or
+ <classname>ObjectMessage</classname>) based on the type
+ of ESB Message (whether it was
+ XML or Serializable, respectively.)
+ This was wrong, as the type of ESB
+ Message should not affect the way in which the Notifier
+ sends responses. Therefore, as of <application>JBossESB
+ 4.2.1CP02</application>, the message type to be used by
+ the Notifier can be set as a property
+ (<classname>org.jboss.soa.esb.message.transport.jms.nativeMessageType</classname>)
on the ESB message. Possible values are
- NotifyJMS.NativeMessage.text or
- NotifyJMS.NativeMessage.object. For backward
- compatibility with previous releases, the default value
- depends upon the ESB Message type: object for
- Serializable and text for XML. However, we encourage
- you not to rely on defaults.
+ <classname>NotifyJMS.NativeMessage.text</classname> or
+ <classname>NotifyJMS.NativeMessage.object</classname>.
+ For compatibility with previous releases, the default
+ value depends upon the ESB Message
+ type: "object" for Serializable and "text" for
+ XML. However, Red Hat discourage users
+ from relying upon defaults.
</para>
</note>
<para>
- As outlined above, the responsibility of a listener is to
- act as a message delivery endpoint and to deliver messages
- to an “Action Processing Pipeline”. Each listener
- configuration needs to supply information for:
+ As outlined above, it is a
+ <systemitem>listener</systemitem>'s responsibilities to act
+ as a message delivery end-point and to deliver messages to
+ the <systemitem>action pipeline</systemitem>. Each
+ <systemitem>listener</systemitem> configuration needs to
+ supply information for:
</para>
<itemizedlist>
<listitem>
<para>
- the Registry (see service-category, service-name,
- service-description and EPR-description tag names).
- If you set the optional remove-old-service tag name
- to true then the ESB will remove any existing
- service entry from the Registry prior to adding
- this new instance. However, this should be used
- with care, because the entire service will be
- removed, including all EPRs.
+ the <systemitem>registry</systemitem> (see the
+ <literal>service-category</literal>,
+ <literal>service-name</literal>,
+ <literal>service-description</literal> and
+ <literal>EPR-description</literal> tag names.) If
+ one sets the optional
+ <literal>remove-old-service</literal> tag name to
+ <code>true</code>, then the Enterprise Service Bus
+ will remove any pre-existing service entry from the
+ <systemitem>registry</systemitem> and then add this
+ new instance. Always use this functionality with
+ care, because the entire service will be removed,
+ including every end-point reference.
</para>
</listitem>
<listitem>
<para>
- instantiation of the listener class (see
- listenerClass tag name).
+ the instantiation of the
+ <systemitem>listener</systemitem> class (see the
+ <literal>listenerClass</literal> tag name.)
</para>
</listitem>
<listitem>
<para>
- the EPR that the listener will be servicing. This
- is transport specific. The following example
- corresponds to a JMS EPR (see connection-factory,
- destination-type, destination-name, jndi-type,
- jndi-URL and message-selector tag names).
+ the end-point reference that the
+ <systemitem>listener</systemitem> will service.
+ This is transport-specific. The following example
+ corresponds to a Java Message Service end-point
+ reference (see the
+ <literal>connection-factory</literal>,
+ <literal>destination-type</literal>,
+ <literal>destination-name</literal>,
+ <literal>jndi-type</literal>,
+ <literal>jndi-URL</literal> and
+ <literal>message-selector</literal> tag names.)
</para>
</listitem>
<listitem>
<para>
- the “action processing pipeline”. One or more
- <action> elements each that must contain at
- least the 'class' tagname that will determine which
- action class will be instantiated for that step in
- the processing chain.
+ the <systemitem>action pipeline</systemitem>. This
+ needs one or more <action> elements, each of
+ which must contain, at the very least, the
+ <literal>class</literal> tag name. These will
+ determine which <systemitem>action</systemitem>
+ class will be instantiated for that link in the
+ <systemitem>chain</systemitem>.
</para>
</listitem>
</itemizedlist>
@@ -188,198 +226,257 @@
<para>
- This example configuration will instantiate a listener
- object (jms-listener attribute) that will wait for incoming
- ESB Messages, serialized within a javax.jms.ObjectMessage,
- and will deliver each incoming message to an
- ActionProcessingPipeline consiting of two steps
- (<action> elements):
+ This example configuration instantiates a
+ <systemitem>listener</systemitem> object (the
+ <property>jms-listener</property> attribute), which will
+ wait for those incoming ESB messages that are serialized
+ within a <classname>javax.jms.ObjectMessage</classname>. It
+ then delivers each incoming message to an
+ <systemitem>action pipeline</systemitem> consisting of two
+ steps (<action> elements):
</para>
- <variablelist>
- <varlistentry>
- <term>action1</term>
- <listitem>
+ <orderedlist>
+ <listitem>
<para>
- MyJMSListenerAction (a trivial example follows)
+ action1: <classname>MyJMSListenerAction</classname> (a trivial example follows)
</para>
</listitem>
- </varlistentry>
-
- <varlistentry>
- <term>notificationAction</term>
- <listitem>
+
+ <listitem>
<para>
- An org.jboss.soa.esb.actions.SystemPrintln
+ notificationAction: an
+ <classname>org.jboss.soa.esb.actions.SystemPrintln</classname>
+ class.
</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ </listitem>
+ </orderedlist>
<para>
- The following trivial action class will prove useful for
- debugging your XML action configuration
+ This <systemitem>action</systemitem> class will prove
+ useful when debugging XML action configurations:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/myjmslisteneraction.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Action classes are the main way in which ESB users can
- tailor the framework to their specific needs. The
- ActionProcessingPipeline class will expect any action class
- to provide at least the following:
+ Use <systemitem>action</systemitem> classes to customised
+ the framework for specific needs. specific needs. The
+ <classname>ActionProcessingPipeline</classname> class
+ expects any other action class to provide, at the minimum,
+ this information:
</para>
<itemizedlist>
<listitem>
<para>
- A public constructor that takes a single argument
- of type ConfigTree
+ a public constructor that takes a single argument of the
+ type <systemitem>ConfigTree</systemitem>
</para>
</listitem>
+
<listitem>
<para>
- One or more public methods that take a Message
- argument, and return a Message result
+ one or more public methods that take a
+ message argument and return a
+ message result.
</para>
</listitem>
</itemizedlist>
<para>
- Optional public callback methods that take a Message
- argument will be used for notification of the result of the
- specific step of the processing pipeline (see items 5 and 6
- below).
+ Use optional public callback methods to provide
+ notification of the result of a specific step in the
+ <systemitem>action pipeline</systemitem> (see items five
+ and six below.)
</para>
<para>
The
- org.jboss,soa.esb.listeners.message.ActionProcessingPipeline
- class will perform the following steps for all steps
- configured using <action> elements:
+ <classname>org.jboss.soa.esb.listeners.message.ActionProcessingPipeline</classname>
+ class performs the following tasks for all of those
+ steps configured via <action> elements. It will:
</para>
<orderedlist>
- <listitem>
-
+ <listitem>
<para>
- Instantiate an object of the class specified in the
- 'class' attribute with a constructor that takes a
- single argument of type ConfigTree
- </para>
-
+ instantiate an object of the class specified in the
+ <property>class</property> attribute. This needs a constructor that
+ takes a single argument of the type
+ <systemitem>ConfigTree</systemitem>.
+ </para>
</listitem>
+
<listitem>
<para>
- Analyze contents of the 'process' attribute.
+ analyse contents of the
+ <property>process</property> attribute.
</para>
<para>
- Contents can be a comma separated list of public
- method names of the instantiated class (step 1),
- each of which must take a single argument of type
- Message, and return a Message object that will be
- passed to the next step in the pipeline
+ The contents can take the form of a comma-separated
+ list of public method names for the instantiated
+ class (step one). Each of these methods must take a
+ single argument of the type
+ <classname>Message</classname> and, subsequently,
+ return a messagem object that will be passed to the
+ next step in the <systemitem>pipeline</systemitem>.
</para>
<para>
- If the 'process' attribute is not present, the
- pipeline will assume a single processing method
- called “process”
+ If the <property>process</property> attribute is
+ not present, the <systemitem>pipeline</systemitem>
+ will assume the use of a single processing method
+ called <methodname>process</methodname>.
</para>
<para>
Using a list of method names in a single
- <action> element has some advantages compared
- to using successive <action> elements, as the
- action class is instantiated once, and methods will
- be invoked on the same instance of the class. This
- reduces overhead and allows for state information
- to be kept in the instance objects.
+ <action> element has some advantages over the
+ use of successive <action> elements. This is
+ because the <systemitem>action</systemitem> class
+ is instantiated once and methods will be invoked on
+ the same instance of that class. This reduces the
+ overhead and means that
+ <firstterm>state</firstterm> information can be
+ kept within the instance objects.
</para>
<para>
- This approach is useful for user supplied (new)
- action classes, but the other alternative (list of
- <action> elements) continues to be a way of
- reusing other existing action classes.
+ This approach is useful for user-supplied (new)
+ <systemitem>action</systemitem> classes. The
+ alternative, (a list of <action> elements),
+ continues to be a way of re-using pre-existing
+ <systemitem>action</systemitem> classes.
</para>
</listitem>
<listitem>
<para>
- Sequentially invoke each method in the list using
- the Message returned by the previous step
+ sequentially invoke each method in the list by using
+ the message returned in the previous step.
</para>
</listitem>
+ </orderedlist>
+ <para>
+ If the value returned by any step is
+ <code>null</code>, the
+ <systemitem>pipeline</systemitem> will cease
+ processing data immediately.
+ </para>
+
+
+
+ <para>
+ The callback method for success in each of the
+ <action> element is as follows:
+ </para>
+
+ <itemizedlist>
<listitem>
<para>
- If the value returned by any step is null the
- pipeline will stop processing immediately.
+ if the list of methods in the
+ <property>process</property> attribute was executed
+ successfully, the <systemitem>pipeline</systemitem>
+ will analyze the contents of the
+ <property>okMethod</property> attribute.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ if no methods were specified, processing will
+ continue with the next <action> element.
+ </para>
+ </listitem>
<listitem>
<para>
- Callback method for success in each <action>
- element: If the list of methods in the 'process'
- attribute was executed successfully, the pipeline
- will analyze contents of the 'okMethod' attribute.
- If none is specified, processing will continue with
- the next <action> element. If a method name
- is provided in the 'okMethod' attribute, it will be
- invoked using the Message returned by the last
- method in step 3. If the pipeline succeeds then the
- okMethod notification will be called on all
- handlers from the last one back to the initial one.
+ if a method name is provided in the
+ <property>okMethod</property> attribute, it will be
+ invoked using the message returned by the last
+ method in step three. If the pipeline succeeds,
+ then the <property>okMethod</property> notification
+ will be called on all handlers from the last back
+ through to the first.
</para>
- </listitem>
+ </listitem>
+ </itemizedlist>
+
+
+
+
+ <para>
+ The callback method for failure in each
+ <action> element is as follows:
+ </para>
+
+ <itemizedlist>
<listitem>
<para>
- Callback method for failure in each <action>
- element: If an Exception occurs then the
- exceptionMethod notification will be called on all
- handlers from the current (failing) handler back to
- the initial handler. At present time, if no
- exceptionMethod was specified, the only output will
- be the logged error. If an
- ActionProcessingFaultException is thrown from any
- process method then an error message will be
- returned as per the rules defined in the next
- section. The contents of the error message will
- either be whatever is returned from the
- getFaultMessage of the exception, or a default
- Fault containing the information within the
- original exception.
+ if an exception occurs, then the
+ <methodname>exceptionMethod</methodname>
+ notification will be called on all handlers from
+ the current (failing) one back to the initial one.
+ (Currently, if no
+ <methodname>exceptionMethod</methodname> was
+ specified, the only output will be the logged
+ error.)
</para>
</listitem>
- </orderedlist>
+
+ <listitem>
+ <para>
+ If an
+ <exceptionname>ActionProcessingFaultException</exceptionname>
+ is thrown from any process method, then an error
+ message will be returned as per the rules defined
+ in the next section. The contents of the error
+ message will be either whatever is returned from
+ the exception's
+ <methodname>getFaultMessage</methodname>, or a
+ default <classname>Fault</classname> that contains
+ the information found within the original
+ exception.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
+
<para>
- Action classes supplied by users to tailor behaviour of the
- ESB to their specific needs, might need extra run time
- configuration (for example the Notifier class in the XML
- above needs the <NotificationList> child element). Each
- <action> element will utilize the attributes mentioned
- above and will ignore any other attributes and optional
- child elements. These will be however passed through to the
- action class constructor in the require ConfigTree
- argument. Each action class will be instantiated with it's
- corresponding <action> element and thus does not see (in
- fact must not see) sibling action elements.
+ If one has supplied additional
+ <systemitem>action</systemitem> classes in order to
+ customise the behaviour of the Enterprise Service Bus, one
+ may need to undertake some extra run-time configuration
+ work (for example, in the XML above, the
+ <systemitem>notifier</systemitem> class requires the
+ <NotificationList> child element). Each
+ <action> element will utilise the attributes
+ mentioned above, ignoring any others and also ignoring any
+ optional child elements. These will, however, be passed
+ through to the <systemitem>action</systemitem> class
+ constructor in the require
+ <systemitem>ConfigTree</systemitem> argument. Each
+ <systemitem>action</systemitem> class will be instantiated
+ with it's corresponding <action> element and, thus,
+ will not and, indeed, must not, see its "sibling"
+ <systemitem>action</systemitem> elements.
</para>
<note>
<para>
- In JBossESB 4.3 the name of the property used to
- enclose NotificationList elements in the <action>
- target is not validated.
+ The name of the property used to enclose the
+ <classname>NotificationList</classname> elements in the
+ <action> target is not validated.
</para>
</note>
@@ -391,12 +488,14 @@
Annotated Action Classes
</title>
- <para>
- JBossESB now has a set of Action Annotations
- that will make it easier to create clean
- ESB Action implementations. We want to hide the
- complexities of implementing interfaces and abstract
- classes, as well as dealing with the ConfigTree type.
+ <para>
+ The <application>JBoss Enterprise Service
+ Bus</application> has a set of <firstterm>action
+ annotations</firstterm> that make it easier to create
+ clean <systemitem>action</systemitem> implementations.
+ This hides the complexity associated with implementing
+ interfaces, abstract classes and dealing with the
+ <systemitem>ConfigTree</systemitem> type.
</para>
<para>
@@ -473,37 +572,42 @@
@Process
</title>
<para>
- The most basic form of Action implementation involves creating
- a simple POJO with a single method, annotated with the @Process
- annotation as follows:
+ The simplest implementation involves creating
+ a basic <firstterm>plain old Java object</firstterm> (POJO)
+ with a single method, annotated with @Process:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The @Process annotation is what Identifies the class as being a
- valid ESB Action. In the case where there are multiple methods
- in the class, it also identifies the method to be used for
- processing the message instance (or some part of the message -
- more on this later with the @BodyParam, @PropertyParam and
- @AttachmentParam).
+ The @Process annotation serves to identify the class as a valid
+ ESB <systemitem>action</systemitem>. In cases in which there
+ are multiple methods in the class, it also identifies the one
+ which is to be used for processing the message instance (or
+ some part of the message. This is explained in more depth when
+ the @BodyParam, @PropertyParam and @AttachmentParam annotations
+ are discussed.)
</para>
<para>
- Configuring an instance of this Action into a Service pipeline
- is the same as with the low/base level Actions implementations
- i.e. those that extend AbstractActionPipelineProcessor or
- implement ActionLifecycle (or one of its other sub-types or
- abstract implementations):
+ To configure an instance of this
+ <systemitem>action</systemitem> on a
+ <systemitem>pipeline</systemitem>, use the same process as that
+ for low/base level <systemitem>action</systemitem>
+ implementations (these being those that extend
+ <classname>AbstractActionPipelineProcessor</classname> or
+ implement <classname>ActionLifecycle</classname> or one of its
+ other sub-types or abstract implementations):
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/annotate2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- In cases where the Action implementation has multiple methods
- annotated with the @Process annotation, you simply use the
- process attribute to specify which of the annotated methods is
- to be used for processing the Message instance (as before):
+ In cases in which multiple methods annotated with @Process are
+ associated with the <systemitem>action</systemitem>
+ implementation, use the <property>process</property> attribute
+ to specify which of them is to be used for processing the
+ message instance:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/annotate3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -522,108 +626,113 @@
<itemizedlist>
<listitem>
<para>
- void: No return value - as with our logger action implementation.
+ void. This means there will be no return value, as with the
+ logger action implementation above.
</para>
</listitem>
<listitem>
<para>
- Message: An ESB Message instance. This message instance then
- becomes the active/current instance on action pipeline.
+ message: This is an ESB message instance. This
+ becomes the active/current instance on <systemitem>action
+ pipeline</systemitem>.
</para>
</listitem>
<listitem>
<para>
- Some other type. If the method does not return an ESB Message
- instance, the returned object instance is set into the
- active/current ESB Message instance on the action pipeline. Where
- it is set on the Message depends on the "set-payload-location"
- <action> configuration property, which default according to
- the normal MessagePayloadProxy rules.
+ some other type. If the method does not return an ESB message
+ instance, the object instance that is returned will be set on
+ the current ESB message instance on the <systemitem>action
+ pipeline</systemitem>. As to where it is set on the message
+ depends on the <property>set-payload-location</property>
+ <action> configuration property, which default according
+ to the normal <classname>MessagePayloadProxy</classname> rules.
</para>
</listitem>
</itemizedlist>
<para>
- @Process methods can specify parameters in a range of
- different ways. You can:
+ Use @Process methods to specify parameters in a range of
+ different ways. One can:
</para>
<orderedlist>
<listitem>
<para>
- Specify the ESB Message instance as a parameter to the method.
+ specify the ESB message instance as a method parameter.
</para>
</listitem>
<listitem>
<para>
- Specify one or more arbitrary parameter types. The ESB
- framework will "hunt" (searching the Message Body, then
- Properties, then Attachments) for data of that type in the
- active/current pipeline Message instance and pass this data as
- the values for those parameters (or null if not found).
+ specify one or more arbitrary parameter types. The Enterprise
+ Service Bus framework will search for data of that type in the
+ active/current pipeline Message instance. Firstly, it will
+ search the message body, then properties, then attachments and
+ pass this data as the values for those parameters (or
+ <code>null</code> if not found.)
</para>
</listitem>
</orderedlist>
<para>
- An example of option #1 was shown above in the logger action.
- An example of option #2 might be something like:
+ An example of the first option was depicted above in the logger
+ action. Here is an example of the second option:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- So in the above example, the @Process method is obviously
- relying on a previous action (in the action pipeline) creating
- OrderHeader and OrderItems object instances and attaching them
- to the active/current ESB Message instance. Perhaps a more
- realistic implementation of such a use case would be to have a
- generic action implementation that decodes an XML/EDI/whatever
- payload to an Order instance, which it returns. Then to have
- the OrderPersister take an Order instance as it's sole
- parameter e.g.
+ In this example, the @Process method is relying on a previous
+ action in the <systemitem>pipeline</systemitem> to create the
+ <code>OrderHeader</code> and <code>OrderItem</code> object
+ instances and attach them to the current message. (Perhaps a
+ more realistic implementation would have a generic action
+ implementation that decodes an XML or EDI payload to an order
+ instance, which it would then returns. The
+ <classname>OrderPersister</classname> would then take an order
+ instance as its sole parameter.) Here is an example:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Chain the 2 actions together in the ESB service configuration:
+ Chain the two actions together in the service configuration:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/annotate6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Option #2 (above) can make your code read a little more
- clearly (less annotation noise), but it carries the obvious
- risks in that the process of runtime "hunting" through the ESB
- Message for the appropriate parameter values is not 100%
- deterministic. For that reason, we support the @BodyParam,
- @PropertyParam and @AttachmentParam method property
+ The code is easier to read in Option #2 because there are less
+ annotations, but it carries a risk because the process of
+ run-time "hunting" through the message for the appropriate
+ parameter values is not completely
+ <firstterm>deterministic</firstterm>. Due to this, Red Hat
+ supports the @BodyParam, @PropertyParam and @AttachmentParam
annotations.
</para>
<para>
- These @Process method parameter annotations allow you to be
- explicit in terms of where in the ESB Message you wish to get
- an individual parameter value for the @Process method. As the
- names suggest, each of these annotations allow you to specify
- a named location (in the ESB Message Body, Properties and
- Attachments) for a specific @Process method parameter:
+ Use these @Process method parameter annotations to explicitly
+ define from where in the message an individual parameter value
+ for the @Process method is to be retrieved. As their names
+ suggest, each of these annotations allow one to specify a
+ named location (in the message body, properties or
+ attachments) for a specific parameter:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- If the specified ESB Message location does not contain a
- value, then a null value will be passed for this parameter
- value and the @Process method instance can decide how to
- handle this. f the specified ESB Message location contains a
- value of the wrong type, a MessageDeliverException exception
- is thrown.
+ If the message location specified does not contain a value,
+ then null will be passed for this parameter (the @Process
+ method instance can decide how to handle this.) If, on the
+ other hand, the specified location contains a value of the
+ wrong type, a
+ <exceptionname>MessageDeliverException</exceptionname> will be
+ thrown.
</para>
</section>
@@ -633,174 +742,180 @@
</title>
<para>
- Most actions will require some user configuration. In the ESB
- action configuration, the action configuration properties are
- supplied as <property> sub-elements of the <action>
- element:
+ One will have to configure most of the actions to some
+ degree. In the ESB action configuration, the properties are
+ supplied as <property> sub-elements of the
+ <action> element:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/annotate8.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Getting these configuration properties into your action using
- the low/base level Action implementations (extend
- AbstractActionPipelineProcessor or implement ActionLifecycle
- etc) involves working with the ConfigTree class, which is
- supplied to the Action via it's constructor. The action
- implementor is forced to:
+ In order to utilise these properties, use the low/base level
+ action implementations (do so by extending
+ <classname>AbstractActionPipelineProcessor</classname> or by
+ implementing <classname>ActionLifecycle</classname>.) This
+ involves working with the <classname>ConfigTree</classname>
+ class, (which is supplied to the action via its constructor.)
+ In order to implement an action, follow these steps:
</para>
<orderedlist>
<listitem>
<para>
- Define a constructor on the Action class that supplies the ConfigTree instance.
+ Define a constructor on the action class that supplies the
+ <classname>ConfigTree</classname> instance.
</para>
</listitem>
<listitem>
<para>
- Get all the relevant action configuration properties from the ConfigTree instance.
+ Obtain all of the relevant action configuration properties from
+ the <classname>ConfigTree</classname> instance.
</para>
</listitem>
<listitem>
<para>
- Check for mandatory action properties, raising exceptions where
- they are not specified on the <action> configuration.
+ Check for mandatory action properties and raise exceptions in
+ those places where they are not specified on the <action>
+ configuration.
</para>
</listitem>
<listitem>
<para>
- Decode all property values from Strings (as supplied on the
- ConfigTree) to their appropriate types as used by the action
- implementation e.g. java.lang.String -> java.io.File,
- java.lang.String -> boolean, java.lang.String -> long etc.
+ Decode all property values from strings (as supplied on the
+ <classname>ConfigTree</classname>) to their appropriate types
+ as used by the action implementation. For example, decide
+ <code>java.lang.String</code> to <code>java.io.File</code>,
+ <code>java.lang.String</code> to Boolean,
+ <code>java.lang.String</code> to long and so forth.
</para>
</listitem>
<listitem>
<para>
- Raise exceptions where the configured value is not decodable to the
- target property type.
+ Raise exceptions at those places where the configured value
+ cannot be decoded to the target property type.
</para>
</listitem>
<listitem>
<para>
- Implement unit tests on all the different configuration
- possibilities to ensure the above tasks were completed properly.
+ Implement <firstterm>unit tests</firstterm> on all the
+ different configuration possibilities to ensure that the
+ tasks listed above were completed properly.
</para>
</listitem>
</orderedlist>
<para>
- So, while the above tasks are not too difficult for the
- action implementor, they are a bit of a pain to implement.
- It can be quite laborious, error prone and lead to
- inconsistencies across actions wrt how configuration errors
- are handled. Then of course... there can be quite a bit of
- code involved with just handling action configuration,
- which can be quite noisy and sitracting wrt what the action
- implementation is really about.
+ Whilst the tasks above are generally not difficult to
+ undertake, they can be a tad laborious, error-prone and
+ lead to inconsistencies across actions with regard to how
+ configuration mistakes are handled. One may also be
+ required to add quite a lot of code, with a net result of
+ less overall clarity.
</para>
<para>
- With the annotated action, we take care of most of the
- above through the @ConfigProperty annotation. Expanding the
- MyLogActions action implementation, which has 2 mandatory
- configuration properties of logFile and logLevel (as
- outlined in the above config example):
+ The annotated action addresses these problems via
+ @ConfigProperty. Expand the MyLogActions implementation,
+ which has two mandatory configuration properties:
+ <property>logFile</property> and
+ <property>logLevel</property>:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate9.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <note>
- <para>
- The @ConfigProperty annotation can also be defined on setter
- methods (Vs on the Field).
+ <note>
+ <para>
+ One can also define the @ConfigProperty annotation on
+ "setter" methods (<literal>V</literal>s on the field.)
</para>
</note>
<para>
- That's it. When the ESB deploys the action, it looks into the action
- implementation and maps in the decoded value (including
- support for enums, as with the LogLevel enum above) of the
- action properties/fields that are annotated with the
- @ConfigProperty annotation. No need to deal with the
- ConfigTree class at all. No need for any noisy code.
+ That is all that needs to be done. When the Enterprise
+ Service Bus deploys the action, it examines both the
+ implementation and the maps found within the decoded value
+ (including any support for enums, as with the LogLevel enum
+ above.) It finds the action fields possessing the
+ @ConfigProperty annotation. Hence the developer is not
+ required to deal with the <classname>ConfigTree</classname>
+ class at all or develop any convoluted code.
</para>
<para>
- So by default, all class Fields annotated with the
- @ConfigProperty annotation are mandatory. Non-mandatory
- Fields are handled in one of two ways:
+ By default, every class field possessing the @ConfigProperty
+ annotation is mandatory. Non-mandatory fields are handled
+ in one of these two ways:
</para>
<orderedlist>
<listitem>
<para>
- By specifying use = Use.OPTIONAL on the @ConfigProperty annotation
- on the Field.
+ by specifying <code>use = Use.OPTIONAL</code> on the field's @ConfigProperty
+ annotation.
</para>
</listitem>
<listitem>
<para>
- By specifying a defaultVal on the @ConfigProperty annotation on the
- Field. Specifying a defaultVal implies it is OPTIONAL.
+ by specifying a <property>defaultVal</property> on the field's
+ @ConfigProperty annotation. (This is optional.)
</para>
</listitem>
</orderedlist>
<para>
- So, if we wanted to make the properties on our log action
- non-mandatory, we could implement the action as:
+ To make the log action's properties optional only,
+ implement the action like this:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate10.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The @ConfigProperty annotation also supports two additional
- fields that may not be used too often:
+ The @ConfigProperty annotation supports two additional
+ fields:
</para>
<orderedlist>
<listitem>
<para>
- name: The name field on the @ConfigProperty annotation allows you
- to explicitly specify the name of the action configuration property
- to be used to populate that Field of the action instance.
+ <property>name</property>: use this to explicitly specify the
+ name of the action configuration property to be used to
+ populate the field of that name on the action instance.
</para>
</listitem>
<listitem>
<para>
- choice: The choice field on the @ConfigProperty annotation allows
- you to constrain the possible allowed configuration values for that
- Field. For most cases, the same can be achieved using an
- enumeration type (as with the LogLevel enumeration type).
+ <property>choice</property>: use this field to constrain the
+ configuration values allowed for itself. This can also be
+ achieved using an enumeration type (as with the
+ <property>LogLevel</property>.)
</para>
</listitem>
</orderedlist>
<para>
- An example of when the name field might be used is when
- migrating an old action implementation (that uses the
- low/base level implementation type) to use the newer
- annotation based implementation, and the old config name for
- a property (which you cannot change for backward
- compatibility reasons) does not map to a valid Java Field
- name. Taking our log action as an example, supposing the old
- configuration for the log action was as follows:
+ The name field might be used in various situations such as
+ when migrating an old action (that uses the low/base level
+ implementation type) to the newer annotation-based
+ implementation, only to find that the old configuration name
+ for a property (which cannot be changed for
+ backward-compatibility reasons) does not map to a valid Java
+ field name. Taking the log action as an example, imagine that
+ this was the old configuration for the log action:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/annotate11.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The property names here do not map to valid Java Field names,
- so in this case, we need to specify the name on the
- @ConfigProperty annotation, as follows:
+ The property names here do not map to valid Java field names,
+ so specify the name on the @ConfigProperty annotation:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate12.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -812,30 +927,31 @@
</title>
<para>
- The bean configuration property values are decoded from their
- configuration String values to their appropriate POJO bean
- property type by the following simple rules:
+ The bean configuration's property values are decoded from
+ their string values. To then matched them against the
+ appropriate POJO bean property type, these simple rules are
+ used:
</para>
<orderedlist>
<listitem>
<para>
- If the property type has a single-arg String constructor, use that, or
+ If the property type has a single-argument string constructor, use that.
</para>
</listitem>
<listitem>
<para>
- If the type is a primitive type, use the single-arg String
- constructor of it's Object type e.g. for an int use the Integer
- object.
+ If it is a "primitive," use its object type's single-argument string
+ constructor. For example, if it is an int, use the Integer
+ object.
</para>
</listitem>
<listitem>
<para>
- If the type is an enum type, use Enum.valueOf to convert the
- configuration String to it's enumeration value.
+ If it is an enum, use <code>Enum.valueOf</code> to convert the
+ configuration string to its enumeration value.
</para>
</listitem>
</orderedlist>
@@ -847,55 +963,58 @@
</title>
<para>
- Sometimes action implementations need to perform some
- initialization at deploy time, as well as some
- cleanup/uninitialization when undeploying. For this, we have
- the @Initialize and @Destroy method annotations.
+ Sometimes action implementations need to perform
+ initialization task at deployment time. They may also need to
+ perform a clean-up whilst being undeployed. For these
+ reasons, there are @Initialize and @Destroy method
+ annotations.
</para>
<para>
- At deploy time, our logging action would probably want to
- perform some checks (e.g. file exists, directory exists etc),
- as well as some initialization (e.g. open the log file for
- writing etc). Then at undeploy, it may need to perform some
- uninitialization tasks (e.g. close the file):
+ To illustrate, here are some examples. At the time of
+ deployment, the logging action may need to perform some
+ checks (that, for example, files and directories exist.) It
+ may also want to perform some initialization tasks (such as
+ opening the log file for writing.) When it is undeployed, the
+ action may need to perform some clean-up tasks (such as
+ closing the file). Here is the code to perform these tasks:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate13.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
- All @ConfigProperty annotations have been processed by the
- time the @Initialize methods are invoked by the ESB deployer.
+ All of the @ConfigProperty annotations have been processed by the
+ time the ESB deployer invokes the @Initialize methods.
Therefore, the @Initialize methods can rely on these fields
- being initialized before execution of the custom
- initialization specified in the @Initialize method.
+ being ready before they execute the customised
+ initialization.
</para>
</note>
<note>
<para>
- You do not need specify methods using both these
- annotations. You only need to specify what is needed i.e. if
- your method only needs initialization, you only need a method
- annotated with the @Initialize annotation i.e. you don't need
- to specify a "matching" method annotated with the @Destroy
- annotation.
+ There is no need to use both of these annotations to specify
+ methods. Only specify them if there is a need; in other
+ words, if a method only needs initialization, only use the
+ @Initialize annotation (one does not have to supply a
+ "matching" method annotated with the @Destroy annotation.)
</para>
</note>
<note>
<para>
- If you want, you can specify a single method and annotate it
+ It is possible to specify a single method and annotate it
with both @Initialize and @Destroy.
</para>
</note>
<note>
<para>
- @Initialize methods can optionally specify a ConfigTree
- parameter, if they want to have access to the actions
- underlying ConfigTree instance.
+ One can optionally specify a
+ <classname>ConfigTree</classname> parameter on @Initialize
+ methods. Do this to have access to the actions which underlie
+ <classname>ConfigTree</classname> instance.
</para>
</note>
</section>
@@ -906,18 +1025,19 @@
</title>
<para>
- These method annotations allow you to specify methods to be
- executed on a successful/failed execution of the action
- pipeline in which the action is configured.
+ Use these annotations to specify methods those to be executed
+ on a successful or failed execution, respectively, of that
+ <systemitem>pipeline</systemitem> in which the action
+ is configured:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/building_and_using_services/annotate14.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- In the case of both of these annotations, the parameters
- passed to the annotated methods are optional. You can supply
- none, some or all of the parameters shown above. The ESB
- framework resolves the relevant parameters in both cases.
+ In the cases of both of these annotations, the parameters
+ passed to the methods are optional. One has the choice of supplying
+ none, some or all of the parameters shown above. The Enterprise Service Bus'
+ framework resolves the relevant parameters in each case.
</para>
</section>
@@ -932,93 +1052,105 @@
</title>
<para>
- Actions are triggered by the arrival of a Message. The
- specific Action implementation is expected to know where
- the data resides within a Message. Because a Service may be
- implemented using an arbitrary number of Actions, it is
- possible that a single input Message could contain
- information on behalf of more than one Action. In which
- case it is incumbent on the Action developer to choose one
- or more unique locations within the Message Body for its
- data and communicate this to the Service consumers.
+ Actions are triggered by the arrival of messages. (Each
+ specific action implementation is expected to know where
+ within a message the data resides.) Because a service may
+ be feature an arbitrary number of actions, a single input
+ message can contain information pertaining to more than one
+ action. In this case, the onus is upon the action developer
+ to choose one or more unique locations within the message's
+ body in which to place the data and then to communicate
+ these locations to the service consumers.
</para>
-
+ <note>
<para>
- Furthermore, because Actions may be chained together it is
- possible that an Action earlier in the chain modifies the
- original input Message, or replaces it entirely.
+ Because actions can be chained together, it is
+ possible that an action earlier in the chain will modify the
+ originally-input message, or even replace it entirely.
</para>
+ </note>
-
- <note>
+ <important>
<para>
- From a security perspective, you should be careful
- about using unknown Actions within your Service chain.
- We recommend encrypting information.
+ From a security perspective, one should be careful
+ about using unknown actions within a service chain.
+ Always encrypt information.
</para>
- </note>
-
+ </important>
+
+ <important>
+ <para>
+ Red Hat recommends retaining the original information
+ if multiple actions are sharing and modifying an input
+ message's data as it flows through the chain. This is so
+ that actions further down the chain still have access to
+ the initial information. (Obviously, there will be some
+ situations in which this is impossible.)
+ </para>
+
+ <para>
+ Actions that modify the data that has been input can also
+ add it to the
+ <classname>org.jboss.soa.esb.actions.post</classname> body
+ location. This means that if there are N actions in the
+ chain, Action N can find the original data in the place at
+ which it would normally search for it. It also means that,
+ if Action N-1 modified the data, then N will find it within
+ the other specified location. To further facilitate action
+ chaining, Action N can check
+ <classname>org.jboss.soa.esb.actions.pre</classname> to see
+ if Action N-2 modified the data.
+ </para>
+ </important>
+
+ <warning>
<para>
- If Actions share data within an input Message and each
- one modifies the information as it flows through the
- chain, by default we recommend retaining the original
- information so that Actions further down the chain
- still have access to it. Obviously there may be
- situations where this is either not possible or would
- be unwise. Within JBossESB, Actions that modify the
- input data can place this within the
- org.jboss.soa.esb.actions.post named Body location.
- This means that if there are N Actions in the chain,
- Action N can find the original data where it would
- normally look, or if Action N-1 modified the data then
- N will find it within the other specified location. To
- further facilitate Action chaining, Action N can see if
- Action N-2 modified the data by looking in the
- org.jboss.soa.esb.actions.pre named Body location.
+ Always be careful when chaining actions that utilise
+ the default body location, in case they conflict in
+ their use of it.
</para>
-
- <note>
- <para>
- As mentioned earlier, you should use the default named
- Body location with care when chaining Actions in case
- chained Actions use it in a conflicting manner.
- </para>
- </note>
+ </warning>
</section>
- <section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-Handling_Responses">
+ <section>
<title>
Handling Responses
</title>
<para>
- There are two processing mechanisms supported for handling
- responses in the action pipeline, implicit processing
- (based on the response of the actions) and explicit
- processing.
+ The <application>JBoss Enterprise Service Bus</application>
+ supports two processing mechanisms for the purpose of
+ handling <systemitem>action pipeline</systemitem>
+ responses. These are called the
+ <firstterm>explicit</firstterm> and
+ <firstterm>implicit</firstterm> processing mechanisms, the
+ latter of which is based on the actions' responses.
</para>
<para>
- If the processing is implicit then responses will be
- processed as follows:
+ If the implicit mechanism is used, then responses will be
+ processed in this way:
</para>
<itemizedlist>
<listitem>
<para>
- If any action in the pipeline returns a null
- message then no response will be sent.
+ if any action in the
+ <systemitem>pipeline</systemitem> returns a null
+ message, then no response is sent.
</para>
</listitem>
<listitem>
<para>
- If the final action in the pipeline returned a
- non-error response then a reply will be sent to the
- ReplyTo EPR of the request message or, if not set,
- to the From EPR of the request message. In the
+ if the final action in the
+ <systemitem>pipeline</systemitem> returns a
+ non-error response, then a reply will be sent to
+ the request message's <property>ReplyTo
+ EPR</property> or, if not set, to the request
+ message' s <property>From EPR</property>. In the
event that there is no way to route responses, an
error message will be logged by the system.
</para>
@@ -1026,68 +1158,74 @@
</itemizedlist>
<para>
- If the processing is explicit then responses will be
- processed as follows:
+ If the explicit mechanism is used, then the responses will
+ be processed in the following manner:
</para>
<itemizedlist>
<listitem>
<para>
- If the action pipeline is specified as 'OneWay'
- then the pipeline will never send a response
+ if the <systemitem>pipeline</systemitem> is
+ configured to be <code>OneWay</code>, then it will
+ never send a response.
</para>
</listitem>
- <listitem>
+
+ <listitem>
<para>
- If the pipeline is specific as 'RequestResponse'
- then a reply will be sent to the ReplyTo EPR of the
- request message or, if not set, to the From EPR of
- the request message. In the event that there is no
- EPR is specified then no error message will be
- logged by the system.
+ if the <systemitem>pipeline</systemitem> is
+ configured to be <code>RequestResponse</code>, then
+ a reply will be sent to the request message's
+ <property>ReplyTo EPR</property>. If it is not set,
+ it will be sent to the request message's
+ <property>From EPR</property>. If no end-point
+ reference has been specified, then no error message
+ will be logged by the system.
</para>
</listitem>
</itemizedlist>
-
- <note>
+<important>
<para>
- We recommend that all action pipelines should use the
- explicit processing mechanism. This can be enabled by
- simply adding the 'mep' attribute to the 'actions' element
- in the jboss-esb.xml file. The value of this attribute
- should be either 'OneWay' or 'RequestResponse'.
+ Always use the explicit processing mechanism. Enable it by
+ simply adding the <property>mep</property> attribute to the
+ <property>actions</property> element in the
+ <filename>jboss-esb.xml</filename> file. The value of this
+ attribute should be set to either <code>OneWay</code> or
+ <code>RequestResponse</code>.
</para>
- </note>
-
+</important>
</section>
- <section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-Error_handling_when_processing_actions">
+ <section>
<title>
- Error handling when processing actions
+ Error Handling When Actions are Being Processed
</title>
<para>
- When processing an action chain, it is possible that errors
- may occur. Such errors should be thrown as exceptions from
- the Action pipeline, thus terminating the processing of the
- pipeline. As mentioned earlier, a Fault Message may be
- returned within an ActionProcessingFaultException. If it is
- important for information about errors to be returned to
- the sender (or some intermediary) then the FaultTo EPR
- should be set. If this is not set, then JBossESB will
- attempt to deliver error messages based on the ReplyTo EPR
- and, if that is also not set, the From EPR. If none of
- these EPRs has been set, then error information will be
- logged locally.
+ Errors may occur when an action chain is being processed.
+ Such errors are thrown as exceptions from the
+ <systemitem>pipeline</systemitem> and, hence, fromthe
+ processing of the pipeline itself. As mentioned earlier, a
+ fault message will be returned as an
+ <exceptionname>ActionProcessingFaultException</exceptionname>.
+ If it is important that information about errors be
+ returned to the sender (or an intermediary), then set the
+ <property>FaultTo EPR</property>. If it is not set, then
+ the <application>JBoss Enterprise Service Bus</application>
+ will attempt to deliver error messages based on the
+ <property>ReplyTo EPR</property>. If that too, has not been
+ set, it will use the <property>From EPR</property>. If none
+ of these have been configured, then the error information
+ will be logged locally.
</para>
<para>
- Error messages of various types can be returned from the
- Action implementations. However, JBossESB supports the
- following “system” error messages, all of which may be
- identified by the mentioned URI in the message Fault, in
- the case that an exception is thrown and no application
- specific Fault Message is present:
+ The action implementations can return error messages of
+ various types. However, the <application>JBoss Enterprise
+ Service Bus</application> supports the following "system"
+ error messages. In the case of an exception being thrown
+ and no application-specific fault message being present, it
+ may be identified by the uniform resource identifier:
</para>
<variablelist>
@@ -1095,87 +1233,97 @@
<term>urn:action/error/actionprocessingerror</term>
<listitem>
<para>
- this means that an action in the chain threw
- an ActionProcessingFaultException but did not
- include a fault message to return. The
- exception details will be contained within the
- “reason” String of the Fault.
+ This means that an action in the
+ <systemitem>chain</systemitem> threw an
+ <exceptionname>ActionProcessingFaultException</exceptionname>
+ but did not include a fault message to return.
+ Find the details of this exception within the
+ <classname>fault</classname>'s
+ <varname>reason</varname> <type>string</type>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>urn:action/error/unexpectederror</term>
- <listitem>
-
+ <listitem>
<para>
- an unexpected exception was caught during the
- processing. Details about the exception can be
- found in the “reason” String of the Fault.
- </para>
-
+ This means that an unexpected exception was
+ caught during processing. Find the details of
+ this exception within the
+ <classname>fault</classname>'s
+ <varname>reason</varname> <type>string</type>.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>urn:action/error/disabled</term>
- <listitem>
-
+ <listitem>
<para>
- action processing is disabled.
- </para>
-
+ This means that action processing is disabled.
+ </para>
</listitem>
</varlistentry>
</variablelist>
<para>
- If an exception is thrown within your Action chain, then it
- will be propagated back to the client within a
- FaultMessageException, which is re-thrown from the Courier
- or ServiceInvoker classes. This exception, which is also
- thrown whenever a Fault message is received, will contain
- the Fault code and reason, as well as any propagated
- exception.
+ If an exception is thrown within the <systemitem>action
+ pipeline</systemitem>, then it will be passed back to the
+ client as a
+ <exceptionname>FaultMessageException</exceptionname>. It is
+ then thrown again from the <classname>Courier</classname>
+ or <classname>ServiceInvoker</classname> classes. This
+ exception, which is also thrown whenever a
+ <classname>Fault</classname> message is received, will
+ contain the <classname>fault</classname> code and reason,
+ as well as any exception that has been passed on.
</para>
</section>
</section>
- <section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-Meta-Data_and_Filters">
+ <section>
<title>
Meta-Data and Filters
</title>
<para>
- As a message flows through the ESB it may be useful to attach
- meta-data to it, such as the time it entered the ESB and the
+ As a message flows through the Enterprise Service Bus, one may
+ wish to to attach meta-data to it. This could include such
+ information as the time the message entered the ESB and the
time it left. Furthermore, it may be necessary to dynamically
- augment the message; for example, adding transaction or
- security information. Both of these capabilities are supported
- in JBossESB through the filter mechanism, for both gateway and
- ESB nodes.
+ augment the message by, for example, adding transaction or
+ security data. The Enterprise Service Bus supports both of
+ these capabilities (for both gateway and ESB nodes), via the
+ <systemitem>filter mechanism</systemitem>.
</para>
<note>
<para>
- The filter property name, the package for the
- InputOutputFilter and its signature all changed in
- JBossESB 4.2 MR3 from earlier milestone releases.
+ Please be aware that the name of the filter property, the
+ package for the InputOutputFilter and its signature all
+ changed in <application>JBossESB 4.2 MR3</application> from
+ those that were present in earlier milestone releases.
</para>
</note>
<para>
- The class org.jboss.soa.esb.filter.InputOutputFilter has two
- methods:
+ The
+ <classname>org.jboss.soa.esb.filter.InputOutputFilter</classname>
+ class has two methods:
</para>
- <itemizedlist>
-
+ <itemizedlist>
<listitem>
<para>
- public Message onOutput (Message msg, Map<String,
- Object> params) throws CourierException which is
- called as a message flows to the transport. An
+ public <type>Message </type>
+ <methodname>onOutput</methodname> (<type>Message</type>
+ <parameter> msg</parameter>, <type>Map<String,
+ Object></type> <parameter> params</parameter>)
+ throws a
+ <exceptionname>CourierException</exceptionname>. This
+ is called as a message flows to the transport. An
implementation may modify the message and return a new
version. Additional information may be provided by the
caller in the form of extra parameters.
@@ -1184,60 +1332,64 @@
<listitem>
<para>
- public Message onInput (Message msg, Map<String,
- Object> params) throws CourierException which is called
- as a message flows from the transport. An
+ public <type>Message</type><methodname>
+ onInput</methodname> (<type>Message</type><parameter>
+ msg</parameter>, <type>Map<String,
+ Object></type><parameter> params</parameter>) throws
+ a <exceptionname>CourierException</exceptionname>. This
+ is called as a message flows from the transport. An
implementation may modify the message and return a new
version. Additional information may be provided by the
caller in the form of extra parameters.
</para>
- </listitem>
-
+ </listitem>
</itemizedlist>
<para>
- Filters are defined in the filters section of the
- jbossesb-properties.xml file (typically located in the
- jbossesb.sar archive) using the property
- org.jboss.soa.esb.filter.<number>, where <number> can be any
- value and is used to indicate the order in which multiple
- filters are to be called (lowest to highest).
+ Define filters in the <code>filters</code> section of the
+ <filename>jbossesb-properties.xml</filename> file (located in
+ the <package>jbossesb.sar</package> archive.) To do so, use the
+ <property>org.jboss.soa.esb.filter.<number></property>
+ property, where <property><number></property> can be any
+ value. This value is used to indicate the order in which
+ multiple filters are to be called (from lowest to highest.)
</para>
<note>
<para>
- You will need to place any changes to your
- jbossesb-properties.xml file on each ESB instance that is
- deployed in your environment. This will ensure that all ESB
- instances can process the same meta-data.
+ It is necessary to place any changes to the
+ <filename>jbossesb-properties.xml</filename> file on each ESB
+ instance that is deployed in the environment. This will ensure
+ that every instances can process the same meta-data.
</para>
</note>
<para>
- JBossESB ships with:
+ The <application>JBoss Enterprise Service Bus</application>
+ ships with:
</para>
<itemizedlist>
<listitem>
<para>
- org.jboss.internal.soa.esb.message.filter.MetaDataFilter
+ <classname>org.jboss.internal.soa.esb.message.filter.MetaDataFilter</classname>
</para>
</listitem>
<listitem>
<para>
- org.jboss.internal.soa.message.filter.GatewayFilter
+ <classname>org.jboss.internal.soa.message.filter.GatewayFilter</classname>
</para>
</listitem>
<listitem>
<para>
- org.jboss.internal.soa.esb.message.filter.EntryExitTimeFilter
+ <classname>org.jboss.internal.soa.esb.message.filter.EntryExitTimeFilter</classname>
</para>
</listitem>
</itemizedlist>
<para>
- which add the following meta-data to the Message as Properties
- with the indicated property names and the returned String
+ These add the following meta-data to the message as properties
+ with the indicated property names and the returned string
values.
</para>
@@ -1248,164 +1400,192 @@
<varlistentry>
<term><classname>org.jboss.soa.esb.message.transport.type</classname></term>
- <listitem><para>File, FTP, JMS, SQL, or Hibernate.</para></listitem>
+ <listitem><para>File, FTP, JMS, SQL or Hibernate.</para></listitem>
</varlistentry>
<varlistentry>
<term><classname>org.jboss.soa.esb.message.source</classname></term>
- <listitem><para>The name of the file from which the message was read.</para></listitem>
+ <listitem><para>This is the name of the file from which the message was read.</para></listitem>
</varlistentry>
<varlistentry>
<term><classname>org.jboss.soa.esb.message.time.dob</classname></term>
- <listitem><para>The time the message entered the ESB, e.g., the time it was sent, or the time it arrived at a gateway.</para></listitem>
+ <listitem><para>This is the time at which the message
+ entered the Enterprise Service Bus. (This could
+ be the time it was sent or the time it arrived at
+ a gateway.)</para></listitem>
</varlistentry>
<varlistentry>
<term><classname>org.jboss.soa.esb.mesage.time.dod</classname></term>
- <listitem><para>The time the message left the ESB, e.g., the time it was died.</para></listitem>
- </varlistentry>
-
+ <listitem><para>This is the time at which the message left
+ the Enterprise Service Bus (in other words, the time it was
+ received.)</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><classname>org.jboss.soa.esb.gateway.original.file.name</classname></term>
- <listitem><para>If the message was received via a file related gateway node, then this element will contain the name of the original file from which the message was sourced.</para></listitem>
+ <listitem><para>If the message was received via a
+ file-related gateway node, then this element will contain the
+ name of the original file from which the message was
+ sourced.</para></listitem>
</varlistentry>
<varlistentry>
<term><classname>org.jboss.soa.esb.gatway.original.queue.name</classname></term>
- <listitem><para>If the message was received via a JMS gateway node, then this element will contain the name of the queue from which it was received.</para></listitem>
+ <listitem><para>If the message was received via a Java Message Service
+ gateway node, then this element will contain the name of the
+ queue from which it arrived.</para></listitem>
</varlistentry>
<varlistentry>
<term><classname>org.jboss.soa.esb.gateway.original.url</classname></term>
- <listitem><para>If the message was received via a SQL gateway node, then this element will contain the original database URL.</para></listitem>
+ <listitem><para>If the message was received via an SQL
+ gateway node, then this element will contain the original
+ database uniform resource locator.</para></listitem>
</varlistentry>
</variablelist>
<note>
<para>
- Although it is safe to deploy the GatewayFilter on all ESB
- nodes, it will only add information to a Message if it is
- deployed on a gateway node.
+ Although it is safe to add the
+ <classname>GatewayFilter</classname> to all of the
+ Enterprise Service Bus' nodes, it will only add information
+ to a message if one deploys it on the <systemitem>gateway
+ node</systemitem>.
</para>
</note>
<para>
- More meta-data can be added to the message by creating and
- registering suitable filters. Your filter can determine whether
- or not it is running within a gateway node through the presence
- (or absence) of the following named entries within the
- additional parameters.
+ Add more meta-data to the message by creating and registering
+ filters. Filters can determine whether or not they are running
+ within a gateway node through the presence (or absence) of the
+ following named-entries within additional parameters:
</para>
- <variablelist><title>Gateway-Generated Message Parameters</title>
-
+ <variablelist><title>Gateway-Generated Message Parameters</title>
<varlistentry>
<term><classname>org.jboss.soa.esb.gateway.file</classname></term>
- <listitem><para>The File from which the Message was sourced. This will only be present if this gateway is file based.</para></listitem>
+ <listitem><para>This is the file from which the message was sourced.
+ This will only be present if the gateway is
+ file-based.</para></listitem>
</varlistentry>
<varlistentry>
<term><classname>org.jboss.soa.esb.gateway.config</classname></term>
- <listitem><para>The ConfigTree that was used to initialize the gateway instance.</para></listitem>
- </varlistentry>
-
+ <listitem><para>This is the
+ <classname>ConfigTree</classname> that was used to
+ initialise the gateway instance.</para></listitem>
+ </varlistentry>
</variablelist>
<note>
<para>
- Only file based, JMS and SQL gateways have support for the
- GatewayFilter in JBossESB 4.8.
+ Red Hat only supports the
+ <classname>GatewayFilter</classname> when one uses
+ file-based Java Message Service and SQL gateways.
</para>
</note>
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-Building_and_Using_Services-What_is_a_Service">
+<section>
<title>
What is a Service?
</title>
<para>
- JBossESB does not impose restrictions on what constitutes a
- service. As we discussed earlier in this document, the ideal
- SOA infrastructure encourages a loosely coupled interaction
- pattern between clients and services, where the message is of
- critical importance and implementation specific details are
- hidden behind an abstract interface. This allows for the
- implementations to change without requiring clients/users to
- change. Only changes to the message definitions necessitate
- updates to the clients.
+ In the <application>JBoss Enterprise Service Bus</application>,
+ a service is defined as "a list of action classes that process
+ a message in a sequential manner." Within this definition, the
+ Enterprise Service Bus does not impose restrictions with regard
+ to what should constitute a service. As discussed earlier in
+ this document, the ideal SOA infrastructure encourages a
+ loosely-coupled interaction pattern between clients and
+ services, whereby the message is of critical importance and
+ implementation specific-details are hidden behind an abstract
+ interface. This means that the implementations can be changed
+ without the need to alter clients at the same time. Only
+ changes to the message definitions will necessitate updates to
+ the clients.
</para>
<para>
- As such and as we have seen, JBossESB uses a message driven
- pattern for service definitions and structures: clients send
- Messages to services and the basic service interface is
- essentially a single process method that operates on the
- Message received. Internally a service is structured from one
- or more Actions, that can be chained together to process
- incoming the incoming Message. What an Action does is
- implementation dependent, e.g., update a database table entry,
- or call an EJB.
+ For this reason, the Enterprise Service Bus uses a
+ message-driven pattern for service definitions and structures:
+ clients send messages to services, the basic service interface
+ being essentially a single process-method that subsequently
+ operates on the message as it is received. Internally, a
+ service is structured from one or more actions, that can be
+ chained together to process the incoming message. All of the
+ tasks undertaken by an action are implementation-dependent. Two
+ examples of this are, firstly, the processes to update a
+ database table entry and, secondly, a call to an
+ <firstterm>Enterprise Java Bean</firstterm>.
</para>
-
+<orderedlist>
+ <listitem>
<para>
- When developing your services, you first need to determine the
- conceptual interface/contract that it exposes to
- users/consumers. This contract should be defined in terms of
- Messages, e.g., what the payload looks like, what type of
- response Message will be generated (if any) etc.
+ When developing customised services, firstly determine the type
+ of conceptual interface (or <firstterm>contract</firstterm>)
+ that it is to expose to consumers. Define it in terms of
+ messages, (think, for example, of what the payload should look
+ like, what type of Response Message, if any, will be generated
+ and so forth.)
</para>
-
- <note>
+ </listitem>
+ <listitem>
<para>
- Once defined, the contract information should be published
- within the registry. At present JBossESB does not have any
- automatic way of doing this.
+ Once defined, publish the contract information
+ in the <systemitem>registry</systemitem>. (At present,
+ there is no way to do this automatically.)
</para>
- </note>
-
+ </listitem>
+ <listitem>
<para>
- Clients can then use the service as long as they do so
- according to the published contract. How your service processes
- the Message and performs the work necessary, is an
- implementation choice. It could be done within a single Action,
- or within multiple Actions. There will be the usual trade-offs
- to make, e.g., manageability versus re-useability.
+ Clients can then use the service, as long as they do so in
+ accordance with the published contract. How the service
+ processes the message and performs the work necessary are
+ implementation choices. It could be done within a single action
+ or within multiple actions. One will have the usual trade-off
+ (that of manageability versus re-usability) to bear in mind
+ when making this decision
</para>
-
+ </listitem>
+</orderedlist>
<note>
<para>
- In subsequent releases we will be improving tool support to
- facilitate the development of services.
+ In subsequent releases, Red Hat will be improving tool
+ support in order to facilitate the development of services.
</para>
</note>
- <section id="sect-SOA_ESB_Programmers_Guide-What_is_a_Service-ServiceInvoker">
+ <section>
<title>
- ServiceInvoker
+ The "ServiceInvoker"
</title>
<para>
- From a clients perspective, the Courier interface and its
+ From a client's perspective, the Courier interface and its
various implementations can be used to interact with
services. However, this is still a relatively low-level
- approach, requiring developer code to contact the registry
- and deal with failures. Furthermore, since JBossESB has
- fail-over capabilities for stateless services, this would
- again have to be managed by the application. See the
- Advanced chapter for more details on fail-over.
+ approach, as it requires the developer code to contact the
+ registry and deal with failures. Furthermore, since the
+ JBoss Enterprise Service Bus has fail-over capabilities for
+ stateless services, this would, again, have to be managed by
+ the application. See the "Advanced" chapter for more details
+ on fail-over functionality.
</para>
<para>
- In JBossESB 4.2, the ServiceInvoker was introduced to help
- simplify the development effort. The ServiceInvoker hides
- much of the lower level details and opaquely works with the
- stateless service fail-over mechanisms. As such,
- ServiceInvoker is the recommended client-side interface for
- using services within JBossESB.
+ The <interfacename>ServiceInvoker</interfacename> was introduced in
+ <application>JBoss Enterprise Service Bus 4.2</application> to help simplify the
+ development effort. It assists by hiding many of the lower
+ level details and works opaquely with the stateless service
+ fail-over mechanisms. Because of this, Red Hat recommends using the
+ <interfacename>ServiceInvoker</interfacename> as the
+ client-side interface for ESB services.
</para>
@@ -1414,101 +1594,147 @@
<para>
- An instance of ServiceInvoker can be created for each
- service with which the client requires interactions. Once
- created, the instance contacts the registry where
- appropriate to determine the primary EPR and, in the case
- of fail-overs, any alternative EPRs.
+ Create an instance of the
+ <interfacename>ServiceInvoker</interfacename> for each
+ service with which the client needs to interact. Once
+ created, each instance contacts the
+ <systemitem>registry</systemitem> where appropriate, in
+ order to determine the primary end-point references (and,
+ in the case of fail-overs, any alternative end-point
+ references.)
</para>
<para>
- Once created, the client can determine how to send Messages
- to the service: synchronously (via deliverSync) or
- asynchronously (via deliverAsync). In the synchronous case,
- a timeout must be specified which represents how long the
- client will wait for a response. If no response is received
- within this period, a MessageDeliverException is thrown.
+ The client can then determine how to send messages to the
+ service: synchronously (via
+ <classname>deliverSync</classname>) or asynchronously (via
+ <classname>deliverAsync</classname>.) When it is
+ synchronous, one must specify a time-out value. This
+ time-out represents for how long the client will await a
+ response. If no response is received during this period, an
+ <exceptionname>ResponseTimeoutException</exceptionname> is
+ thrown.
</para>
<note>
<para>
- From JBossESB 4.5 onwards the ResponseTimeoutException is
- thrown, which is derived from MessageDeliverException.
+ From <application>JBossESB 4.5</application> onwards, the
+ <exceptionname>ResponseTimeoutException</exceptionname> is
+ thrown. This is derived from
+ <exceptionname>MessageDeliverException</exceptionname>.
</para>
</note>
<para>
- Failures to contact the Registry or to successfully look up the
- service are indicated by throwing a RegistryException from
- deliverSync. Timeout values may indicate that the service has
- failed, simply overloaded and cannot respond in the time or
- that the work requested takes longer than the timeout allowed.
- In some cases the problem will be transient and trying again
- later may be sufficient.
- </para>
+ A
+ <exceptionname>RegistryException</exceptionname> is thrown from
+ <classname>deliverSync</classname> if there is a failure to either contact the
+ <systemitem>registry</systemitem> or to successfully look up
+ the service. Time-out values may
+ indicate one of three possibilities:
+ </para>
- <para>
- Any other type of failure during communication with the service
- cause a FaultMessageException to be thrown.
+ <orderedlist>
+ <listitem>
+ <para>
+ a service failure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ an indication that it is simply overloaded and cannot
+ respond in time
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the work requested is taking longer than the allowed
+ duration of time-out.
+ </para>
+ </listitem>
+ </orderedlist>
+<note>
+ <para>
+ In some cases the problem will be
+ transient and, therefore, it may disappear on the next try.
</para>
-
+</note>
<note>
<para>
- When using the deliverAsync method all errors are thrown as
- MessageDeliverExcepion instances, with the actual exception
- embedded within it.
+ Any other kind of failure during communication with the service
+ will result in a
+ <exceptionname>FaultMessageException</exceptionname> being
+ thrown.
</para>
</note>
<para>
As mentioned earlier in this document, when sending a
- Message it is possible to specify values for To, ReplyTo,
- FaultTo etc. within the Message header. When using the
- ServiceInvoker, because it has already contacted the
- registry at construction time, the To field is unnecessary.
- In fact, when sending a Message through ServiceInvoker, the
- To field will be ignored in both the synchronous and
- asynchronous delivery modes. In a future release of
- JBossESB it may be possible to use any supplied To field as
- an alternate delivery destination should the EPRs returned
- by the registry fail to resolve to an active service.
+ message it is possible for one to specify values for
+ <classname>To</classname>, <classname>ReplyTo</classname>,
+ <classname>FaultTo</classname> and so forth, within the
+ header. When using the
+ <interfacename>ServiceInvoker</interfacename>, the
+ <classname>To</classname> field is not needed. This is
+ because it has already contacted the
+ <systemitem>registry</systemitem> at the time of being
+ built. In fact, when sending a message through the
+ <interfacename>ServiceInvoker</interfacename>, the
+ <property>To</property> field will be ignored in both the
+ synchronous and asynchronous delivery modes.
+ </para>
+<note>
+ <para>
+ In a future
+ release of the <application>JBoss Enterprise Service
+ Bus</application>, it may be possible to use any supplied
+ <property>To</property> field as an alternate delivery
+ destination, should the end-point references returned by
+ the <systemitem>registry</systemitem> fail to resolve to an
+ active service.
</para>
-
+</note>
+<note>
<para>
- We will discuss the fail-over properties of JBossESB in the
- Advanced section and how ServiceInvoker can opaquely mask
- failures of individual service instances if multiple copies
- appear in the registry. However, in some cases it may be
- desired to prevent automatic fail-over and inform the
- application immediately that a failure occurs. This can be
- set at the global level by setting the
- org.jboss.soa.esb.exceptionOnDeliverFailure property to
- true in the JBossESB property file. Alternatively this can
- be configured on a per message basis by setting the same
- property in the specific Message property to true. In both
- cases the default is false.
+ The <application>JBoss Enterprise Service
+ Bus</application>'s fail-over properties are discussed in
+ the "Advanced" section of this book. In that section, there
+ is also a discussion of how the
+ <interfacename>ServiceInvoker</interfacename> can opaquely
+ mask failures of individual service instances if multiple
+ copies appear in the <systemitem>registry</systemitem>.
+ However, one may wish, in some cases, to prevent automatic
+ fail-over in order to, instead, inform the application
+ immediately that a failure occurs. To achieve this, set the
+ global level by configuring the
+ <classname>org.jboss.soa.esb.exceptionOnDeliverFailure</classname>
+ property to <code>true</code> in the
+ <filename>property</filename> file. Alternatively,
+ configure this on a per-message basis. One can do this by
+ setting that same property in the specific message to
+ <code>true</code>. (In both cases, the default value is
+ <code>false</code>.)
</para>
-
+</note>
</section>
- <section id="sect-SOA_ESB_Programmers_Guide-Transactions">
+ <section>
<title>
Transactions
</title>
<para>
- Some Couriers support transactional delivery semantics, e.g.,
- InVM and JMS. The current delivery semantics for such Couriers
- is based on JMS transacted sessions, i.e., the message is
- placed on a queue within the scope of a transaction but not
- actually delivered until the enclosing transaction has
- committed; it is then pulled by the receiver in the scope of a
- separate transaction. Unfortunately for synchronous
- request/response interactions this can result in a timeout
- waiting for the response since the sender blocks waiting for
- the response before it can terminate the delivery transaction.
+ Some couriers, such as the InVM and the Java Message Service,
+ support <firstterm>transactional delivery
+ semantics</firstterm>. The current delivery semantics for such
+ a courier are based on <firstterm>JMS transacted
+ sessions</firstterm>. In other words, the message is placed in
+ a queue within the scope of a transaction. However, it is not
+ actually delivered until the enclosing transaction has been
+ committed. It is then pulled by the receiver within the scope
+ of a separate transaction.
</para>
<para>
@@ -1520,138 +1746,159 @@
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-What_is_a_Service-Services_and_ServiceInvoker">
+<section>
<title>
Services and the ServiceInvoker
</title>
<para>
- In a client-service environment the terms client and
- service are used to represent roles and a single entity can
- be a client and a service simultaneously. As such, you
- should not consider ServiceInvoker to be the domain of
- “pure” clients: it can be used within your Services and
- specifically within Actions. For example, rather than using
- the built-in Content Based Routing, an Action may wish to
- re-route an incoming Message to a different Service based
- on evaluation of certain business logic. Or an Action could
- decide to route specific types of fault Messages to the
- Dead Letter Queue for later administration.
+ In a client-service environment, the titular terms "client"
+ and "service" are used to represent roles. Understand that
+ a single entity can be both a client and a service
+ simultaneously. Hence, do not consider the
+ <interfacename>ServiceInvoker</interfacename> to be purely
+ the domain of clients: it can be used within services and,
+ specifically, within actions. For example, rather than
+ using the built-in <systemitem>content-based
+ router</systemitem>, an action may re-route an incoming
+ message to a different service based on evaluation of
+ certain business logic. Alternatively, an action could
+ determine to route specific kinds of fault message to the
+ <systemitem>Dead Letter Queue</systemitem> for later
+ administrative review.
</para>
<para>
- The advantage of using ServiceInvoker in this way is that
- your Services will be able to benefit from the opaque
- fail-over mechanism described in the Advanced chapter. This
- means that one-way requests to other Services, faults etc.
- can be routed in a more robust manner without imposing more
- complexity on the developer.
+ The advantage of using the
+ <interfacename>ServiceInvoker</interfacename> in this way,
+ is that one's services will be able to benefit from the
+ opaque fail-over mechanism (which is described in the
+ "Advanced" chapter.) This means that one-way requests to
+ other services, faults and so on can be routed in a more
+ robust manner without imposing more complexity upon the
+ developer.
</para>
</section>
- <section id="sect-SOA_ESB_Programmers_Guide-What_is_a_Service-InVM_Transport">
+ <section>
<title>
InVM Transport
</title>
<para>
- The InVM transport is a new feature since JBossESB 4.3 that
+ The <firstterm>InVM Transport</firstterm> is a feature that
provides communication between services running on the same
- JVM. This means that instances of ServiceInvoker can invoke
- a service from within the same JVM without any networking
- or message serialization overhead.
+ Java Virtual Machine (InVM stands for <firstterm>In Virtual
+ Machine</firstterm>.) This means that instances of the
+ <interfacename>ServiceInvoker</interfacename> can invoke
+ services from within the same JVM without generating any
+ networking or message serialization overhead.
</para>
<note>
<para>
- It is important to realize that InVM achieves its
- performance benefits by optimizing the internal data
- structures that are used to facilitate inter-service
- communication. For example, the queue used to store messages
- is not persistent (durable) which means that Messages may be
- lost in the event of failures. Furthermore if a service is
- shutdown before the queue is emptied, those Messages will
- not be delivered. Further limitations are mentioned
- throughout this section within corresponding Notes. Because
- JBossESB allows services to be invoked across multiple
- different transports concurrently you should be able to
- design your services such that you can achieve high
- performance and reliability by the suitable choice of
- transport for specific Message types.
- </para>
+ It is important to realise that the InVM feature achieves
+ its performance benefits by optimising those internal data
+ structures used to facilitate inter-service communication.
+ Note that the queue used to store messages is not
+ <firstterm>persistent</firstterm> (durable.) This means
+ that messages may be lost in the event of a failure.
+ Furthermore, if a service is shut down before the queue is
+ emptied, those messages will not be delivered. Other
+ limitations are mentioned throughout this section (within
+ corresponding notes.)
+ </para>
</note>
-
<para>
- Earlier versions of the ESB did not support this transport
- and required every service to be configured with at least
- one Message Aware listener. This is not longer a
- requirement; Services can now be configured without any
- <listeners> configuration and still be invokable from
- within their VM e.g.
+ Because the <application>JBoss Enterprise Service
+ Bus</application> allows services to be invoked
+ concurrently across multiple different transports, it is
+ straightforward to design services in such a way that they
+ can achieve high performance and reliability. Do this by
+ making a suitable choice of transport for each
+ type of message.
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/invm.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- This makes Service configuration a little more straightforward.
- </para>
+ Earlier versions of the Enterprise Service Bus did not
+ support this transport and required one to configure every
+ service to possess at least one message-aware listener.
+ This is no longer a requirement; services can now be
+ configured without any <listeners> configuration and
+ still be invokable from within their own virtual machines:
+ </para>
+
+
+ <programlisting language="XML"><xi:include href="extras/building_and_using_services/invm.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+ <para>
+ This makes service configuration a little more
+ straightforward.
+ </para>
</section>
-
+
<section>
<title>
InVM Scope
</title>
- <para>
- InVM Service invocation scope can be controlled through the
- “invmScope” attribute on the <service> element. The
- ESB currently supports 2 scopes:
+ <para>
+ Control InVM service invocation scope through the
+ <service> element's <property>invmScope</property>
+ attribute. Red Hat currently supports two such scopes:
</para>
<orderedlist>
<listitem>
<para>
- NONE: The Service is not invokable over the
- InVM transport.
+ <code>NONE</code>: The Service cannot be invoked over the
+ InVM Transport. This is the
+ the default value.
</para>
</listitem>
<listitem>
<para>
- GLOBAL: (Default) The Service is invokable over
- the InVM transport from within the same
+ <code>GLOBAL</code>: The service can be
+ invoked the InVM transport from within the same
Classloader scope.
</para>
</listitem>
</orderedlist>
-
+<note>
<para>
- A “LOCAL” scope will be added in a future release, which
- will restrict invocation to within the same .esb
- deployment.
+ A <code>LOCAL</code> scope will be added in a future
+ release. It will limit the scope of invocation to within
+ the same deployed <filename>.esb</filename> archive.
</para>
-
+</note>
<para>
- Each service can specify their own InVM scope in the
- invmScope attribute on the <service> element of their
- services configuration:
+ Specify an individual InVM scope for each service bu using
+ the appropriately-named <parameter>invmScope</parameter>
+ attribute (found on the services configuration's
+ <service> element):
</para>
- <programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/Code_Example7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/building_and_using_services/Code_Example7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The default InVM Scope for an ESB deployment can be set in
- the jbossesb-properties.xml file through the
- “core:jboss.esb.invm.scope.default” config property. If not
- defined, the default scope is “GLOBAL”.
+ Specify the default InVM scope for an Enterprise Service
+ Bus deployment via
+ <filename>jbossesb-properties.xml</filename> file's
+ <property>core:jboss.esb.invm.scope.default</property>
+ property. The pre-configured value is <code>NONE</code>.
+ (However, if this property were undefined, the default scope
+ would actually be <code>GLOBAL</code>.)
</para>
</section>
@@ -1662,77 +1909,86 @@
</title>
<para>
- The InVM listener can execute within a transacted or
- non-transacted scope in the same manner as the other
- transports which support transactions. This behaviour
- can be controlled through explicit or implicit
- configuration.
- </para>
+ The <systemitem>InVM listener</systemitem> can run
+ within either <firstterm>transacted</firstterm> or
+ <firstterm>non-transacted scopes</firstterm>. It does
+ so in the same manner as the other transports which
+ support transactions. Control this behaviour by
+ modifying either explicit or implicit configuration
+ settings.
+ </para>
+
<para>
- The explicit configuration of the transacted scope is
- controlled through the definition of the
- “invmTransacted” attribute on the <service> element and
- will always take precedence over the implicit
+ Manipulate the transacted scope's explicit
+ configuration through the service element's
+ <property>invmTransacted</property> attribute. This
+ setting always take precedence over the implicit
configuration.
</para>
-
+ <note>
<para>
- The ImVM listener will be implicitly transacted if
- there is another transacted transport configured on the
- service. At present these additional transports can be
- jms, scheduled or sql.
+ The <systemitem>InVM listener</systemitem> will be transacted
+ implicitly if there is another transacted transport
+ configured on the same service. At present, these additional
+ transports can be of the JMS, Scheduled or
+ SQL types.
</para>
+ </note>
</section>
<section>
<title>
Transaction Semantics
</title>
-
+<warning>
<para>
- The InVM transport in JBossESB is not transactional and
- the message queue is held only in volatile memory. This
- means that the Message Queue for this transport will be
- lost in the case of system failure or shutdown.
- </para>
+ The Enterprise Service Bus' <firstterm>InVM
+ Transport</firstterm> is not transactional and the
+ <systemitem>message queue</systemitem> is held in
+ volatile memory. This means that the latter will be
+ lost in the case of shut down or system failure.
+ </para>
+</warning>
- <note>
+ <important>
<para>
- You may not be able to achieve all of the ACID semantics,
- particularly when used in conjunction with other transactional
- resources such as databases, because of the volatility aspect
- of the InVM queue. But the performance benefits of InVM should
- outweigh this downside in the majority of cases. In the
- situations where full ACID semantics are required, we recommend
- that you use one of the other transactional transports, such as
- JMS or database.
+ One may not be able to achieve all of the ACID (Atomicity,
+ Consistency, Isolation, Durability) semantics with the InVM
+ transport, especially when itis used in conjunction with other
+ transactional resources such as databases. This is because of
+ the volatility of the InVM queue. However, the performance
+ benefits of InVM will outweigh this downside in the majority of
+ cases. In situations in which full ACID semantics are required,
+ Red Hat recommends that one uses another of the transactional
+ transports, such as the Java Message Service.
</para>
- </note>
+ </important>
<para>
- When using InVM within a transaction, the message will not
- appear on the receiver's queue until the transaction
- commits, although the sender will get an immediate
- acknowledgement that the message has been accepted to be
- later queued. If a receiver attempts to pull a message from
- the queue within the scope of a transaction, then the
- message will be automatically placed back on the queue if
- that transaction subsequently rolls back. If either a sender
- or receiver of a message needs to know the transaction
- outcome then they should either monitor the outcome of the
- transaction directly, or register a Synchronization with the
- transaction.
+ When InVM is used within a transaction, the
+ message will not appear on the receiver's queue until that
+ transaction actually commits. However, the sender will
+ receive an immediate acknowledgment that the message has
+ been accepted for later queuing. If a receiver attempts to
+ pull a message that is within the scope of a transaction from the
+ queue, then that message will be automatically placed back in
+ the queue in the case that the transaction is subsequently
+ rolled back. If either a message sender or receiver
+ needs to know the transaction outcome, then they should
+ either monitor it directly, or register a transaction
+ <firstterm>synchronization</firstterm>.
</para>
<para>
- When a message is placed back on the queue by the transaction
- manager, it may not go back into the same location. This is a
- deliberate choice in order to maximize performance. If your
- application needs specific ordering of messages then you
- should consider a different transport or group related
- messages into a single “wrapper” message.
+ When the <firstterm>Transaction Manager</firstterm> places a
+ message back in the queue, it may not go back to the same
+ location. This was a deliberate design choice made with the
+ intention of maximising performance. If one's application
+ needs messages to be placed in a specific order, then either
+ consider using a different transport or group related messages
+ within one single "wrapper" message.
</para>
</section>
@@ -1743,8 +1999,9 @@
</title>
<para>
- To change the number of listener threads associated
- with an InVM transport,
+ In order to change the number of listener threads
+ associated with an InVM Transport, use
+ this code:
</para>
@@ -1756,53 +2013,54 @@
<section>
<title>
- Lock-step Delivery
+ Lock-Step Delivery
</title>
<para>
- The InVM Transport delivers messages with low overhead to
- an in-memory message queue. This is very fast and the
- message queue can become overwhelmed if delivery is
- happening too quickly for the Service consuming the
- messages. To mitigate these situations the InVM transport
- provides a "Lock-Step" delivery mechanism.
+ The <systemitem>InVM transport</systemitem> delivers
+ low-overhead messages to an in-memory queue. This occurs
+ very quickly and, as a result, the message queue can become
+ overwhelmed if delivery is happening too rapidly for the
+ service that is "consuming" the messages. To mitigate this
+ situation, the InVM Transport provides a
+ <firstterm>lock-step delivery</firstterm> mechanism.
</para>
<para>
- The "Lock-Step" delivery method attempts to ensure that
- messages are not delivered to a service faster than the
- service is able to retreive them. It does this by blocking
- message delivery until the receiving Service picks up the
- message or a timeout period expires.
+ This mechanism ensures that messages are not delivered to a
+ service at a rate faster than that at which the latter is
+ able to retrieve them. It does this by blocking delivery
+ until either the receiving service picks up the message or
+ a time-out period expires.
</para>
-
+ <note>
<para>
- This is not a synchronous delivery method. It does not wait
- for a response or for the service to process the message. It
- only blocks until the message is removed from the queue by
- the service.
+ This is not a synchronous delivery method.
+ It does not wait for a response or for the service to
+ process the message. It only blocks delivery until the
+ message is removed from the queue by the service.
</para>
-
+ </note>
<para>
- Lock Step delivery is disabled by default, but can be easily
- enabled for a service using its <property> settings on
- the <service>:
+ Lock-step delivery is disabled by default. To enable it,
+ use the <service>'s <property> settings:
</para>
<itemizedlist>
<listitem>
<para>
- inVMLockStep: A boolean value controlling
- whether LockStep delivery is enabled
+ <property>inVMLockStep</property>: this is a
+ Boolean value that controls whether LockStep
+ delivery is enabled
</para>
</listitem>
<listitem>
<para>
- inVMLockStepTimeout: The maximum number of
- milliseconds that message delivery will be
- blocked while waiting for a message to be
- retreived.
+ <property>inVMLockStepTimeout</property>: this
+ is the maximum number of milliseconds for which
+ message delivery will be blocked whilst the
+ system waits for a message to be retreived.
</para>
</listitem>
</itemizedlist>
@@ -1811,11 +2069,12 @@
<note>
<para>
- If using InVM within the scope of a transaction, lock-step
- delivery is disabled. This is because the insertion of a
- message in to the queue is contingent on the commit of the
- enclosing transaction, which may occur an arbitrary time
- before or after the expected lock-step wait period.
+ If one is using the <systemitem>InVM transport</systemitem>
+ within the scope of a transaction, lock-step delivery is
+ disabled. This is because the insertion of a message into
+ the queue is contingent on the commitment of the enclosing
+ transaction. This commitment may occur at any time before
+ or after the expected lock-step wait period.
</para>
</note>
@@ -1827,11 +2086,12 @@
</title>
<para>
- One of the features of the ServiceInvoker is that of load
- balancing invocations in situations where there are
- multiple endpoints available for the target Service. The
- ServiceInvoker supports a number of load balancing
- strategies as part of this feature.
+ If a service is available and the
+ <interfacename>ServiceInvoker</interfacename> is being used, it is
+ always invoked in preference to its InVM transport. Other
+ <firstterm>load balancing strategies</firstterm> are only
+ applied in the absence of the the target service having an
+ InVM end-point.
</para>
<para>
@@ -1849,18 +2109,23 @@
</title>
<para>
- By default, the InVM transport passes Messages “by
- reference”. In some situations, this can cause data
- integrity issues, not to mention class cast issues
- where messages are being exchanged across
- ClassLoader boundaries.
+ By default, the <systemitem>InVM
+ transport</systemitem> passes Messages
+ <firstterm>by reference</firstterm>. In some
+ situations, this can cause data integrity issues.
+ It can also result in <firstterm>class
+ cast</firstterm> issues, whereby messages are
+ exchanged across <classname>ClassLoader</classname>
+ boundaries.
</para>
<para>
- Message passing “by value” (and so avoid issues such as
- those listed above) can be turned on by setting the
- “inVMPassByValue” property on the service in question to “true”:
+ In order to avoid these problems, set message-passing to
+ work <firstterm>by value</firstterm>. Turn this on by
+ setting the service in question's
+ <property>inVMPassByValue</property> property to
+ <code>true</code>:
</para>
@@ -1877,18 +2142,18 @@
</title>
<para>
- A contract definition can be specified on a service by the
- inclusion of XML schema definitions representing the incoming
- request, outgoing response and fault detail messages which are
- supported by the corresponding service. The schemas
- representing the request and response messages are used to
- define the format of the contents for the main body section of
- the message and can enforce validation of that content.
+ To specify a contract definition on a service, include an
+ <firstterm>XML schema definition</firstterm>. These schemas
+ definitions represent those incoming request, outgoing response
+ and fault messages supported by the corresponding service. Use
+ the schemas representing the request and response messages to
+ define the format of the main body section's contents also to
+ enforce validation of that same content.
</para>
<para>
- The schemas are declared by specifying the following attributes
- on the <actions> element associated with the service
+ Declare the schemas by specifying the following attributes on
+ the service's <actions> element:
</para>
@@ -1906,7 +2171,7 @@
<row>
<entry>inXsd</entry>
- <entry>The resource containing the schema for the
+ <entry>This is the resource containing the schema for the
request message, representing a single
element.</entry>
<entry>xsd:string</entry>
@@ -1914,31 +2179,26 @@
<row>
<entry>outXsd</entry>
- <entry>The resource containing the schema for the
+ <entry>This is the resource containing the schema for the
response message, representing a single element.</entry><entry>
xsd:string</entry>
</row>
<row>
<entry>faultXsd</entry>
- <entry>A comma separated list of schemas, each
+ <entry>This is a comma-separated list of schemas, each
representing one or more fault elements.</entry><entry>
xsd:string</entry>
</row>
<row>
<entry>requestLocation</entry>
- <entry>The location of the request contents within the
- body, if not the default location. </entry><entry>
+ <entry>This is the location of the request contents within the
+ body, if it is not in the default location. </entry><entry>
xsd:string</entry>
</row>
- <row>
- <entry>responseLocation</entry>
- <entry>The location of the response contents within the
- body, if not the default location.</entry><entry>
- xsd:string</entry>
- </row>
+
</tbody>
</tgroup>
@@ -1949,37 +2209,38 @@
<section>
<title>
- Message validation
+ Message Validation
</title>
<para>
- The contents of the request and response messages can
- be automatically validated providing that the
- associated schema has been declared on the '<actions>'
- element. The validation can be enabled by specifying
- the 'validate' attribute on the '<actions>' element
- with a value of 'true'.
+ To automatically validate the contents of the request
+ and response messages, the associated schema must be
+ declared on the <actions> element. Enable this
+ functionality by setting the <actions> element's
+ <property>validate</property> attribute to
+ <code>true</code>.
</para>
-
+<note>
<para>
Validation is disabled by default.
</para>
-
+</note>
</section>
<section>
<title>
- Exposing an ESB service as a webservice
+ Exposing ESB Services via Web Service End-Points
</title>
<para>
- Declaration of the contract schemas will automatically
- enable the exposure of the ESB service through a webservice
- endpoint, the contract for which can be located through the
- contract web application. This functionality can modified
- by specifying the 'webservice' attribute, the values for
- which are as follows.
+ Simply declaring contract schemas automatically exposes an
+ ESB service through a web service end-point, the contract
+ for which can be located via the
+ <application>Contract</application> web application. To
+ modify this functionality, specify the
+ <property>webservice</property> attribute, the values for
+ which are as follows:
</para>
<table>
@@ -1999,7 +2260,7 @@
<row>
<entry>true</entry>
- <entry>A web service end-point is published (default).</entry>
+ <entry>A web service end-point will be published (default.)</entry>
</row>
</tbody>
@@ -2008,14 +2269,14 @@
<para>
- By default the webservice endpoint does not support
- WS-Addressing but this can be enabled through use of the
- 'addressing' attribute.
+ By default, the web service end-point does not support
+ <classname>WS-Addressing</classname>. To enable this feature,
+ configure the <property>addressing</property> attribute.
</para>
- <table id="ws_Addressing_table">
+ <table>
<title>WS-Addressing Values</title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
<colspec colname="c1" colwidth="1*"/>
@@ -2028,26 +2289,28 @@
<row>
<entry>false</entry>
- <entry>No support for WS-Addressing (default).</entry>
+ <entry>WS-Addressing is not supported (default.)</entry>
</row>
<row>
<entry>true</entry>
- <entry>Require WS-Addressing support.</entry>
+ <entry>WS-Addressing support is required.</entry>
</row>
</tbody>
</tgroup>
- </table>
+ </table>
<para>
- When support for addressing is enabled, the WS-Addressing
- Message Id, Relates To URIs and relationship types will be
- added as properties of the incoming messages.
+ When support for addressing is enabled, the
+ <property>WS-Addressing Message Id</property>,
+ <property>Relates To URIs</property> and
+ <property>Relationship</property> types are added, as
+ properties, to the incoming messages.
</para>
- <table id="ws_properties_table">
+ <table>
<title>WS-Addressing Properties</title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
<colspec colname="c1" colwidth="4*"/>
@@ -2059,18 +2322,21 @@
<tbody>
<row>
<entry><classname>org.jboss.soa.esb.gateway.ebws.messageID</classname></entry>
- <entry>The WS-Addressing message id.</entry>
+ <entry>This is the WS-Addressing message identifier.</entry>
</row>
<row>
<entry><classname>org.jboss.soa.esb.gateway.ebws.relatesTo</classname></entry>
- <entry>A String array containing the WS-Addressing RelatesTo URIs.</entry>
+ <entry>This is a string array containing the
+ WS-Addressing <property>Relates To
+ URIs</property>.</entry>
</row>
<row>
<entry><classname>org.jboss.soa.esb.gateway.ebws.relationshipType</classname></entry>
- <entry>A String array containing the WS-Addressing
- Relationship Types corresponding to the RelatesTo URIs.</entry>
+ <entry>This is a string array containing the WS-Addressing
+ <property>Relationship</property> types corresponding to the <property>Relates To
+ URIs</property>.</entry>
</row>
</tbody>
@@ -2078,22 +2344,23 @@
</table>
<para>
- The following example illustrates the declaration of a
- service which wishes to validate the request/response
- messages but without exposing the service through a
- webservice endpoint.
+ The next example illustrates how to declare a service
+ which, (without being exposed through a web service
+ end-point), "wishes" to validate the request/response
+ messages:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/servicedeclarationwithoutexposing.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The following example illustrates the declaration of a service
- which wishes to validate the request/response messages and
- expose the service through a webservice endpoint. In addition
- the service expects the request to be provided in the named
- body location 'REQUEST' and will return its response in the
- named body location 'RESPONSE'.
+ The final example depicts the declaration of a service which
+ wishes to validate the request/response messages and be exposed
+ through a web service end-point. In addition to that, the
+ service expects the request to be provided in the
+ <property>REQUEST</property> named body location. It will give
+ its response in the <property>RESPONSE</property> named body
+ location.
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/building_and_using_services/servicedeclarationexposing.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Configuration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Configuration.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Configuration.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -24,13 +24,13 @@
</para>
<para>
- The model has 2 main sections:
+ This model has two main sections:
</para>
<figure><title>JBoss Enterprise Service Bus Configuration Model</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/configuration/chapter9_JBoss_ESB_conf_model.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/configuration/chapter9_JBoss_ESB_conf_model.png" />
</imageobject>
</mediaobject>
</figure>
@@ -59,13 +59,16 @@
</orderedlist>
<para>
- By far the easiest way to create configurations based on this
- model is using JBoss Developer Studio (<ulink
- url="http://www.jboss.com/products/devstudio/" />), but you can
- also to use an XSD aware XML Editor such as the XML Editor in
- the Eclipse IDE. This provides the author with auto-completion
- features when editing the configuration. Right mouse-click on
- the file -> Open With -> XML Editor.
+ Using JBoss
+ Developer Studio is,
+ by far, the easiest way to create configurations based on this
+ model but one can also use
+ an XSD-aware XML Editor such as the one found
+ in the <application>Eclipse </application> integrated development environment.
+ This provides the author with auto-completion features for use when
+ editing the configuration. Right mouse-click on the file ->
+ <guilabel>Open With</guilabel> -> <guilabel>XML
+ Editor</guilabel>.
</para>
</section>
@@ -75,14 +78,14 @@
<figure><title>Providers Configuration Model</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/configuration/chapter9_providers_conf_model.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/configuration/chapter9_providers_conf_model.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- The <providers> part of the configuration defines all of
- the message <provider> instances for a single instance of
+ The <code><providers></code> part of the configuration defines all of
+ the message <code><provider></code> instances for a single instance of
the ESB. Two types of providers are currently supported:
</para>
@@ -93,7 +96,7 @@
“Event Driven” providers, that is, for
listeners that are “pushed” messages.
Examples of this provider type would be
- the <jms-provider>.
+ the <code><jms-provider></code>.
</para>
</listitem>
@@ -108,35 +111,40 @@
</itemizedlist>
<para>
- A Bus Provider (e.g. <jms-provider>) can contain multiple <bus>
- definitions. The <provider> can also be decorated with
- <property> instances relating to provider specific properties
- that are common across all <bus> instances defined on that
- <provider> (e.g. for JMS - “connection-factory”,
- “jndi-context-factory” etc). Likewise, each <bus> instance can
- be decorated with <property> instances specific to that <bus>
- instance (e.g. for JMS - “destination-type”, “destination-name”
- etc).
+ A Bus Provider (e.g. <code><jms-provider></code>) can contain multiple
+ <code><bus></code> definitions. The <code><provider></code> can also be
+ decorated with <code><property></code> instances relating to provider
+ specific properties that are common across all <code><bus></code>
+ instances defined on that <code><provider></code>. For example, for JMS, these may be
+ “connection-factory”, “jndi-context-factory” and so on. Likewise,
+ each <code><bus></code> instance can be decorated with <code><property></code>
+ instances specific to that <code><bus></code> instance (such as. for JMS,
+ “destination-type”, “destination-name” and so forth.)
</para>
<para>
- As an example, a provider configuration for JMS would be as
- follows:
+ The following is an example provider configuration for JMS:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/configuration/Code_Example16.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The above example uses the “base” <provider> and <bus> types.
- This is perfectly legal, but we recommend use of the
- specialized extensions of these types for creating real
- configurations, namely <jms-provider> and <jms-bus> for JMS.
- The most important part of the above configuration is the busid
- attribute defined on the <bus> instance. This is a required
- attribute on the <bus> element/type (including all of its
- specializations - <jms-bus> etc). This attribute is used within
- the <listener> configurations to refer to the <bus> instance on
- which the listener receives its messages. More on this later.
+ The above example uses the “base” <code><provider></code>
+ and <code><bus></code> types. This is perfectly legal, but
+ we recommend use of the specialized extensions of these types
+ for creating real configurations, namely
+ <code><jms-provider></code> and
+ <code><jms-bus></code> for the Java Message Service. The
+ most important part of the above configuration is the
+ <property>busid</property> attribute defined on the
+ <code><bus></code> instance. This is a required attribute
+ on the <code><bus></code> element/type (including all of
+ its specializations such as <code><jms-bus></code> and so
+ forth.) This attribute is used within the
+ <code><listener></code> configurations to refer to the
+ <code><bus></code> instance, on which the listener
+ receives its messages. There will be more discussion of this
+ later in this book.
</para>
</section>
@@ -150,7 +158,7 @@
<figure><title>Services Configuration Model</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/configuration/chapter9_services_conf_model.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/configuration/chapter9_services_conf_model.png" />
</imageobject>
</mediaobject>
</figure>
@@ -221,19 +229,18 @@
</table>
<para>
- A <service> may define a set of <listeners> and a
- set of <actions>. The configuration model defines a
- “base” <listener> type, as well as specializations for
- each of the main supported transports (<jms-listener>,
- <sql-listener> etc.)
+ A <code><service></code> may define a set of <code><listeners></code> and a
+ set of <code><actions></code>. The configuration model defines a “base”
+ <code><listener></code> type, as well as specializations for each of
+ the main supported transports (<code><jms-listener></code>,
+ <code><sql-listener></code> etc.)
</para>
<para>
- The “base” <listener> defines the following attribute.
+ The “base” <code><listener></code> defines the following attribute.
These attribute definitions are inherited by all
- <listener> extensions. As such, they can be set for all
- of the listeners and gateways supported by JBossESB, such as
- InVM.
+ <code><listener></code> extensions. As such, they can be set for all of
+ the listeners and gateways supported by JBossESB, including the InVM transport.
</para>
<table id="SOA_ESB_Programmers_Guide-_Services_-Listener_Attributes">
@@ -312,9 +319,7 @@
is-gateway
</entry>
<entry>
- Whether or not the listener instance is a
- “Gateway” or “Message Aware” Listener. See
- footnote.
+ Whether or not the listener instance is a “Gateway”.
<footnote>
<para>
A message bus defines the details of a
@@ -334,39 +339,38 @@
</table>
<para>
- Listeners can define a set of zero or more <property>
- elements (just like the <provider> and <bus>
+ Listeners can define a set of zero or more <code><property></code>
+ elements (just like the <code><provider></code> and <code><bus></code>
elements/types). These are used to define listener specific
properties.
</para>
<note>
<para>
- For each gateway listener defined in a service, an
- ESB-aware (or “native”) listener must also be defined. This
- is because gateway listeners do not define bidirectional
- endpoints but, rather, “startpoints” into the ESB. You
- cannot send a message to a Gateway from within the ESB.
- Also, note that, since a gateway is not an endpoint, it
- does not have an Endpoint Reference (EPR) persisted in the
- registry.
+ For each gateway listener defined in a service, an ESB-aware
+ (or “native”) listener must also be defined. This is because
+ gateway listeners do not define bidirectional endpoints but,
+ rather, “startpoints” into the ESB. You
+ cannot send a message to a Gateway from within the ESB. Also, note that, since a
+ gateway is not an endpoint, it does not have an Endpoint
+ Reference (EPR) persisted in the registry.
</para>
</note>
<para>
- An example of a <listener> reference to a <bus> can
+ An example of a <code><listener></code> reference to a <code><bus></code> can
be seen in the following illustration (using “base” types only).
</para>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/configuration/image22.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata align="center" fileref="images/configuration/image22.png" />
</imageobject>
</mediaobject>
<para>
A Service will do little without a list of one or more
- <actions>. <action>s typically contain the logic for
+ <code><actions></code>. <code><action></code>s typically contain the logic for
processing the payload of the messages received by the service
(through its listeners). Alternatively, it may contain the
transformation or routing logic for messages to be consumed by
@@ -374,7 +378,7 @@
</para>
<para>
- The <action> element/type defines the following attributes.
+ The <code><action></code> element/type defines the following attributes.
</para>
<table id="SOA_ESB_Programmers_Guide-_Services_-Action_Attributes">
@@ -421,8 +425,7 @@
class
</entry>
<entry>
- The org.jboss.soa.esb.actions.ActionProcessor
- implementation class name.
+ The <classname>org.jboss.soa.esb.actions.ActionProcessor</classname> implementation class name.
</entry>
<entry>
xsd:string
@@ -440,7 +443,7 @@
reflectively called for message
processing.(Default is the “process” method as
defined on the
- ActionProcessor class).
+ <classname>ActionProcessor</classname> class).
</entry>
<entry>
xsd:int
@@ -454,30 +457,30 @@
</table>
<para>
- In a list of <action> instances within an <actions>
+ In a list of <code><action></code> instances within an <code><actions></code>
set, the actions are called (that is, their “process” method is called)
- in the order in which the <action> instances appear in the
- <actions> set. The message returned from each
- <action> is used as the input message to the next
- <action> in the list.
+ in the order in which the <code><action></code> instances appear in the
+ <code><actions></code> set. The message returned from each
+ <code><action></code> is used as the input message to the next
+ <code><action></code> in the list.
</para>
<para>
Like a number of other elements/types in this model, the
- <action> type can also contain zero or more
- <property> element instances. The <property>
+ <code><action></code> type can also contain zero or more
+ <code><property></code> element instances. The <code><property></code>
element/type can define a standard name-value-pair, or contain
free form content (xsd:any). According to the XSD, this free
- form content is valid as child content for the <property>
+ form content is valid as child content for the <code><property></code>
element/type, no matter where it is in the configuration (on any
- of <provider>, <bus>, <listener> and any of
- their derivatives). However, it is only on <action>-
- defined <property> instances that this free-form child
+ of <code><provider></code>, <code><bus></code>, <code><listener></code> and any of
+ their derivatives). However, it is only on <code><action></code>-
+ defined <code><property></code> instances that this free-form child
content is used.
</para>
<para>
- As stated in the <action> definition above, actions are
+ As stated in the <code><action></code> definition above, actions are
implemented through implementing the
<classname>org.jboss.soa.esb.actions.ActionProcessor class</classname>. All
implementations of this interface must contain a public
@@ -496,8 +499,7 @@
</para>
<para>
- So an example of an <actions> configuration might be as
- follows:
+ So an example of an <code><actions></code> configuration might be as follows:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/configuration/Code_Example17.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -511,47 +513,49 @@
<para>
The JBoss ESB configuration model defines transport specific
- specializations of the “base” types <provider>,
- <bus> and <listener> (JMS, SQL etc). This allows us
- to have stronger validation on the configuration, as well as
- making configuration easier for those that use an XSD aware XML
- Editor (e.g. the Eclipse XML Editor). These specializations
- explicitly define the configuration requirements for each of
- the transports supported by JBoss ESB out of the box. It is
- recommended to use these specialized types over the “base”
- types when creating JBoss ESB configurations, the only
- alternative being where a new transport is being supported
+ specializations of the “base” types <code><provider></code>,
+ <code><bus></code> and <code><listener></code> (JMS, SQL and so forth.) This allows you
+ to have stronger validation on the configuration. It also
+ makes configuration easier if you use an XSD-aware XML
+ Editor (such as the Eclipse XML Editor). These specializations
+ explicitly define the configuration requirements for each of the
+ transports supported by JBoss ESB out-of-the-box. It is
+ recommended that you use these specialized types instead of the “base”
+ types when creating JBoss ESB configurations. The only
+ alternative is whereby a new transport is being supported
outside an official JBoss ESB release.
</para>
<para>
The same basic principals that apply when creating
configurations from the “base” types also apply when creating
- configurations from the transport specific alternatives:
+ configurations from the transport-specific alternatives:
</para>
<orderedlist>
- <listitem>
+ <listitem>
+
<para>
- Define the provider configuration e.g. <jms-provider>.
- </para>
+ Define the provider configuration e.g. <code><jms-provider></code>.
+ </para>
+
</listitem>
-
- <listitem>
+ <listitem>
+
<para>
Add the bus configurations to the new provider (for example,
- <jms-bus>), and assign a unique busid attribute
+ <code><jms-bus></code>), and assign a unique busid attribute
value.
</para>
</listitem>
<listitem>
<para>
- Define your <services> as "normal," adding
+ Define your <code><services></code> as "normal," adding
transport-specific listener configurations (such as
- <jms-listener>) that reference (using busidref) the
+ <code><jms-listener></code>) that reference (using busidref) the
new bus configurations you just made. (For example,
- <jms-listener> referencing a <jms-bus>.)
+ <code><jms-listener></code> referencing a <code><jms-bus></code>.)
</para>
</listitem>
</orderedlist>
@@ -560,7 +564,7 @@
The only rule that applies when using these transport-specific
types is that you cannot cross-reference from a listener of one
type, to a bus of another. In other words, you can only reference a
- <jms-bus> from a <jms-listener>. A runtime error
+ <code><jms-bus></code> from a <code><jms-listener></code>. A runtime error
will result where cross-references are made.
</para>
@@ -1125,43 +1129,49 @@
<section>
<title>
- Read-only FTP Listener
+ Read-Only FTP Listener
</title>
<para>
- Setting the ftp-provider property “read-only” to true will
- tell the system that the remote file system does not allow
- write operations. This is often the case when the ftp
- server is running on a mainframe computer where permissions
- are given to a specific file.
+ Setting the ftp-provider property “read-only” to "true" will tell the system that
+ the remote file system does not allow write operations. This is often the case when
+ the FTP server is running on a mainframe computer where permissions are given to a
+ specific file.
</para>
<para>
- The read-only implementation uses JBoss TreeCache to hold a
- list of the filenames that have been retrieved and only
- fetch those that have not previously been retrieved. The
- cache should be configured to use a cacheloader to persist
- the cache to stable storage.
+ The read-only implementation uses JBoss TreeCache to hold a list of the file names that
+ have been retrieved. It is also used to fetch only those that have
+ not previously been retrieved. The cache
+ should be configured to use a cacheloader in order to persist to stable storage.
</para>
-
+ <!-- SOA 1533 -->
<note>
<para>
- There must exist a strategy for removing the filenames
- from the cache. There might be an archiving process on
- the mainframe that moves the files to a different
- location on a regular basis. The removal of filenames
- from the cache could be done by having a database
- procedure that removes all filenames from the cache
- every couple of days. Another strategy would be to
- specify a TreeCacheListener that upon evicting
- filenames from the cache also removes them from the
- cacheloader. The eviction period would then be
- configurable. This can be configured by setting a
- property (removeFilesystemStrategy-cacheListener) in
- the ftp-listener configuration.
+ Depending on how the files used to invoke the gateway
+ are created and have content written to them, it is
+ possible for the listener to access a file before its
+ content is completely written. To avoid this timing
+ issue, a temporary file should first be created and
+ fully populated with the intended content. Once the
+ content in the temporary file is complete, it should be
+ moved to the directory/filename configured for the FTP
+ gateway listener.
+</para>
+</note>
+
+
+ <para>
+ Please note that a strategy must exist for removing the file names from the
+ cache. This might take the form of an archiving process on the mainframe that moves the files to a
+ different location on a regular basis. The removal of file names from the cache could be
+ undertaken by having a database procedure that removes them from the cache every
+ few days. Another strategy would be to specify a TreeCacheListener that, upon
+ evicting file names from the cache, also removes them from the cacheloader. The eviction
+ period would then be configurable. This can be set via a property
+ (removeFilesystemStrategy-cacheListener) in the ftp-listener configuration.
</para>
- </note>
-
+
<table orient="land">
<title>Read-only FTP Listener Configuration </title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
@@ -1393,8 +1403,11 @@
<para>
The JBR Gateway supports a number of configuration properties that
- can be set on either the <jbr-provider>, <jbr-bus> or
- <jbr-listener> elements (as <property> elements).
+ can be set on either the <property><jbr-provider></property>,
+ <property><jbr-bus></property> or
+ <property><jbr-listener></property> elements (as
+ <property><property></property> elements). Here is summary of
+ them:
</para>
<table>
@@ -1441,14 +1454,12 @@
</table>
<para>
- Also note that the JBR Gateway supports setting of JBR specific
- configuration properties. This can be done by prefixing the
- property name with "jbr-". Consult the JBoss Remoting docs
- (<ulink url="http://www.jboss.org/jbossremoting/" />)for the
- JBR specific settings relevant to the configured protocol. The
- following is an example of a configuration that specifies JBR
- specific settings for configuring a Keystore and Client
- authentication mode for HTTPS:
+ Also note that the JBR Gateway supports the setting of JBR-specific
+ configuration properties. This can be done by prefixing the property
+ name with <property>jbr-</property>. Consult the JBoss Remoting docs for the JBR specific
+ settings relevant to the configured protocol. The following is an
+ example of a configuration that specifies JBR specific settings for
+ configuring a Keystore and Client authentication mode for HTTPS:
</para>
@@ -1456,14 +1467,15 @@
<programlisting language="Java" role="JAVA"><xi:include href="extras/configuration/jbrconfig.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The JBR Gateway expects all response headers to be located in
- the Message.Properties as instances of
- org.jboss.soa.esb.message.ResponseHeader class. So if you
- require the JBR Gateway to set specific response headers, the
- ESB Message provided to the Gateway response decompose (e.g.
- after a synchronous invocation of the target service) must
- contains instances of the ResponseHeader class, set on the
- Message.Properties.
+ The JBR Gateway expects all response headers to be located in the
+ <classname>Message.Properties</classname> as instances of
+ <classname>org.jboss.soa.esb.message.ResponseHeader</classname> class.
+ So if one requires the JBR Gateway to set specific response headers, the
+ Enterprise Service Bus Message provided to the Gateway response
+ decompose (for example, after a synchronous invocation of the target
+ service) must contains instances of the
+ <classname>ResponseHeader</classname> class, set on the
+ <classname>Message.Properties</classname>.
</para>
</section>
@@ -1477,26 +1489,28 @@
</title>
<para>
- As it's name suggests, this gateway allows you to expose
- Message-Unaware HTTP endpoints on JBoss ESB.
+ The <firstterm>HTTP</firstterm> Gateway allows one to expose
+ message-unaware HyperText Transfer Protocol end-points on the Enterprise
+ Service Bus.
</para>
<para>
- This gateway uses the JBoss ESB/App Server HTTP Container for
- exposing HTTP endpoints, so many of the configurations are managed
- at the container level e.g. bind/port address, SSL etc.
+ The Gateway uses the JBoss Enterprise Service Bus Application Server
+ HTTP Container to expose HTTP end-points, hence many of the
+ configurations are managed at the container level, these being. the
+ bind/port address, SSL and so forth.
</para>
-<section>
-
+ <section>
<title>
Basic Configuration
</title>
<para>
- The easiest way to configure the <http-gateway> on a Service
- is as follows (no provider configuration required):
+ It is easiest to configure the <http-gateway> on a Service in
+ the following manner. (Note that no provider configuration is
+ required.)
</para>
@@ -1504,9 +1518,11 @@
<para>
- The above configuration uses the “default” HTTP Bus provider since
- it doesn't define a busrefid attribute. It uses the Service name to
- construct the HTTP endpoint address as follows:
+ The above configuration uses the <literal>default</literal> HTTP bus
+ provider. This is because since
+ it does not define a <property>busrefid</property> attribute. It
+ uses the Service name to
+ construct the HTTP end-point address in the following way:
</para>
<para>
@@ -1628,12 +1644,10 @@
</title>
<para>
- The HTTP Request obviously contains a lot of information (aside
- from a data payload) that may be required by the Service i.e. not
- just a request payload (e.g. in the case of POST). This
- information is stored, by the gateway, in a HttpRequest object
- instance on the Message. Actions can access it as follows:
- </para>
+ The HyperText Transfer Protocol Request contains a great deal of
+ information that may be required by the Service (that is,. not just
+ a request payload, as. in the case of <code>POST</code>.)
+ </para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/configuration/parametermap.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -1919,8 +1933,7 @@
</entry>
<entry>
<para>
- Specifies the content/mime type of the payload data
- specified by the classpathResource attribute.
+ Specifies the content/mime type of the payload data specified by the classpathResource attribute.
</para>
</entry>
<entry>Required</entry>
@@ -1928,7 +1941,7 @@
<row>
<entry>
- characterEncoding
+ <property>characterEncoding</property>
</entry>
<entry>
<para>
@@ -1997,7 +2010,7 @@
<row>
<entry>
- responseCode
+ <property>responseCode</property>
</entry>
<entry>
<para>
@@ -2010,7 +2023,7 @@
<row>
<entry>
- contentType
+ <property>contentType</property>
</entry>
<entry>
<para>
@@ -2032,7 +2045,7 @@
<row>
<entry>
- length
+ <property>length</property>
</entry>
<entry>
<para>
@@ -2043,7 +2056,7 @@
<row>
<entry>
- headers
+ <property>headers</property>
</entry>
<entry>
<para>
@@ -2233,7 +2246,7 @@
<row>
<entry>
- No
+ <property>No</property>
</entry>
<entry>
<para>
@@ -2245,7 +2258,7 @@
<row>
<entry>
- No
+ <property>No</property>
</entry>
<entry>
<para>
@@ -2257,7 +2270,7 @@
<row>
<entry>
- Yes
+ <property>Yes</property>
</entry>
<entry>
<para>
@@ -2269,7 +2282,7 @@
<row>
<entry>
- Yes
+ <property>Yes</property>
</entry>
<entry>
<para>
@@ -2497,20 +2510,15 @@
</para>
<para>
- The old configuration model used a free form (non-validatable)
- XML configuration with ESB components receiving thier
- configurations via an instance of
- org.jboss.soa.esb.helpers.ConfigTree. The new configuration
- model is XSD based, however the underlying component
- configuration pattern is still via an instance of
- org.jboss.soa.esb.helpers.ConfigTree. This means that at the
- moment, the XSD based configurations are mapped/transformed
- into ConfigTree style configurations.
+ The old model used free-form XML, with ESB components receiving
+ their configurations via an instance of <classname>org.jboss.soa.esb.helpers.ConfigTree</classname>.
+ The new configuration model is XSD-based. However, the underlying component configuration pattern
+ is still via an instance of org.jboss.soa.esb.helpers.ConfigTree. This means that, at the moment,
+ the XSD-based configurations are mapped/transformed into ConfigTree-style configurations.
</para>
<para>
- Developers that were used to using the old model now need to
- keep the following in mind:
+ Developers who have been accustomed to the old model now need to keep the following in mind:
</para>
<orderedlist>
@@ -2577,15 +2585,15 @@
All components within the core receive their configuration
parameters as XML. How these parameters are provided to the
system is hidden by the
- org.jboss.soa.esb.parameters.ParamRepositoryFactory:
+ <classname>org.jboss.soa.esb.parameters.ParamRepositoryFactory</classname>:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/configuration/prf.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
This returns implementations of the
- org.jboss.soa.esb.parameters.ParamRepository interface which
- allows for different implementations:
+ <classname>org.jboss.soa.esb.parameters.ParamRepository</classname>
+ interface (which allows for different implementations):
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/configuration/pipr.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -2593,19 +2601,20 @@
<para>
Within this version of the JBossESB, there is only a single
- implementation, the
- org.jboss.soa.esb.parameters.ParamFileRepository, which expects
- to be able to load the parameters from a file. The
- implementation to use may be overridden using the
+ implementation, (the
+ <classname>org.jboss.soa.esb.parameters.ParamFileRepository</classname>,)
+ which expects to be able to load the parameters from a file. The
+ implementation to use this may be over-ridden using the
org.jboss.soa.esb.paramsRepository.class property.
</para>
<note>
<para>
- We recommend that you construct your ESB configuration file
- using Eclipse or some other XML editor. The JBossESB
- configuration information is supported by an annotated XSD
- which should help if using a basic editor.
+ It is recommended that you construct your ESB configuration file
+ using <application>Eclipse</application> or some other XML
+ editor. The JBossESB configuration information is supported
+ by an annotated XSD, which should help if you are using a more basic
+ editor.
</para>
</note>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Connectors_and_Adapters.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Connectors_and_Adapters.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Connectors_and_Adapters.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -17,23 +17,23 @@
</title>
<para>
- Not all clients and services of JBossESB will be able to
- understand the protocols and Message formats it uses natively.
- As such there is a need to be able to bridge between ESB-aware
+ Not all of the JBoss Enterprise Service Bus' clients and services will be able to
+ understand the protocols and Message formats that it uses natively.
+ Because of this, there is a need to be able to bridge between ESB-aware
endpoints (those that understand JBossESB) and ESB-unaware
- endpoints (those that do not understand JBossESB). Such
- bridging technologies have existed for many years in a variety
- of distributed systems and are often referred to as Connectors,
+ endpoints (those that do not understand JBossESB.) Such bridging
+ technologies have existed for many years in a variety of
+ distributed systems and are often referred to as Connectors,
Gateways or Adapters.
</para>
<para>
One of the aims of JBossESB is to allow a wide variety of
- clients and services to interact. JBossESB does not require
- that all such clients and services be written using JBossESB or
- any ESB for that matter. There is an abstract notion of an
+ clients and services to interact. JBossESB does not require that
+ all such clients and services be written using JBossESB or any
+ ESB for that matter. There is an abstract notion of an
Interoperability Bus within JBossESB, such that endpoints that
- may not be JBossESB-aware can still be “plugged in to” the bus.
+ may not be JBossESB-aware can still be “plugged into” the bus.
</para>
<note>
@@ -44,12 +44,10 @@
</note>
<para>
- All JBossESB-aware clients and services communicate with one
- another using Messages, (these will be described later.) A
- Message is simply a standardized format for information
- exchange, containing a header, body (payload), attachments and
- other data. Additionally, all JBossESB-aware services are
- identified using Endpoint References (EPRs).
+ All JBossESB-aware clients and services communicate with one another using Messages,
+ (these will be described later.) A Message is simply a standardized format for information exchange,
+ containing a header, body (payload), attachments and other data. Additionally, all JBossESB-aware
+ services are identified using Endpoint References (EPRs).
</para>
<para>
@@ -130,11 +128,11 @@
</itemizedlist>
<para>
- There are a few off the shelf composer classes: the default
+ There are a few off-the-shelf composer classes; the default
'file' composer class will just package the file contents into
- the Message body; same idea for JMS messages. Default message
- composing class for a SQL table row is to package contents of
- all columns specified in configuration, into a java.util.Map.
+ the Message body; with the same process occurring for JMS messages. The default message
+ composing class for an SQL table row is to package contents of
+ all columns specified in the configuration, into a java.util.Map.
</para>
<para>
@@ -152,21 +150,21 @@
<para>
- From JBossESB 4.5 onwards, the FileGateway accepts the
- file-filter-class configuration attribute which allows you to
+ From JBossESB 4.5 onwards, the <literal>FileGateway</literal> accepts the
+ <classname>file-filter-class</classname> configuration attribute which allows you to
define a FileFilter implementation that may be used to select
the files used by the gateway in question. Initialisation of
- user defined FileFilter instances is performed by the gateway
- if the instance is also of type
- org.jboss.soa.esb.listeners.gateway.FileGatewayListener.FileFilterInit,
- in which case the init method will be called and passed the
- gateway ConfigTree instance.
+ user-defined <literal>FileFilter</literal> instances is performed by the gateway if
+ the instance is also of type
+ <classname>org.jboss.soa.esb.listeners.gateway.FileGatewayListener.FileFilterInit</classname>,
+ in which case the <literal>init</literal> method will be called and passed to the
+ gateway <literal>ConfigTree</literal> instance.
</para>
<para>
- By default the following FileFilter implementations are defined
- and used by the FileGateway: if an input suffix is defined in
+ By default, the following <literal>FileFilter</literal> implementations are defined
+ and used by the <literal>FileGateway</literal>: if an input suffix is defined in
the configuration then files matching that suffix will be
returned; alternatively if there is no input suffix then any
file is accepted as long as it does not match the work suffix,
@@ -247,15 +245,17 @@
<listitem>
<para>
- File Gateways: instances of the
- org.jboss.soa.esb.listeners.message.MessageComposer
+ Instances of the
+ <interfacename>org.jboss.soa.esb.listeners.message.MessageComposer</interfacename>
interface are responsible for performing the
conversion. To change the default behavior,
provide an appropriate implementation that
defines your own compose and decompose methods.
- The new MessageComposer implementation should
- be provided in the configuration file using the
- composer-class attribute name.
+ The new
+ <interfacename>MessageComposer</interfacename>
+ implementation should be provided in the
+ configuration file using the composer-class
+ attribute name.
</para>
</listitem>
@@ -305,7 +305,7 @@
inflow integration. To enable a gateway for a service, you must
first implement an endpoint class. This class is a Java class
that must implement the
- org.jboss.soa.esb.listeners.jca.InflowGateway class:
+ <classname>org.jboss.soa.esb.listeners.jca.InflowGateway</classname> class:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/connectors_and_adaptors/inflowgateway.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -328,22 +328,23 @@
</para>
<para>
- At configuration time, the ESB creates a ServiceInvoker and
- invokes the setServiceInvoker method on the endpoint class. The
- ESB then activates the JCA endpoint and the endpoint class
- instance is ready to receive messages. In the JmsEndpoint
- example, the instance receives a JMS message and converts it to
- an ESB message type. Then it uses the ServiceInvoker instance
- to invoke on the target service.
+ At configuration time, the ESB creates a
+ <classname>ServiceInvoker</classname> and invokes the
+ <methodname>setServiceInvoker</methodname> method on the
+ endpoint class. The ESB then activates the JCA endpoint and the
+ endpoint class instance is ready to receive messages. In the
+ JmsEndpoint example, the instance receives a JMS message and
+ converts it to an ESB message type. It then uses the
+ ServiceInvoker instance to invoke on the target service.
</para>
<note>
<para>
The JMS Endpoint class is provided for you with the ESB
distribution under
- org.jboss.soa.esb.listeners.jca.JmsEndpoint It is quite
- possible that this class would be used over and over again
- with any JMS JCA inflow adapters.
+ <classname>org.jboss.soa.esb.listeners.jca.JmsEndpoint</classname>
+ It is quite possible that this class would be used over and
+ over again with any JMS JCA inflow adapters.
</para>
</note>
@@ -351,8 +352,7 @@
<title>Configuration</title>
<para>
- A JCA inflow gateway is configured in a jboss-esb.xml file.
- Here's an example:
+ A JCA inflow gateway is configured in a <filename>jboss-esb.xml</filename> file. Here's an example:
</para>
@@ -364,8 +364,7 @@
<para>
- JCA gateways are defined in <jca-gateway> elements.
- These are the configurable attributes of this XML element.
+ JCA gateways are defined in <jca-gateway> elements. These are the configurable attributes of this XML element.
</para>
<table>
@@ -410,8 +409,9 @@
</entry>
<entry>
The name of the adapter you are using. In
- JBoss it is the filename of the RAR you
- deployed, e.g., jms-ra.rar
+ JBoss it is the file name of the
+ <abbrev>RAR</abbrev> you deployed, e.g.,
+ <filename>jms-ra.rar</filename>
</entry>
</row>
@@ -595,17 +595,17 @@
</para>
<para>
- Specifying the ActivationMapper globally is done through the
- jbossesb-properties.xml file and defines the default mapper used
- for the specified JCA adapter The name of the property to be
- configured is “org.jboss.soa.esb.jca.activation.mapper.<adapter
- name>” and the value is the class name of the ActivationMapper.
+ Specifying the <literal>ActivationMapper</literal> globally is done through the
+ <filename>jbossesb-properties.xml</filename> file. It defines the default mapper used for the
+ specified JCA adapter The name of the property to be configured is
+ <classname>org.jboss.soa.esb.jca.activation.mapper."adapter name"</classname>” and the value is
+ the classname of the ActivationMapper.
</para>
<para>
- The following snippet the configuration of the default
- ActivationMapper used to map the properties on the the activation
- specification for the JBoss JCA adapter, jms-ra.rar.
+ The following snippet the configuration of the default ActivationMapper used
+ to map the properties on the the activation specification for the JBoss JCA
+ adapter, <filename>jms-ra.rar</filename>:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/connectors_and_adaptors/activationmanager.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -619,8 +619,8 @@
</para>
<para>
- The following snippet shows an example specifying the mapper
- configuration within the listener configuration.
+ The following snippet shows an example specifying the mapper configuration
+ within the listener configuration:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/connectors_and_adaptors/mappingconfig.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Developing_Custom_Actions.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -11,26 +11,29 @@
</title>
<para>
- To implement a custom Action Processor, simply implement the
- org.jboss.soa.esb.actions.ActionPipelineProcessor interface.
+ In order to implement a custom Action Processor, simply use the
+ <interfacename>org.jboss.soa.esb.actions.ActionPipelineProcessor</interfacename>
+ interface.
</para>
<para>
- This interface supports implementation of stateless actions that
- have a managed lifecycle. A single instance of a class implementing
- this interface is instantiated on a per pipeline basis (i.e. per
- action configuration). This means you can cache resources needed by
- the action in the initialise method, and clean them up in the
- destroy method.
+ This interface supports the implementation of <firstterm>managed
+ life-cycle</firstterm> stateless actions. A single instance of a
+ class that implements this interface is instantiated on a
+ "per-pipeline" basis (in other words, per-action configuration.)
+ This means that one can cache the resources needed by the action in
+ the <methodname>initialise</methodname> method, and then clean them
+ up by using the <methodname>destroy</methodname> method.
</para>
<para>
- As a convenience, you should simple extend the
- org.jboss.soa.esb.actions.AbstractActionPipelineProcessor.
+ The implementing class should process the message from within the
+ the <methodname>process</methodname> method.
</para>
<para>
- Example:
+ It should be convenient to simply extend the
+ <classname>org.jboss.soa.esb.actions.AbstractActionPipelineProcessor</classname>:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/abstractaction.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -42,36 +45,42 @@
</title>
<para>
- Actions generally act as templates that require external
- configuration to perform their tasks. For example, a
- PrintMessage action might take a property named 'message' to
- indicate what to print and a property 'repeatCount' to indicate
- the number of times to print it. The action configuration in
- the jboss-esb.xml file might look like this:
+ Actions generally act as templates. They require external
+ configuration in order to perform their tasks. For example, a
+ <classname>PrintMessage</classname> action might use a property
+ named <property>message</property> to indicate what to print and
+ another property called <property>repeatCount</property> to
+ indicate the number of times to print it. If so, the action
+ configuration in the <filename>jboss-esb.xml</filename> file
+ would look something like this:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/developing_custom_actions/hworld.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The default method for loading property values in an action
- implementation is the use of a ConfigTree instance. The
- ConfigTree provides a DOM-like view of the action XML. By
- default, actions are expected to have a public constructor
- that takes a ConfigTree as a parameter. For example:
+ A <classname>ConfigTree</classname> instance is the default
+ method to use in order to load property values into an
+ action implementation. The <classname>ConfigTree</classname>
+ provides a <abbrev>DOM</abbrev>-like view of the action
+ <abbrev>XML</abbrev> code. By default, actions are expected
+ to have a public constructor that takes a
+ <classname>ConfigTree</classname> as a parameter. For
+ example:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/developing_custom_actions/configtree.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Another approach to setting action properties is to add setters
- on the action that correspond to the property names and allow
- the framework to populate them automatically. In order to have
- the action bean auto-populated, the action class must implement
- the org.jboss.soa.esb.actions.BeanConfiguredAction marker
- interface. For example, the following class has the same
- behavior as the one above.
+ One may take another approach to setting properties by adding
+ "setters" on the action that will correspond to the property
+ names. This will thereby allow the framework to populate them
+ automatically. The action class must implement the
+ <classname>org.jboss.soa.esb.actions.BeanConfiguredAction</classname>
+ marker interface in order to make the action Bean populate
+ automatically. The following class has the same behavior as that
+ shown above, in order to demonstrate this:
</para>
@@ -79,17 +88,19 @@
<note>
<para>
- The Integer parameter in setRepeatCount() is automatically
- converted from the String representation specified in the
- XML.
+ The <type>Integer</type> parameter in the
+ <methodname>setRepeatCount()</methodname> method is
+ automatically converted from the <type>String</type>
+ representation specified in the <abbrev>XML</abbrev>.
</para>
</note>
<para>
- The BeanConfiguredAction method of loading properties is a good
- choice for actions that take simple arguments, while the
- ConfigTree method is better when you need to deal with the XML
- representation directly.
+ The <methodname>BeanConfiguredAction</methodname> method of
+ loading properties is a good choice for actions that take simple
+ arguments, while the <methodname>ConfigTree</methodname> method
+ is a better option in situations when one needs to deal with the
+ <abbrev>XML</abbrev> representation directly.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Example.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Example.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Example.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -8,41 +8,36 @@
<chapter id="chap-SOA_ESB_Programmers_Guide-Example">
<title>
- Example
+
+ An Example
</title>
<section>
<title>
- How to use the Message
+ How to Use the Message
</title>
<para>
- The Message is a critical component in the SOA development
- approach. In contains application specific data sent from
- clients to services and vice versa. In some cases that data may
- be as simple as “turn on the light”, or as complex as “search
- this start chart for any anomalous data that may indicate a
- planet.” What goes into a Message is entirely application
- specific and represents an important aspect of the contract
- between a service and its clients. In this section we shall
- describe some best practices around the Message and how to use
- it.
+ Conceptually, the message is a critical aspect of the SOA
+ development approach. Messages contain the application-specific
+ data sent between clients and services. The data in a message
+ represents an important aspect of the "contract" between a
+ service and its clients. In this section, one shall learn best
+ practices to use in regard to this component.
</para>
<para>
- Let's consider the following example which uses a Flight
- Reservation service. This service supports the following
- operations:
+ Firstly, consider the following flight reservation service
+ example. This service supports the following operations:
</para>
<variablelist>
<varlistentry>
- <term>reserveSeat</term>
-
+ <term> reserveSeat </term>
<listitem>
<para>
- this takes a flight number and seat number and
- returns success or failure indication.
+ This takes a flight and seat number and
+ returns a success or failure indication.
</para>
</listitem>
</varlistentry>
@@ -52,113 +47,123 @@
<listitem>
<para>
- this takes a flight number and a seat number and
- returns an indication of whether or not the seat is
+ This takes a flight and seat number and
+ returns an indication of whether or not the seat is
currently reserved.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>upgradeSeat</term>
-
+ <term> upgradeSeat </term>
<listitem>
<para>
- this takes a flight number and two seat numbers
- (the currently reserved seat and the one to move
- to).
+ This takes a flight number and two seat numbers
+ (the currently reserved seat and the one to which
+ the passenger will move.)
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
- When developing this service, it will likely use technologies
- such as EJB3, Hibernate etc. to implement the business logic.
- In this example we shall ignore how the business logic is
- implemented and concentrate on the service.
+ When developing a service, one will nearly always use
+ technologies such as <firstterm>Enterprise Java
+ Beans</firstterm> (EJB3) and <firstterm>Hibernate</firstterm>
+ in order to implement the business logic. This example does not
+ teach the reader how to implement this logic. Instead, the
+ service itself is the focal point of the study.
</para>
<para>
- The role of the service is to plug the logic into the bus. In
- order to do this, we must determine how the service is exposed
- on to the bus, i.e., what contract it defines for clients. In
- the current version of JBossESB, that contract takes the form
- of the Messages that clients and services can exchange. There
- is no formal specification for this contract within the ESB,
- i.e., at present it is something that the developer defines and
- must communicate to clients out-of-band from the ESB. This will
- be rectified in subsequent releases.
+ The service's role is to "plug" the logic into the Bus. In
+ order to configure it to do this, firstly determine how the
+ service is exposed to the Bus, (that is, the type of contract
+ it defines for the clients.) In the current version of the <application>JBoss
+ Enterprise Service Bus</application>, this contract takes the form of the
+ various messages that the clients and services exchange.
+ </para>
+
+<note>
+ <para>
+ Currently, there is no formal specification for this contract
+ within the ESB. In other words, it is something that the
+ developer defines and communicates to clients irrespective of
+ the Enterprise Service Bus. This will be rectified in a
+ subsequent release.
</para>
-
+</note>
<section>
<title>
The Message Structure
</title>
<para>
- From a service perspective, of all the components within a
- Message, the Body is probably the most important, since it
- is used to convey information specific to the business
+ From the perspective of a service, of all a message's
+ components, the nody is the most important. This is because
+ it is used to convey information specific to the business
logic. In order to interact, both client and service must
- understand each other. This takes the form of agreeing on
- the transport (e.g., JMS or HTTP), as well as agreeing on
- the dialect (e.g., where in the Message data will appear
- and what format it will take).
+ understand each other. This understanding takes the form of
+ an agreement on the mode of transport (such as Java Message
+ Service or HTTP) and the dialect to be used (the format in
+ which the data is to appear in the message.)
</para>
<para>
- If we take the simple case of a client sending a Message
- directly to our Flight Reservation service, then we need to
- determine how the service can determine which of the
- operations the Message concerns. In this case the developer
- decides that the opcode (operation code) will appear within
- the Body as a String (“reserve”, “query”, “upgrade”) at the
- location “org.example.flight.opcode”. Any other String
- value (or the absence of any value) will be considered an
- illegal Message.
+ If one were to take the simple case of a client sending a
+ message directly to the example flight reservation service,
+ then one would need to decide how the service is going to
+ determine which of the operations is concerned with the
+ message. In this case, the developer decides that the
+ <code>opcode</code> (operation code) will appear within the
+ body as a string (<code>reserve</code>, <code>query</code>,
+ <code>upgrade</code>) at the location called
+ <classname>org.example.flight.opcode</classname>. Any other
+ string value (or, indeed, the complete absence of a value)
+ will result in the message being considered illegal.
</para>
- <note>
+ <important>
<para>
- It is important that all values within a Message are
- given unique names, to avoid clashes with other
- clients or services.
+ Ensure that every value within a message is given a
+ unique name. Do so to avoid clashes with other clients
+ and services.
</para>
- </note>
+ </important>
+
<para>
- The Message Body is the primary way in which data should be
+ The message body is the primary means by which data is
exchanged between clients and services. It is flexible
- enough to contain any number of arbitrary data type. The
- other parameters necessary for carrying out the business
- logic associated with each operation would also be suitably
- encoded.
+ enough to contain any number of arbitrary data types. (The
+ other parameters required to execute the business
+ logic associated with each operation should be suitably
+ encoded.)
</para>
<itemizedlist>
<listitem>
<para>
- “org.example.flight.seatnumber” for the seat
- number, which will be an integer.
+ Use <classname>org.example.flight.seatnumber</classname>
+ for the seat number, which will be an integer.
</para>
</listitem>
<listitem>
<para>
- “org.example.flight.flightnumber” for the flight
- number, which will be a String.
+ Use <classname>org.example.flight.flightnumber</classname>
+ for the flight number, which will be a string.
</para>
</listitem>
<listitem>
<para>
- “org.example.flight.upgradenumber” for the upgraded
- seat number, which will be an integer.
+ Use <classname>org.example.flight.upgradenumber</classname>
+ for the upgraded seat number, which will be an integer.
</para>
</listitem>
</itemizedlist>
- <table id="SOA_ESB_Programmers_Guide-_The_Message_Structure_-Operation_Parameters">
+ <table>
<title>Operation Parameters</title>
<tgroup align="center" cols="5" colsep="1" rowsep="1">
<thead>
@@ -182,14 +187,14 @@
<entry>querySeat</entry>
<entry>String: query</entry>
<entry>integer</entry>
- <entry>String</entry>
+ <entry>string</entry>
<entry>N/A</entry>
</row>
<row>
<entry>upgradeSeat</entry>
<entry>String: upgrade</entry>
<entry>integer</entry>
- <entry>String</entry>
+ <entry>string</entry>
<entry>integer</entry>
</row>
</tbody>
@@ -197,28 +202,26 @@
</table>
<para>
- As we have mentioned, all of these operations return
- information to the client. Such information will likewise
- be encapsulated within a Message. The determination of the
- format of such response Messages will go through the same
- processes as we are currently describing. For
- simplification purposes we shall not consider the response
- Messages further.
+ All of these operations return information to the client.
+ They do so by encapsulating it within a message. Response
+ messages go through the same processes as that currently
+ being described in order for their own formats to be
+ determined. For the purpose of simplification, the response
+ messages will not be considered further in this example.
</para>
<para>
- From a JBossESB Action perspective, the service may be
- built using one or more Actions. For example, one Action may
- pre-process the incoming Message and transform the content
- in some way, before passing it on to the Action which is
- responsible for the main business logic. Each of these
- Actions may have been written in isolation (possibly by
- different groups within the same organization or by
- completely different organizations). In such an architecture
- it is important that each Action has its own unique view of
- where the Message data resides that is of interest only to
- that Action or it is entirely possible for chained Actions
- to overwrite or interfere with one another.
+ Build the service using one or more actions. These
+ pre-process the incoming message and transform its contents
+ in some way, before passing it on to the action which is
+ responsible for the main business logic. Each of these
+ actions can be written in isolation (possibly by different
+ groups within the same organisation or even by completely
+ different organisations.) Always make sure that each action
+ has a unique view of the message data upon which it acts.
+ If this is not the case, it is possible that chained
+ actions may either overwrite or otherwise interfere with
+ each other.
</para>
</section>
@@ -230,9 +233,10 @@
</title>
<para>
- At this point we have enough information to construct the
- service. For simplicity, we shall assume that the business
- logic is encapsulated within the following pseudo-object:
+ At this point, one has learned enough to be able to
+ construct the service. For the sake of simplicity, it shall
+ be assumed that the business logic is encapsulated within
+ the following "pseudo-object:"
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/example/airlinereservation.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -240,17 +244,16 @@
<note>
<para>
- You could develop your business logic from POJOs, EJBs,
- Spring etc. JBossESB provides support for many of these
- approaches out of the box. You should examine the
- relevant documentation and examples.
+ Develop business logic using Plain Old Java Objects,
+ Enterprise Java Beans or Spring. The <application>JBoss
+ Enterprise Service Bus</application> provides
+ out-of-the-box support for many of these approaches.
+ (Examine the relevant documentation for each.)
</para>
</note>
<para>
- The process method of the service Action (we'll assume no
- chaining of Actions) then becomes (ignoring error
- checking):
+ The service action's processing becomes this:
</para>
@@ -259,24 +262,26 @@
<note>
<para>
- As with WS-Addressing, rather than embed the opcode
- within the Message Body, you could use the Action field
- of the Message Header. This has the drawback that it
- does not work if multiple JBossESB Actions are chained
- together and each needs a different opcode.
+ As with WS-Addressing, one could use the message
+ header's <property>action</property> field, rather than
+ embed the <property>opcode</property> within the
+ message body. This has a drawback in that it does not
+ work if multiple actions are chained together and if
+ each of thesee needs a different
+ <property>opcode</property>.
</para>
</note>
</section>
<section>
<title>
- Unpicking the payload
+ Decoding the Payload
</title>
<para>
- As you can see, the process method is only the start. Now
- we must provide methods to decode the incoming Message
- payload (the Body):
+ Choosing the process method is only the start of the
+ process. Now provide a method to decode the incoming
+ message's payload. Do so like this:
</para>
@@ -284,23 +289,23 @@
<para>
- What this method illustrates is how the information within
- the Body is extracted and then used to invoke a method on
- some business logic. In the case of reserveSeat, a response
- is expected by the client. This response Message is
- constructed using any information returned by the business
- logic as well as delivery information obtained from the
- original received Message. In this example, we need the To
- address for the response, which we take from the ReplyTo
- field of the incoming Message. We also need to relate the
- response with the original request and we accomplish this
- through the RelatesTo field of the response and the
- MessageID of the request.
+ This method illustrates how the information held within the
+ body is extracted. After having done so, it then invokes
+ another method for business logic. In the case of the
+ <code>reserveSeat</code>, the client expects a response.
+ Construct this response using any information returned by
+ the business logic as well as additional delivery
+ information obtained from the original message. In this
+ example, one needs the <property>To</property> address for
+ the response, which is taken from the incoming message's
+ <property>ReplyTo</property> field. One also needs to
+ relate the response to the original request. Accomplish
+ this via both the response's <property>RelatesTo</property>
+ field and the request's <property>MessageID</property>.
</para>
<para>
- All of the other operations supported by the service will
- be similarly coded.
+ Code every operation supported by the service similarly.
</para>
</section>
@@ -312,28 +317,30 @@
</title>
<para>
- As soon as we have the Message definitions supported by the
- service, we can construct the client code. The business
- logic used to support the service is never exposed directly
- by the service (that would break one of the important
- principles of SOA: encapsulation). This is essentially the
- inverse of the service code:
+ As soon as the message definitions are supported by the
+ service, begin to construct the client code. The business
+ logic used to support the service is never directly exposed
+ by the latter (as that would break one of the important
+ principles of SOA methodology:
+ <firstterm>encapsulation</firstterm>.) The client code is
+ essentially the inverse of that for the service:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/example/flightservicenewserviceinvoker.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
- Much of what we have outlined above may seem similar to
- those who have worked with traditional client/server
- stub generators. In those systems, the low-level
- details, such as opcodes and parameters, would be
- hidden behind higher level stub abstractions. In future
- releases of JBossESB we intend to support such
- abstractions to easy the development approach. As such,
- working with the raw Message components, such as Body
- and Header, will be hidden from the majority of
- developers.
+ Much of what has been outlined above will seem familiar
+ to those readers who have worked with traditional
+ client/server <firstterm>stub generators</firstterm>.
+ In those systems, the low-level details (such as the
+ <property>opcodes</property> and the parameters), are
+ hidden behind higher-level stub abstractions. In future
+ releases, such abstractions will be supported as this
+ will simplify the development approach. When this is
+ implemented, the ability to work with the raw
+ message components, such as the body and header, will
+ be hidden from the majority of developers.
</para>
</note>
@@ -342,15 +349,17 @@
<section>
<title>
- Configuration for a remote ServiceInvoker
+ Configuration for a Remote Service Invoker
</title>
<para>
- Using the ServiceInvoker from within actions in the ESB does
- not require any additional configuration and will work out of
- the box. But using the ServiceInvoker from a remote JVM, such
- as from a stand-alone Java application, a servlet, an EJB etc,
- will require the following jars need to be available:
+ One will find that using the
+ <classname>ServiceInvoker</classname> from within the ESB's
+ actions works "out-of-the-box": no additional configuration is
+ required. However, to use it from a remote Java Virtual Machine,
+ (which is the case for a stand-alone Java application, servlet
+ or Enterprise Java Bean), firstly ensure that these
+ <filename>JAR</filename> files are available:
</para>
<simplelist type="vert" columns="2">
@@ -381,8 +390,8 @@
<para>
- The following configuration file is also required to be
- available on the classpath:
+ Next, check that the following configuration files are on the
+ classpath:
</para>
<itemizedlist>
@@ -396,7 +405,8 @@
<para>
<filename>META-INF/uddi.xml</filename>
</para>
- </listitem>
+ </listitem>
+
</itemizedlist>
</section>
@@ -408,10 +418,11 @@
</title>
<para>
- The following Java program can be used to verify that the
- configuration of a remote client. This assumes that the
- helloworld quickstart has been deployed and that the ESB
- server is running.
+ Use the following Java program to verify that a remote
+ client's configuration is working correctly. (Firstly, make
+ sure that the <filename>helloworld</filename> quick-start
+ has been deployed and that the Enterprise Service Bus
+ server is running.)
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/example/verifyconfig.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -423,71 +434,77 @@
<title>
Hints and Tips
</title>
-
+
+
<para>
- You may find the following useful when developing your
- clients and services.
+ These hints may be of use when building clients and
+ services:
</para>
<itemizedlist>
<listitem>
<para>
- When developing your Actions make sure that any
- payload information specific to an Action is
- maintained in unique locations within the Message
- Body.
+ when developing an action, ensure that any payload
+ information specific to it is maintained in
+ unique message body locations.
</para>
</listitem>
<listitem>
<para>
- Try not to expose any back-end service
- implementation details within your Message. This
- will make it difficult to change the implementation
- without affecting clients. Message definitions
- (contents, formats etc.) which are implementation
- agnostic help to maintain loose coupling.
+ try not to expose any back-end service
+ implementation details within the message, because
+ this will make it difficult to change the
+ implementation without affecting clients. Use
+ message definitions (contents, formats and so on)
+ which are "implementation-agnostic" as this will help to
+ keep the coupling loose.
</para>
</listitem>
<listitem>
<para>
- For stateless services, use the ServiceInvoker as
- it will opaquely handle fail-over.
+ for stateless services, use the
+ <interfacename>ServiceInvoker</interfacename> as it
+ handles fail-over "opaquely."
</para>
</listitem>
<listitem>
<para>
- When building request/response applications, use
- the correlation information (MessageID and
- RelatesTo) within the Message Header.
+ when building request/response applications, use
+ the correlation information (that is,
+ <property>MessageID</property> and
+ <property>RelatesTo</property>) that is found
+ within the message header.
</para>
</listitem>
<listitem>
<para>
- Consider using the Header Action field for your
- main service opcode.
+ consider using the <property>Header
+ Action</property> field for the main service
+ <property>opcode</property>.
</para>
</listitem>
<listitem>
<para>
- If using asynchronous interactions in which there
- is no delivery address for responses, consider
- sending any errors to the MessageStore so that they
- can be monitored later.
- </para>
+ if one is using asynchronous interactions for which
+ there are no response delivery addresses, consider
+ sending any errors to the <systemitem>message
+ store</systemitem>. This is so that these errors
+ can be analysed later. </para>
</listitem>
<listitem>
<para>
- Until JBossESB provides more automatic support for
- service contract definitions and dissemination,
+ until the <application>JBoss Enterprise Service
+ Bus</application> provides better automatic support
+ for service contract definition and publication,
consider maintaining a separate repository of these
- definitions that is available to developers and
- users.
+ definitions, and make it available to both
+ developers and users.
</para>
</listitem>
</itemizedlist>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Fault-tolerance_and_Reliability.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Fault-tolerance_and_Reliability.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Fault-tolerance_and_Reliability.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -7,37 +7,38 @@
<chapter id="chap-SOA_ESB_Programmers_Guide-Fault-tolerance_and_Reliability">
<title>
- Fault-tolerance and Reliability
+ Fault-Tolerance and Reliability
</title>
<para>
- In this Chapter we shall look at the reliability characteristics of
- JBossESB. We shall examine what failure modes you should expect to
- be tolerated with this release and give advice on how to improve
- the fault tolerance of your applications. However, in order to
- proceed we need to define some important terms. If you wish to skip
- the following sections because you understand this topic already,
- you may go straight to the Reliability Guarantees section.
+ This chapter provides a study of the JBoss Enterprise Service Bus'
+ reliability characteristics. The reader will learn about which
+ failure modes he or she can expect to find "tolerated" within this
+ release. This chapter will also provide advice on how one can
+ improve the fault tolerance of one's applications. However, in order
+ to proceed, some important terms must first be defined.
</para>
<para>
- Dependability is defined as the trustworthiness of a component such
- that reliance can be justifiably placed on the service (the
- behavior as perceived by a user) it delivers. The reliability of a
- component is a measure of its continuous correct service delivery.
- A failure occurs when the service provided by the system no longer
- complies with its specification. An error is that part of a system
- state which is liable to lead to failure, and a fault is defined as
- the cause of an error.
+ <firstterm>Dependability</firstterm> is defined as "the
+ trustworthiness of a component such that reliance can be justifiably
+ placed on the service (the behavior as perceived by a user) it
+ delivers." The reliability of a component is a measure of its
+ continuous correct service delivery. A failure occurs when the
+ service provided by the system no longer complies with its
+ specification. An error is ""that part of a system state which is
+ liable to lead to failure" and a fault is defined as "the cause of
+ an error."
</para>
<para>
- A fault-tolerant system is one which is designed to fulfill its
- specified purpose despite the occurrence of component failures.
- Techniques for providing fault-tolerance usually require mechanisms
- for consistent state recovery mechanisms, and detecting errors
- produced by faulty components. A number of fault-tolerance
- techniques exist, including replication and transactions.
+ A <firstterm>fault-tolerant</firstterm> system is one "which is
+ designed to fulfill its specified purpose despite the occurrence of
+ component failures." Techniques for providing fault-tolerance
+ usually require mechanisms for consistent state recovery mechanisms,
+ and detecting errors produced by faulty components. A number of
+ fault-tolerance techniques exist, including replication and
+ transactions.
</para>
<section>
@@ -46,46 +47,44 @@
</title>
<para>
- Given a (distributed) system, it would be useful if we were
- able to describe its behavior formally in a way that will help
- establish the correctness of the applications run on it. If
- this then imposes restrictions on the permissible behavior of
- the applications we will need to understand how these
- restrictions can be enforced and the implications in weakening
- or strengthening them. A useful method of building such a
- formal description with respect to fault-tolerance is to
- categorize the system components according to the types of
- faults they are assumed to exhibit.
+ It is necessary to formally describe the behavior of a system before
+ the correctness of applications running on it can be demonstrated. This
+ process establishes behavioral restrictions for applications. It also clarifies
+ the implications of weakening or strengthening these restrictions.
</para>
<para>
- Four possible classifications of failures are: omission, value,
- timing, and arbitrary. Associated with each component in the
- system will be a specification of its correct behavior for a
- given set of inputs. A non-faulty component will produce an
- output that is in accordance with this specification. The
- response from a faulty component need not be as specified,
- i.e., it can be anything. The response from a given component
- for a given input will be considered to be correct if not only
- the output value is correct but also that the output is
- produced on time, i.e., produced within a specified time limit.
+ Categorizing system components according to the types of faults they are
+ assumed to exhibit is a recommended method of building such a formal description
+ with respect to fault-tolerance.
</para>
<para>
- The classifications are:
+ Each component in the system has a specification of its correct behavior for
+ a given set of inputs. A correctly working component will produce
+ an output that is in accordance with this specification. The response from a faulty
+ component need not be as specific. The response from a component for a
+ given input will be considered correct if the output value is both correct
+ and produced within a specified time limit.
</para>
+ <para>
+ Four possible classifications of failures are: Omission, value,
+ timing, and arbitrary.
+ </para>
+
<variablelist>
<varlistentry>
<term> Omission fault/failure </term>
<listitem>
<para>
- a component that does not respond to an input from
- another component, and thereby fails by not
- producing the expected output is exhibiting an
- omission fault and the corresponding failure an
- omission failure. A communication link which
- occasionally loses messages is an example of a
+ A component that does not respond to an input from
+ another component and, thereby, fails by not
+ producing the expected output is exhibiting
+ an <emphasis>omission fault</emphasis>. The
+ corresponding failure is an <emphasis>omission
+ failure</emphasis>. A communication link which
+ occasionally loses messages is an example of a
component suffering from an omission fault.
</para>
</listitem>
@@ -96,12 +95,13 @@
<listitem>
<para>
- a fault that causes a component to respond within
- the correct time interval but with an incorrect
- value is termed a value fault (with the
- corresponding failure called a value failure). A
- communication link which delivers corrupted
- messages on time suffers from a value fault.
+ A fault that causes a component to respond within
+ the correct time interval but with an incorrect
+ value is termed a <emphasis>value fault</emphasis> (with the
+ corresponding failure called a <emphasis>value
+ failure</emphasis>). A communication link which
+ delivers corrupted messages on time suffers from a
+ value fault.
</para>
</listitem>
@@ -110,14 +110,15 @@
<term> Timing fault/failure </term>
<listitem>
<para>
- a timing fault causes the component to respond with
- the correct value but outside the specified
- interval (either too soon, or too late). The
- corresponding failure is a timing failure. An
- overloaded processor which produces correct values
- but with an excessive delay suffers from a timing
- failure. Timing failures can only occur in systems
- which impose timing constraints on computations.
+ A timing fault causes the component to respond
+ with the correct value but outside the specified
+ interval (either too soon or too late). The
+ corresponding failure is a <emphasis>timing
+ failure</emphasis>. An overloaded processor which
+ produces correct values but with an excessive delay
+ suffers from a timing failure. Timing failures can
+ only occur in systems which impose timing
+ constraints on computations.
</para>
</listitem>
</varlistentry>
@@ -126,30 +127,30 @@
<term> Arbitrary fault/failure </term>
<listitem>
<para>
- the previous failure classes have specified how a
- component can be considered to fail in either the
- value or time domain. It is possible for a
- component to fail in both the domains in a manner
- which is not covered by one of the previous
- classes. A failed component which produces such an
- output will be said to be exhibiting an arbitrary
- failure (Byzantine failure).
+ The previous failure classes have specified how a
+ component can be considered to fail in either the
+ value or time domains. It is possible for a component
+ to fail in both of these domains in a manner which is
+ not covered by one of the previous classes. A
+ failed component which produces such an output will
+ be said to be exhibiting an <emphasis>arbitrary
+ failure</emphasis> (<emphasis>Byzantine
+ failure</emphasis>).
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
- An arbitrary fault causes any violation of a component’s
- specified behavior. All other fault types preclude certain
- types of fault behavior, the omission fault type being the most
- restrictive. Thus the omission and arbitrary faults represent
- two ends of a fault classification spectrum, with the other
- fault types placed in between. The latter failure
- classifications thus subsume the characteristics of those
- classes before them, e.g., omission faults (failures) can be
- treated as a special case of value, and timing faults
- (failures). Such ordering can be represented as a hierarchy:
+ An arbitrary fault causes any violation of a component’s specified
+ behavior. All other fault types preclude certain types of fault
+ behavior, the omission fault type being the most restrictive. Thus
+ the omission and arbitrary faults represent two ends of a fault
+ classification spectrum, with the other fault types placed in between.
+ The latter failure classifications thus subsume the characteristics of
+ those classes before them, e.g., omission faults (failures) can be
+ treated as a special case of value, and timing faults (failures). Such
+ ordering can be represented as a hierarchy:
</para>
<figure><title>Fault classification hierarchy</title>
@@ -167,99 +168,89 @@
</title>
<para>
- Within JBossESB there is nothing that will allow it to
- tolerate Byzantine/arbitrary failures. As you can probably
- imagine, these are extremely difficult failures to detect
- due to their nature. Protocols do exist to allow systems to
- tolerate arbitrary failures, but they often require
- multi-phase coordination or digital signatures. Future
- releases of JBossESB may incorporate support for some of
- these approaches.
+ Within JBossESB there is nothing that will allow it to tolerate
+ arbitrary failures. As you can probably imagine, these are extremely
+ difficult failures to detect due to their nature. Protocols do exist
+ to allow systems to tolerate arbitrary failures, but they often require
+ multi-phase coordination or digital signatures. Future releases of
+ JBossESB may incorporate support for some of these approaches.
</para>
<para>
- Because value, timing and omission failures often require
- semantic information concerning the application (or
- specific operations), there is only so much that JBossESB
- can do directly to assist with these types of faults.
- However, by correct use of JBossESB capabilities such as
- RelatesTo and MessageID within the Message header, it is
- possible for applications to determine whether or not a
- received Message is the one they are waiting for or a
- delayed Message, for example. Unfortunately Messages that
- are provided too soon by a service, e.g., asynchronous
- one-way responses to one-way requests, may be lost due to
- the underlying transport implementation. For instance, if
- using a protocol such as HTTP there is a finite buffer (set
- at the operating system level) within which responses can
- be held before they are passed to the application. If this
- buffer is exceeded then information within it may be lost
- in favor of new Messages. Transports such as FTP or SQL do
- not necessarily suffer from this specific limitation, but
- may exhibit other resource restrictions that can result in
- the same behavior.
+ Because value, timing and omission failures often require semantic
+ information concerning the application (or specific operations), there is
+ only so much that JBossESB can do directly to assist with these types of
+ faults. However, by correct use of JBossESB capabilities (such as RelatesTo
+ and MessageID within the Message header), it is possible for applications
+ to determine, for example, whether or not a received Message
+ is either the one for which they are waiting
+ or a delayed Message. Unfortunately, Messages that are
+ provided too soon by a service, (such as asynchronous one-way responses to
+ one-way requests), may be lost due to the underlying transport implementation.
+ For instance, if you are using a protocol such as HTTP there is a finite buffer (set
+ at the operating system level) within which responses can be held before they
+ are passed on to the application. If this buffer is exceeded, then information
+ within it may be lost in favor of new Messages. Transports such as FTP or SQL
+ do not necessarily suffer from this specific limitation but may exhibit other
+ resource restrictions that can result in the same behavior.
</para>
<para>
- Tolerating Messages that are delayed is sometimes easier
- than tolerating those that arrive too early. However, from
- an application perspective, if an early Message is lost
- (e.g., by buffer overflow) it is not possible to
- distinguish it from one that is infinitely delayed.
- Therefore, if you construct your applications (consumers
- and services) to use a retry mechanism in the case of lost
- Messages, timing and omission failures should be tolerated,
- with the following exception: your consumer picks up an
- early response out of order and incorrectly processes it
- (which then becomes a value failure). Fortunately if you
- use RelatesTo and MessageID within the Message header, you
- can spot incorrect Message sequences without having to
- process the entire payload (which is obviously another
- option available to you).
+ Tolerating Messages that are delayed is sometimes easier than
+ tolerating those that arrive too early. However, from an application
+ perspective, if an early Message is lost (by a buffer overflow for example),
+ it is not possible to distinguish it from one that is infinitely
+ delayed. Therefore, if you construct your applications (both consumers and
+ services) to use a retry mechanism in the case of lost Messages,
+ timing and omission failures should then be tolerated. However, there is following
+ exception: When your consumer picks up an early response out of order and
+ incorrectly processes it, resulting in a value failure.
+ Fortunately, if you use RelatesTo and MessageID within the Message
+ header, you can spot incorrect Message sequences without having to
+ process the entire payload (which is obviously another option available
+ to you).
</para>
<para>
- Within a synchronous request-response interaction pattern,
- many systems built upon RPC will automatically resend the
- request if a response has not been received within a finite
- period of time. Unfortunately at present JBossESB does not
- do this and you will have to used the timeout mechanism
- within Couriers or ServiceInvoker to determine when (and
- whether) to send the Message again. As we saw in the
- Advanced Chapter, it will retransmit the Message if it
- suspects a failure of the service has occurred that would
- affect Message delivery.
+
+ If a response has not been received within a finite
+ period of time within a synchronous request-response
+ interaction pattern, many systems built upon RPC will automatically resend the
+ request. Unfortunately, at present, JBossESB does
+ not do this and you will have to used the timeout mechanism
+ within Couriers or ServiceInvoker to determine when (and
+ whether) to send the Message again. As described in the
+ Advanced Chapter, it will retransmit the Message if it
+ suspects a failure of the service that would
+ affect Message delivery has occurred.
</para>
<note>
<para>
- You should use caution when retransmitting Messages to
- services. JBossESB currently has no notion of retained
- results or detecting retransmissions within the
- service, so any duplicate Messages will be delivered to
- the service automatically. This may mean that your
- service receives the same Message multiple times (e.g.,
- it was the initial service response that got lost
- rather than the initial request). As such, your service
- may attempt to perform the same work. If using
- retransmission (either explicitly or through the
- ServiceInvoker fail-over mechanisms), you will have to
- deal with multiple requests within your service to
- ensure it is idempotent.
+ You should use care when retransmitting Messages to services.
+ JBossESB currently has no notion of retained results and cannot detect
+ retransmissions within the service. <!-- so any duplicate Messages will be
+ delivered to automatically.--> This may mean that your service
+ receives the same Message multiple times (if, for example, it was the initial
+ service response that became lost rather than the initial request. As
+ such, your service may attempt to perform the same work.) If using
+ re-transmission (either explicitly or through the ServiceInvoker
+ fail-over mechanisms), you will have to deal with multiple requests
+ within your service to ensure it is idempotent.
</para>
</note>
<para>
- The use of transactions (such as those provided by JBossTS)
- and replication protocols (as provided by systems like
- JGroups) can help to tolerate many of these failure models.
- Furthermore, in the case where forward progress is not
- possible because of a failure, using transactions the
- application can then roll back and the underlying
- transaction system will guarantee data consistency such
- that it will appear as though the work was never attempted.
- At present JBossESB offers transactional support through
- JBossTS when deployed within the JBoss Application Server.
+ The use of transactions, (such as those provided by JBossTS),
+ and replication protocols (as provided by systems like
+ JGroups), can help with regard to failure toleration.
+ Furthermore, (in the case where forward progress is
+ not possible because of a failure), by using transactions the
+ application can roll back. The underlying
+ transaction system will then guarantee data consistency such
+ that it will appear as though the work was never attempted. At
+ present, when deployed within the JBoss Application Server,
+ JBossESB offers transactional support through JBossTS.
</para>
</section>
@@ -270,85 +261,76 @@
</title>
<para>
- An ideal failure detector is one which can allow for the
- unambiguous determination of the liveliness of an entity,
- (where an entity may be a process, machine etc.,), within a
- distributed system. However, guaranteed detection of
- failures in a finite period of time is not possible because
- it is not possible to differentiate between a failed system
- and one which is simply slow in responding.
+ An ideal failure detector is one which can allow for the
+ unambiguous determination of the liveliness of an "entity"
+ within a distributed system
+ (where an entity may be a process, machine and so on).
+ However, guaranteed detection
+ of failures in a finite period of time is not possible
+ because one cannot differentiate between a failed
+ system and one which is simply slow in responding.
</para>
<para>
- Current failure detectors use timeout values to determine
- the liveness of entities: for example, if a machine does not
- respond to an “are-you-alive?” message within a specified
+ Current failure detectors use timeout values to determine
+ the availability of entities. For example, if a machine does
+ not respond to an “Are-you-alive?” message within a specified
time period, it is assumed to have failed. If the values
- assigned to such timeouts are wrong (e.g., because of
- network congestion), incorrect failures may be assumed,
- potentially leading to inconsistencies when some machines
- “detect” the failure of another machine while others do not.
- Therefore, such timeouts are typically assigned given what
- can be assumed to be the worst case scenario within the
- distributed environment in which they are to be used, e.g.,
- worst case network congestion and machine load. However,
- distributed systems and applications rarely perform exactly
- as expected from one execution to another. Therefore,
+ assigned to such timeouts are wrong (because of a cause such
+ as network congestion), incorrect failures may be assumed.
+ This may potentially lead to inconsistencies, whereby some
+ machines “detect” the failure of another, whilst others do
+ not. Therefore, such timeouts are typically assigned based
+ upon an assumption of the worst case scenario within the
+ distributed environment in which they are to be used (for
+ example, worst case network congestion and machine load.)
+ However, distributed systems and applications rarely perform
+ exactly as expected from one execution to another. Therefore,
fluctuations from the worst case assumptions are possible,
and there is always a finite probability of making an
incorrect failure detection decision.
</para>
<para>
- Given that guaranteed failure detection based upon timeouts
- is not possible, there has been much work on failure
- suspectors: a failure suspector works by realising that
- although guaranteed failure detection is impossible,
- enforcing a decision that a given entity may have failed on
- to other, active entities is possible. Therefore, if one
- entity assumes another has failed, a protocol is executed
- between the remaining entities to either agree that it will
- be assumed to have failed (in which case it is excluded
- from the system and no further work by it will be accepted)
- or that it has not failed: the fact that one entity thinks
- it has failed does not mean that all entities will reach
- the same decision. If the entity has not failed and is
- excluded then it must eventually execute another protocol
- to be recognised as being alive.
+ Guaranteed failure detection is not possible. However, known active
+ entities can communicate with each other and agree that an unreachable
+ entity may have failed. This is the work of a <firstterm>failure suspector</firstterm>.
+ If one entity assumes another has failed, a protocol is executed between
+ the remaining entities to decide tor agree that it has failed or not. If
+ it is agreed that the entity has failed, then it is excluded from the
+ system and no further work by it will be accepted. The fact that one entity
+ thinks it has failed does not mean that all entities will reach the same
+ decision. If the entity has not failed and is excluded, then it must execute
+ another protocol to be recognized as alive.
</para>
<para>
- The advantage of the failure suspector is that all
- correctly functioning entities within the distributed
- environment will agree upon the liveness of another
- suspected failed entity. The disadvantage is that such
- failure suspection protocols are heavy-weight, typically
- requiring several rounds of agreement. In addition, since
- suspected failure is still based upon timeout values, it is
- possible for non-failed entities to be excluded, thus
- reducing (possibly critical) resource utilisation and
- availability.
+ The advantage of the <literal>failure suspector</literal> is that all correctly functioning
+ entities within the distributed environment will agree upon the state of an
+ entity suspected to have failed. The disadvantage is that such failure-suspecting protocols
+ are heavy-weight, and typically require several rounds to reach agreement. In addition, since
+ suspected failure is still based upon timeout values, it is possible for
+ entities which have not actually failed to be excluded, thus
+ reducing (possibly critical) resource utilization and availability.
</para>
<para>
- Some applications can tolerate the fact that failure
- detection mechanisms may occasionally return an incorrect
- answer. However, for other applications the incorrect
- determination of the liveliness of an entity may lead to
- problems such as data corruption, or in the case of mission
- critical applications (e.g., aircraft control systems or
- nuclear reactor monitoring) could result in loss of life.
+ Some applications can tolerate the fact that failure detection
+ mechanisms may occasionally return an incorrect answer. However, for
+ others, the incorrect determination of the liveliness of
+ an entity may lead to problems such as data corruption, or in the case
+ of mission-critical applications (such as aircraft control systems or
+ nuclear reactor monitoring) could result in the loss of life.
</para>
<para>
- At present JBossESB does not support failure detectors or
- failure suspectors. We hope to address this shortcoming in
- future releases. For now you should develop your consumers
- and services using the techniques previously mentioned
- (e.g., MessageID and time-out/retry) to attempt to
- determine whether or not a given service has failed. In
- some situations it is better and more efficient for the
- application to detect and deal with suspected failures.
+ At present, JBossESB does not support failure detectors or failure
+ suspectors. This shortcoming will hopefully be addressed in a future release. For
+ now, you should develop your consumers and services using the techniques
+ previously mentioned (such as MessageID and time-out/retry) in order to attempt to
+ determine whether or not a given service has failed. In some situations
+ it is actually better and more efficient for the application to detect and deal
+ with suspected failures.
</para>
</section>
@@ -361,46 +343,41 @@
</title>
<para>
- As we have seen, there are a range of ways in which failures
- can happen within a distributed system. In this section we will
- translate those into concrete examples of how failures could
- affect JBossESB and applications deployed on it. In the section
- on Recommendations we shall cover ways in which you can
- configure JBossESB to better tolerate these faults, or how you
+ As you have seen, there are a range of ways in which failures can
+ happen within a distributed system. In this section, you will
+ see concrete examples of how failures could
+ affect JBossESB and applications deployed on it. In the section
+ on Recommendations ways in which you can
+ configure JBossESB to better tolerate these faults will be
+ covered, along with advice on how you
should approach your application development.
</para>
<para>
- There are many components and services within JBossESB. The
- failure of some of them may go unnoticed to some or all of your
- applications depending upon when the failure occurs. For
- example, if the Registry Service crashes after your consumer
- has successfully obtained all necessary EPR information for the
- services it needs in order to function, then it will have no
- adverse affect on your application. However, if it fails before
- this point, your application will not be able to make forward
- progress. Therefore, in any determination of reliability
- guarantees it is necessary to consider when failures occur as
+ There are many components and services within JBossESB. The
+ failure of some of them may go unnoticed to some or all of your
+ applications depending upon when the failure occurs. For example,
+ if the Registry Service crashes after your consumer has
+ successfully obtained all necessary EPR information for the
+ services it needs in order to function, then the crash will have no
+ adverse affect on your application. However, if it fails before
+ this point, your application will not be able to make forward
+ progress. Therefore, in any determination of reliability
+ guarantees, it is necessary to consider when failures occur as
well as the types of those failures.
</para>
<para>
- It is never possible to guarantee 100% reliability and fault
- tolerance. The laws of physics (namely thermodynamics and the
- always increasing nature of entropy) mean that hardware
- degrades and human error is inevitable. All we can ever do is
- offer a probabilistic approach: with a high degree of
- probability, a system will tolerate failures and ensure data
- consistency/make forward progress. Furthermore, proving
- fault-tolerance techniques such as transactions or replication
- comes at a price: performance. This trade-off between
- performance and fault-tolerance is best achieved with
- application knowledge: any attempts at opaquely imposing a
- specific approach will inevitably lead to poorer performance in
- situations where it is imply not necessary. As such, you will
- find that many of the fault-tolerance techniques supported by
- JBossESB are disabled by default. You should enable them when
- it makes sense to do so.
+ It is never possible to guarantee 100% reliability and fault tolerance. Hardware
+ failure and human error is inevitable. However, you can ensure, with a high degree
+ of probability, that a system will tolerate failures, maintain data consistency and make
+ forward progress. Fault-tolerance techniques, such as transactions or replication, always
+ comes at a cost to performance. This trade-off between performance and fault-tolerance
+ is best achieved with knowledge of the application. Attempting to uniformly impose a
+ specific approach to all applications inevitably leads to poorer performance in
+ situations where it was not necessary. As such, you will find that many of the
+ fault-tolerance techniques supported by JBossESB are disabled by default. You should
+ enable them only when it makes sense to do so.
</para>
<section>
@@ -409,91 +386,90 @@
</title>
<para>
- We have previously discussed how message loss or delay may
- adversely affect applications. We have also shown some
- examples of how messages could be lost within JBossESB. In
- this section we shall discuss message loss in more detail.
+ You have previously read how message loss or delay may
+ adversely affect applications. You have also seen some
+ examples of how messages could be lost within JBossESB. In
+ this section message loss will be discussed in more detail.
</para>
<para>
- Many distributed systems support reliable message delivery,
- either point-to-point (one consumer and one provider) or
- group based (many consumers and one provider). Typically
- the semantics imposed on reliability are that the message
- will be delivered or the sender will be able to know with
- certainty that it did not get to the receiver, even in the
- presence of failures. It is frequently the case that
- systems employing reliable messaging implementations
- distinguish between a message being delivered to the
- recipient and it being processed by the recipient: for
- instance, simply getting the message to a service does not
- mean much if a subsequent crash of the service occurs
- before it has time to work on the contents of the message.
+ Many distributed systems support reliable message delivery,
+ either point-to-point (one consumer and one provider) or
+ group-based (many consumers and one provider). Even in the
+ presence of failures, the
+ semantics imposed on reliability are typically such that
+ the message will be
+ delivered or the sender will be able to know with certainty that
+ it failed to reach the receiver.
+ It is frequently the case that systems which employ reliable
+ messaging implementations distinguish between a message being
+ delivered to the recipient and it subsequently being processed by the
+ recipient. For instance, simply sending the message to a
+ service does not mean much if a subsequent crash of that same
+ service occurs before it has had time to work on the contents
+ of the message.
</para>
<para>
- Within JBossESB, the only transport you can use which gives
- the above mentioned failure semantics on Message delivery
- and processing is JMS: with transacted sessions (an
- optional part of the JMSEpr), it is possible to guarantee
- that Messages are received and processed in the presence of
- failures. If a failure occurs during processing by the
- service, the Message will be placed back on to the JMS
- queue for later re-processing. However, this does have some
- important performance implications: transacted sessions can
- be significantly slower than non-transacted sessions so
- should be used with caution.
+ Within JBossESB, the only transport you can use which gives the
+ aforementioned failure semantics on Message delivery and processing, is
+ JMS. If you use transacted sessions, (an optional part of the
+ <classname>JMSEpr</classname>), it is possible to guarantee that Messages
+ are received and processed in the presence of failures. If a failure occurs
+ during processing by the service, the Message will be placed back on the
+ JMS queue for later re-processing. However, transacted sessions can be
+ significantly slower than non-transacted sessions and so should be used with caution.
</para>
<para>
- Because none of the other transports supported by JBossESB
- come with transactional or reliable delivery guarantees, it
- is possible for Messages to be lost. However, in most
- situations the likelihood of this occurring is small.
- Unless there is a simultaneous failure of both sender and
- receiver (possible but not probable), the sender will be
- informed by JBossESB about any failure to deliver the
- Message. If a failure of the receiver occurs whilst
- processing and a response was expected, then the receiver
- will eventually time-out and can retry.
+ Because none of the other transports supported by JBossESB
+ come with transactional or reliable delivery guarantees, it
+ is possible for Messages to be lost. However, in most
+ situations, the likelihood of this occurring is small. Unless
+ there is a simultaneous failure of both sender and receiver
+ (possible but not probable), the sender will be informed by
+ JBossESB about any failure to deliver the Message. If a
+ failure of the receiver occurs whilst processing and a
+ response was expected, then the receiver will eventually
+ time-out and can retry.
</para>
<note>
<para>
- Using asynchronous message delivery can make failure
- detection/suspicion difficult (theoretically impossible
- to achieve). You should consider this aspect when
+ Using asynchronous message delivery can make failure
+ detection/suspicion difficult (indeed, theoretically impossible
+ to achieve). You should consider this aspect when
developing your applications.
</para>
</note>
<para>
- For these reasons, the Message fail-over and redelivery
- protocol that was described in the Advanced Chapter is a
- good best-effort approach. If a failure of the service is
- suspected then it will select an alternative EPR (assuming
- one is available) and use it. However, if this failure
- suspicion is wrong, then it is possible that multiple
- services will get to operate on the same Message
- concurrently. Therefore, although it offers a more robust
- approach to fail-over, it should be used with care. It
- works best where your services are stateless and
- idempotent, i.e., the execution of the same message
- multiple times is the same as executing it once.
+ For these reasons, the Message fail-over and re-delivery
+ protocol that was described in the Advanced Chapter is a
+ good best-effort approach. If a failure of the service is
+ suspected, then it will select an alternative EPR (assuming
+ one is available,) and use it. However, if this suspicion of failure
+ is wrong, then it is possible that multiple
+ services will operate on the same Message
+ concurrently. Therefore, although it offers a more
+ robust approach to fail-over, it should be used with care.
+ It works best where your services are stateless and
+ idempotent, (in other words, the execution of the same message
+ multiple times is the same as executing it once.)
</para>
<para>
- For many services and applications this type of redelivery
- mechanism is fine. The robustness it provides over a single
- EPR can be a significant advantage. The failure modes where
- it does not work, i.e., where the client and service fails
- or the service is incorrectly assumed to have failed, are
- relatively uncommon. If your services cannot be idempotent,
- then until JBossESB supports transactional delivery of
- messages or some form of retained results, you should
- either use JMS or code your services to be able to detect
- retransmissions and cope with multiple services performing
- the same work concurrently.
+ For many services and applications, this type of re-delivery
+ mechanism is fine. The robustness it provides over a single
+ EPR can be a significant advantage. The failure modes where
+ it does not work, (in other words, where the client and
+ service fails or the service is incorrectly assumed to have
+ failed), are relatively uncommon. If your services cannot be
+ idempotent, then until such a time as JBossESB supports transactional
+ delivery of messages or some form of retained results, you
+ should either use JMS or code your services to be able to
+ detect re-transmissions and cope with multiple services
+ performing the same work concurrently.
</para>
</section>
@@ -504,14 +480,13 @@
</title>
<para>
- We saw earlier how failure detection/suspicion is difficult
- to achieve. In fact until/unless a failed machine recovers,
- it is not possible to determine the difference between a
- crashed machine or one that is simply running extremely
- slowly. Furthermore, because networks can become
- partitioned, it is entirely possible that different
- consumers have different views of which services are
- available (often referred to as split-brain syndrome).
+ It was described earlier how failure detection/suspicion is difficult to achieve. In
+ fact, until a failed machine recovers, it is not possible to determine the
+ difference between a crashed machine or one that is simply running extremely slowly.
+ Networks can also become partitioned: This is a situation where the network becomes divided,
+ and effectively acts as two or more separate networks. When this happens, consumers
+ on different parts of the network can only see the services available in their own
+ part. This is sometimes called "split-brain syndrome".
</para>
</section>
@@ -523,15 +498,16 @@
</title>
<para>
- Unless using transactions or a reliable message delivery
- protocol such as JMS, JBossESB will only tolerate crash
- failures that are not catastrophic (i.e., the entire system
- does not fail) and result in the ability of JBossESB and/or
- the application to unambiguously reason about the liveness
- of the endpoints involved. If services crash or shutdown
- cleanly before receiving messages, then it is safe to use
- transports other than JMS.
+ JBossESB is able to recover from a catastrophic failure
+ that shuts down the entire system when you use either
+ transactions or a reliable message delivery protocol
+ such as JMS.
</para>
+
+ <para>
+ Without these, JBossESB can only tolerate failures when the
+ availability of the endpoints involved is guaranteed.
+ </para>
</section>
@@ -553,12 +529,12 @@
</title>
<para>
- Once a message is accepted by a Gateway it will not be lost
- unless sent within the ESB using an unreliable transport.
- All of the following JBossESB transports can be configured
- to either reliably deliver the Message or ensure it is not
- removed from the system: JMS, FTP, SQL. Unfortunately HTTP
- cannot be so configured.
+ Once a message is accepted by a Gateway it will not be lost
+ unless sent within the ESB using an unreliable transport.
+ JMS, FTP and SQL are JBossESB transports can be configured to
+ either reliably deliver the Message or ensure it is not
+ removed from the system. Unfortunately, HTTP
+ cannot be configured in this way.
</para>
</section>
@@ -569,27 +545,27 @@
</title>
<para>
- The ServiceInvoker will place undeliverable Messages to the
- Redelivery Queue if sent asynchronously. Synchronous
- Message delivery that fails will be indicated immediately
- to the sender. In order for the ServiceInvoker to function
- correctly the transport must indicate an unambiguous
- failure to deliver to the sender. A simultaneous failure of
- the sender and receiver may result in the Message being
- lost.
+ The ServiceInvoker will place undeliverable Messages in the
+ Re-delivery Queue if they have been sent asynchronously. Synchronous
+ Message delivery that fails will be indicated to the sender immediately.
+ In order for the ServiceInvoker to function
+ correctly, the transport must indicate a
+ failure to deliver to the sender unambiguously. A simultaneous failure
+ of the sender and receiver may result in the Message being
+ lost.
</para>
</section>
- <section>
+ <section id="sect-SOA_ESB_Programmers_Guide-Reliability_Guarantees-JMS_Broker">
<title>
JMS Broker
</title>
<para>
Messages that cannot be delivered to the JMS broker will be
- queued within the Redelivery Queue. For enterprise
- deployments a clustered JMS broker is recommended.
+ placed within the Redelivery Queue. For enterprise
+ deployments, a clustered JMS broker is recommended.
</para>
</section>
@@ -600,16 +576,16 @@
</title>
<para>
- As with most distributed systems, we differentiate between
- a Message being received by the container within which
- services reside and it being processed by the ultimate
- destination. It is possible for Messages to be delivered
- successfully but for an error or crash during processing
- within the Action pipeline to cause it to be lost. As
- mentioned previously, it is possible to configure some of
- the JBossESB transports so they do not delete received
- Messages when they are processed, so they will not be lost
- in the event of an error or crash.
+ It is important to differentiate between
+ a Message being received by the container within which
+ services reside and it being processed by the ultimate
+ destination. It is possible for Messages to be delivered
+ successfully, only for an error or crash during processing
+ within the Action pipeline to cause its loss. As
+ mentioned previously, it is possible to configure some of
+ the JBossESB transports so that they do not delete received
+ Messages when they are processed. This is in order that they will
+ not be lost in the event of an error or crash.
</para>
</section>
@@ -622,31 +598,31 @@
</title>
<para>
- Given the previous overview of failure models and the
- capabilities within JBossESB to tolerate them, we arrive at the
- following recommendations:
+ Given the previous overview of failure models and the
+ capabilities within JBossESB to tolerate them, the following
+ recommendations can be made:
</para>
<itemizedlist>
<listitem>
+
<para>
- Try to develop stateless and idempotent services. If
- this is not possible, use MessageID to identify
- Messages so your application can detect retransmission
- attempts. If retrying Message transmission, use the
- same MessageID. Services that are not idempotent and
- would suffer from redoing the same work if they receive
- a retransmitted Message, should record state
- transitions against the MessageID, preferably using
- transactions. Applications based around stateless
- services tend to scale better as well.
+ Try to develop stateless and idempotent services. If
+ this is not possible, use MessageID to identify Messages
+ so that your application can detect re-transmission attempts.
+ If retrying Message transmission, use the same MessageID.
+ Services that are not idempotent (and would suffer from
+ re-doing the same work if they receive a re-transmitted
+ Message), should record state transitions against the
+ MessageID, preferably using transactions. Furthermore, applications
+ based around stateless services tend to scale better.
</para>
</listitem>
<listitem>
<para>
- If developing stateful services, use transactions and a
- JMS implementation (clustered preferably).
+ If developing stateful services, use transactions and a (preferably clustered)
+ JMS implementation.
</para>
</listitem>
@@ -751,16 +727,17 @@
</itemizedlist>
<para>
- Despite what you may have read in this Chapter, failures are
- uncommon. Over the years hardware reliability has improved
- significantly and good software development practices including
- the use of formal verification tools have reduced the chances
- of software problems. We have given the information within this
- Chapter to assist you in determining the right development and
- deployment strategies for your services and applications. Not
- all of them will require high levels of reliability and fault
- tolerance, with associated reducing in performance. However,
- some of them undoubtedly will.
+ Despite the impression that you may have gained from this
+ Chapter, failures are
+ uncommon. Over the years, hardware reliability has improved
+ significantly and good software development practices (including
+ the use of formal verification tools) have reduced the chances of
+ software problems. We have given the information within this
+ Chapter to assist you when you determine the right development and
+ deployment strategies for your services and applications. Not all
+ of them will require high levels of reliability and fault tolerance,
+ with associated reducing in performance. However, some of them
+ undoubtedly will.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/JBossESB.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/JBossESB.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/JBossESB.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -5,26 +5,36 @@
]>
<chapter>
- <title>
- JBossESB
- </title>
+ <title>
- <section>
- <title>
- Rosetta
- </title>
+ The JBoss Enterprise Service Bus
+ </title>
+
+
+ <section>
+ <title>
+ Rosetta
+ </title>
+
+ <para>
+ At the core of the <application>JBoss Enterprise SOA
+ Platform</application> is <firstterm>Rosetta</firstterm>, an
+ enterprise service bus which has been deployed at many mission
+ critical sites over the past several years. These deployments
+ have included highly heterogeneous environments. One such site
+ included an IBM mainframe running z/OS, DB2 and Oracle
+ databases, Windows and Linux servers and a variety of
+ third-party applications, as well as other services that were
+ outside of the corporation’s information technology
+ infrastructure.
+ </para>
- <para>
- The core of JBossESB is Rosetta, an ESB that has been in commercial
- deployment at a mission critical site for over 3 years. The
- architectCommitted revision 28034. ure of Rosetta is shown below.
- </para>
-
<note>
<para>
- In the diagram, processor classes refer to the Action classes
- within the core that are responsible for processing on triggered
- events.
+ In the following diagram, the term, <firstterm>processor
+ classes</firstterm>, refers to those action classes within
+ Rosetta's core that are responsible for processing when events are
+ triggered.
</para>
</note>
@@ -32,45 +42,47 @@
<figure><title>Rosetta</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/jboss_esb/rosetta.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/jboss_esb/rosetta.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- There are many reasons why users may want disparate applications,
- services and components to interoperate, e.g., leveraging legacy
- systems in new deployments. Furthermore, such interactions between
- these entities may occur both synchronously or asynchronously. As
- with most ESBs, Rosetta was developed to facilitate such
- deployments, but providing an infrastructure and set of tools that
- could:
+ One may want disparate applications, services and components to
+ interoperate for many reasons, one example being the wish to
+ leverage legacy systems in new deployments. Furthermore, such
+ interactions between these entities may occur either
+ <firstterm>synchronously</firstterm> or
+ <firstterm>asynchronously</firstterm>. As with most enterpise
+ service buses, Rosetta was developed to facilitate such deployments
+ but, in addition, it provides an infrastructure and set of tools
+ that can:
</para>
<itemizedlist>
<listitem>
<para>
- Be easily configured to work with a wide variety of transport
- mechanisms (e.g., email and JMS).
+ be configured easily to work with a wide variety of transport
+ mechanisms (such as e. mail and JMS.)
</para>
</listitem>
<listitem>
<para>
- Offer a general purpose object repository.
+ offer a general-purpose object repository.
</para>
</listitem>
<listitem>
<para>
- Enable pluggable data transformation mechanisms.
+ enable one to implement pluggable data transformation mechanisms.
</para>
</listitem>
<listitem>
<para>
- Support logging of interactions.
+ support logging of interactions.
</para>
</listitem>
</itemizedlist>
@@ -89,7 +101,7 @@
files to/from the outside world and attachments in e-mail messages
to ‘well known’ e-mail accounts.
</para>
-
+
<para>
As we shall see when examining the JBossESB core, which is based on
Rosetta, the challenge was to provide a set of tools and a
@@ -104,105 +116,114 @@
can be unaware of transport and triggering mechanisms.
</para>
-
-<note>
+<important>
<para>
- Within JBossESB source we have two trees:
- org.jboss.internal.soa.esb and org.jboss.soa.esb. You should limit
- your use of anything within the org.jboss.internal.soa.esb package
- because the contents are subject to change without notice.
- Alternatively anything within the org.jboss.soa.esb is covered by
- our deprecation policy.
+ There are two trees within the source code:
+ <filename>org.jboss.internal.soa.esb</filename> and
+ <filename>org.jboss.soa.esb</filename>. Use the contents of the
+ <filename>org.jboss.internal.soa.esb</filename> package sparingly
+ because they are subject to change without notice. By contrast,
+ everything within the <filename>org.jboss.soa.esb</filename>
+ package is covered by Red Hat's deprecation policy.
</para>
-</note>
+</important>
</section>
<section>
<title>
- The core of JBossESB in a nutshell
+ The JBoss Enterprise Service Bus' Core: A Summary
</title>
<para>
- Rosetta is built on four core architectural components:
+ Rosetta is built on top of four key architectural components. They are:
</para>
-<itemizedlist>
+<orderedlist>
<listitem>
<para>
- Message Listener and Message Filtering code. Message Listeners
- act as “inbound” message routers that listen for messages (e.g.
- on a JMS Queue/Topic, or on the file system) and present the
- message to a message processing pipeline that filters the
- message and routes it (“outbound” router) to another message
- endpoint.
+ <firstterm>message listener</firstterm> and <firstterm>message
+ filtering</firstterm> code. Message listeners act as routers
+ that "listen" for inbound messages for messages (such as those
+ on a JMS queue or topic, or on the file system). They then
+ present the message to a processing pipeline that filters and
+ routes it (via an outbound router) to another message
+ end-point.
</para>
</listitem>
<listitem>
<para>
- Data transformation via the SmooksAction action processor. See
- the “Message Transformation” chapter in the ServicesGuide for
- further details.
+ a data transformation component that acts via the
+ <systemitem>SmooksAction</systemitem> processor. (Read the
+ “Message Transformation” chapter in the <emphasis>Services
+ Guide</emphasis> to learn more about this.)
</para>
</listitem>
<listitem>
<para>
- A Content Based Routing Service. See the “What is Content-Based
- Routing” chapter in the ServicesGuide for further information.
+ a <firstterm>content-based routing</firstterm> service. (Read the “What is
+ Content-Based Routing?” chapter in the <emphasis>Services
+ Guide</emphasis> to learn more about this.)
</para>
</listitem>
<listitem>
<para>
- A Message Repository, for saving messages/events exchanged
- within the ESB. See the “What is the Registry” chapter in the
- ServicesGuide for further details.
+ a <firstterm>message repository</firstterm>, used to save
+ messages and/or events that have been exchanged within the ESB.
+ (Read the “What is the Registry?” chapter in the
+ <emphasis>Services Guide</emphasis> to learn more about this.)
</para>
</listitem>
-</itemizedlist>
+</orderedlist>
<para>
- These capabilities are offered through a set of business
- classes, adapters and processors, which will be described in
- detail later. Interactions between clients and services are
- supported via a range of different approaches, including JMS,
- flat-file system and email.
+ These components themselves consist of a set of business
+ classes, adapters and processors, described in detail later in
+ this <emphasis>Guide</emphasis>. Client-service interaction is
+ facilitated via a range of different approaches, including JMS,
+ flat-file systems and e. mail.
</para>
<para>
- A typical JBossESB deployment is shown below. We shall return to
- this diagram in subsequent sections.
+ Here is a depiction of a typical <application>JBoss Enterprise
+ Service Bus</application> deployment:
</para>
+ <figure><title>Typical Deployment</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/jboss_esb/image8.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
<note>
<para>
- Some of the components in the diagram (e.g., LDAP server) are
- configuration choices and may not be provided out-of-the-box.
- Furthermore, the Processor and Action distinction shown in the
- above diagram is merely an illustrative convenience to show the
- concepts involved when an incoming event (message) triggers the
- underlying ESB to invoke higher-level services.
+ Some of the components in the diagram (such as the lightweight
+ directory access protocol server) are configuration choices and
+ may not be provided "out-of-the-box." Furthermore, the distinction
+ shown between processors and actions is merely an illustrative
+ convenience intended to show the concepts involved when an
+ incoming event (that is, a message) triggers the underlying
+ enterprise service bus to invoke higher-level services.
</para>
</note>
- <figure><title>Typical Deployment</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/jboss_esb/image8.png" width="100%" scalefit="1" contentdepth="100%" />
- </imageobject>
- </mediaobject>
- </figure>
+
<para>
- In the following chapters we shall look at the various
- components within JBossESB and show how they interact and can be
- used to develop SOA-based applications.
+ Having gained a high-level understanding, read on to learn, in
+ more detail, about the various <application>JBoss Enterprise
+ Service Bus</application> components, the ways in which they
+ interact and how they can be used to develop SOA-based
+ applications.
</para>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Other_Components.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Other_Components.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Other_Components.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -11,11 +11,12 @@
</title>
<para>
- In this Chapter we shall look at other infrastructural components
- and services within JBossESB. Several of these services have their
- own documentation which you should also read: the aim of this
- Chapter is to simply give an overview of what else is available to
- developers.
+ Read this chapter to learn about the other infrastructural
+ components and services that exist within the <application>JBoss
+ Enterprise Service Bus</application>. Several of these services
+ have their own documentation which one should also read; the aim of
+ this chapter is simply to provide an overview of other things that
+ are available to developers.
</para>
<section>
@@ -24,25 +25,29 @@
</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 <application>JBoss Enterprise Service Bus</application>'s
+ <firstterm>message store</firstterm> mechanism has been
+ designed with the purpose of audit tracking in mind. As is the
+ case with other ESB services, it is
+ <firstterm>pluggable</firstterm>, meaning that one can "plug
+ in" one's own persistence mechanism should there be the need to
+ do so. The <systemitem>message store</systemitem> is in the
+ form of a <firstterm>database persistence
+ mechanism</firstterm>. If something else is required such as,
+ for instance, a file persistence mechanism, then it is simply a
+ matter of writing one's own service, and then over-riding the
+ default behaviour 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.
+ At present, the <systemitem>message store</systemitem> is a
+ base implementation only. Red Hat is working with the community
+ and partners to drive the feature set forward. It will
+ eventually support advanced auditing functionality in order to
+ meet managerial requirements. What one sees at the moment is
+ only a starting point.
</para>
-
+</note>
</section>
<section>
@@ -52,31 +57,34 @@
</title>
<para>
- Often clients and services will communicate using the same
- vocabulary. However, there are situations where this is not the
- case and on-the-fly transformation from one data format to
- another will be required. It is unrealistic to assume that a
- single data format will be suitable for all business objects,
- particularly in a large scale or long running deployment.
- Therefore, it is necessary to provide a mechanism for
- transforming from one data format to another.
+ Most of the time, clients and services communicate using the
+ same vocabulary. However, there are times when this will not be
+ the case and one will require an "on-the-fly" transformation
+ mechanism to translate from one format to another another. It
+ is unrealistic to assume that a single data format will suit
+ every business object, particularly in a large-scale or
+ long-running deployment. Therefore, a data transformation
+ mechanism has been provided.
</para>
<para>
- In JBossESB this is the role the Transformation Service. This
- version of the ESB is shipped with an out-of-the-box
- Transformation Service based on Smooks (<ulink
- url="http://www.smooks.org" />). Smooks is a Transformation
- Implementation and Management framework. It allows you
- implement your transformation logic in XSLT, Java etc and
- provides a management framework through which you can centrally
- manage the transformation logic for your message-set.
+ It is called the <firstterm>Transformation Service</firstterm>.
+ The current version of the <application>JBoss Enterprise
+ Service Bus</application> ships with an out-of-the-box version
+ of this service based on <application>Smooks</application>.
+ <application>Smooks</application> is a transformation,
+ implementation and management framework. It allows one to
+ implement transformation logic in formats like XSLT and Java.
+ It also provides a management framework through which one can
+ centrally manage this logic.
</para>
<note>
<para>
- For more details see the “Message Transformations” chapter in
- the ServicesGuide.
+ To learn more about <application>Smooks</application>, read
+ both the "Message Transformations" chapter in the
+ <emphasis>Services Guide</emphasis> and the <emphasis>Smooks
+ Guide</emphasis> itself.
</para>
</note>
</section>
@@ -87,14 +95,36 @@
</title>
<para>
- Sometimes it is necessary for the ESB to dynamically route
- messages to their sources. For example, the original
- destination may no longer be available, the service may have
- moved, or the application simply wants to have more control
- over where messages go based on content, time-of-day etc. The
- Content-based Routing mechanism within JBossESB can be used to
- route Messages based on arbitrarily complex rules, which can be
- defined within XPath or Drools notation.
+ Sometimes the <application>JBoss Enterprise Service
+ Bus</application> finds it necessary to dynamically route
+ messages back to their sources. This may be the case when:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ the original destination is no longer available
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ services have been moved
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the application simply needs to have more control over
+ where messages are sent based on their content, the
+ time-of-day or other attributes
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Use the <firstterm>content-based routing</firstterm> mechanism
+ to route messages based on arbitrarily complex rules. (These
+ rules can be defined in XPath, Regex Content-Based Routing
+ (CBR) or JBoss Rules notation.)
</para>
</section>
@@ -105,26 +135,27 @@
</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
+ In the context of SOA, a <systemitem>registry</systemitem>
+ provides applications and businesses a central point in which
+ to store information about services. It is expected to provide
+ its clients with the same level of information and the same
+ breadth of services as a conventional market-place would.
+ Ideally a <systemitem>registry</systemitem> should also
+ facilitate the automatic discovery and execution of e. commerce
+ transactions and provide a dynamic environment for these.
+ Therefore, a <systemitem>registry</systemitem> is more than an
+ "e. business directory:" it is an key component of SOA
infrastructure.
</para>
<para>
- In many ways, the Registry Service can be considered to be the
- "heart" of the JBoss Enterprise Service Bus: services can
- "self-publish" their end-point references to the Registry when
- they are activated and then remove them when they are taken out
- of service. Consumers can consult the Registry in order to
- determine which end-point reference is that which is needed for
- the current service task.
+ Consider the <systemitem>registry</systemitem> as the "heart"
+ of the <application>JBoss Enterprise Service Bus</application>:
+ services can "self-publish" their end-point references to it
+ and remove them when they are no longer in use. Consumers, too,
+ can consult the <systemitem>registry</systemitem> in order to
+ determine which end-point reference they need for their current
+ service task.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Service_Orientated_Architecture_Overview.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Service_Orientated_Architecture_Overview.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Service_Orientated_Architecture_Overview.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -8,63 +8,47 @@
<title>
Appendix B: Service Orientated Architecture Overview
</title>
-
+
<para>
- JBossESB is a Service Oriented Architecture (SOA) infrastructure.
- SOA represents a popular architectural paradigm
- <footnote><para>
- The principles behind SOA have been around for many years, but
- Web Services have popularised
- </para></footnote>
- for applications,
- with Web Services as probably the most visible way of achieving an
- SOA.
- <footnote><para>
- It is possible to build non-SOA applications using Web
- Services.
- </para></footnote>
- Web Services implement capabilities that are available to
- other applications (or even other Web Services) via industry
- standard network and application interfaces and protocols. SOA
- advocates an approach in which a software component provides its
- functionality as a service that can be leveraged by other software
- components. Components (or services) represent reusable software
- building blocks.
+ JBossESB is a Service Oriented Architecture (SOA) infrastructure. SOA
+ represents a popular architectural paradigm for applications development.
+ While the principles behind SOA have existed for many years and it does not
+ necessarily require the use of web services, it is these that popularised it.
</para>
<para>
- SOA allows the integration of existing systems, applications and
- users into a flexible architecture that can easily accommodate
- changing needs. Integrated design, reuse of existing IT investments
- and above all, industry standards are the elements needed to create
- a robust SOA.
+ Web services implement capabilities that are available to other applications
+ (or even other web services) via industry standard network and application
+ interfaces and protocols. SOA advocates an approach in which one software component
+ provides its functionality as a service that can be leveraged by
+ others. Components (or services) thus represent reusable software building blocks.
</para>
<para>
As enterprises slowly emerge from the mad rush of cost reduction
into a more stable period of cost management, many of them find
- themselves in unfamiliar territory. Prior to the economic slow
- down, most firms understood the options they had for IT investment.
- Many embarked on major package implementations (e.g., Siebel,
- Peoplesoft and so on), while others built on the legacy systems
- they have trusted for years. Either way, most firms recognized the
- return promised and made the investment. Today, the appetite for
- such large investment is gone.
+ themselves in unfamiliar territory. Prior to the economic slow down,
+ most firms understood the options they had for IT investment. Many
+ embarked on major package implementations (installing products such as Siebel, PeopleSoft
+ and so on), while others built on the legacy systems they had
+ trusted for years. Either way, most firms recognized the return
+ promised and made the investment. Today, the appetite for such large
+ investment is gone.
</para>
<para>
- However, enterprises still need to make forward progress and keep
- ahead of the competition. SOA (and typically Web Services as a
- concrete implementation of those principles) make this possible.
- The result is dramatic improvements in collaboration between users,
- applications and technology components, generating significant
- value for any business creating competitive advantage.
+ However, enterprises still need to make progress and keep
+ ahead of the competition. SOA (and Web Services as a
+ concrete implementation of those principles) make this possible. The
+ result is dramatic improvements in collaboration between users,
+ applications and technology components, generating significant value
+ for any business creating competitive advantage.
</para>
<para>
Imagine a company that has existing software from a variety of
- different vendors, e.g., SAP, PeopleSoft. Some of these software
- packages may be useful to conduct business with other companies
+ different vendors, such as SAP and PeopleSoft. Some of these software
+ packages may be used to conduct business with other companies
(customers, suppliers, etc.) and therefore what the company would
like to do is to take those existing systems and make them
available to other companies, by exposing them as services. A
@@ -126,24 +110,21 @@
</para>
<para>
- However, whilst the ultimate goal of SOA is inter-company
- interactions, services do not need to be accessed using the
- Internet. They can be easily made available to clients residing on
- a local network. It is common for web services to be used in this
- context to provide integration between systems operating within a
- single company.
+ However, whilst the ultimate goal of SOA is inter-company
+ interactions, services do not need to be accessed using the Internet. They
+ can be easily made available to clients residing on a local network. It is common for
+ web services to be used in this context to provide integration between systems
+ operating within a single company.
</para>
<para>
- An example of how Web services can connect applications both
- intra-company and inter-company can be understood by considering a
- stand-alone inventory system. If you don't connect it to anything
- else, it's not as valuable as it could be. The system can track
- inventory, but not much more. Inventory information may have to be
- entered separately in the accounting and customer relationship
- management systems. The inventory system may be unable to
- automatically place orders to suppliers. The benefits of such an
- inventory system are diminished by high overhead costs.
+ As demonstration of how web services can connect applications to each other both
+ within and between companies, consider a stand-alone inventory system.
+ If you do not connect it to anything else, it is not as valuable as it could otherwise be. The
+ system can track inventory but not do much more. Inventory information may have to be
+ entered separately in the accounting and customer relationship management systems.
+ The inventory system may be unable to automatically place orders to suppliers. The
+ benefits of such an inventory system are diminished by high overhead costs.
</para>
<para>
@@ -161,26 +142,23 @@
</para>
<para>
- Businesses are waking up to the benefits of SOA. These include:
+ Businesses are "waking up" to the benefits of SOA. These include:
</para>
<itemizedlist>
<listitem>
<para>
- opening the door to new business opportunities by making it
- easy to connect with partners;
+ opening the door to new business opportunities by making it easy to connect with partners;
</para>
</listitem>
<listitem>
<para>
- saving time and money by cutting software development time
- and consuming a service created by others;
+ saving time and money by cutting software development time and consuming a service created by others;
</para>
</listitem>
<listitem>
<para>
- increasing revenue streams by easily making your own
- services available.
+ increasing revenue streams by easily making your own services available.
</para>
</listitem>
</itemizedlist>
@@ -191,12 +169,12 @@
<para>
The problem space can be categorized by past IT investments in
the area of eProcurement, eSourcing, Supply Chain Management,
- Customer Relationship Management (CRM) and, indeed, Internet
- computing in general. All of these investments were made in a
- "silo." The decisions made in this space, (along with the
- incremental growth of these systems to meet short-term tactical
- requirements), hurt the long-term viability of the applications
- and infrastructure.
+ Customer Relationship Management (CRM) and, indeed, Internet computing in
+ general. All of these investments were made in a "silo." The
+ decisions made in this space, (along
+ with the incremental growth of these systems to meet short-term
+ tactical requirements), hurt
+ the long-term viability of the applications and infrastructure.
</para>
<para>
@@ -217,8 +195,7 @@
<listitem>
<para>
- Delivering IT solutions faster and smarter: A
- standards based approach will allow organizations
+ A standards-based approach will allow organizations
to connect and share information and business
processes much faster and easier than before. IT
delivery productivity is markedly improved through
@@ -233,25 +210,24 @@
<listitem>
<para>
- Maximizing return on investment: Web Services opens
- the way for new business opportunities by enabling
- new business models. Web Services present the
- ability to measure value and discrete return much
- differently than traditional functional-benefit
- methods. Typical Total Cost of Ownership (TCO)
- models do not take into account the lifetime value
- generated by historical investment. This cost
- centric view destroys many opportunities to exploit
- these past investments and most enterprises end up
- building redundancy into their architecture, not
- out of necessity, but of perceived need. These same
- organizations focus the value proposition of their
- IT investment on a portfolio of applications,
- balanced by the overhead of infrastructure. An
- approach based on Web Services takes into account
- the lifetime contribution of legacy IT investment
- and promotes an evolution of these investments
- rather than a planned replacement.
+ Implementation of Web Services opens the way for new business
+ opportunities by enabling new organisational models. Web
+ Services present the ability to measure value and
+ discrete return much differently than traditional
+ functional-benefit methods. Typical Total Cost of
+ Ownership (TCO) models do not take into account the
+ lifetime value generated by historical investment.
+ This cost-centric view destroys many opportunities
+ to exploit these past investments and most
+ enterprises end up building redundancy into their
+ architecture, not out of necessity but of perceived
+ need. These same organizations focus the value
+ proposition of their IT investment on a portfolio of
+ applications, balanced by the overhead of
+ infrastructure. An approach based on Web Services
+ takes into account the lifetime contribution of
+ legacy IT investment and promotes an evolution of
+ these systems rather than a planned replacement.
</para>
</listitem>
</orderedlist>
@@ -267,45 +243,42 @@
<para>
Software-as-a-service has become a pervasive model for
- forward-looking enterprises wishing to streamline operations,
- as it leads to lower cost of ownership and provides competitive
- differentiation in the marketplace. Using Web Services gives
- enterprises a viable opportunity to drive significant costs out
- of software acquisitions, react to rapidly changing market
- conditions and conduct transactions with business partners at
- will. Loosely coupled, standards-based architectures are one
- approach to distributed computing. They allow software
- resources available on the network to be leveraged.
- Applications that provide separate business processes,
- presentation rules, business rules and data access in separate,
- loosely-coupled layers will not only assist in the construction
- of better software but also make it more adaptable to future
- change.
+ forward-looking enterprises wishing to streamline operations, as it leads to lower cost
+ of ownership and provides competitive differentiation in the
+ marketplace. Using Web Services gives enterprises a viable opportunity
+ to drive significant costs out of software
+ acquisitions, react to rapidly changing market conditions and
+ conduct transactions with business partners at will. Loosely
+ coupled, standards-based architectures are one approach to
+ distributed computing. They allow software resources
+ available on the network to be leveraged. Applications that provide
+ separate business processes, presentation rules, business rules
+ and data access in separate, loosely-coupled layers will not
+ only assist in the construction of better software but also make
+ it more adaptable to future change.
</para>
<para>
- SOA will allow for combining existing functions with new
- development efforts, allowing the creation of composite
- applications. Leveraging what works lowers the risks in
- software development projects. By reusing existing functions,
- it leads to faster deliverables and better delivery quality.
+ SOA allows you to combining existing functions with new development efforts, resulting in
+ composite applications. The re-use of existing functionality in this way
+ reduces the overall project risk and delivery time-frame. It also improves the overall quality
+ of the software.
</para>
<para>
Loose coupling helps preserve the future by allowing parts to
- change at their own pace without the risks linked to costly
- migrations using monolithic approaches. SOA allows business
+ be changed at their own pace without the risks linked to the costly
+ which occur with monolithic approaches. SOA allows business
users to focus on business problems at hand without worrying
- about technical constraints. For the individuals who develop
- solutions, SOA helps in the following manner:
+ about technical constraints. SOA helps the individuals who
+ develop the solutions, in the following manner:
</para>
<itemizedlist>
<listitem>
- <para>Business analysts focus on higher order
- responsibilities in the development lifecycle while
- increasing their own knowledge of the business
- domain.</para>
+ <para>Business analysts can focus on higher-order responsibilities in the
+ development life-cycle while increasing their own knowledge of the business
+ domain.</para>
</listitem>
<listitem>
<para>
@@ -324,27 +297,28 @@
<listitem>
<para>
Development teams can deviate from initial requirements
- without incurring additional risk
+ without incurring additional risk.
</para>
</listitem>
<listitem>
<para>
- Components within architecture can aid in becoming
- reusable assets in order to avoid reinventing the wheel
+ Components within architecture can becomr
+ reusable assets so that the business can avoid reinventing the wheel.
</para>
</listitem>
<listitem>
<para>
- Functional decomposition of services and their
+ The flexibility, future
+ maintainability and ease of integration efforts is
+ preserved by functional decomposition of services and their
underlying components with respect to the business
- process helps preserve the flexibility, future
- maintainability and eases integration efforts
+ process
</para>
</listitem>
<listitem>
<para>
- Security rules are implemented at the service level and
- can solve many security considerations within the
+ Security rules are implemented at the service level. They can, therefore,
+ solve many security considerations within the
enterprise
</para>
</listitem>
@@ -356,12 +330,12 @@
<title>Basics of SOA</title>
<para>
- Traditional distributed computing environments have been
- tightly coupled in that they do not deal with a changing
- environment well. For instance, if an application is
- interacting with another application, how do they handle data
- types or data encoding if data types in one system change? How
- are incompatible data-types handled?
+ Traditional distributed computing environments have been tightly
+ coupled, in the sense that they do not deal with a changing environment at all
+ well. For instance, if one application is interacting with
+ another, how do they handle data types or data
+ encoding if data formats in one system change? How are
+ incompatible data-types handled?
</para>
<para>
@@ -639,18 +613,18 @@
<title>JBossESB and its Relationship with SOA</title>
<para>
- SOA is more than technology: it does not come in a
- shrink-wrapped box and requires changes to the way in which
- people work and interact as much as assistance from underlying
- infrastructures, such as JBossESB. With JBossESB 4.8, Red Hat
+ SOA is more than technology; it does not come in a
+ shrink-wrapped box and it requires changes to the way in which
+ people work and interact as much as it does assistance from underlying
+ infrastructures, such as JBossESB. With JBossESB, Red Hat
is providing a base SOA infrastructure upon which SOA
- applications can be developed. With the 4.2.1 release, most of
- the necessary hooks for SOA development are in place and Red
- Hat is working with its partners to ensure that their higher
- level platforms leverage these hooks appropriately. However,
- the baseline platform (JBossESB) will continue to evolve, with
+ applications can be developed. Most of
+ the necessary hooks for SOA development are in place and Red Hat
+ is working with its partners to ensure that their higher level
+ platforms leverage these hooks appropriately. However, the
+ baseline platform (JBossESB) will continue to evolve, with
out-of-the-box improvements around tooling, runtime management,
- service life-cycle etc. In JBossESB 4.8, it may be necessary
+ service life-cycle etc. In JBossESB, it may be necessary
for developers to leverage these hooks themselves, using
low-level API and patterns.
</para>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Services_and_Messages.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Services_and_Messages.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Services_and_Messages.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -10,116 +10,176 @@
</title>
<para>
- In keeping with SOA principles, everything within JBossESB is
- considered to be either a service or a message. Services
- encapsulate the business logic or points of integration with
- legacy systems. Messages are the way in which clients and
- services communicate with each other.
+ From this point, in keeping with Service-Oriented Architecture
+ principles, one should think of everything within the
+ <application>JBoss Enterprise Service Bus</application> as being
+ either a <firstterm>service</firstterm> or a
+ <firstterm>message</firstterm>. Thinking in terms of these
+ concepts will facilitate more rapid understanding of how the
+ software works.
</para>
-
+
+
+
+
+<itemizedlist>
+ <listitem>
<para>
- In the following sections we shall look at how Services and
- Messages are supported within JBossESB.
+ each service encapsulates either business logic or a point of
+ integration with legacy systems.
</para>
-
+ </listitem>
+ <listitem>
+ <para>
+ it is through messages that clients and services
+ communicate with each other.
+ </para>
+ </listitem>
+</itemizedlist>
- <section id="sect-SOA_ESB_Programmers_Guide-Services_and_Messages-The_Service">
- <title>The Service</title>
+ <para>
+ Read the next section to learn how services and
+ messages are supported.
+ </para>
+
+ <section>
+ <title>Services</title>
+
<para>
- A “Service” in JBossESB is defined as a list of “Action”
- classes that process an ESB Message in a sequential manner (see
- below). This list of Action classes is referred to as an
- “Action Pipeline”. A Service can define a list of “Listeners”,
- which act as inbound routers for the Service, routing messages
- to the Action Pipeline.
+ In the <application>JBoss Enterprise Service Bus</application>,
+ one can define a service as "a list of <firstterm>action
+ classes</firstterm> that process a message in a sequential
+ manner."
</para>
<para>
- The following is a very simple JBossESB configuration that
- defines a single Service that simply prints the contents of the
- ESB Message to the console.
+ The list of action classes to which this definition refers is
+ known as an <firstterm>action pipeline</firstterm>.
</para>
-
+
+ <para>
+ A service can also define a list of
+ <firstterm>listeners</firstterm>.
+ <systemitem>Listeners</systemitem> act as inbound routers for
+ the service, in the sense that they direct messages to the
+ <systemitem>action pipeline</systemitem>.
+ </para>
+
+ <para>
+ Here is a very simple configuration. It defines a
+ single service which simply prints the contents of a message
+ to the console:
+ </para>
+
+
- <programlisting language="XML" role="XML"><xi:include href="extras/services_and_messages/code1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <programlisting language="XML"><xi:include href="extras/services_and_messages/code1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
<para>
- As you can see from the above example, a Service has “category”
- and “name” attributes. When JBossESB deploys the Service, it
- uses these attributes to register the Service endpoints
- (listeners) in the Service Registry (see Registry Guide).
- Clients can invoke the Service using the ServiceInvoker as
- follows.
+ A service has <property>category</property> and
+ <property>name</property> attributes. When the service is
+ deployed, it uses these attributes to register its listeners as
+ <firstterm>end-points</firstterm> in the <firstterm>Service
+ Registry</firstterm>. Clients can invoke a service by using the
+ <classname>ServiceInvoker</classname> class.
</para>
+
+ <programlisting language="Java"><xi:include href="extras/services_and_messages/Code_Example2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/Code_Example2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
<para>
- The ServiceInvoker uses the Service Registry (see
- ServicesGuide) to lookup the available Endpoint addresses for
- the “Retail:ShoeStore” Service. It takes care of all the
- transport details of getting the message from the Client to one
- of the available Service Endpoints (JMS, FTP, HTTP etc), hiding
- all of the lower level details from the Client.
+ In this example, the <classname>ServiceInvoker</classname> uses
+ the <systemitem>Services Registry</systemitem>
+
+ <footnote>
+ <para>
+ This information is in the <emphasis>JBoss Enterprise
+ SOA Platform Services Guide</emphasis>, which is provided
+ as the file <filename>Services_Guide.pdf</filename> or
+ can be viewed online at <ulink
+ url="http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/" />.
+ </para>
+ </footnote>
+
+
+ to look up the available end-point addresses for the
+ <code>Retail:ShoeStore</code> service. The registry
+ automatically handles the process of sending the message from
+ the client to one of the available end-points. To the client,
+ the process of transporting the message is completely
+ transparent.
</para>
<para>
- The Endpoint addresses made available to the ServiceInvoker
- will depend on the list of listeners configured on the
- Service such as JMS, FTP or HTTP. No listeners are
- configured on the Service in the above example, but its
- InVM listener has been enabled using invmScope="GLOBAL"1.
- (The InVM transport is a new feature since JBossESB 4.3
- that provides communication between services running on the
- same JVM. The section on "InVM Transport" contains more
- information about this feature.) To add additional
- Endpoints for the Service, we need to explicitly add
- listener configurations on the Service. JBossESB supports
- two forms of listener configuration:
+ The point in time at which end-point addresses are made
+ available to the <classname>ServiceInvoker</classname>
+ depends on the kinds of listeners configured on the
+ service. These could, for example, be of the types JMS, FTP
+ or HTTP. (In the example above, no listeners have been
+ configured, but the service's <firstterm>InVM
+ listener</firstterm> has been enabled by use of
+ <code>invmScope="GLOBAL"</code>.)
</para>
-
+
+ <para>
+ The InVM transport is an Enterprise
+ Service Bus feature that provides communication between
+ services running on the same <firstterm>Java Virtual
+ Machine</firstterm> (JVM.)
+ </para>
+<important>
+ <para>
+ To enable additional endpoints, add
+ listener configurations to a service.
+ </para>
+</important>
+ <para>
+ Two types of listener configuration are supported. These are:
+ </para>
<itemizedlist>
- <listitem>
-
+ <listitem>
<para>
- Gateway Listeners
+ <firstterm>Gateway Listeners</firstterm>
</para>
<para>
- These listener configurations configure a “Gateway”
- Endpoint. These Endpoint types can be used to get
- messages onto an ESB bus. It is responsible for
- “normalizing” the message payload by wrapping it into
- an ESB Message (see below) before shipping it to the
- Service's Action Pipeline.
+ These provide <firstterm>gateway
+ end-points</firstterm>, which provides a point of entry
+ for any messages coming from outside the ESB
+ deployment. They also have the responsibility for
+ "normalizing" the message payload by "wrapping" it in
+ an <firstterm>ESB Message</firstterm> before they send
+ it to the service's <systemitem>action
+ pipeline</systemitem>.
</para>
</listitem>
- <listitem>
+
+ <listitem>
<para>
- ESB-Aware Listeners
+ <firstterm>ESB-Aware Listeners</firstterm>
</para>
<para>
- These listener configurations configure an “ESB Aware”
- Endpoint. These Endpoint types are used to exchange ESB
- Messages (see below) between ESB Aware components e.g.
- exchanging messages on the bus.
- </para>
-
- </listitem>
+ These provide <firstterm>ESB-aware
+ end-points</firstterm>. This is the type of end-point
+ used to exchange ESB messages between ESB-aware
+ components. (ESB-aware listeners can, for example, be
+ used to exchange messages on the Bus.)
+ </para>
+ </listitem>
</itemizedlist>
<para>
- The following is an example of how a JMS Gateway listener can
- be added to the above ShoeStore Service.
+ This example shows how to add a JMS gateway listener to the
+ ShoeStore Service:
</para>
@@ -127,98 +187,104 @@
<para>
- In the above configuration, we added a bus <providers>
- section to the configuration. This is where we configure the
- transport level details for Endpoints. In this case we added a
- <jms-provider> section that defines a single
- <jms-bus> for the Shoe Store JMS Queue. This bus is then
- referenced in the <jms-listener> defined on the Shoe
- Store Service. The Shoe Store is now invocable via two
- Endpoints – the InVM Endpoint and the JMS Gateway Endpoint. The
- ServiceInvoker will always use a Service's local InVM Endpoint,
- if available, in preference to other Endpoint types.
+ One can see above that a bus <providers> section has been
+ added to the configuration. It is here that one configures the
+ transport level details for end-points. In this case,
+ <jms-provider> section has been added, the purpose of
+ which is to define a single <jms-bus> for the Shoe Store
+ JMS queue. This bus is then referenced in the
+ <jms-listener> defined on the Shoe Store Service. The
+ Shoe Store is now "invocable" via the InVM and JMS Gateway
+ end-points. (The <systemitem>ServiceInvoker</systemitem> always
+ prefers to use a service's local InVM end-point if one is
+ available.)
</para>
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-Services_and_Messages-The_Message">
+<section>
<title>
The Message
</title>
<para>
- All interactions between clients and services within JBossESB
- occur through the exchange of Messages. In order to encourage
- loose coupling we recommend a message-exchange pattern based on
- one-way messages, i.e., requests and responses are independent
- messages, correlated where necessary by the infrastructure or
- application. Applications constructed in this way are less
- brittle and can be more tolerant of failures, giving developers
- more flexibility in their deployment and message delivery
- requirements.
+ Every interaction between clients and services occurs through
+ the exchange of messages. Therefore, Red Hat recommends making
+ use of a <firstterm>message-exchange pattern</firstterm> during
+ the development process, the reason being that this will
+ encourage <firstterm>loose coupling</firstterm>. Requests and
+ responses should be independent messages, correlated where
+ necessary by the infrastructure or the application. Programs
+ constructed in this way will be more tolerant of failure and
+ give developers more flexibility to reach their deployment and
+ message delivery requirements.
</para>
<para>
- To ensure loose coupling of services and develop SOA
- applications, it is necessary to:
+ Follow these guidelines to ensure that services are
+ loosely-coupled and robust SOA applications will result:
</para>
<orderedlist>
<listitem>
<para>
- Use one-way message exchanges rather than request-response.
+ Use one-way message exchanges rather than a request-response architecture.
</para>
</listitem>
+
<listitem>
<para>
Keep the contract definition within the exchanged
- messages. Try not to define a service interface that
- exposed back-end implementation choices, because that
- will make changing the implementation more difficult
- later.
+ messages. Avoid defining a service interface that
+ exposes the back-end implementation choices, as this
+ will make it very difficult to change the implementation
+ at a later date.
</para>
</listitem>
- <listitem>
+
+ <listitem>
<para>
Use an extensible message structure for the message
- payload so that changes to it can be versioned over
- time, for backward compatibility.
- </para>
-
+ payload so that changes to it can be versioned over time
+ (for backward-compatibility.)
+ </para>
</listitem>
- <listitem>
+ <listitem>
<para>
- Do not develop fine-grained services: this is not a
- distributed-object paradigm, which can lead to brittle
- applications.
+ Do not develop excessively fine-grained services as
+ these often lead to extremely complex applications that
+ cannot be modified for to meet changing environments.
+ (Remember that SOA's paradigm is one of services,
+ not distributed objects.)
</para>
-
</listitem>
+
</orderedlist>
<para>
- In order to use a one-way message delivery pattern with
- requests and responses, it is obviously necessary to encode
- information about where responses should be sent. That
- information may be present in the message body (the payload)
- and hence dealt with solely by the application, or part of the
- initial request message and typically dealt with by the ESB
- infrastructure.
+ Always encode the information as to where responses should be
+ sent within the message itself when using a one-way message
+ delivery pattern with requests and responses. This is a
+ requirement in these situations. Put this information in either
+ the message body (the payload), (meaning the application will
+ deal with it) or, alternatively, place it in part of the
+ initial request message (meaning the enterprise service bus
+ infrastructure will deal with it).
</para>
<para>
- Therefore, central to the ESB is the notion of a message, whose
- structure is similar to that found in SOAP:
+ Central to the ESB is the notion of a message, the structure of
+ which is similar to that found in SOA:
</para>
@@ -227,13 +293,13 @@
<para>
- Pictorially the basic structure of the Message can be
- represented as shown below. In the rest of this section we
- shall examine each of these components in more detail.
+ Pictorially, the basic structure of the message can be
+ represented in the form shown above. (Read the rest of this
+ section, to learn about each of the components in more detail.)
</para>
<para>
- In UML, the Message structure can be represented as:
+ The message structure can be also be depicted in UML:
</para>
<figure><title>Basic Structure of a Message</title>
@@ -246,9 +312,9 @@
<para>
Each message is an implementation of the
- org.jboss.soa.esb.message.Message interface. Within that package
- are interfaces for the various fields within the Message as
- shown below:
+ <interfacename>org.jboss.soa.esb.message.Message</interfacename>
+ interface. Within that package are subsequent interfaces for
+ the various message fields:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/Code_Example5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -257,29 +323,47 @@
<warning>
<para>
- In JBossESB, Attachments and Properties are not treated
- differently from the Body. The general concepts they
- embody are currently being re-evaluated and may change
- significantly in future releases. As such, we recommend
- developers do not use Attachments.
+ Do not use either <interfacename>Properties</interfacename> or
+ <interfacename>Attachments</interfacename> at this time.
</para>
- </warning>
+
+ <para>
+ The general concepts that they embody are under
+ re-evaluation and may change significantly in future
+ releases.
+ </para>
+
+ <para>
+ Put <interfacename>Property</interfacename> and
+ <interfacename>Attachment</interfacename> data in the
+ message body instead.
+ </para>
+ </warning>
+
+
<para>
- The Header contains routing and addressing information
- for this message. As we saw earlier, JBossESB uses an
- addressing scheme based on the WS-Addressing standard
- from W3C. We shall discuss the
- org.jboss.soa.esb.addressing.Call class in the next
- section.
+ The <firstterm>header</firstterm> contains message
+ routing and addressing information in the form of
+ <firstterm>end-point references</firstterm>. The header
+ also contains information that is used to uniquely
+ identify the message. The <application>JBoss Enterprise
+ Service Bus</application> uses an addressing scheme
+ based on the WS-Addressing standard created by the W3C.
+ (Read the next section to learn about the
+ <classname>org.jboss.soa.esb.addressing.Call</classname>
+ class.)
</para>
-
- <programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_header.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+
+ <programlisting language="Java"><xi:include href="extras/services_and_messages/public_header.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- The Context contains session related information, such as
- transaction or security contexts.
+ The <firstterm>context</firstterm> contains session-related
+ information. This can include transaction and security
+ contexts. <firstterm>User-enhanced contexts</firstterm> are
+ also supported.
</para>
<note>
@@ -290,22 +374,26 @@
</para>
</note>
- <para>
- The Body typically contains the payload of the message. It
- may contain a list of Objects of arbitrary types. How these
- objects are serialized to/from the message body when it is
- transmitted is up to the specific Object type.
+ <para>
+ The <firstterm>body</firstterm> contains the message's
+ "payload". Use the body to send any number of differing
+ data types. (One is not restricted to just sending and
+ receiving single data items.) The way in which these
+ objects are serialized when they go to and from the message
+ body is decided by the specific object-type.
</para>
- <note>
+ <warning>
<para>
- You should be extremely careful about sending
- Serialized objects within the Body: not everything
- that can be Serialized will necessarily be meaningful
- at the receiver, e.g., database connections.
+ Be extremely careful when sending serialized objects
+ to and from the message body. Not necessarily
+ everything that can be serialized will be meaningful
+ at the receiving end, an example being database
+ connections.
</para>
- </note>
+ </warning>
+
<programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_interface.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -319,28 +407,30 @@
<important>
<para>
- The byte array component of the Body was deprecated in
- JBossESB 4.2.1. If you wish to continue using a byte array
- in conjunction with other data stored in the Body, then
- simply use add with a unique name. If your clients and
- services want to agree on a location for a byte array, then
- you can use the one that JBossESB uses:
- ByteBody.BYTES_LOCATION.
+ The message body's <firstterm>byte array</firstterm> component
+ was deprecated in <application>JBoss ESB 4.2.1</application>. To continue using
+ a byte array in conjunction with other data stored in
+ the body, utilise <code>add</code>, giving it a unique
+ name. If one's clients and services want to agree to a
+ location for a byte array, one can use that which the
+ <application>JBoss ESB</application> itself uses:
+ <property>ByteBody.BYTES_LOCATION</property>.
</para>
</important>
- <note>
+ <warning>
<para>
- The default named Object (DEFAULT_LOCATION) should be used with
- care so that multiple services or Actions do not overwrite each
- other's data.
+ Use the default named object
+ (<property>DEFAULT_LOCATION</property>) with care so that
+ multiple services and actions do not overwrite each other's
+ data.
</para>
- </note>
+ </warning>
<para>
- The Fault can be used to convey error information. The
- information is represented within the Body.
+ <firstterm>Fault</firstterm> conveys error
+ information. This information is found in the message body.
</para>
@@ -348,170 +438,211 @@
<programlisting language="Java"><xi:include href="extras/services_and_messages/public_interface_fault.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- <warning>
+ <warning>
<para>
- In JBossESB, Attachments and Properties are not treated
- differently from the Body. The general concepts they
- embody are currently being re-evaluated and may change
- significantly in future releases. As such, we recommend
- developers do not use Attachments or Properties.
+ Do not use either <interfacename>Properties</interfacename> or
+ <interfacename>Attachments</interfacename> at this time.
</para>
- </warning>
+ <para>
+ The general concepts that they embody are under
+ re-evaluation and may change significantly in future
+ releases.
+ </para>
<para>
- A set of message properties, which can be used to
- define additional meta-data for the message.
+ Put <interfacename>Property</interfacename> and
+ <interfacename>Attachment</interfacename> data in the
+ message body instead.
</para>
+ </warning>
+
+ <para>
+ Use message properties to define additional meta-data.
+ Here is a set of such properties:
+ </para>
+
<programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_interface_properties.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<note>
<para>
- JBossESB does not implement Properties as
- java.util.Properties for the same reason Web Services
- stacks do not: it places restrictions on the types of
- clients and services that can used. If you need to
- send java.util.Properties then you can embed them
- within the current abstraction.
- </para>
- </note>
+ The <property>properties</property> which use
+ <interfacename>java.util.Properties</interfacename>
+ have not been implemented within the <application>JBoss
+ Enterprise Service Bus</application>. This is because
+ they would restrict the types of client and service
+ that could be used. Web Services stacks do not
+ implement them either, for exactly the same reasons. To
+ overcome this limitation, embed
+ <interfacename>java.util.Properties</interfacename>
+ within the current abstraction.
+ </para>
+ </note>
<para>
- Messages may contain attachments that do not appear in the main
- payload body. For example, imagines, drawings, binary document
- formats, zip files etc. The Attachment interface supports both
- named and unnamed attachments.
+ One can add attachments that do not appear in the main message
+ body. Such attachments include images, drawings, documents in binary
+ formats and compressed files. The
+ <interfacename>Attachment</interfacename> interface supports
+ both named and unnamed attachments. However, note that, in the
+ current release, only Java
+ serialized objects can be attached. (This restriction will be
+ removed in a subsequent release.)
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_interface_attachment.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
-
+ <note>
<para>
- Attachments may be used for a number of reasons (some of
- which have been outlined above). At a minimum, they may be
- used to more logically structure your message and improve
- performance of large messages, e.g., by streaming the
- attachments between endpoints.
+ There are number of reasons to use attachments. Generally,
+ they are employed to provide the message with a more
+ logical structure. They also provide a way to improve
+ performance with regard to the processing of large messages
+ as they can be streamed between end-points.
</para>
-
+ </note>
<note>
<para>
- At present JBossESB does not support specifying other
- encoding mechanisms for the Message or attachment
- streaming. This will be added in later releases and where
- appropriate will be tied in to the SOAP-with-attachments
- delivery mechanism. Therefore, currently attachments are
- treated in the same way as named objects within the Body.
+ The <application>JBoss Enterprise Service Bus</application>
+ does not allow one to specify other encoding mechanisms for
+ either the message or the streaming of attachments. This
+ feature will be added in a later release and, where
+ appropriate, it will be tied to the
+ <firstterm>SOAP-with-attachments</firstterm> delivery
+ mechanism. Currently, attachments are treated in the same
+ way as named objects within the message body.
</para>
</note>
<para>
- Given that there are attachments, properties, and named
- objects, you may be wondering where should you put your
- payload? The answer is fairly straightforward:
+ Readers sometimes find themselves overwhelmed when they find
+ that they have to choose between attachments, properties and
+ named objects when deciding where to put the payload. However,
+ the choice is really quite straightforward:
</para>
<itemizedlist>
<listitem>
<para>
- As a service developer, you define the contract that
- clients use in order to interact with your service. As
- part of that contract, you will specify both functional
- and non-functional aspects of the service, e.g., that
- it is an airline reservation service (functional) and
- that it is transactional (non-functional). You'll also
- define the operations (messages) that the service can
- understand. As part of the message definition, you
- stipulate the format (e.g., Java Serialized message
- versus XML) and the content (e.g., transaction context,
- seat number, customer name etc.) When defining the
- content, you can specify where in the Message your
- service will expect to find the payload. That can be in
- the form of attachments or specific named objects (even
- the default named object if you so wish). It is
- entirely up to the service developer to determine. The
- only restrictions are that objects and attachments must
- be globally uniquely named, or one service (or Action)
+ The developer defines the contract that the
+ clients will use in order to interact with his or her
+ service. As part of that contract, one will specify both
+ functional and non-functional aspects of the service;
+ for example, that it is an airline reservation service
+ (functional) and that it is transactional in nature
+ (non-functional.)
+ </para>
+
+ <para>
+ The developer will also define the operations (messages)
+ that the service can understand. The format (such as
+ Java Serialized Message or XML) is also defined as part
+ of the message definition (In the example case, they
+ will the transaction context, seat number, customer name
+ and so forth.) When one defines the content, one can
+ specify whereabouts in the message the service will
+ expect to find the payload. (This can be in the form of
+ attachments or specific, named objects or even the
+ default named object, if one so wishes.) It is entirely
+ up to the service developer to determine. The only
+ restriction is that objects and attachments must have a
+ globally-unique name (otherwise one service or action
may inadvertently pick up a partial payload meant for
- another if the same Message Body is forwarded across
- multiple hops.
+ another, if the same message body is being
+ forwarded along on multiple "hops.")
</para>
</listitem>
<listitem>
<para>
- As a service users, you obtain the contract definition
- about the service (e.g., through UDDI or out-of-band
- communication) and this will define where in the
- message the payload must go. Information placed in
- other locations will likely be ignored and result in
- incorrect operation of the service.
+ As a user, one can obtain the service's contract
+ definition (either through
+ either the UDDI registry or via an out-of-band
+ communication) and this will define whereabouts in the
+ message the payload must be placed. Information put in
+ other locations will almost certainly be ignored,
+ resulting in the incorrect operation of the service.
</para>
</listitem>
</itemizedlist>
-
- <note>
- <para>
- There is more information about how to define your
- Message payload in the Message Payload section of this
- document.
- </para>
- </note>
-
+
+
</section>
-<section id="SOA_ESB_Programmers_Guide-JBoss_ESB-Obtaining_and_Setting_Data_on_the_Message_Body">
+<section>
<title>
- Getting and Setting Data on the Message Body
+ Obtaining and Setting Data
</title>
<para>
- By default, all JBossESB 4.2.1GA+ components (Actions, Listeners,
- Gateways, Routers, Notifiers etc) get and set data on the message
- through the messages “Default Payload Location”.
+ Every Enterprise Service Bus component (whether they be
+ <systemitem>actions</systemitem>,
+ <systemitem>listeners</systemitem>,
+ <systemitem>gateways</systemitem>, <systemitem>routers</systemitem>
+ or <systemitem>notifiers</systemitem>) is, by default, configured
+ to "get" and "set" data on the message using that message's
+ <firstterm>Default Payload Location</firstterm>.
</para>
<para>
- All ESB components use the MessagePayloadProxy to manage getting
- and setting of the payload on the message. It handles the default
- case, as outlined above, but also allows this to be overridden in a
- uniform manner across all components. It allows the “get” and “set”
- location for the message payload to be overridden in a uniform way
- using the following component properties:
+ All of these components use the
+ <classname>MessagePayloadProxy</classname> to manage the retrieval
+ of the payload and to set it on the message. This class handles the
+ default case that was outlined above but it also allows these
+ settings to be overridden in a uniform manner across all
+ components. Alternatively, one can override the "get" and "set"
+ location for the message payload in a uniform way by using the
+ following component properties:
</para>
<itemizedlist>
<listitem>
<para>
- <property>get-payload-location</property>: The location
- from which to retrieve the message payload.
+ <property>get-payload-location</property>: this is the
+ location from which to obtain the message payload.
</para>
</listitem>
<listitem>
<para>
- <property>set-payload-location</property>: The location
- on which to set the message payload.
+ <property>set-payload-location</property>: this is the
+ location at which to set the message payload.
</para>
</listitem>
</itemizedlist>
<note>
<para>
- Prior to JBossESB 4.2.1GA there was no default message
- payload exchange pattern in place. JBossESB 4.2.1GA+ can be
- configured to exchange payload data according to the pre
- 4.2.1GA approach (i.e. is backward compatible with) by
- setting the “use.legacy.message.payload.exchange.patterns”
- property to “true” in the “core” section/module of the
- jbossesb-properties.xml file (found in the jbossesb.sar).
- </para>
+ Prior to <application>JBossESB 4.2.1GA</application>, there was no default message
+ payload exchange pattern in place. To make subsequent releases
+ backwards-compatible, undertake these steps:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Go to <filename>jbossesb.sar</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Open the <filename>jbossesb-properties.xml</filename> file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the <property>core</property> section, set the
+ <property>use.legacy.message.payload.exchange.patterns</property>
+ property to <code>true</code>.
+ </para>
+ </listitem>
+ </orderedlist>
</note>
</section>
@@ -519,24 +650,29 @@
- <section id="sect-SOA_ESB_Programmers_Guide-The_Message-Extensions_to_Body">
+ <section>
<title>
- Extensions to Body
+ Extending the Body
</title>
<para>
- Although you can manipulate the contents of a Message Body
- directly in terms of bytes or name/value pairs, it is often
- more natural to use one of the following predefined Message
- structures, which are simply different views onto the data
- contained in the underlying Body.
+ There are a number of interfaces available that simplify
+ this process of manipulating the message body's contents.
+ They do so by providing predefined message structures and
+ methods to use.
</para>
<para>
- As well as the basic Body interface, JBossESB supports the
- following interfaces, which are extensions on the basic
- Body interface:
+ These interfaces are extensions to that of the body and can
+ be used in conjunction with existing clients and services.
+ Message consumers do not need to be aware of these new
+ types because the message's underlying data structure
+ remains unchanged. However, it is important to realise that
+ these extension classes do not store their data in the
+ default location; hence, one should retrieve such data by
+ using the appropriate methods that correspond to each
+ class.
</para>
<variablelist><title>Extensions Types</title>
@@ -546,9 +682,10 @@
<listitem>
<para>
- the content of the Body is an arbitrary String, and
- can be manipulated via the getText and setText
- methods.
+ Use this when the content of the body is an arbitrary string.
+ Manipulate it by using the
+ <methodname>getText</methodname> and
+ <methodname>setText</methodname> methods.
</para>
</listitem>
</varlistentry>
@@ -557,36 +694,41 @@
<varlistentry><term><filename><classname>org.jboss.soa.esb.message.body.content.ObjectBody</classname></filename></term>
<listitem>
<para>
- the content of the Body is a Serialized Object, and
- can be manipulated via the getObject and setObject
- methods.
+ Use this when the body's content is a serialized
+ object. Manipulate it using the
+ <methodname>getObject</methodname> and
+ <methodname>setObject</methodname> methods.
</para>
</listitem>
</varlistentry>
<varlistentry><term><filename><classname>org.jboss.soa.esb.message.body.content.MapBody</classname></filename></term>
<listitem>
<para>
- the content of the Body is a Map<String,
- Serialized), and can be manipulated via the
- setMap and other methods.
+ Use this when the body's content is a
+ map(string, serialized). Manipulate it using
+ the <methodname>setMap</methodname> and other
+ methods.
</para>
</listitem>
</varlistentry>
<varlistentry><term><filename><classname>org.jboss.soa.esb.message.body.content.BytesBody</classname></filename></term>
<listitem>
<para>
- the content of the Body is a byte stream that
- contains arbitrary Java data-types. It can be
- manipulated using the various setter and getter
- methods for the data-types. Once created, the
- BytesMessage should be placed into either a
- read-only or write-only mode, depending upon how it
- needs to be manipulated. It is possible to change
- between these modes (using readMode and writeMode),
- but each time the mode is changed the buffer
- pointer will be reset. In order to ensure that all
- of the updates have been pushed into the Body, it
- is necessary to call flush when finished.
+ Use this when the body's content is a byte stream
+ that contains an arbitrary Java data-type.
+ Manipulate it using the methods for the data-type.
+ Once created, the
+ <classname>BytesMessage</classname> should be
+ placed in either read-only or write-only mode,
+ depending on how one intends to manipulate it. Use
+ the <methodname>readMode()</methodname> and
+ <methodname>writeMode()</methodname> methods to
+ change between these modes but be aware that each
+ time the mode is changed, the buffer pointer will
+ be reset. Hence, one must also call the
+ <methodname>flush()</methodname> method to ensure
+ that all of the updates have been applied correctly
+ to the body.
</para>
</listitem>
</varlistentry>
@@ -596,31 +738,37 @@
<para>
- You can create Messages that have Body implementations
- based on one of these specific interfaces through the
- XMLMessageFactory or SerializedMessageFactory classes. The
- need for two different factories is explained in the
- section on Message Formats, which is described later in the
- document.
+ To create messages that have body implementations based on
+ one of these specific interfaces, use either the
+ <classname>XMLMessageFactory</classname> class or the
+ <classname>SerializedMessageFactory</classname> class. (The
+ <classname>XMLMessageFactory</classname> and
+ <classname>SerializedMessageFactory</classname> classes are
+ more convenient to use when working with messages than
+ <classname>MessageFactory</classname> and its associates.)
</para>
<para>
- For each of the various Body types, you will find an
- associated create method (e.g., createTextBody) that allows
- you to create and initialize a Message of the specific
- type. Once created, the Message can be manipulated directly
- through the raw Body or via the specific interface. If the
- Message is transmitted to a recipient, then the Body
- structure will be maintained, e.g., it can be manipulated
- as a TextBody.
+ The observant reader will notice a
+ <methodname>create</methodname> method associated with each
+ of the various body types. An example is
+ <methodname>createTextBody</methodname>. Use this to create
+ and initialize a message of that specific type. Once
+ created, manipulate the message directly by editing the raw
+ body or by using its interface's methods. The body's
+ structure is maintained even after transmission so that it
+ can be manipulated by the message recipient using the
+ methods of the interface that created it.
</para>
<para>
- The XMLMessageFactory and SerializedMessageFactory are more
- convenient ways in which to work with Messages than the
- MessageFactory and associated classes, which are described
- in the following sections.
+ The <classname>XMLMessageFactory</classname> and
+ <classname>SerializedMessageFactory</classname> represent
+ more convenient ways with which to work with messages than
+ that offered by the <classname>MessageFactory</classname>
+ and its associated classes. However, it is the latter which
+ will now be described.
</para>
<note>
@@ -641,13 +789,14 @@
<section>
- <title id="SOA_ESB_Programmers_Guide-JBoss_ESB-The_Message_Header">
+ <title>
The Message Header
</title>
<para>
- As we saw above, the Header of a Message contains a
- reference to the org.jboss.soa.esb.addressing.Call
+ Message header's contents are contained in an instance
+ of the
+ <classname>org.jboss.soa.esb.addressing.Call</classname>
class:
</para>
@@ -656,11 +805,12 @@
<para>
- The properties below support both one way and request
- reply interaction patterns:
+ <classname>org.jboss.soa.esb.addressing.Call</classname>
+ supports both one-way and request-reply interaction
+ patterns.
</para>
-
- <table id="SOA_ESB_Programmers_Guide-Services_messages-call">
+
+ <table>
<title><classname>org.jboss.soa.esb.addressing.Call</classname> Properties</title>
<tgroup align="left" cols="4" colsep="1" rowsep="1">
<colspec colname="c1" colwidth="1*"/>
@@ -669,7 +819,7 @@
<colspec colname="c4" colwidth="5*"/>
<thead>
<row>
- <entry>Property</entry><entry>Type</entry><entry>Required</entry><entry>Description</entry>
+ <entry>Property</entry><entry>Type</entry><entry>Required?</entry><entry>Description</entry>
</row>
</thead>
<tbody>
@@ -677,66 +827,35 @@
<entry>To</entry>
<entry>EPR</entry>
<entry>Yes</entry>
- <entry>The address of the intended receiver of this message.</entry>
+ <entry>The message recipient's address.</entry>
</row>
<row>
<entry>From</entry>
<entry>EPR</entry>
<entry>No</entry>
- <entry>Reference of the endpoint where the message originated from.</entry>
+ <entry>The end-point at which the message originated.</entry>
</row>
<row>
<entry>ReplyTo</entry>
<entry>EPR</entry>
<entry>No</entry>
- <entry>An endpoint reference that identifies
- the intended receiver for replies to
- this message. If a reply is expected, a
- message must contain a [ReplyTo]. The
- sender must use the contents of the
- [ReplyTo] to formulate the reply
- message. If the [ReplyTo] is absent, the
- contents of the [From] may be used to
- formulate a message to the source. This
- property may be absent if the message
- has no meaningful reply. If this
- property is present, the [MessageID]
- property is required.
- </entry>
+ <entry>An end-point reference that identifies
+ the recipient of replies to this
+ message.</entry>
</row>
<row>
<entry>FaultTo</entry>
<entry>EPR</entry>
<entry>No</entry>
- <entry>An endpoint reference that identifies
- the intended receiver for faults related
- to this message. When formulating a
- fault message the sender must use the
- contents of the [FaultTo] of the message
- being replied to to formulate the fault
- message. If the [FaultTo] is absent, the
- sender may use the contents of the
- [ReplyTo] to formulate the fault
- message. If both the [FaultTo] and
- [ReplyTo] are absent, the sender may use
- the contents of the [From] to formulate
- the fault message. This property may be
- absent if the sender cannot receive
- fault messages (e.g., is a one-way
- application message). If this property
- is present, the [MessageID] property is
- required.
- </entry>
+ <entry>An end-point reference that identifies
+ the recipient for fault alerts.</entry>
</row>
<row>
<entry>Action</entry>
<entry>URI</entry>
<entry>Yes</entry>
- <entry>
- An identifier that uniquely (and opaquely)
- identifies the semantics implied by this
- message.
- </entry>
+ <entry>This uniquely and opaquely identifies
+ the semantics implied by the message.</entry>
</row>
<row>
<entry>MessageID</entry>
@@ -759,35 +878,35 @@
</tbody>
</tgroup>
</table>
-
+
<para>
- The relationship between the Header and the various
- EPRs can be illustrated as follows in UML:
+ The relationship between the header and the various
+ end-point references can be illustrated thus:
</para>
- <figure><title>Relationship Between the Header and EPR in UML</title>
+ <figure><title>Relationship Between the Header and the End-Point Reference in UML</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/services_and_messages/chapter3_relation_header_and_EPR.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/services_and_messages/chapter3_relation_header_and_EPR.png" />
</imageobject>
</mediaobject>
</figure>
<para>
- When working with Messages, you should consider the role of the
- header when developing and using your clients and services. For
- example, if you require a synchronous interaction pattern based
- on request/response, you will be expected to set the ReplyTo
- field, or a default EPR will be used; even with
- request/response, the response need not go back to the original
- sender, if you so choose. Likewise, when sending one-way
- messages (no response), you should not set the ReplyTo field
- because it will be ignored.
+ Always consider the role of the header when developing and
+ using services. For example, if one needs a
+ <firstterm>synchronous interaction pattern</firstterm> based
+ upon request and response, be sure to set the
+ <property>ReplyTo</property> field or a default end-point
+ reference will be used. Even with "request/response," the
+ response need not go back to the original sender. Likewise,
+ when sending one-way (no response) messages, do not set the
+ <property>ReplyTo</property> field because it will be ignored.
</para>
<note>
<para>
- Please see details on the LogicalEPR.
+ Read the section on the LogicalEPR for more details.
</para>
</note>
@@ -801,49 +920,50 @@
<note>
<para>
- The Message Header is formed in conjunction with the
- Message by the creator and is immutable once
- transmitted between endpoints. Although the interfaces
- allow the recipient to modify the individual values,
- JBossESB will ignore such modifications. In future
- releases it is likely that such modifications will be
- disallowed by the API as well for improved clarity.
- These rules are laid down in the WS-Addressing
- standards.
+ The message header is formed in conjunction with the
+ message. It is immutable once it has been transmitted
+ between end-points. Although the interfaces allow the
+ recipient to modify the individual values, the
+ <application>JBoss Enterprise Service Bus</application>
+ will ignore such modifications. (In future releases it
+ is likely that such modifications will also be
+ disallowed by the application programming interface, in
+ order to improve clarity.) These rules can be found in
+ the <literal>WS-Addressing</literal> standards.
</para>
</note>
</section>
- <section id="SOA_ESB_Programmers_Guide-JBoss_ESB-The_LogicalEPR">
+ <section>
<title>
LogicalEPR
</title>
<para>
- A LogicalEPR is an EPR that simply specifies the name
- and category of an ESB Service/Endpoint. It contains no
- physical addressing information.
+ Make sure that the <property>ReplyTo</property> or
+ <property>FaultTo</property> end-point references
+ always use the <firstterm>LogicalEPR</firstterm>, as
+ opposed to one of the "physical" end-point references
+ (such as JMS-EPR.) A
+ <systemitem>LogicalEPR</systemitem> is an end-point
+ reference that simply specifies the name and category
+ of an ESB service or end-point. It contains no physical
+ addressing information.
</para>
<para>
- Clients setting the ReplyTo or FaultTo EPRs should always
- use the LogicalEPR, as opposed to one of the Physical EPRs
- (JMSEpr etc). The LogicalEPR is the preferred option
- because it makes no assumptions about the capabilities of
- the user of the EPR (typically the ESB itself, but not
- necessarily), or when the EPR will be used i.e. a physical
- EPR may no longer be valid by the time it gets used. By
- it's non-Physical nature, a LogicalEPR is also a lot easier
- to “handle” from a user perspective. The user of the
- LogicalEPR can use the Service name and category details
- supplied in the EPR to lookup the physical endpoint details
- for that Service/Endpoint at the point in time when they
- intend making the invocation i.e. they will get relevant
- addressing information. The user will also be able to
- select an endpoint type that suits it i.e. if it's easier
- for the user to make the invocation using a file based
- transport (Vs e.g. JMS), then they can select that type of
- transport.
+ It is best to use the <systemitem>LogicalEPR</systemitem>
+ because it makes no assumptions about the end-point
+ reference user (which is usually, but not necessarily
+ always, the Enterprise Service Bus itself.) The
+ <systemitem>LogicalEPR</systemitem>'s client can use the
+ service name and category details that have been supplied
+ unto it to "look up" the physical end-point for that
+ service. The client will do so at the point in time at
+ which it intends to <firstterm>invoke</firstterm> the
+ service (that is, receive the relevant addressing
+ information.) The client will also be able to select a
+ physical end-point type to suit.
</para>
</section>
<section>
@@ -852,25 +972,15 @@
</title>
<para>
- When sending Messages, it is possible that errors will
- occur, either during the transmission or
- reception/processing of the Message. JBossESB will
- route any faults to the EPR mentioned in the FaultTo
- field of the incoming message. If this is not set, then
- it will use the ReplyTo field or, failing that, the
- From field. If no valid EPR is obtained as a result of
- checking all of these fields, then the error will be
- output to the console. If you do not wish to be
- informed about such faults, such as when sending a
- one-way message, you may wish to use the DeadLetter
- Queue Service EPR as your FaultTo. In this way, any
- faults that do occur will be saved for later
- processing.
+ The <firstterm>FaultTo</firstterm> is an end-point
+ reference that identifies the recipient to whom
+ faults related to the message are to be sent.
</para>
<note>
<para>
- Please see details on the LogicalEPR.
+ Please see the details about the
+ <systemitem>LogicalEPR</systemitem>.
</para>
</note>
</section>
@@ -881,23 +991,29 @@
</title>
<para>
- Because the recommended interaction pattern within
- JBossESB is based on one-way message exchange,
- responses to messages are not necessarily automatic: it
- is application dependent as to whether or not a sender
- expects a response. As such, a reply address (EPR) is
- an optional part of the header routing information and
- applications should be setting this value if necessary.
- However, in the case where a response is required and
- the reply EPR (ReplyTo EPR) has not been set, JBossESB
- supports default values for each type of transport.
- Some of these ReplyTo defaults require system
- administrators to configure JBossESB correctly.
+ Because the <application>JBoss Enterprise Service
+ Bus</application>'s recommended interaction pattern is
+ based on a one-way message exchange, messages may not
+ receive respones automatically: it is
+ application-dependent as to whether or not a sender
+ expects a response. As such, a reply address (end-point
+ reference) is an optional part of the header routing
+ information and applications should set this value if
+ necessary. However, in the case whereby a response is
+ required and the reply end-point reference
+ (<firstterm>ReplyTo</firstterm> EPR) has not been set,
+ the <application>JBoss Enterprise Service
+ Bus</application> can provide default values for each
+ type of transport. (Note that to use some of these
+ <systemitem>ReplyTo</systemitem> defaults requires
+ system administrators to configure the
+ <application>JBoss Enterprise Service Bus</application>
+ specifically.)
</para>
- <table id="SOA_ESB_Programmers_Guide-Services_messages-default_replyto">
- <title>Default <property>ReplyTo</property> by transport</title>
+ <table>
+ <title>Default <systemitem>ReplyTo</systemitem> by Transport</title>
<tgroup align="left" cols="2" colsep="1" rowsep="1">
<colspec colname="c1" colwidth="1*"/>
<colspec colname="c2" colwidth="6*"/>
@@ -909,109 +1025,114 @@
<tbody>
<row>
<entry>JMS</entry>
- <entry>a queue with a name based on the one used to deliver the original request: <request queue name>_reply.</entry>
+ <entry>A queue with the same name as that used to deliver the
+ original request. It has the suffix of <property>_reply</property>.</entry>
</row>
<row>
<entry>JDBC</entry>
- <entry>A table in the same database with a name
- based on the one used to deliver the
- original request: <request table
- name>_reply_table. The new table
- needs the same columns as the request
- table.
- </entry>
+ <entry>A table in the same database with the same name as that used
+ to deliver the original request. It has the suffix of
+ <property>_reply_table</property>. (The reply table needs the same
+ column definitions as the request table.)</entry>
</row>
<row>
<entry>files</entry>
- <entry>For both local and remote files, no
- administration changes are required:
- responses will be written into the same
- directory as the request but with a
- unique suffix to ensure that only the
- original sender will pick up the response.</entry>
+ <entry>No administration changes are required
+ for either local or remote files. Responses are
+ saved in the same directory as the request
+ but with a unique suffix to ensure that only
+ the original sender will pick up the
+ response.</entry>
</row>
</tbody>
</tgroup>
</table>
-
- <note>
- <para>
- Please see details on the LogicalEPR.
- </para>
- </note>
-
+
</section>
- <section id="SOA_ESB_Programmers_Guide-JBoss_ESB-The_Message_Payload">
+ <section>
<title>
- The Message payload
+ The Message Payload
</title>
<para>
- From an application/service perspective the message payload
- is a combination of the Body and Attachments. In this
- section we shall give an overview of best practices when
- constructing and using the message payload.
+ The message payload is defined as a combination of the
+ body, the attachments and the properties.
</para>
- <warning>
+ <warning>
<para>
- In JBossESB, Attachments and Properties are not treated
- differently from the Body. The general concepts they
- embody are currently being re-evaluated and may change
- significantly in future releases. As such we shall not
- be considering the Attachments as part of the payload in
- the rest of this discussion.
+ Do not use either <interfacename>Properties</interfacename> or
+ <interfacename>Attachments</interfacename> at this time.
+ </para>
+
+ <para>
+ The general concepts that they embody are under
+ re-evaluation and may change significantly in future
+ releases.
</para>
- </warning>
-
+
+ <para>
+ Put <interfacename>Property</interfacename> and
+ <interfacename>Attachment</interfacename> data in the
+ message body instead.
+ </para>
+ </warning>
+
+
<para>
- The UML representation of the payload is shown below:
+ Here is a UML representation of the payload:
</para>
-
+ <figure><title>UML Representation of the Message Payload</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/services_and_messages/chapter3_uml_representation_payload.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+
<para>
- More complex content may be added through the add method, which
- supports named Objects. Using <name, Object> pairs allows
- for a finer granularity of data access. The type of Objects
- that can be added to the Body can be arbitrary: they do not
- need to be Java Serializable. However, in the case where
- non-Serializable Objects are added, it is necessary to provide
- JBossESB with the ability to marshal/unmarshal the Message when
- it flows across the network. See the section of Message Formats
- for more details.
+ To apply more complex content, use the
+ <methodname>add</methodname> method, which supports named
+ objects. To achieve a finer "granularity" of data access, use
+ named object-pairs. Objects of any type can be added to the
+ message body. (To add objects that are not Java-serializable,
+ one must provide the <application>JBoss Enterprise Service
+ Bus</application> with the ability to
+ <firstterm>marshal</firstterm> and
+ <firstterm>un-marshal</firstterm> the message. See the section
+ on "Message Formats" for more details on this process.)
</para>
-
+ <note>
<para>
- If no name is supplied to set or get, then the default name
- defined by DEFAULT_LOCATION will be used.
+ If no name has been supplied for "setting" or "getting," then
+ that which was defined against the
+ <property>DEFAULT_LOCATION</property> setting will be utilised.
</para>
+ </note>
-
<note>
<para>
- Be careful when using Serialized Java objects in messages
- because it constrains the service implementations.
+ Be careful when using serialized Java objects in messages,
+ because they constrain the service implementation.
</para>
</note>
<para>
- It is easiest to work with the Message Body through the
- named Object approach. One can add, remove and inspect
- individual data items within the Message payload without
- having to decode the entire Body. Furthermore, one can
- combine named Objects with the byte array within the payload.
+ It is easiest to work with the message body through the
+ "named-object" approach. This way, one can add, remove and
+ inspect individual data items without having to decode the
+ entire body. Furthermore, one can combine named objects
+ with the payload's byte array.
</para>
<note>
<para>
- In general you will find it easier to work with the Message
- Body through the named Object approach. You can add, remove
- and inspect individual data items within the Message payload
- without having to decode the entire Body. Furthermore, you
- can combine named Objects within the payload with the byte
- array.
+ Currently, only Java-serialized objects can be attached.
+ This restriction will be removed in a subsequent release.
</para>
</note>
@@ -1026,115 +1147,123 @@
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-The_Message-The_MessageFactory">
+<section>
<title>
The MessageFactory
</title>
<para>
- Internally to an ESB component, the message is a collection
- of Java objects. However, messages need to be serialized
- for a number of reasons, e.g., transmitted between address
- spaces (processes) or saved to a persistent datastore for
- auditing or debugging purposes. The external representation
- of a message may be influenced by the environment in which
- the ESB is deployed. Therefore, JBossESB does not impose a
- specific normalized message format, but supports a range of
- them.
+ Although each Enterprise Service Bus component treats every
+ message as a collection of Java objects, it is often
+ necessary to serialize these messages. Situations in which
+ one might have to do so include when the data is to be
+ stored, when the message is to be sent between different
+ ESB processes and when one is debugging.
</para>
<para>
- All implementations of the
- org.jboss.soa.esb.message.Message interface are obtained
- from the org.jboss.soa.esb.message.format.MessageFactory
+ The <application>JBoss Enterprise Service Bus</application>
+ does not impose a single, specific "normalized" format for
+ message serialization because requirements will be
+ influenced by the unique characteristics of each ESB
+ deployment. Every implementation of the
+ <interfacename>org.jboss.soa.esb.message.Message</interfacename>
+ interface can obtained from the
+ <classname>org.jboss.soa.esb.message.format.MessageFactory</classname>
class:
</para>
- <example><title><classname>org.jboss.soa.esb.message.format.MessageFactory</classname></title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_abstract_class_messagefactory.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
- </example>
+ <programlisting language="Java"><xi:include href="extras/services_and_messages/public_abstract_class_messagefactory.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+
<para>
- Message serialization implementations are uniquely
- identified by a URI. The type of implementation required
- may be specified when requesting a new instance, or the
- configured default implementation may be used. Currently
- JBossESB provides two implementations, which are defined in
- the org.jboss.soa.esb.message.format.MessageType class:
+ Uniform resource indicators uniquely identify message
+ serialization implementations. Either specify the
+ implementation when creating a new instance or use the
+ pre-configured default.
</para>
<itemizedlist>
<listitem>
<para>
- MessageType.JBOSS_XML: this uses an XML representation of
- the Message on the wire. The schema for the message is
- defined in the message.xsd within the schemas directory. The
- URI is urn:jboss/esb/message/type/JBOSS_XML.
+ <property>MessageType.JBOSS_XML</property>: this uses an XML
+ representation of the message on the
+ <firstterm>wire</firstterm>. The message's schema is defined
+ in the <filename>message.xsd</filename> file, (found within
+ the <filename>schemas</filename> directory.) Its URI is
+ urn:jboss/esb/message/type/JBOSS_XML.
</para>
</listitem>
<listitem>
<para>
- MessageType.JAVA_SERIALIZED: this implementation requires
- that all components of a Message are Serializable. It
- obviously requires that recipients of this type of Message
- have sufficient information (the Java classes) to be able to
- de-serialize the Message. The URI is urn:jboss/esb/message/type/JAVA_SERIALIZED.
+ <property>MessageType.JAVA_SERIALIZED</property>: this
+ implementation requires that every components of a message
+ is serialisable. It obviously also requires that this
+ message type's recipients have sufficient information (the
+ Java classes) to be able to de-serialize them. Its URI is
+ urn:jboss/esb/message/type/JAVA_SERIALIZED.
</para>
</listitem>
</itemizedlist>
<important>
<para>
- You should be wary about using the JAVA_SERIALIZED
- version of the Message format because it more
- easily ties your applications to specific service
- implementations, i.e., it breaks loose coupling.
+ Be wary about using the
+ <property>JBOSS_SERIALIZED</property> version of
+ the message format because it can easily tie one's
+ applications to specific service implementations.
</para>
</important>
<para>
- Other Message implementations may be provided at runtime
- through the org.jboss.soa.esb.message.format.MessagePlugin:
+ To provide other message implementations at run-time, use
+ the <classname>org.jboss.soa.esb.message.format.MessagePlugin</classname>:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_interface_message_plugin.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
<para>
- Each plug-in must uniquely identify the type of Message
- implementation it provides (via getMessage), using the
- getType method. Plug-in implementations must be identified
- to the system via the jbossesb-properties.xml file using
- property names with the
- org.jboss.soa.esb.message.format.plugin extension.
+ Each plug-in must use the
+ <methodname>getType()</methodname> method to uniquely
+ identify the type of message implementation it provides.
+ Plug-in implementations must be identified to the system by
+ being recorded in the
+ <filename>jbossesb-properties.xml</filename> file. To do
+ so, they use property names with the
+ <classname>org.jboss.soa.esb.message.format.plugin</classname>
+ extension.
</para>
<note>
<para>
- The default Message type is JBOSS_XML. However, this
- can be changed by setting the property
- org.jboss.soa.esb.message.default.uri to the desired
- URI.
+ The default Message type is <classname>JBOSS_XML
+ </classname>. To change it, set the
+ <property>org.jboss.soa.esb.message.default.uri
+ </property> property to the name of the desired URI.
</para>
</note>
</section>
-<section id="sect-SOA_ESB_Programmers_Guide-Message_Formats">
+<section>
<title>
Message Formats
</title>
<para>
- As mentioned previously, JBossESB supports two
- serialized message formats: MessageType.JBOSS_XML and
- MessageType.JAVA_SERIALIZED. In the following sections
- we shall look at each of these formats in more detail.
+ As mentioned previously, the <application>JBoss
+ Enterprise Service Bus</application> supports two
+ serialized message formats:
+ <literal>MessageType.JBOSS_XML</literal> and
+ <literal>MessageType.JAVA_SERIALIZED</literal>. Read
+ this section to learn more about each of these.
</para>
@@ -1143,24 +1272,26 @@
</para>
<para>
- This implementation requires that all contents are Java
- Serializable. Any attempt to add a non-Serializable
- object to the Message will result in a
- IllegalParameterException being thrown.
+ This implementation requires that all of a message's
+ components be serializable. It also requires that the
+ recipients of this type of message be able to
+ de-serialise it. In other words, this implementation
+ must be able to <firstterm>instantiate</firstterm> the
+ Java classes contained within the message.
</para>
<para>
- It also requires that all contents be
- Java-serializable. Any attempt to add a
- non-serializable object to the Message will result
- in an
+ Furthermore, it requires that all of the contents
+ be <firstterm>Java-serializable</firstterm>. Any
+ attempt to add a non-serializable object to the
+ message will result in an
<exceptionname>IllegalParameterException</exceptionname>
being thrown.
</para>
<para>
- The <abbrev>URI</abbrev> for it is
- <filename>urn:jboss/esb/message/type/JAVA_SERIALIZED</filename>.
+ The URI for this implementation is
+ urn:jboss/esb/message/type/JAVA_SERIALIZED.
</para>
<para>
@@ -1169,16 +1300,19 @@
<para>
This implementation uses an XML representation
- of the Message on the wire. The schema for the
- message is defined in the message.xsd within
- the schemas directory. Arbitrary objects may be
- added to the Message, i.e., they do not have to
- be Serializable. Therefore, it may be necessary
- to provide a mechanism to marshal/unmarshal
- such objects to/from XML when the Message needs
- to be serialized. This support can be provided
- through the
- org.jboss.soa.esb.message.format.xml.marshal.MarshalUnmarshalPlugin:
+ of the message on the
+ <systemitem>wire</systemitem>. The schema for
+ the message is defined in the
+ <filename>message.xsd</filename> file (found
+ within the <filename>schemas</filename>
+ directory.) Arbitrary objects may be added to
+ the message; in other words, they do not have
+ to be serializable. Therefore, it may be
+ necessary to provide a mechanism to marshal and
+ un-marshal such objects to and from XML when
+ the message needs to be serialized. Provide
+ this support through the
+ <classname>org.jboss.soa.esb.message.format.xml.marshal.MarshalUnmarshalPlugin</classname>:
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/services_and_messages/public_interface_marshall_unmarshall.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -1191,22 +1325,23 @@
</note>
<para>
- Plug-ins can be registered with the system through the
- jbossesb-properties.xml configuration file. They should
- have attribute names that start with the
- MARSHAL_UNMARSHAL_PLUGIN. When packing objects in XML,
- JBossESB runs through the list of registered plug-ins
- until it finds one that can deal with the object type
- (or faults). When packing, the name (type) of the
- plug-in that packed the object is also attached to
- facilitate unpacking at the Message receiver.
+ Marshaling plug-ins must be registered with the system
+ through the
+ <filename>jbossesb-properties.xml</filename>
+ configuration file. Their attribute names must start
+ with the <property>MARSHAL_UNMARSHAL_PLUGIN</property>
+ prefix.
</para>
<para>
- Now that we have looked at the concepts behind services
- and Messages, we shall examine how to construct
- services using the framework provided by Rosetta in the
- following Chapter.
+ When it is packing objects in XML, The
+ <application>JBoss Enterprise Service Bus</application>
+ checks the list of registered plug-ins until it finds
+ one that can deal with the object type in question. (If
+ it does not find a suitable plug-in, it returns a fault
+ message.) The name of the plug-in that packed the
+ object is also attached to the message. This
+ information helps the recipient to unpack it.
</para>
</section>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/The_Enterprise_Service_Bus.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/The_Enterprise_Service_Bus.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/The_Enterprise_Service_Bus.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -9,18 +9,33 @@
The Enterprise Service Bus
</title>
- <section>
- <title>
- What is an ESB?
- </title>
-
- <para>
- The ESB is seen as the next generation of EAI – better and without
- the vendor-lockin characteristics of old. As such, many of the
- capabilities of a good ESB mirror those of existing EAI offerings.
- Traditional EAI stacks consist of:
- </para>
-
+<section>
+ <title>
+ What is an Enterprise Service Bus?
+ </title>
+
+ <para>
+ <firstterm>Enterprise Service Buses</firstterm>
+ are the next
+ generation of <firstterm>Enterprise Application
+ Integration</firstterm> (EAI) technology. A
+ good Enterprise Service Bus will offer capabilities that mirror
+ those of existing EAI solutions without locking one
+ into the offerings of a single vendor.
+ </para>
+
+ <para>
+ This book has been written for software developers wishing to
+ program for the <application>JBoss Enterprise Service
+ Bus</application> in large firms, such as financial
+ institutions, insurance businesses, utilities and the telecommunications
+ industry. This text provides a detailed reference to building
+ applications and also explains the theory behind the key
+ components to give the reader a conceptual understanding of the
+ <application>JBoss Enterprise Service Bus</application>.
+ </para>
+
+
<para>
A traditional EAI stack consists of the following:
</para>
@@ -85,7 +100,7 @@
<figure><title>Simple File Movement</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/enterprise_service_bus/esb1.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/enterprise_service_bus/esb1.png" />
</imageobject>
</mediaobject>
</figure>
@@ -103,7 +118,7 @@
<figure><title>Simple File Movement with Transformation</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/enterprise_service_bus/esb2.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/enterprise_service_bus/esb2.png" />
</imageobject>
</mediaobject>
</figure>
@@ -116,7 +131,7 @@
<figure><title>Simple File Movement with Transformation and Queuing</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/enterprise_service_bus/esb3.png" width="100%" scalefit="1" contentdepth="100%" />
+ <imagedata fileref="images/enterprise_service_bus/esb3.png" />
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Web_Services_Support.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Web_Services_Support.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Web_Services_Support.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -18,52 +18,64 @@
</title>
<para>
- JBossESB supports both JBossWS-Native and JBossWS-CXF stacks.
- JBossESB has a number of Webservice based components for
- exposing and invoking Webservice endpoints (i.e. SOAP onto the
- bus and SOAP off the bus):
+ The JBoss Enterprise Service Bus has several components that are
+ used for exposing and invoking Webservice end points.
</para>
<orderedlist>
<listitem>
<para>
- SOAPProcessor: The SOAPProcessor action allows you
- to expose JBossWS 2.x and higher Webservice
- Endpoints through endpoints (listeners) running on
- the ESB (“SOAP onto the bus”). This allows you to
- use JBossESB to expose Webservice Endpoints
- (wrapper Webservices) for services that don't
- expose a Webservice Interface. JBossWS Webservice
- Endpoints exposed via this JBossESB action are “ESB
- Message Aware” and can be used to invoke Webservice
- Endpoints over any transport channel supported by
- the ESB.
- </para>
- <caution>
- <para>
- JBossWS-CXF Endpoints are not "ESB Message Aware”.
- </para>
- </caution>
- </listitem>
+ The <classname>SOAPProcessor</classname> action
+ lets one expose <application>JBossWS
+ 2.x</application> and higher <firstterm>Webservice
+ Endpoints</firstterm> through listeners running on
+ the <abbrev>ESB</abbrev>. This can be achieved even
+ if the end points do not provide web-service
+ interfaces of their own. The
+ <abbrev>JBossWS</abbrev> Webservice Endpoints
+ exposed by the <classname>SOAPProcessor</classname>
+ action are <emphasis>ESB Message-Aware</emphasis>.
+ Therefore, they can be used to invoke other
+ Webservice Endpoints over any transport channel that
+ is supported by the Enterprise Service Bus.
+ </para>
+
+
+ <para>
+ Note that the <classname>SOAPProcessor</classname> action is
+ sometimes also referred to as <firstterm>SOAP on the
+ bus</firstterm>.
+ </para>
+ </listitem>
<listitem>
<para>
- SOAPClient: The SOAPClient action allows you to
- make invocations on Webservice endpoints (“SOAP off
- the bus”).
- </para>
+ The <classname>SOAPClient</classname> action allows
+ one to make invocations on Webservice Endpoints.
+ </para>
+
+ <para>
+ The <classname>SOAPClient</classname> action is also
+ referred to as <firstterm>SOAP off the
+ bus</firstterm> by some.
+ </para>
+
</listitem>
</orderedlist>
- <note>
- <para>
- For more details on these components and how to configure
- and use them, see the ServicesGuide.
+ <note>
+ <para>
+ In order to learn more about these components, one should
+ refer to the <emphasis>Services Guide</emphasis>. It
+ explains, in detail, how to configure them.
</para>
<para>
- You can also find more information within the wiki
- pages shipped with the JBossESB documentation.
+ More information about this topic can also be found
+ within the "Wiki" pages that are been shipped with the
+ JBoss <abbrev>ESB</abbrev> documentation. At the moment
+ JBossESB supports both JBossWS-Native and JbossWS-CXF
+ stacks.
</para>
</note>
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Writing_JAXB_Annotation_Introduction_Configurations.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Writing_JAXB_Annotation_Introduction_Configurations.xml 2010-08-15 23:23:43 UTC (rev 34731)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/Writing_JAXB_Annotation_Introduction_Configurations.xml 2010-08-15 23:29:06 UTC (rev 34732)
@@ -11,9 +11,10 @@
</title>
<para>
- JAXB Annotation Introduction configurations are very easy to write.
- If you're already familiar with the JAXB Annotations, you'll have
- no problem writing a JAXB Annotation Introduction configuration.
+ The configurations for the <abbrev>JAXB</abbrev> (<firstterm>Java Architecture for XML
+ Binding</firstterm>) Annotation Introduction are very easy to write. If the reader is
+ already familiar with the <abbrev>JAXB</abbrev> Annotations, there should be no difficulty
+ in writing a <firstterm>JAXB Annotation Introduction</firstterm> configuration.
</para>
<para>
@@ -25,7 +26,7 @@
<para>
- Only 3 annotations are currently supported:
+ At present, only three annotations are supported:
</para>
<orderedlist>
@@ -58,27 +59,28 @@
</orderedlist>
<para>
- The basic structure of the configuration file follows the basic
- structure of a Java class i.e. a “Class” containing “Fields” and
- “Methods”. The <Class>, <Field> and <Method>
- elements all require a “name” attribute for the name of the Class,
- Field or Method. The value of this name attribute supports regular
- expressions. This allows a single Annotation Introduction
- configuration to be targeted at more than one Class, Field or
- Member e.g. setting the namespace for a fields in a Class, or for
- all Classes in a package etc.
+ The basic structure of the configuration file follows the that of a
+ Java class (that is, a "Class" containing "Fields" and "Methods".)
+ The <Class>, <Field> and <Method> elements all
+ require a “name” attribute. This attribute provides the name of the
+ Class, Field or Method. This name attribute's value is able to
+ support regular expressions. This allows a single Annotation
+ Introduction configuration to be targeted at more than one Class,
+ Field or Member (by, for example, setting the name-space for a field
+ in a Class, or for all Classes in a package.)
</para>
<para>
The Annotation Introduction configurations match exactly with the
- Annotation definitions themselves, with each annotation
- “element-value pair” represented by an attribute on the annotations
- introduction configuration. Use the XSD and your IDE to editing the
- configuration.
+ annotation definitions themselves, with each annotation
+ <firstterm>element-value pair</firstterm> represented by an
+ attribute on the Annotations Introduction configuration. (One should
+ use the <abbrev>XSD</abbrev> and an <abbrev>IDE</abbrev> to edit the
+ configuration.)
</para>
<para>
- So here is an example:
+ Finally, here is an example:
</para>
<programlisting language="XML" role="XML"><xi:include href="extras/appendix_a/Code_Example21.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,47 @@
+public class MyCustomGateway extends AbstractThreadedManagedLifecycle {
+
+ private ConfigTree listenerConfig;
+ private Service service;
+ private ServiceInvoker serviceInvoker;
+
+ public MyCustomGateway(final ConfigTree config) throws ConfigurationException {
+ super(config);
+ this.listenerConfig = config;
+
+ String serviceCategory = listenerConfig.getRequiredAttribute(ListenerTagNames.TARGET_SERVICE_CATEGORY_TAG);
+ String serviceName = listenerConfig.getRequiredAttribute(ListenerTagNames.TARGET_SERVICE_NAME_TAG);
+
+ service = new Service(serviceCategory, serviceName);
+ }
+
+ protected void doInitialise() throws ManagedLifecycleException {
+ // Create the ServiceInvoker instance for the target service....
+ try {
+ serviceInvoker = new ServiceInvoker(service);
+ } catch (MessageDeliverException e) {
+ throw new ManagedLifecycleException("Failed to create ServiceInvoker for Service '" + service + "'.");
+ }
+ }
+
+ protected void doRun() {
+ while(isRunning()) {
+ // Wait for a message....
+ Object payloadObject = waitForPayload();
+
+ // Send the message to the target service's Action Pipeline via
+ // the ServiceInvoker...
+ try {
+ Message esbMessage = MessageFactory.getInstance().getMessage();
+
+ esbMessage.getBody().add(payloadObject);
+ serviceInvoker.deliverAsync(esbMessage);
+ } catch (MessageDeliverException e) {
+ e.printStackTrace();
+ }
+ }
+ }
+
+ private Object waitForPayload() {
+ // Wait for a message...
+ }
+}
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway2.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway2.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway2.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,29 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd"
+ parameterReloadSecs="5">
+
+ <providers>
+ <bus-provider name="CustomProvider">
+ <property name="provider-property" value="buprovider-prop-value" />
+
+ <bus busid="custom-bus">
+ <property name="bus-property" value="bus-prop-value" />
+ </bus>
+ </bus-provider>
+ </providers>
+
+ <services>
+ <service category="Custom" name="Listener" description="" invmScope="GLOBAL">
+ <listeners>
+ <listener name="custom-listener" busidref="custom-bus" is-gateway="true">
+ <property name="gatewayClass" value="com.acme.listeners.MyCustomGateway" />
+ <property name="listener-property" value="listener-prop-value" />
+ </listener>
+ </listeners>
+ <actions mep="OneWay">
+ ...
+ </actions>
+ </service>
+ </services>
+
+</jbossesb>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway3.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway3.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway3.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,23 @@
+Public class OrderFileListener implements ScheduledEventMessageComposer {
+
+ public void initialize(ConfigTree config) throws ConfigurationException {
+ // TODO: Initialise File filters etc, using the config to access properties configured on the listener...
+ }
+
+ public Message composeMessage() throws SchedulingException {
+ Message message = MessageFactory.getInstance().getMessage();
+
+ // TODO: Read one or more order files and populate the data into the ESB message for pipeline processing...
+
+ return message;
+ }
+
+ public Message onProcessingComplete(Message message) throws SchedulingException {
+ // TODO: Post pipeline processing...
+ return message;
+ }
+
+ public void uninitialize() {
+ // TODO: Any relevant cleanup tasks...
+ }
+}
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway4.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway4.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway4.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,25 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd">
+
+ <providers>
+ <schedule-provider name="schedules">
+ <simple-schedule scheduleid="ordersPole" frequency="5" frequencyUnits="seconds" />
+ </schedule-provider>
+ </providers>
+
+ <services>
+ <service category="OrderManagement" name="OrderProcessing" description="Order Processing Service">
+
+ <listeners>
+ <scheduled-listener name="orderFileListener" scheduleidref="ordersPole" event-processor="com.acme.OrderFileListener"/>
+ </listeners>
+
+ <actions>
+ <action name="action1" class="..."/>
+ <action name="action2" class="..."/>
+ <action name="action3" class="..."/>
+ </actions>
+ </service>
+ </services>
+
+</jbossesb>
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway5.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway5.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway5.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,14 @@
+public class OrderListener implements MessageListener {
+
+ public void onMessage(final Message message) {
+ if(message instanceof ObjectMessage) {
+ Order order = ((ObjectMessage) message).getObject();
+
+ // Create and populate an ESB message with the order....
+ Message esbMessage = MessageFactory.getInstance().getMessage();
+ esbMessage.getBody().add(order);
+
+ // TODO: Add code to forward the ESB message to the Action Pipeline...
+ }
+ }
+}
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway6.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway6.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway6.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,38 @@
+public class OrderListener implements MessageListener {
+
+ private ActionProcessingPipeline pipeline;
+
+ public void start(ConfigTree config) throws ConfigurationException {
+ // Create and initialize the pipeline..
+ pipeline = new ActionProcessingPipeline(config);
+ pipeline.initialise();
+
+ // TODO: Add JMS code for connecting this JMS MessageListener to the JMS Queue...
+ }
+
+ public void onMessage(final Message message) {
+ if(message instanceof ObjectMessage) {
+ Order order = ((ObjectMessage) message).getObject();
+
+ // Create and populate an ESB message with the order....
+ Message esbMessage = MessageFactory.getInstance().getMessage();
+ esbMessage.getBody().add(order);
+
+ // Forward the ESB message to the Action Pipeline...
+ boolean success = pipeline.process(message);
+ if(!success) {
+ // TODO: Handle error....
+ }
+ }
+ }
+
+ public void stop() {
+ try {
+ // TODO: Add JMS code for disconnecting from JMS Queue....
+ } finally {
+ if(pipeline != null) {
+ pipeline.destroy() ;
+ }
+ }
+ }
+}
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway7.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway7.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway7.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,15 @@
+import com.acme.OrderListener;
+
+OrderListener orderListener = new OrderListener();
+
+// Start the listener (passing the config)...
+orderListener.start(config);
+
+// Wait until the Groovy Gateway is signaled to stop...
+def stopped = false;
+while(!stopped) {
+ stopped = gateway.waitUntilStopping(200);
+}
+
+// Now stop the listener...
+orderListener.stop();
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway8.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway8.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Programmers_Guide/en-US/extras/advanced/customgateway8.xmlt 2010-08-15 23:29:06 UTC (rev 34732)
@@ -0,0 +1,21 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd">
+
+ <services>
+ <service category="OrderManagement" name="OrderProcessing" description="Order Processing Service">
+
+ <listeners>
+ <groovy-listener name="orderJmsListener" script="/com/acme/OrderListener.groovy">
+ <property name="queueName" value="..."/>
+ </groovy-listener>
+ </listeners>
+
+ <actions>
+ <action name="action1" class="..."/>
+ <action name="action2" class="..."/>
+ <action name="action3" class="..."/>
+ </actions>
+ </service>
+ </services>
+
+</jbossesb>
More information about the jboss-svn-commits
mailing list