JBoss SOA Platform

The JBoss ESB Beginner's Guide is officially published today!

2012-01-25T06:09:00.000-08:00

It's available at Packt now! http://www.packtpub.com/jboss-esb-beginners-guide/book

And at Amazon: http://www.amazon.com/JBoss-ESB-Beginners-Guide-DiMaggio/dp/1849516588/

A review of the book is here: http://rickwagner.blogspot.com/2011/10/book-review-for-jboss-esb-beginners.html

The JBossESB-Smooks Integration in the SOA Platform Post - now on DZone

2011-01-17T09:01:00.001-08:00

And - DZone just picked up that last post too:

http://java.dzone.com/articles/jbossesb-smooks-integration

The JBossESB-Smooks Integration in the SOA Platform

2011-01-12T15:04:00.000-08:00

One of the great strengths of the SOA Platform is its wealth of software integrations. In this post, we'll examine the JBoss ESB - Smooks integration in the SOA Platform and how it can be used to perform two of the primary operations or an ESB; message transformations and message routing:

Message transformation enables the JBossESB to translate message payloads (the message body plus attachments and properties) from one form to another so that the message can be processed by different services.
Message routing enables the JBossESB to move messages to files, to JMS assets such as queues, and over the ESB "bus" between services.

A 30-Second Introduction to Smooks

It's common to refer to Smooks as a transformation engine, but that's not the full story. Smooks is really a more general purpose processing framework that is capable of dealing with with fragments of a message. Smooks accomplishes this with "visitor logic", where a "visitor" is Java code that performs a specific action on a specific fragment of a message. This enables Smooks to perform different actions on different fragments of messages. As is stated by the Smooks project (http://www.smooks.org/mediawiki/index.php?title=Why_Smooks_was_Created):

Smooks supports these types of message fragment processing:

Templating: Transform message fragments with XSLT or FreeMarker
Java Binding: Bind message fragment data into Java objects
Splitting: Split messages fragments and rout the split fragments over multiple transports and destinations
Enrichment: "Enrich" message fragments with data from databases
Persistence: Persist message fragment data to databases
Validation: Perform basic or complex validation on message fragment data

The SOA Platform SmooksAction out-of-the-box action provides you access to all these Smooks capabilities.

The JBossESB implements several out of the box actions to support message transformation and routing. SmooksAction (org.jboss.soa.esb.smooks.SmooksAction) enables you to use a powerful set of Smooks operations within the SOA Platform. Transformations are probably the first type of operation that you think of with Smooks, but with the SmooksAction you can also make use of Smooks operations such as splitting and routing message payloads.

A Simple Transformation with Smooks

Let's look at a very simple example, the aptly named "transform_XML2XML_simple" quickstart. This quickstart performs a message transformation by applying an XSLT (EXtensible Stylesheet Language Transformations) to an XML message. The message is transformed into XML in a different form. The interesting parts of the quickstart's jboss-esb.xml file are:

1:  <actions mep="OneWay">  
2:  <action class="org.jboss.soa.esb.actions.SystemPrintln" name="print-before">  
3:  <property name="message" value="[transform_XML2XML_simple] Message before transformation">  
4:  </property>  
5:  <action class="org.jboss.soa.esb.smooks.SmooksAction" name="simple-transform">  
6:  <property name="smooksConfig" value="/smooks-res.xml">  
7:  <property name="reportPath" value="/tmp/smooks_report.html">  
8:  </property>  
9:  <action class="org.jboss.soa.esb.actions.SystemPrintln" name="print-after">  
10: <property name="message" value="[transform_XML2XML_simple] Message after transformation">  
11: </property>

Line 1: This line is not specific to transformations, but it's worth mentioning. "mep" stands for "message exchange pattern." The pattern used by this quickstart is "one-way" in that the requester invokes a service (by sending it a message) and then does not wait for a response.
Lines 2-4, 9-24: These lines simply cause the message to be written to the server log before and after its transformation. (org.jboss.soa.esb.actions.SystemPrintln, is, incidentally, the only out-of-the-box action in the Miscellaneous action group.)
Line 5: Here's where we specify that we want to invoke a SmooksAction
Line 6: And here is the XSLT that will be executed. We'll examine this file in a moment.
Line 7: This line is actually not in the quickstart. I've added the reportPath property it so that we can review the resulting report. Note that generating this report does require some processing resources, so it should not be used in production environments. See below for screen-shots of this report.

Now, let's look at smooks-res.xml:

1:  <?xml version='1.0' encoding='UTF-8'?>  
2:  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.0.xsd">  
3:    
4:  <resource-config selector="OrderLine">  
5:  <resource type="xsl">  
6:  <![CDATA[<line-item>  
7:  <product><xsl:value-of select="./Product/@productId" /></product>  
8:  <price><xsl:value-of select="./Product/@price" /></price>  
9:  <quantity><xsl:value-of select="@quantity" /></quantity>  
10:  </line-item>]]>  
11:  </resource>  
12:  <param name="is-xslt-templatelet">true</param>  
13:  </resource-config>  
14:  </smooks-resource-list>

Line 2: The namespace referenced here is the Smooks XML Schema Definition
Line 4: The resource-config element corresponds to an org.milyn.cdr.SmooksResourceConfiguration object[11]
Lines 7-9: These XPath (XML Path Language) statements locate the Product element's productId and price attributes and the OrderLine element's quantity attributes. XPath is used by XSLT to find or reference data in XML documents.

When you run this quickstart, you'll see the XML message as defined in SampleOrder.xml displayed before and after it undergoes the XSLT transformation.

Content Based Routing with Smooks

The routing of data from one place to another is one of the most basic, and common, problems facing any networked software application. This routing can take many forms, such as email being sent to the correct recipient or network traffic being routed around the globe based on system names defined in DNS. In the context of an Enterprise Service Bus such as the JBossESB in the SOA Platform, where everything is either a message or a service, routing means getting messages delivered to the correct services.

JBossESB Routing Choices

The JBossESB supports multiple actions to route messages to services right out of the box (http://jboss-soa-p.blogspot.com/2009/09/works-great-right-out-of-box.html) such as:

HttpRouter (org.jboss.soa.esb.actions.routing.HttpRouter) - The HttpRouter routes the incoming message to a URL that you specify in the action definition.
JMSRouter (org.jboss.soa.esb.actions.routing.JMSRouter) - This action routes the incoming message to JMS. For example, to a JMS queue where a service can then retrieve the message asynchronously. In order to find the correct JMS queue or topic, you specify values for properties such as jndi-name, initial-context-factory, and jndi-URL in the action definition.
StaticRouter (org.jboss.soa.esb.actions.StaticRouter) - As its name implies, this router establishes static routes that do not change based on the content of the messages or a set of routing rules.
StaticWiretap (org.jboss.soa.esb.actions.StaticWiretap) - Maybe it's the comic book fan in me, but this is my favorite name for an action. There's something film noir-ish about a "wiretap." You can almost imagine Humphrey Bogart sitting it the back room of a bar listening in on a wiretapped SOA action. (On black and white film, of course.) In practice, it's not all that exciting. This action implements the Enterprise Integration Pattern for a wiretap (http://www.eaipatterns.com/WireTap.html). The goal of a wiretap is to inspect each message, without affecting the operation of the action chain. This can be a useful action to use to aid in debugging a service.

JBossESB and Contest Based Routing

These are all very useful, but they are also all static in nature in that once you define the path for the messages, that's the path that the messages always take. For example, a static path could be used so that messages from the sales department service are always sent to the warehouse inventory control service. But, what if you had several warehouses each of which stored a different set of products? And what if you wanted to be able to vary the route of the messages dynamically? For example, what if you want the route the message takes to be based on the actual content in the message? Well, the JBossESB also supports multiple types of content based routing (CBR).

Two relatively lightweight approaches (http://jbossesb.blogspot.com/2009/10/content-based-routing-in-jbossesb-just.html) for content based routing are supported:

XPath Content Based Routing - Note that this is completely defined in the jboss-esb.xml file. No additional configuration files are needed.
Regex Content Based Routing - An external configuration file is used to define XPath expressions that govern the routing.

Now, if you are dealing with a more complex set of routing "rules," the JBossESB supports using JBoss Rules (http://jboss-soa-p.blogspot.com/2009/07/when-content-knows-way-content-based.html) to define the routing rules. Rules provides you with the rich feature set of JBoss Drools to control the dynamic routing of messages based on their content. JBoss Drools is a complete enterprise platform for rules-based application development, workflow, administration, and event processing. It also provides an integration with JBossESB to support content based routing. You define the content based routing algorithm in a set of rules.

But wait - there's more.

Content Based Routing with Smooks

You might think of JBoss Smooks (http://www.smooks.org/) as primarily a tool for performing XML transformations (for example, for transforming data from CSV to XML), but it can also be used for content based routing on the JBossESB in the SOA Platform. Some of the things that Smooks allows you to do with content based routing are:

Splitting of messages - Don't just route the whole message, but split out the parts of the message, say sales order items and route them to separate services.
Even more complex splitting of messages - For example, split out those sales order items and then combine each of them with data from other parts of the message (say, customer informatin) before performing the message routing. This is more than just basic message fragment extraction, as the extracted data can be combined or otherwise processed.
Routing split message fragments in multiple formats - For example, routing XML to one service, Java to another, CSV data to still another.
Fast performance - Smooks is able to perform all the message splitting and routing (even for multiple destinations and multiple formats) in a single filtering pass of the message. This makes for fast performance as there is no need to evaluate multiple XPaths multile times on the same message. Smooks is also able to handle big (make that REALLY BIG as in > 50MB) messages efficiently.
Complex conditionals - Smooks is not limited to just the conditionals that XPath supports.

The best way to understand and appreciate the advantages and flexibility of content based routing on the JBossESB with Smooks is to see it in action. Note that we'll be following a programming tradition as we'll take a quickstart as starting point, and expand it to fulfill our requirements.

The quickstart is named: smooks_file_splitter_router

Now, as the quickstart's name indicates, its objective is to demonstrate both splitting files and routing messages. The quickstart's "Splitter" service makes use of a File Gateway. Its file system listener ("fs-listener") uses the Smooks org.jboss.soa.esb.smooks.splitting.FileStreamSplitter to split an incoming XML message and route message fragments to the "Receiver" service.

Let's take a closer look at how this works, and then we'll expand on the quickstart to perform some additional content based routing.

The quickstart is initiated by the "runtest" ant target. This invokes the org.jboss.soa.esb.sample.quickstart.smooksfilesplitterrouter.InputOrderGenerator class which creates the "SampleOrder.xml" file for the File Gateway. SampleOrder.xml contains multiple orders and follows this form:

1:  <order id="332">  
2:  <header>  
3:  <customer number="123">Joe</customer>  
4:  </header>  
5:  <order-items>  
6:  <order-item id="1">  
7:  <product>1</product>  
8:  <quantity>2</quantity>  
9:  <price>8.80</price>  
10:  </order-item>  
11:  <order-item id="2">  
12:  <product>2</product>  
13:  <quantity>2</quantity>  
14:  <price>8.80</price>  
15:  </order-item>  
16:  <order-item id="3">  
17:  <product>3</product>  
18:  <quantity>2</quantity>  
19:  <price>8.80</price>  
20:  </order-item>  
21:  <order-item id="4">  
22:  <product>4</product>  
23:  <quantity>2</quantity>  
24:  <price>8.80</price>  
25:  </order-item>  
26:  <order-item id="5">  
27:  <product>5</product>  
28:  <quantity>2</quantity>  
29:  <price>8.80</price>  
30:  </order-item>  
31:  <order-item id="6">  
32:  <product>6</product>  
33:  <quantity>2</quantity>  
34:  <price>8.80</price>  
35:  </order-item>  
36:  <order-item id="7">  
37:  <product>7</product>  
38:  <quantity>2</quantity>  
39:  <price>8.80</price>  
40:  </order-item>  
41:  <order-item id="8">  
42:  <product>8</product>  
43:  <quantity>2</quantity>  
44:  <price>8.80</price>  
45:  </order-item>  
46:  <order-item id="9">  
47:  <product>9</product>  
48:  <quantity>2</quantity>  
49:  <price>8.80</price>  
50:  </order-item>  
51:  </order-items>  
52:  </order>

The best way to understand the operation of the quickstart is to take a closer look at the providers and services defined in the jboss-esb.xml file. Note that in the case of this quickstart, jboss-esb.xml is actually generated from jboss-esb-unfiltered.xml at run time to include environment specific information such as directory names. Here's jboss-esb-unfiltered.xml:

1:  <?xml version = "1.0" encoding = "UTF-8"?>  
2:  <jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.1.0.xsd"  
3:    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
4:    xsi:schemaLocation="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.1.0.xsd http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.1.0.xsd"  
5:    parameterReloadSecs="5">  
6:     
7:    <providers>  
8:        <fs-provider name="FSprovider1">  
9:            <fs-bus busid="smooksFileChannel">  
10:                <fs-message-filter  
11:                    directory="@INPUTDIR@"  
12:                    input-suffix=".xml"  
13:                    work-suffix=".esbWorking"  
14:                    post-delete="true"  
15:                    post-directory="@OUTPUTDIR@"  
16:                    post-suffix=".sentToEsb"  
17:                    error-delete="false"  
18:                    error-directory="@ERRORDIR@"  
19:                    error-suffix=".IN_ERROR"  
20:                  />  
21:            </fs-bus>  
22:        </fs-provider>  
23:    
24:    </providers>  
25:    
26:    <services>  
27:    
28:      <!--  
29:          Splitter Service...  
30:      -->  
31:      <service category="QS" name="Splitter" description="Splitter Service" invmScope="GLOBAL">  
32:          <listeners>  
33:          <!-- Splitting the message at the gateway via the FileStreamSplitter composer class allows us to  
34:                   handle huge messages... -->  
35:              <fs-listener name="FileGateway" busidref="smooksFileChannel" is-gateway="true" schedule-frequency="2">  
36:                  <property name="composer-class" value="org.jboss.soa.esb.smooks.splitting.FileStreamSplitter"/>  
37:                  <property name="splitterConfig" value="/smooks-config.xml"/>  
38:              </fs-listener>  
39:          </listeners>  
40:          <actions mep="OneWay">  
41:              <action name="print" class="org.jboss.soa.esb.actions.SystemPrintln">  
42:                  <property name="message" value="[Splitter] Message Split complete"/>  
43:              </action>  
44:       
45:              <!-- The next action is for Continuous Integration testing -->  
46:              <action name="testStore" class="org.jboss.soa.esb.actions.TestMessageStore"/>  
47:          </actions>  
48:      </service>  
49:        
50:      <!--  
51:          Receiver Service...  
52:      -->  
53:      <service category="QS" name="Receiver" description="Receiver Service" invmScope="GLOBAL">  
54:          <actions mep="OneWay">  
55:              <action name="print" class="org.jboss.soa.esb.actions.SystemPrintln">  
56:                  <property name="message" value="[Receiver] Message Fragment Received"/>  
57:              </action>  
58:          </actions>  
59:      </service>  
60:       
61:    </services>  
62:        
63:  </jbossesb>

Lines 7-24 - This is the definition of the file system gateway. What's interesting to note here are:
Lines 11-12 - Here's the input directory. Based on its configuration, the listener will listen for files with an .xml extension that are created in the INPUT directory.
Line 13 - While the file gateway is processing the file, it is renamed to have an extension of "esbWorking".
Lines 14-16 - After the file is processed, it is renamed again, this time to have an extension of "sentToEsb," and then it is deleted.
Lines 17-19 - And, if an error occurs, the file is renamed to have an extension of "IN_ERROR" and is saved in the error directory.

The "Splitter" service is defined in lines 31-48. The most interesting lines are:

35:  <fs-listener name="FileGateway" busidref="smooksFileChannel" is-gateway="true" schedule-frequency="2">  
36:      <property name="composer-class" value="org.jboss.soa.esb.smooks.splitting.FileStreamSplitter"/>  
37:      <property name="splitterConfig" value="/smooks-config.xml"/>  
38:  </fs-listener>

Line 35 - Here's the start of the file gateway definition.
Line 36 - Note that when the file gateway detects the presence of a file, it invokes the Smooks org.jboss.soa.esb.smooks.splitting.FileStreamSplitter class. And what does this class do with the file?
Line 37 - It splits the message into fragments, based on the conditions and actions defined in the smooks-config.xml file.

The message fragments are then routed to the Receiver service, which simply writes the message to the server.log.

The smooks-config.xml file is where the file splitting and routing is defined, so let's take a closer look there:

1:  <?xml version="1.0"?>  
2:  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"  
3:          xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.2.xsd"  
4:          xmlns:ftl="http://www.milyn.org/xsd/smooks/freemarker-1.1.xsd"  
5:          xmlns:esbr="http://www.jboss.org/xsd/jbossesb/smooks/routing-1.0.xsd">  
6:   
7:      <params>          
8:          <param name="stream.filter.type">SAX</param>  
9:      </params>  
10:   
11:     <conditions>  
12:         <!-- route the even numbered order items -->  
13:         <condition id="routeItem"><!-- orderItem.itemId % 2 == 0 --></condition>  
14:     </conditions>  
15:   
16:     <!-- Capture some data from the message into the bean context... -->  
17:     <jb:bean beanId="header" class="java.util.Hashtable" createOnElement="order">  
18:         <jb:value property="orderId" data="order/@id"/>  
19:         <jb:value property="customerNumber" data="header/customer/@number"/>  
20:         <jb:value property="customerName" data="header/customer"/>  
21:     </jb:bean>  
22:     <jb:bean beanId="orderItem" class="java.util.Hashtable" createOnElement="order-item">  
23:         <jb:value property="itemId" data="order-item/@id"/>  
24:         <jb:value property="productId" data="order-item/product"/>  
25:         <jb:value property="quantity" data="order-item/quantity"/>  
26:         <jb:value property="price" data="order-item/price"/>  
27:     </jb:bean>  
28:   
29:     <!-- On each order-item, apply a template to the data captured into the bean context,  
30:          binding the templating result back into the bean context under the  
31:          beanId "orderItemFragment" to be routed by the following ESB Router... -->  
32:     <ftl:freemarker applyOnElement="order-item">  
33:         <condition idRef="routeItem" />  
34:         <ftl:template>/orderitem-split.ftl</ftl:template>  
35:         <ftl:use>  
36:            <ftl:bindTo id="orderItemFragment" />  
37:         </ftl:use>  
38:     </ftl:freemarker>  
39:   
40:     <!-- On each order-item, route the "orderItemFragment" bean to the  -->  
41:     <esbr:routeBean beanIdRef="orderItemFragment" toServiceCategory="QS" toServiceName="Receiver" routeOnElement="order-item">  
42:         <condition idRef="routeItem" />  
43:     </esbr:routeBean>  
44:  
45: </smooks-resource-list>

As we described a minute ago, the two main actions being performed are the splitting of the incoming message into fragments, and then the routing of the resulting fragments to services. Let's look at the how the splitting is performed. Recall that the sampleOrder.xml file included these XML elements.

 <order id='332'>  
 <header>  
 <customer number="123">Joe</customer>  
 </header>  
 <order-items>  
 <order-item id='1'>  
 <product>1</product>  
 <quantity>2</quantity>  
 <price>8.80</price>  
 </order-item>  
 (followed by more order-items)

Remember how we talked about Smooks' ability to process large messages efficiently? At this point, it's important to note that when Smooks splits the XML message, it processes each orderItem one at a time, and it only keeps one orderItem in memory at a time. This is one way in which Smooks is able to efficiently process large messages.

Lines 17-21 - As the comments indicate, this captures data from the message, and extracts the orderId, customerName and customerNumber properties (note the use of xPath to navigate the original XML message) into a header (org.jboss.soa.esb.sample.quickstart.smooksfilesplitterrouter.Header) bean.
Lines 22-27 - And, this does the same for the orderItems.
Lines 30-38 - And here, Smooks takes the header and orderItems beans, and uses a Freemarker (http://freemarker.sourceforge.net/) template to create an orderItemFragment bean that has this organization:

1:   <orderitem id="${orderItem.itemId}" order="${header.orderId}">  
2:       <customer>  
3:           <name>${header.customerName}</name>  
4:           <number>${header.customerNumber}</number>  
5:       </customer>  
6:       <details>  
7:           <productId>${orderItem.productId}</productId>  
8:           <quantity>${orderItem.quantity}</quantity>  
9:           <price>${orderItem.price}</price>  
10:       </details>

Note that Smooks is able to combine elements from both the header and orderItems beans into an orderItemFragment bean.

So much for the splitting, now let's take a look at how Smooks routes the message fragments to services.

Lines 11-14 - First, Smooks establishes a condition ("routeItem") that must be met in order for the message to be routed. In this example, the value of the orderItem.itemId element must be an even number.
Lines 41 - And here's where the routing actually starts. This line defines the attributes for the JBoss ESB router ("routeBean"). The attributes defined for this quickstart are:
beanIdRef - this is the references of the bean that will be routed to the intended service
toServiceCategory - The category of that service, as defined in the quickstart's jboss-esb.xml file
toServiceName - And the name of that service ("Receiver"), again, as defined in the quickstart's jboss-esb.xml file
routeOnElement - And, finally the content element used to determine the route for messages to follow - in the case of the quickstart, this is the order-item

A good way to look at content based routing with Smooks is that new messages are built from data in fragments in the original source message. In the case of the quickstart, we want to route data from each in an message. In this case, since the routeOnElement is the order-item, when the Smooks processing filter reaches the end of every order-item fragment, it will route a message to "somewhere" i.e. the end of the fragment is used to trigger the routing. (Many thanks to Tom F. for this summary!)

Line 42 - The ID of the condition that must match in order for the routing to occur. This ID ("routeItem") maps to the routing condition defined in line 13.

One attribute that is not explicitly defined by in this quickstart is "routeBefore." This attribute enables you to control when the routing occurs. This can be either (at the start) a specific message fragment is processed by Smooks, or after (at the end) it has processed the fragment. The default value is after, which is why the quickstart does not explicitly define the attribute.

Note that the full set of attributes that control routing to JBossESB services with Smooks are defined in the routing-1.0.xsd file that is deployed to a SOA Platform server in: smooks.esb/META-INF/xsd/jbossesb/smooks/routing-1.0.xsd

Closing Thoughts

OK, let's review what happened. The quickstart demonstrated two features of the integration between Smooks and the JBossESB in the SOA Platform; file splitting and routing. First, the quickstart took a single, and potentially very large XML file, and split its content into two separate beans, then combined elements of those two beans into a new bean. When Smooks performed this splitting and transformation of data from one form to another, it did so in a serial fashion, where only one instance was in memory at a time, so that it could efficiently handle even large numbers of instances. Then, Smooks found an element in the newly created bean, and based on the content of that element, routed the newly created bean in a message to an ESB service.

And - note that in order for this quickstart to accomplish these tasks, it was not necessary to write large amounts of new custom code. A Smooks configuration file and a FreeMarker template file, coupled with a call to the org.jboss.soa.esb.smooks.splitting.FileStreamSplitter class was all that was needed in the quickstart. Smooks and the JBossESB in the SOA Platform did the rest!

Acknowledgements

As always, I want to thank the JBoss SOA Platform team and community (especially Tom Fennally and Kevin Conner) for their timely review input for this blog post!

References

Cross Posted to DZone

2010-09-27T17:26:00.000-07:00

The SOA Platform - JBossESB - SAML post was just cross posted on DZone:

http://java.dzone.com/articles/asserting-security-jbossesb

Asserting Security - The JBossESB Integration with SAML in the JBoss SOA Platform

2010-09-20T19:13:00.000-07:00

Introduction - When Two User Accounts is One Too Many

Have you ever noticed how whenever you visit a new doctor, you have to fill out a new medical history, longhand and on paper? Sometimes you make a mistake or sometimes someone else makes a mistake transcribing the information. Why can't the information be shared in a secure way? The same type of problem exists with computer systems, web applications, and passwords. If you frequently access multiple remote systems or applications, you invariably have to manage multiple user accounts. (At one of my past jobs, I actually had 17 user accounts across several systems. The killer was that the accounts all had different password complexity rules and expiration schedules.)

What's happening here is that you have authentication and authorization information in different security "domains". What's needed in our internet and web-based world, is a standard way to securely (and easily!) share user accounts between systems. In other words, we need a way to perform "single sign-on" (SSO) between multiple security domains. What you want to be able to do is to have the different applications and sites that you rely on, regardless of each application's implementation or operating environment, to be able to safely share your login information, without you having to login repeatedly, or maintain multiple different accounts.

One solution to this problem is the "Security Assertion Markup Language" (SAML).

The Standard: SAML

SAML was created by the Security Services Technical Committee of the Organization for the Advancement of Structured Information Standards (OASIS - http://www.oasis-open.org).

Wikipedia (http://en.wikipedia.org/wiki/SAML) defines SAML as: '...an XML-based standard for exchanging authentication and authorization data between security domains, that is, between an identity provider (a producer of assertions) and a service provider (a consumer of assertions)...'
Ref: Organization for the Advancement of Structured Information Standards (OASIS - http://www.oasis-open.org)

Let's dissect that deceptively short definition into smaller pieces. Each of these pieces covers one of SAML's important characteristics and the motivations for its creation.

XML based - One of the goals of the SAML is for it to be a standard that can be used by different applications and systems to replace proprietary security methods. If you're going to create a standard, then basing it on XML is a good start!
Exchanging data - The ultimate goal is of course to support the secure exchange of data between applications and systems and users. In the context of security, the applications, systems, and users are referred to as "principals.")
Authentication and Authorization - These two aspects of security are related, but refer to different tasks. Authentication refers to verifying the identity of the principle. Authorization refers to verifying that the principal is permitted to perform a specific action.
Security domains - "Federation" is an important concept to keep in mind when you talk about security domains. In the context of a political system, federation refers to the separating of overlapping of areas of control between the states that make up a greater federation. It may be that each state is able to make laws specific to the state, but they must also abide by the laws of the greater federation. (Ever hear of Fort Sumter? http://www.nps.gov/fosu/) It's like that when security domains are federated too. You might want to establish a large-scale domain for all your employees, so that they can all use the same login information to access multiple shared systems such as vacation trackers or a corporate intranet, while at the same time, you can establish smaller domains so that restricted groups of those employees can use that same login information to access purchasing or payroll information.
Identity Provider - In the context of using SAML, an identity provider supplies authentication information when and where requested by a principal. Note that this in contrast to security systems that rely on cookies stored and supplied by the client web browsers, or ticketing systems such as Kerberos where the client supplies a ticket to a service. In SAML, a Identity Providers are the producers of security "assertions."
Service Provider - In the context of using SAML, service providers rely on Identity Providers. When the principal requests its identity to be confirmed, an Identity Provider sends this information, in the form of a SAML sercurity assertion. So, in SAML, Service Providers are the consumers of the security assertions.

But, while it is a standard, it is not an implementation. For a SAML implemention, we need to look at JBoss PicketLink.

The Implementation: JBoss PicketLink

PicketLink (http://jboss.org/picketlink) is the JBoss Identity Management (IdM) project. PicketLink is actually built on the JBoss "PicketBox" (formerly known as "JBoss Security") framework. PicketBox (http://www.jboss.org/picketbox) provides developers with a framework where these security functions can be easily configured: authentication, authorization, auditing, and mapping (Principal to Roles and Attributes).

PicketLink is an "umbrella" project that pulls together multiple components to support various security and Identity Management requirements. As listed on the PicketLink project site, these components are:

AuthZ (a authorization framework)
Federated Identity (remember our discussion of federated security domains a minute ago?)
Identity Management (this provides a common framework for handing users and groups and supports using identity repositories such as LDAP)
Negotiation (this provides SPNego*/Kerberos based Desktop single sign-on)
XACML (an implementation of the Oasis eXtensible Access Control Markup Language - this provides fine-grained authorization capabilities)

* Simple and Protected GSSAPI (Generic Security Services Application Programming Interface) Negotiation Mechanism - yes, that is a mouthful.

Security Token Service (STS)

The SAML integration with the JBossESB in the SOA Platform is supported by the PicketLink Security Token Service (PicketLinkSTS). PicketLink provides login modules (https://community.jboss.org/wiki/PicketLinkSTSLoginModules) two of which JBossESB uses.

The primary focus of the ESB integration is for PicketLink to provide security modules and SAML Token support for ESB services. (http://community.jboss.org/wiki/JBossESBSAMLSupport) The ESB service configures the org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule class to issue (produce) a SAML Security Token.

The best way to look at this integration is to see it in action. So, we'll "learn by doing" by examining it in a SOA Platform "quickstart."

The Quickstart

I never get tired of saying that one of the great features of the SOA Platform is its extensive, and always growing, set of "quickstart" programs. These programs go far beyond being simple examples as they clearly illustrate various features supported by the Platform. They also serve as a great resource for writing your own applications. For our example, we'll look at the "security_saml" quickstart.

This quickstart illustrates the SOA Platform JBossESB's support for SAML support as provided by PicketLink's Security Token Service (PicketLinkSTS). As the quickstart's readme file states:

The following (4) procedures will be demonstrated by this quickstart:

Using the PicketLink Project's STSIssuingLoginModule to issue a SAML Assertion from PicketLinkSTS, then
Using the PicketLink Project's STSValidatingLoginModule to validate a SAML Assertion from PicketLinkSTS, then
Injecting the SAML Assertion into a SOAP Message, then
Using SOAPProcessor to invoke an external Web Service that is secured by PicketLinkSTS.

Before we walk through the actions that quickstart performs, let's examine the configuration and binary files that control these procedures. Because the quickstart has to handle the issuing and validation of the
SAML Assertion in addition to actually configuring the quickstart's web service and sending a message to that service, there are a larger number of configuration, execution, and test data related XML files than are used in some other quickstarts.

But, hey, don't panic! We'll examine the files in detail and describe how they are used and also, how they all tie together. Let's divide and conquer and examine these files in the following logical groups:

Group #1 - PicketLinkSTS related files

picketlink-sts-client.properties
login-config-unfiltered.xml
jboss-service.xml
jboss-wsse-client.xml

Group #2 - Test data related files

soap-request.xml
smooks-saml-injector-template.xml
|smooks-saml-injector.xml

Group #3 - ESB archive related files

deployment.xm
jbm-queue-service.xml
jboss-esb.xml
jbossesb-properties.xml

NOTE: We'll hop around a bit between these groups of files, depending on the relationships between the files.

Group #1 - PicketLinkSTS related files

Let's start with the PicketLink's Security Token Service related files.

The picketlink-sts-client.properties file defines the STS configuration for the STSIssuingLoginModule and STSValidatingLoginModule.

1:  serviceName=PicketLinkSTS  
2:  portName=PicketLinkSTSPort  
3:  endpointAddress=http://localhost:8080/picketlink-sts/PicketLinkSTS  
4:  username=admin  
5:  password=admin

Line 1 - The service name. Make a mental note of this as we'll come back to this in a minute.
Line 3 - The endpoint of service. This will be active once we deploy the quickstart.
Line 4-5 - This username and password are actually only used by the STSValidatingLoginModule. In contrast, the STSIssuingLoginModule uses callbacks to retrieve the username and password from the authentication request, which is extracted from the SOAP Security header. Where is the SOAP Security header defined? Read on.

Like most of the SOA Platform quickstarts, the security_saml quickstart initiates its actions by generating a message that then is sent over the Platform's JBossESB to selected services. The soap-request.xml file defines the SOAP request that is sent.

1:  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:good="http://security_saml/goodbyeworld" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">  
2:    <soapenv:Header>  
3:      <wsse:Security>  
4:     <wsse:UsernameToken>  
5:      <wsse:Username>admin</wsse:Username>  
6:      <wsse:Password>admin</wsse:Password>  
7:     </wsse:UsernameToken>  
8:    </wsse:Security>  
9:    </soapenv:Header>  
10:    <soapenv:Body>  
11:      <good:sayGoodbye>  
12:       <message>Goodbye!!</message>  
13:      </good:sayGoodbye>  
14:    </soapenv:Body>  
15:   </soapenv:Envelope>

Lines 4-7 - These are the lines that we're interested in for this file. The "UsernameToken" security header information is used by the STSIssuingLoginModule as the username/credential for the user for whom a security token should be issued.

Speaking of the STSIssuingLoginModule, let's shift gears and look at the "quickstart-specific-assemblies" ant target in the build.xml file. This target is called when the quickstart is deployed.

1:   <target name="quickstart-specific-assemblies">  
2:     <!-- Overriden from the target of the same name in base-build.xml. -->  
3:     <!-- Called by the "deploy" target. Don't call directly!! -->  
4:    
5:     <!-- Build the webservice... -->  
6:       <war warfile="build/${ant.project.name}.war"  
7:         webxml="${basedir}/war/resources/WEB-INF/web.xml">  
8:         <fileset dir="${basedir}/war/view">  
9:           <include name="**/*"/>  
10:         </fileset>  
11:       </war>  
12:    
13:       <copy file="${basedir}/login-config-unfiltered.xml" tofile="${basedir}/login-config.xml" filtering="true" overwrite="true">  
14:               <filterset>  
15:                   <filter token="STS_CONFIG_FILE_PATH" value="${basedir}/picketlink-sts-client.properties"/>  
16:               </filterset>  
17:           </copy>  
18:     </target>

Lines 6-11 create the .war file that is used to deploy the quickstart's target web service. We'll come back to this service in a bit.
For now, let's look at the element on lines 13-17. What's happening here is that the login-config-unfiltered.xml file is used as a template to create a login-config.xml file that will be used by the quickstart's services. The processing of the element replaces the "STS_CONFIG_FILE_PATH" string in login-config-unfiltered.xml with the value defined in line 44.

What's the point of doing this templating? After all, why not just edit the login-config.xml file directly? It's a safety measure and is typically used with ant to build a project so that you can easily and safely make changes to a project and perhaps several configuration files with one command. This is much safer than trying to remember all the places that you have to edit the same information.

In our case, this results in a login-config.xml file that looks like this:

1:  <policy>  
2:      <application-policy name="saml-issue-token">  
3:      <authentication>  
4:        <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">  
5:          <module-option name="configFile">/jboss/local/502_CR3_signed/jboss-soa-p.5.0.0/jboss-as/samples/quickstarts/security_saml/picketlink-sts-client.properties</module-option>  
6:          <module-option name="endpointURI">http://security_saml/goodbyeworld</module-option>  
7:          <module-option name="password-stacking">true</module-option>  
8:        </login-module>  
9:        <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">  
10:           <module-option name="configFile">/jboss/local/502_CR3_signed/jboss-soa-p.5.0.0/jboss-as/samples/quickstarts/security_saml/picketlink-sts-client.properties</module-option>  
11:           <module-option name="password-stacking">useFirstPass</module-option>  
12:         </login-module>  
13:       </authentication>  
14:     </application-policy>  
15:    
16:     <application-policy name="saml-validate-token">  
17:       <authentication>  
18:         <login-module code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">  
19:           <module-option name="configFile">/jboss/local/502_CR3_signed/jboss-soa-p.5.0.0/jboss-as/samples/quickstarts/security_saml/picketlink-sts-client.properties</module-option>  
20:           <module-option name="useOptionsCredentials">true</module-option>  
21:         </login-module>  
22:       </authentication>  
23:     </application-policy>  
24:   </policy>

What's happening in this file? We're defining security domains. Remember how we talked about the quickstart demonstrating how to either issue (produce) or validate (consume) a SAML Security Token. Each has an applicaiton policy defined. For JBoss servers, security domains are configured with elements files named "login-config.xml."

Line 2 - Here's the start of the domain that is used to issue the SAML Security Token.
Line 4 - A reference to the STSIssuingLoginModule that we discussed earlier.
Line 5 - And here's a pointer to the picketlink-sts-client.properties file that we discussed a minute ago. (Yes, all these configuration files do tie together.)
Line 6 - The endpoint of the target web service is: http://security_saml/goodbyeworld - note that the endpointURI in STS properties is actually just the "domain" to which the security token will be applicable. Imagine you have two systems where access to one does not necessarily imply access to the other, yet they both want to use the same STS. You would look at the endpointURI to verify the token is for the relevant system. The system itself may include many web services that are secured as a collective.
Line 7 - Each login module gets a shared map. When the "password-stacking" option is set to "useFirstPass," with this option, the login module looks for username/pass in that shared map instead of using the callback handler.
Line 9 - And, here's the start of the domain that is used to validate the SAML Security Token.
Line 16 - And here's the start of the domain that is used to validate the SAML Security Token.
Line 20 - What's interesting to note here is the use of the "useOptionsCredentials" login module. Unlike "password-stacking," this option causes the login module to use credentials from its properties file. In the case of our quickstart, this is the picketlink-sts-client.properties file. In this context, "true" allows the login module to store the password in the shared map, in anticipation of its later use by another login module through "useFirstPass".

OK, our login credentials are happily defined. What's next? The security domains defined in login-config are static. They are read by the server when the server is started or an application is deployed. Let's look now at the jboss-service.xml file:

1:  <server>  
2:    <mbean code="org.jboss.security.auth.login.DynamicLoginConfig" name="org.jboss.esb.samples.quickstarts.security_saml:service=LoginModule">  
3:      <attribute name="AuthConfig">login-config.xml</attribute>  
4:      <depends optional-attribute-name="LoginConfigService">jboss.security:service=XMLLoginConfig</depends>  
5:      <depends optional-attribute-name="SecurityManagerService">jboss.security:service=JaasSecurityManager</depends>  
6:    </mbean>  
7:  </server>  
8:

Line 2 - As its name indicates, org.jboss.security.auth.login.DynamicLoginConfig enables us to dynamically deploy a security domain. In the case of our quickstart, the MBean makes use of the XMLLoginConfig service (line 4) and the SecurityManagerService (line 5).

And the last of the security-related is the jboss-wsse-client.xml file. This file defines the JBoss WebService configuration that the quickstart client will use to access the web service. The configuration defined in this file will cover all requests sent by the client, and all responses received by the client. Note that this has really nothing to do with SAML/STS. The quickstart has configured the ESB service to support WS-Security UsernameToken, so that we can then use this user/password to authenticate against STS and request a token.

1:  <?xml version="1.0" encoding="UTF-8"?>  
2:  <jboss-ws-security xmlns="http://www.jboss.com/ws-security/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
3:   xsi:schemaLocation="http://www.jboss.com/ws-security/config http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">  
4:   <config>  
5:     <username/>  
6:   </config>  
7:  </jboss-ws-security>

Lines 4-6 - This config element indicates that all requests and responses must contain a username.

For more information on Web Service Security, see: http://docs.sun.com/source/819-0788/xwss2.html, http://community.jboss.org/wiki/WSSecurityConfig, http://community.jboss.org/wiki/jbossws-ws-securityoptions

Group #2 - Test data related files

We discussed the soap-request.xml a few minutes ago. Let's look at the smooks-saml-injector-template.xml and smooks-saml-injector.xml files now. These files are used to transform a message, to inject the SAML assertion into a SOAP message that is sent using WS Security.

As its name indicates, the smooks-saml-injector-template.xml file is a temlplate and is used by the smooks-saml-injector.xml file. Let's look at smooks-saml-injector.xml

1:   <?xml version="1.0"?>  
2:   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd">  
3:    
4:     <import file="smooks-saml-injector-template.xml">  
5:     <param name="selector">/Envelope/Header/Security</param>  
6:     <param name="selectorNamespace">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</param>  
7:     <param name="securityNamespace">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</param>  
8:     <param name="headerNamespace">http://schemas.xmlsoap.org/soap/envelope/</param>  
9:   </import>  
10:      
11:    <import file="smooks-saml-injector-template.xml">  
12:      <param name="selector">/Envelope/Header</param>  
13:      <param name="selectorNamespace">http://schemas.xmlsoap.org/soap/envelope/</param>  
14:      <param name="securityNamespace">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</param>  
15:      <param name="headerNamespace">http://schemas.xmlsoap.org/soap/envelope/</param>  
16:      <param name="addXmlNs">false</param>  
17:    </import>  
18:     
19:   </smooks-resource-list>

What we see in this file are two separate elements. Each defines the selector, security and header namespaces that are used to define the security domain. But, what's the reason behind the second ? And why does it refer to http://schemas.xmlsoap.org/soap/envelope instead of http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd? The reason is that sometimes there is no need to inject the namespaces as the wsse:security may be qualified already. That's the reason for the second block.

Before we look at group #3 (the ESB related files), let's take a look at the web service and the web service client used by the quickstart .

The web service itself is pretty basic - it's defined in GoodbyeWorldWS.java

1:   package org.jboss.soa.esb.samples.quickstart.securitysaml.webservice;  
2:    
3:   import javax.jws.WebService;  
4:   import javax.jws.WebMethod;  
5:   import javax.jws.Oneway;  
6:   import javax.jws.WebParam;  
7:   import javax.jws.HandlerChain;  
8:   import javax.jws.soap.SOAPBinding;  
9:    
10:   import org.jboss.soa.esb.message.Message;  
11:   import org.jboss.soa.esb.message.Body;  
12:   import org.jboss.soa.esb.actions.ActionUtils;  
13:   import org.jboss.soa.esb.actions.soap.SOAPProcessor;  
14:    
15:   @HandlerChain(file="handlerchain.xml")  
16:   @WebService(name = "GoodbyeWorldWS", targetNamespace="http://security_saml/goodbyeworld")  
17:   public class GoodbyeWorldWS {  
18:    
19:     @WebMethod  
20:     public String sayGoodbye(@WebParam(name="message") String message) {  
21:       Message esbMessage = SOAPProcessor.getMessage();  
22:       System.out.println("Succesfully invoked WS!");  
23:       System.out.println("SOAPRequest perhaps mediated by ESB:\n" + esbMessage.getBody().get());  
24:       return "... Ah Goodbye then!!!! - " + message;  
25:     }  
26:    
27:     @WebMethod  
28:     public String sayAdios(String message) {  
29:       Message esbMessage = SOAPProcessor.getMessage();  
30:       if(esbMessage != null) {  
31:         System.out.println("**** SOAPRequest perhaps mediated by ESB:\n" + esbMessage.getBody().get());  
32:       }  
33:       System.out.println("Web Service Parameter - message=" + message);  
34:       return "... Adios Amigo!!!! - " + message;  
35:     }  
36:       
37:     @WebMethod  
38:     @Oneway  
39:     public void sayGoodbyeWithoutResponse(@WebParam(name="message") String message) {  
40:    
41:       Message esbMessage = SOAPProcessor.getMessage();  
42:       if(esbMessage != null) {  
43:         System.out.println("**** SOAPRequest perhaps mediated by ESB:\n" + esbMessage.getBody().get());  
44:       }  
45:       System.out.println("Web Service Parameter - message=" + message);  
46:     }  
47:       
48:   }

If this program looks more like a POJO (a "plain old java object") with annotations than a web service, well, you're correct!

One of the features of the JBossESB in the SOA Platform is how it enables you to easily expose a web service's endpoints on the ESB. To do this, you write a "service wrapper webservice" that conforms to the JSR 181 ("Web Services Metadata for the Java Platform") standard. JSR 181 enables you to create webservices from a POJO by adding annotations such as @WebService and @WebMethod to it. This service wrapper webservice wraps calls to your service and exposes that service through JBossESB listeners. Your service can also be accessed through other transports (FTP, JMS, etc.) supported by the JBossESB in the SOA Platform. These 3 types of JBossWS webservice endpoints can be exposed through JBoss ESB listeners using this action:

Webservice bundled into a JBossESB .esb archive - When the webservice .war is bundled into a deployed .esb archive
Webservice bundled into an .ear - When the .war is bundled into a deployed .ear
Standalone webservice - When the webservice .war is deployed

When we examine the jboss-esb.xml file, we'll see that the JBossESB's SOAPProcessor (org.jboss.soa.esb.actions.soap.SOAPProcessor) is used to expose the web service's -endpoints.

But wait, there's more!

On line 15, we see this annotation: @HandlerChain(file="handlerchain.xml")

A handler is a message interceptor to do processing of incoming and outgoing messages. SOAP handlers provide methods to access SOAP messages.
A HandlerChain is a list of handlers. The handlerchain referenced on line 15 is defined as follows in the handlerchain.xml file.

1:   <?xml version="1.0" encoding="UTF-8"?>  
2:   <jws:handler-config xmlns:jws="http://java.sun.com/xml/ns/javaee">  
3:       <jws:handler-chains>  
4:           <jws:handler-chain>  
5:               <jws:handler>  
6:                   <jws:handler-class>org.picketlink.identity.federation.core.wstrust.handlers.STSSaml20Handler</jws:handler-class>  
7:               </jws:handler>  
8:           </jws:handler-chain>  
9:       </jws:handler-chains>  
10:   </jws:handler-config>

Line 6 - What's interesting in this file is line 6. The org.picketlink.identity.federation.core.wstrust.handlers.STSSaml20Handler handler class enables the quickstart to insert the SAML security assertion into the message as it is processed by the web service.

OK. That's the web service. Now let's look at the quickstart's client code in HttpClient.java

1:  package org.jboss.soa.esb.samples.quickstart.securitysaml.test;  
2:    
3:  import org.jboss.remoting.Client;  
4:  import org.jboss.remoting.InvokerLocator;  
5:  import org.jboss.internal.soa.esb.util.StreamUtils;  
6:  import org.jboss.remoting.transport.http.HTTPMetadataConstants;  
7:    
8:  import java.util.HashMap;  
9:  import java.util.Map;  
10:    
11:  public class HttpClient  
12:  {  
13:    // Default locator values  
14:    private static String transport = "http";  
15:    private static String host = "localhost";  
16:    private static int port = 5400;  
17:    private static String payload;  
18:    
19:    public void makeInvocation(String locatorURI) throws Throwable  
20:    {  
21:     InvokerLocator locator = new InvokerLocator(locatorURI);  
22:     System.out.println("Calling remoting server with locator uri of: " + locatorURI);  
23:    
24:     Client remotingClient = new Client(locator);  
25:     remotingClient.connect();  
26:    
27:     Map metadata = new HashMap();  
28:     metadata.put("TYPE", "POST");  
29:     remotingClient.invokeOneway(payload, metadata );  
30:    
31:     System.out.println("Sent http post to server.");  
32:     Integer responseCode = (Integer) metadata.get(HTTPMetadataConstants.RESPONSE_CODE);  
33:     String responseMessage = (String) metadata.get(HTTPMetadataConstants.RESPONSE_CODE_MESSAGE);  
34:     System.out.println("Response code from server: " + responseCode);  
35:     System.out.println("Response message from server: " + responseMessage);  
36:     remotingClient.disconnect();  
37:    
38:    }  
39:    
40:    public static void main(String[] args) throws Exception  
41:    {  
42:     if(args != null && args.length == 4)  
43:     {  
44:       transport = args[0];  
45:       host = args[1];  
46:       port = Integer.parseInt(args[2]);  
47:           payload = StreamUtils.getResourceAsString(args[3], "UTF-8");  
48:     }  
49:     String locatorURI = transport + "://" + host + ":" + port;  
50:     HttpClient client = new HttpClient();  
51:     try  
52:     {  
53:       client.makeInvocation(locatorURI);  
54:     }  
55:     catch(Throwable e)  
56:     {  
57:       e.printStackTrace();  
58:     }  
59:    }  
60:  }

There's nothing unusual here as the client simply sends an HTTP POST request to a target URL. How does this client get executed? Through this target defined in the build.xml file.

1:  <target name="runtest" depends="compile"  
2:   description="sends a HTTP request to the JBossRemoting gateway">  
3:    <echo>Http Client</echo>  
4:   <java fork="yes" classname="org.jboss.soa.esb.samples.quickstart.securitysaml.test.HttpClient" failonerror="true">  
5:     <arg value="http"/>  
6:     <arg value="localhost"/>  
7:     <arg value="9888"/>  
8:     <arg value="soap-request.xml"/>  
9:     <classpath refid="exec-classpath"/>  
10:   </java>  
11:  </target>  
12:

Line 7 - OK. There's nothing unusual here either. Or, is there? Look at line #7. Where did port 9888 get defined? After all, the the server is running on port 8080. We'll find the answer when we examine the quickstart's jboss-esb.xml file next.

(And, last of all, the DisplaySubjectAction.java class is a customer ESB action called by services to display the javax.security.auth.Subject extracted from the message.)

Group #3 - ESB archive related files

The deployment.xml, jbm-queue-service.xml, and jbmq-queue-service.xml files all reference the JMS queues and topics that will be needed by the quickstart. The jbossesb-properties.xml file is used to define properties used by the quickstart and to over-ride server-wide settings.

The file that we want to look at in detail is jboss-esb.xml. This file defines the quickstart's services configuration, including listeners and actions, and the providers.

(Note that while we'll be examining most of the contents of the jboss-esb.xml file in detail, we'll be doing it in pieces or fragments so that it's easier to follow. The line numbers in each of these fragments will therefore be different from the actual (whole) file.)

Let's start with the providers. As the name indicates, these elements define resources provided by by the ESB to the quickstart.

1:  <providers>  
2:     <jms-provider name="JBossMessaging" connection-factory="ConnectionFactory">  
3:       <jms-bus busid="quickstartGatewayChannel">  
4:         <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_security_saml_gw"/>  
5:      </jms-bus>  
6:      <jms-bus busid="quickstartEsbChannel">  
7:        <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_security_saml_esb"/>  
8:      </jms-bus>  
9:    </jms-provider>  
10:      
11:     <jbr-provider name="JBR-Http" protocol="http" host="localhost">  
12:          <jbr-bus busid="Http-1" port="9888" />  
13:     </jbr-provider>  
14:      
15:  </providers>

Line 2 - Here's the start of the JMS provider. This is where we will see the definitions of JMS queues and topics.
Line 3 - Note that each queue has a "busid" value defined for it. We'll see the busid's used in the service definitions in a moment.
Line 7 - Remember how we discussed how each ESB-unaware queue required a corresponding ESB-aware queue to be defined?
Line 11 - This is the definition for a JBoss remoting provider. This makes use of JBoss Remoting (JBR) into JBoss ESB as a transport option and supports HTTP (and SSL, which we're not using in this quickstart). What's interesting here is that the jbr-provider enables us to define the port (remember how we saw the reference to port 9888 in the "runtest" ant target in the build.xml file?) that the provider provides (pardon the pun) to a service.

The remainder of the jboss-esb.xml file defines the quickstart's (3) services. We'll look at the configuration of the services now, and then we'll look at the actual operation of the services when we walk through what happens when we run the quickstart.

1:  <service category="SamlSecurityQuickstart" name="issueTokenService"  
2:      invmScope="GLOBAL"  
3:      description="This service demonstrates how a service can be configured to issue and validate a security token">  
4:      
5:      <security moduleName="saml-issue-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSIssueCallbackHandler">  
6:        <!-- disable the security context timeout so that our security context is re-evaluated -->  
7:        <property name="org.jboss.soa.esb.services.security.contextTimeout" value="0"/>  
8:      </security>  
9:      
10:     <listeners>  
11:       <jms-listener name="JMSGatewayListener" busidref="quickstartGatewayChannel" is-gateway="true"/>  
12:         <jbr-listener name="Http-Gateway" busidref="Http-1" is-gateway="true">  
13:           <property name="synchronous" value="false"/>  
14:         </jbr-listener>  
15:    </listeners>  
16:     
17:   <actions mep="OneWay">  
18:      
19:      <!-- Uncomment if you'd like to print the current Subject  
20:        <action name="printSubject" class="org.jboss.soa.esb.samples.quickstart.securitysaml.DisplaySubjectAction"/>  
21:        -->  
22:       
23:      <action name="routeAction" class="org.jboss.soa.esb.actions.StaticRouter">  
24:        <property name="destinations">  
25:          <route-to service-category="SamlSecurityQuickstart" service-name="securedSamlService"/>  
26:        </property>  
27:      </action>  
28:      
29:    </actions>  
30:  </service>

Line 1: Service name and category are used to differentiate the services. Every service has a category and name attribute. JBossESB uses these attributes to register a service's listeners (gateway listeners or ESB-aware listeners) endpoints in a service registry.
Line 2 - The InVM transport enables services to communicate using the same JVM and without having to go through a second non-gateway provider. This makes things more efficient as the services don't have use any networking protocols between JVM instances. The "GLOBAL" value indicates that the this service can be invoked using the InVM transport using the same JVM.
Line 5 - Remember how we defined the appplication-policy name in login-config.xml? (Hint: The policy name was "saml-issue-token.") That's right. This is the moduleName. The callbackHandler defined here overrides the one defined in jbossesb-properties.xml. Remember that the username and password can be provided by a callback. In the case of this service the callback is JBossSTSIssueCallbackHandler. The callback handler retreives the username and password of the user for whom a security token should be issued.
Line 7 - Setting the org.jboss.soa.esb.services.security.contextTimeout property to zero ensures that every time the service is invoked the security context is re-evaluated.
Line 10 - Here's where the definition of the services listeners begins. These are well-named as they "listen" for incoming messages, based on the designated queue and protocol.
Line 12 - Remember how we reviewed the "Http-1" busidref in the "providers" section of the jboss-esb file? Well, here's where it's used. The JMS queue associated with this busidref is "listened to" for incoming messages. When a message is received, the service's action pipeline (in this case a pipeline of only one action) is executed. The reference to "gateway" indicates that the message originates outside of the ESB and is passed into the ESD through this "gateway."
Line 17 - The service's actions' definitions start here. The message exchange pattern (or "mep" for short) is asynchronous as the service will not wait for a response before moving on.
Line 20 - We'll uncomment this line later on so we can see the security subject displayed in the server log.
Line 25 - What happens to the message after the service issues the security assert? It's routed to the next service defined in the jboss-esb.xml file. In this case it's a static route, but the ESB actually supports other routing options too, including content based routing. (http://jboss-soa-p.blogspot.com/2009/07/when-content-knows-way-content-based.html)

Next, let's look at the service to which the first service routes messages.

1:  <service category="SamlSecurityQuickstart" name="securedSamlService"  
2:    invmScope="GLOBAL"  
3:    description="This service demonstrates that an ESB service can be configured to only validate a security token.">  
4:      
5:    <security moduleName="saml-validate-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSTokenCallbackHandler">  
6:        <!-- disable the security context timeout so that our security context is re-evaluated -->  
7:        <property name="org.jboss.soa.esb.services.security.contextTimeout" value="0"/>  
8:    </security>  
9:      
10:    <actions mep="OneWay">  
11:      
12:      <!-- Uncomment if you'd like to print the current Subject  
13:         <action name="printSubject" class="org.jboss.soa.esb.samples.quickstart.securitysaml.DisplaySubjectAction"/>  
14:      -->  
15:      
16:      <action name="routeAction" class="org.jboss.soa.esb.actions.StaticRouter">  
17:        <property name="destinations">  
18:          <route-to service-category="SamlSecurityQuickstart" service-name="sendExternal"/>  
19:        </property>  
20:     </action>  
21:      
22:    </actions>  
23:  </service>

There are two interesting lines in this service definition.

Line 5 - In contrast to the first service, this service uses the org.jboss.soa.esb.services.security.auth.login.JBossSTSTokenCallbackHandler class as a call back handler.
Line 18 - Routes the message to the next service.

1:  <service category="SamlSecurityQuickstart" name="sendExternal"  
2:    invmScope="GLOBAL"  
3:    description="This service demonstrates that an ESB service can be configured to only validate a security token and call an external WS with the security token.">  
4:      
5:    <security moduleName="saml-validate-token" callbackHandler="org.jboss.soa.esb.services.security.auth.login.JBossSTSTokenCallbackHandler"/>  
6:      
7:    <actions mep="OneWay">  
8:      
9:      <!-- Uncomment if you'd like to print the current Subject  
10:       <action name="printSubject" class="org.jboss.soa.esb.samples.quickstart.securitysaml.DisplaySubjectAction"/>  
11:     -->  
12:      
13:     <action name="addSamlSecurityHeader" class="org.jboss.soa.esb.smooks.SmooksAction">  
14:       <property name="smooksConfig" value="/smooks/smooks-saml-injector.xml" />  
15:     </action>  
16:      
17:     <action name="JBossWSAdapter" class="org.jboss.soa.esb.actions.soap.SOAPProcessor">  
18:       <property name="jbossws-endpoint" value="GoodbyeWorldWS"/>  
19:     </action>  
20:      
21:   </actions>  
22:  </service>

What's different from the second service in this service is:

Lines 13-15 - This action invokes the Smooks script to inject the SAML assert into the message.
Lines 17-18 - And finally, the target web service is invoked via the org.jboss.soa.esb.actions.soap.SOAPProcessor out of the box JBossESB action.

Running the Quickstart

OK - let's run the quickstart and watch it in action. Running the quickstarts is a deceptively simple task in that they generally requires only a small number of steps to execute. In the case of the security_saml quickstart, we only have to execute these (2) ant commands:

1:  ant deploy  
2:  ant runtest

But - hang on - let's examine in detail just what each command actually does.

ant deploy

Many of the quickstarts require some "set up" work in order to run. In the case of the security_saml quickstart this set up involves deploying not only the quickstart, but also the PicketLink Security Token Server (STS) .war file that is included in the quickstart. Here's the deploy target in the quickstart's build.xml file.

1:  <target name="quickstart-specific-predeploys">  
2:    <copy file="${basedir}/picketlink-sts.war" todir="${org.jboss.esb.server.deploy.dir}"/>  
3:  </target>

Here's the server log when the quickstart is deployed.

1:  23:04:13,512 INFO [TomcatDeployment] undeploy, ctxPath=/Quickstart_Security_Saml  
2:  23:04:13,547 INFO [EsbDeployment] Stopping 'Quickstart_Security_Saml.esb'  
3:  23:04:13,837 INFO [Http11Protocol] Stopping Coyote HTTP/1.1 on http-localhost%2F127.0.0.1-9888  
4:  23:04:13,844 INFO [JBossRemotingGatewayListener] JBoss Remoting Gateway listener 'listener' stopped.  
5:  23:04:14,075 INFO [EsbDeployment] Destroying 'Quickstart_Security_Saml.esb'  
6:  23:04:14,075 WARN [ServiceMessageCounterLifecycleResource] Calling cleanup on existing service message counters for identity ID-6  
7:  23:04:14,075 WARN [SmooksResource] Closing smooks resources for identity ID-6  
8:  23:04:14,213 INFO [QueueService] Queue[/queue/quickstart_security_saml_esb_reply] stopped  
9:  23:04:14,215 INFO [QueueService] Queue[/queue/quickstart_security_saml_esb] stopped  
10:  23:04:14,216 INFO [QueueService] Queue[/queue/quickstart_security_saml_gw] stopped  
11:  23:04:14,487 INFO [QueueService] Queue[/queue/quickstart_security_saml_gw] started, fullSize=200000, pageSize=2000, downCacheSize=2000  
12:  23:04:14,518 INFO [QueueService] Queue[/queue/quickstart_security_saml_esb] started, fullSize=200000, pageSize=2000, downCacheSize=2000  
13:  23:04:14,550 INFO [QueueService] Queue[/queue/quickstart_security_saml_esb_reply] started, fullSize=200000, pageSize=2000, downCacheSize=2000  
14:  23:04:14,571 INFO [EsbDeployment] Starting ESB Deployment 'Quickstart_Security_Saml.esb'  
15:  23:04:15,870 INFO [CoyoteInvoker] Using org.apache.coyote.http11.Http11Protocol for http (coyote) invoker protocol handler.  
16:  23:04:15,871 INFO [Http11Protocol] Initializing Coyote HTTP/1.1 on http-localhost%2F127.0.0.1-9888  
17:  23:04:15,871 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-localhost%2F127.0.0.1-9888  
18:  23:04:15,871 INFO [JBossRemotingGatewayListener] JBoss Remoting Gateway listener 'listener' started.  
19:  23:04:16,090 INFO [TomcatDeployment] deploy, ctxPath=/Quickstart_Security_Saml

Remember the JBoss Remoting Gateway that we configured to run on port 9888? Here it is:

1:  23:04:15,871 INFO [Http11Protocol] Initializing Coyote HTTP/1.1 on http-localhost%2F127.0.0.1-9888  
2:  23:04:15,871 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-localhost%2F127.0.0.1-9888  
3:  23:04:15,871 INFO [JBossRemotingGatewayListener] JBoss Remoting Gateway listener 'listener' started.

OK, let's run the quickstart and watch it in action!

1:  runtest:  
2:     [echo] Http Client  
3:     [java] Calling remoting server with locator uri of: http://localhost:9888  
4:     [java] Sent http post to server.  
5:     [java] Response code from server: 200  
6:     [java] Response message from server: OK

Well - that's a bit anti-climatic after all this setup work. Let's and take a more in-depth look at what just happened.

The quickstart begins by sending a message to the JBR-remoting gateway that we defined on port 9888. We can see this in the build.xml file:

1:  <target name="runtest" depends="compile"  
2:    description="sends a HTTP request to the JBossRemoting gateway">  
3:    <echo>Http Client</echo>  
4:    <java fork="yes" classname="org.jboss.soa.esb.samples.quickstart.securitysaml.test.HttpClient" failonerror="true">  
5:       <arg value="http"/>  
6:       <arg value="localhost"/>  
7:       <arg value="9888"/>  
8:       <arg value="soap-request.xml"/>  
9:       <classpath refid="exec-classpath"/>  
10:    </java>  
11:  </target>

At this point, we'll un-comment the lines in the jboss-esb.xml file that invoke the org.jboss.soa.esb.samples.quickstart.securitysaml.DisplaySubjectAction - and we'll restart the server with logging set to the DEBUG level. If you spend your time developing or testing software, then the ability to "up" the logging level provides you with a goal mine of potential debugging information. Note that for the purposes of this essay, we'll look at selected log messages as logging at the DEBUG level can be very(!) verbose.

The first service defined in the jboss-esb.xml ("issueTokenService") file is located:

1:  2010-09-07 20:46:43,801 DEBUG [org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl] (JBossRemoting Server Oneway(3)-1) Going to query the registry for name pattern [issueTokenService]  
2:  2010-09-07 20:46:43,898 DEBUG [org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl] (JBossRemoting Server Oneway(3)-1) Service name: issueTokenService  
3:  2010-09-07 20:46:43,898 DEBUG [org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl] (JBossRemoting Server Oneway(3)-1) Description: This service demonstrates how a service can be configured  
4:   to issue and validate a security token

The incoming message is received by the JBR gateway:

1:  2010-09-07 20:46:43,898 DEBUG [org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl] (JBossRemoting Server Oneway(3)-1) Key id: uddi:juddi.apache.org:1e71f7ae-e72d-4a38-a39c-cad7c1b1d250  
2:  2010-09-07 20:46:43,900 DEBUG [org.jboss.soa.esb.client.ServiceInvoker] (JBossRemoting Server Oneway(3)-1) EPR=InVMEpr [ PortReference < <wsa:Address  
3:  invm://53616d6c5365637572697479517569636b73746172742424242424242424242424246973737565546f6b656e53657276696365/false?false#10000/>, <wsa:ReferenceProperties jbossesb:passByValue :  
4:  false/>, <wsa:ReferenceProperties jbossesb:type : urn:jboss/esb/epr/type/invm/> > ] XML=<wsa:From xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"><wsa:Address>invm:  
5:  //53616d6c5365637572697479517569636b73746172742424242424242424242424246973737565546f6b656e53657276696365/false?false#10000</wsa:Address><wsa:ReferenceProperties>  
6:  <jbossesb:passByValue xmlns:jbossesb="http://schemas.jboss.com/ws/2007/01/jbossesb">false</jbossesb:passByValue><jbossesb:type xmlns:jbossesb="http://schemas.jboss.com/ws/2007  
7:  /01/jbossesb">urn:jboss/esb/epr/type/invm</jbossesb:type></wsa:ReferenceProperties></wsa:From>  
8:  2010-09-07 20:46:43,907 DEBUG [org.jboss.soa.esb.client.ServiceInvoker] (JBossRemoting Server Oneway(3)-1) EPR=EPR: PortReference < <wsa:Address http://localhost:9888/> > XML=<wsa:From  
9:  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"><wsa:Address>http://localhost:9888</wsa:Address></wsa:From>  
10:  2010-09-07 20:46:43,924 DEBUG [org.jboss.soa.esb.filter.FilterManager] (JBossRemoting Server Oneway(3)-1) FilterManager calling org.jboss.internal.soa.esb.message.filter.MetaDataFilter@8e85e1.onOutput  
11:  2010-09-07 20:46:43,924 DEBUG [org.jboss.soa.esb.filter.FilterManager] (JBossRemoting Server Oneway(3)-1) FilterManager calling org.jboss.internal.soa.esb.message.filter.GatewayFilter@f77a23.onOutput

And the message is passed to the ESB-aware queue:

1:  2010-09-07 20:46:43,924 DEBUG [org.jboss.internal.soa.esb.couriers.transport.InVMTransport] (JBossRemoting Server Oneway(3)-1) Delivering message to 53616d6c5365637572697479517569636b73746172742424242424242424242424246973737565546f6b656e53657276696365  
2:  2010-09-07 20:46:43,924 DEBUG [org.jboss.internal.soa.esb.couriers.transport.InVMTransport] (JBossRemoting Server Oneway(3)-1) Delivering message direct to 53616d6c5365637572697479517569636b73746172742424242424242424242424246973737565546f6b656e53657276696365 queue  
3:  2010-09-07 20:46:43,926 DEBUG [org.jboss.internal.soa.esb.couriers.transport.InVMTransport] (Thread-29) Pickup of message from 53616d6c5365637572697479517569636b73746172742424242424242424242424246973737565546f6b656e53657276696365

The assert is created:

1:  2010-09-07 20:46:46,078 DEBUG [org.picketlink.identity.federation.core.wstrust.auth.AbstractSTSLoginModule] (pool-24-thread-1) Added Credential :SamlCredential[<Assertion  
2:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" ID="ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185"  
3:  IssueInstant="2010-09-08T00:46:45.294Z" Version="2.0"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">PicketLinkSTS</Issuer><Subject xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><NameID  
4:   NameQualifier="urn:picketlink:identity-federation" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">admin</NameID><SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"  
5:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/></Subject><Conditions NotBefore="2010-09-08T00:46:45.294Z" NotOnOrAfter="2010-09-08T02:46:45.294Z"  
6:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><AudienceRestriction xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Audience xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://security_saml  
7:  /goodbyeworld</Audience></AudienceRestriction></Conditions><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:SignedInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">  
8:  <dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:SignatureMethod  
9:  Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:Reference URI="#ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185"  
10:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transforms xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-  
11:  signature" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" xmlns:dsig="http://www.w3.org/2000/09  
12:  /xmldsig#"/><dsig:DigestValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">mcisCWAF28n4AQVYf1OEzeotBFA=</dsig:DigestValue></dsig:Reference></dsig:SignedInfo><dsig:SignatureValue  
13:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">GyX1b4gN/lEiu6wbdddL4uSgPu2uyPALiYgKlCvOScnEBimO62ctj0lRWMVOlNywqso9TcqFS7fb  
14:  4fjbHif/m3S7mFfq+HhRlr3+StTtz9XWFoO/vn2twSKuwToX156RwzGlT4NvMAapmJI474uvValN  
15:  /HcLLHpqB2GI1XwD0kg=</dsig:SignatureValue><dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:KeyValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:RSAKeyValue  
16:   xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Modulus xmlns:dsig="http://www.w3.org/2000/09  
17:  /xmldsig#">suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1  
18:  dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKw  
19:  lYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo>  
20:  </dsig:Signature></Assertion>]  
21:  2010-09-07 20:46:46,081 DEBUG [org.jboss.internal.soa.esb.services.security.PrivateCryptoUtil] (pool-24-thread-1) SealAlgorithm 'TripleDES' keySize '168'  
22:  2010-09-07 20:46:46,173 DEBUG [org.jboss.soa.esb.listeners.message.ActionProcessingPipeline] (pool-24-thread-1) executing processor 0  
23:  org.jboss.soa.esb.listeners.message.OverriddenActionLifecycleProcessor@1ae20eb

The issueTokenService displays the subject assert:

1:  2010-09-07 20:46:46,175 INFO [STDOUT] (pool-24-thread-1) Subject in MyListenerAction : Subject:  
2:    Public Credential: SamlCredential[<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#"  
3:  ID="ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185" IssueInstant="2010-09-08T00:46:45.294Z" Version="2.0"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">PicketLinkSTS</Issuer><Subject  
4:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><NameID NameQualifier="urn:picketlink:identity-federation" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">admin</NameID><SubjectConfirmation  
5:  Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/></Subject><Conditions NotBefore="2010-09-08T00:46:45.294Z"  
6:  NotOnOrAfter="2010-09-08T02:46:45.294Z" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><AudienceRestriction xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Audience  
7:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://security_saml/goodbyeworld</Audience></AudienceRestriction></Conditions><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">  
8:  <dsig:SignedInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments" xmlns:dsig="http://www.w3.org  
9:  /2000/09/xmldsig#"/><dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:Reference URI="#ID_bc96b4b9-0743-49ca-  
10:  8e32-b0bd3cd80185" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transforms xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transform Algorithm="http://www.w3.org/2000/09  
11:  /xmldsig#enveloped-signature" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"  
12:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:DigestValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">mcisCWAF28n4AQVYf1OEzeotBFA=</dsig:DigestValue></dsig:Reference>  
13:  </dsig:SignedInfo><dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">GyX1b4gN/lEiu6wbdddL4uSgPu2uyPALiYgKlCvOScnEBimO62ctj0lRWMVOlNywqso9TcqFS7fb  
14:  4fjbHif/m3S7mFfq+HhRlr3+StTtz9XWFoO/vn2twSKuwToX156RwzGlT4NvMAapmJI474uvValN  
15:  /HcLLHpqB2GI1XwD0kg=</dsig:SignatureValue><dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:KeyValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:RSAKeyValue  
16:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Modulus xmlns:dsig="http://www.w3.org/2000/09  
17:  /xmldsig#">suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1  
18:  dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKw  
19:  lYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo>  
20:  </dsig:Signature></Assertion>]  
21:  2010-09-07 20:46:46,178 DEBUG [org.jboss.soa.esb.listeners.message.ActionProcessingPipeline] (pool-24-thread-1) executing processor 1 org.jboss.soa.esb.actions.StaticRouter@826935

The message is routed to the 2nd service "securedSamlService"):

1:  2010-09-07 20:46:46,179 DEBUG [org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl] (pool-24-thread-1) Going to query the registry for name pattern [securedSamlService]

Where the assert is validated:

1:  2010-09-07 20:46:46,791 DEBUG [org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule] (pool-25-thread-1) Validation result: true

And the subject is displayed again:

1:  2010-09-07 20:46:46,833 INFO [STDOUT] (pool-25-thread-1) Subject in MyListenerAction : Subject:  
2:    Public Credential: SamlCredential[<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#"  
3:   ID="ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185" IssueInstant="2010-09-08T00:46:45.294Z" Version="2.0"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">PicketLinkSTS</Issuer><Subject  
4:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><NameID NameQualifier="urn:picketlink:identity-federation" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">admin</NameID><SubjectConfirmation  
5:  Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/></Subject><Conditions NotBefore="2010-09-08T00:46:45.294Z"  
6:  NotOnOrAfter="2010-09-08T02:46:45.294Z" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><AudienceRestriction xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Audience  
7:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://security_saml/goodbyeworld</Audience></AudienceRestriction></Conditions><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">  
8:  <dsig:SignedInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments" xmlns:dsig="http://www.w3.org  
9:  /2000/09/xmldsig#"/><dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:Reference URI="#ID_bc96b4b9-0743-49ca-  
10:  8e32-b0bd3cd80185" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transforms xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transform Algorithm="http://www.w3.org/2000/09  
11:  /xmldsig#enveloped-signature" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"  
12:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:DigestValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">mcisCWAF28n4AQVYf1OEzeotBFA=</dsig:DigestValue></dsig:Reference>  
13:  </dsig:SignedInfo><dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">GyX1b4gN/lEiu6wbdddL4uSgPu2uyPALiYgKlCvOScnEBimO62ctj0lRWMVOlNywqso9TcqFS7fb  
14:  4fjbHif/m3S7mFfq+HhRlr3+StTtz9XWFoO/vn2twSKuwToX156RwzGlT4NvMAapmJI474uvValN  
15:  /HcLLHpqB2GI1XwD0kg=</dsig:SignatureValue><dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:KeyValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:RSAKeyValue  
16:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Modulus xmlns:dsig="http://www.w3.org/2000/09  
17:  /xmldsig#">suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1  
18:  dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKw  
19:  lYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo>  
20:  </dsig:Signature></Assertion>]

And the message is routed to the sendExternal service:

1:  2010-09-07 20:46:46,833 DEBUG [org.jboss.soa.esb.listeners.message.ActionProcessingPipeline] (pool-25-thread-1) executing processor 1 org.jboss.soa.esb.actions.StaticRouter@1596c3a  
2:  2010-09-07 20:46:46,834 DEBUG [org.jboss.internal.soa.esb.services.registry.JAXRRegistryImpl] (pool-25-thread-1) Going to query the registry for name pattern [sendExternal]  
3:  2010-09-07 20:46:47,391 DEBUG [org.picketlink.identity.federation.core.wstrust.auth.AbstractSTSLoginModule] (pool-26-thread-1) Added Credential :SamlCredential[<Assertion  
4:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" ID="ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185"  
5:  IssueInstant="2010-09-08T00:46:45.294Z" Version="2.0"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">PicketLinkSTS</Issuer><Subject xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><NameID  
6:   NameQualifier="urn:picketlink:identity-federation" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">admin</NameID><SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"  
7:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/></Subject><Conditions NotBefore="2010-09-08T00:46:45.294Z" NotOnOrAfter="2010-09-08T02:46:45.294Z"  
8:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><AudienceRestriction xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Audience xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://security_saml  
9:  /goodbyeworld</Audience></AudienceRestriction></Conditions><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:SignedInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">  
10:  <dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:SignatureMethod  
11:  Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:Reference URI="#ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185"  
12:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transforms xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-  
13:  signature" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" xmlns:dsig="http://www.w3.org/2000/09  
14:  /xmldsig#"/><dsig:DigestValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">mcisCWAF28n4AQVYf1OEzeotBFA=</dsig:DigestValue></dsig:Reference></dsig:SignedInfo><dsig:SignatureValue  
15:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">GyX1b4gN/lEiu6wbdddL4uSgPu2uyPALiYgKlCvOScnEBimO62ctj0lRWMVOlNywqso9TcqFS7fb  
16:  4fjbHif/m3S7mFfq+HhRlr3+StTtz9XWFoO/vn2twSKuwToX156RwzGlT4NvMAapmJI474uvValN  
17:  /HcLLHpqB2GI1XwD0kg=</dsig:SignatureValue><dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:KeyValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:RSAKeyValue  
18:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Modulus xmlns:dsig="http://www.w3.org/2000/09  
19:  /xmldsig#">suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1  
20:  dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKw  
21:  lYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo>  
22:  </dsig:Signature></Assertion>]  
23:  2010-09-07 20:46:47,392 DEBUG [org.jboss.soa.esb.listeners.message.ActionProcessingPipeline] (pool-26-thread-1) executing processor 0  
24:  org.jboss.soa.esb.listeners.message.OverriddenActionLifecycleProcessor@1ac4773

The subject is displayed a final time:

1:  2010-09-07 20:46:47,392 INFO [STDOUT] (pool-26-thread-1) Subject in MyListenerAction : Subject:  
2:    Public Credential: SamlCredential[<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2001/04/xmlenc#" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#"  
3:  ID="ID_bc96b4b9-0743-49ca-8e32-b0bd3cd80185" IssueInstant="2010-09-08T00:46:45.294Z" Version="2.0"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">PicketLinkSTS</Issuer><Subject  
4:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><NameID NameQualifier="urn:picketlink:identity-federation" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">admin</NameID><SubjectConfirmation  
5:  Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/></Subject><Conditions NotBefore="2010-09-08T00:46:45.294Z"  
6:  NotOnOrAfter="2010-09-08T02:46:45.294Z" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><AudienceRestriction xmlns="urn:oasis:names:tc:SAML:2.0:assertion"><Audience  
7:  xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://security_saml/goodbyeworld</Audience></AudienceRestriction></Conditions><dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">  
8:  <dsig:SignedInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments" xmlns:dsig="http://www.w3.org  
9:  /2000/09/xmldsig#"/><dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:Reference URI="#ID_bc96b4b9-0743-49ca-  
10:  8e32-b0bd3cd80185" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transforms xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Transform Algorithm="http://www.w3.org/2000/09  
11:  /xmldsig#enveloped-signature" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/></dsig:Transforms><dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"  
12:  xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"/><dsig:DigestValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">mcisCWAF28n4AQVYf1OEzeotBFA=</dsig:DigestValue></dsig:Reference>  
13:  </dsig:SignedInfo><dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">GyX1b4gN/lEiu6wbdddL4uSgPu2uyPALiYgKlCvOScnEBimO62ctj0lRWMVOlNywqso9TcqFS7fb  
14:  4fjbHif/m3S7mFfq+HhRlr3+StTtz9XWFoO/vn2twSKuwToX156RwzGlT4NvMAapmJI474uvValN  
15:  /HcLLHpqB2GI1XwD0kg=</dsig:SignatureValue><dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:KeyValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:RSAKeyValue  
16:   xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"><dsig:Modulus xmlns:dsig="http://www.w3.org/2000/09  
17:  /xmldsig#">suGIyhVTbFvDwZdx8Av62zmP+aGOlsBN8WUE3eEEcDtOIZgO78SImMQGwB2C0eIVMhiLRzVPqoW1  
18:  dCPAveTm653zHOmubaps1fY0lLJDSZbTbhjeYhoQmmaBro/tDpVw5lKJns2qVnMuRK19ju2dxpKw  
19:  lYGGtrP5VQv00dfNPbs=</dsig:Modulus><dsig:Exponent xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">AQAB</dsig:Exponent></dsig:RSAKeyValue></dsig:KeyValue></dsig:KeyInfo></dsig:Signature></Assertion>]

Smooks inserts the assert into the message:

1:  2010-09-07 20:46:47,916 DEBUG [org.milyn.util.ClassUtil] (pool-26-thread-1) Adding org.milyn.javabean.decoders.BigDecimalDecoder to list of classes  
2:  2010-09-07 20:46:47,917 DEBUG [org.milyn.util.ClassUtil] (pool-26-thread-1) Adding org.milyn.javabean.decoders.BigIntegerDecoder to list of classes  
3:  2010-09-07 20:46:47,918 DEBUG [org.milyn.util.ClassUtil] (pool-26-thread-1) Adding org.milyn.javabean.decoders.BooleanDecoder to list of classes  
4:  (lots more lines like this)  
5:

And the web service is accessed:

1:  2010-09-07 20:46:48,415 DEBUG [org.jboss.ws.core.EndpointInvocation] (pool-26-thread-1) transformPayloadValue: org.jboss.ws.core.soap.SOAPBodyElementDoc -> org.jboss.soa.esb.samples.quickstart.securitysaml.webservice.jaxws.SayGoodbye  
2:    </soapenv:Header>  
3:    <soapenv:Body>  
4:     <good:sayGoodbye>  
5:       <message>Goodbye!!</message>  
6:     </good:sayGoodbye>  
7:    </soapenv:Body>  
8:  </soapenv:Envelope>

Closing Thoughts

OK, let's review what happened.

The quickstart demonstrate these (4) procedures:

Using the PicketLink Project's STSIssuingLoginModule to issue a SAML Assertion from PicketLinkSTS, then
Using the PicketLink Project's STSValidatingLoginModule to validate a SAML Assertion from PicketLinkSTS, then
Injecting the SAML Assertion into a SOAP Message, then
Using SOAPProcessor to invoke an external Web Service that is secured by PicketLinkSTS.

And, notice what the quickstart did not have to do - it did not have to include a large amount of custom-written code to issue or validate the SAML Assertion. PicketLinkSTS and the JBossESB in the SOA Platform did the heavy lifting.

Acknowledgements

As always, I want to thank the JBoss SOA Platform team and community (especially Anil Saldhana, Babak Mozaffari, and Kevin Conner for their timely review input for this blog post).

References

Organization for the Advancement of Structured Information Standards (OASIS - http://www.oasis-open.org)
PicketLink (http://jboss.org/picketlink)
PicketBox (http://www.jboss.org/picketbox)
SAML Token support for ESB services. (http://community.jboss.org/wiki/JBossESBSAMLSupport)
PicketLink Login Modules (https://community.jboss.org/wiki/PicketLinkSTSLoginModules)
Web Service Security (http://docs.sun.com/source/819-0788/xwss2.html, http://community.jboss.org/wiki/WSSecurityConfig, http://community.jboss.org/wiki/jbossws-ws-securityoptions
JSR 181 ("Web Services Metadata for the Java Platform") (http://jcp.org/en/jsr/detail?id=181)
http://docs.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5/html/ESB_Programmers_Guide/index.html

Reposted in DZone

2010-08-17T12:20:00.000-07:00

The post describing the JBossESB / Drools integration in the SOA Platform was just posted up on DZone:

http://java.dzone.com/articles/jbossesb-drools-integration

The JBossESB-Drools Integration in the JBoss SOA Platform

2010-07-08T08:13:00.000-07:00

As I've mentioned in previous posts and articles, one of the great strengths of the JBoss SOA Platform is the large number of integrations that it supports. Some of these integrations take the form of support for JBoss and third-party supplied JMS and UDDI providers or support for multiple JDKs and databases. The SOA Platform also supports an integration to jBPM for business process orchestration, and JBDS for application development.

In this post, I want to take a look at the SOA Platform's integration with JBoss Rules. In an earlier blog post (http://jboss-soa-p.blogspot.com/2009/07/when-content-knows-way-content-based.html), I discussed using Rules to implement content based routing over the JBossESB. In this post, we'll look at another aspect of the JBossESB-Rules integration; the creation of rules-based services.

Before we examine this integration in detail, let's take a quick look at JBoss Rules.

Drools and Rules

JBoss Rules as packaged in the SOA Platform is the commercialized version of the open source "Drools" project. (You can learn more about Drools at the project web site here: http://www.jboss.org/drools/) Drools is a unified and integrated solution for Business Rules, Business Processes Management, and Event Processing. The Drools project is organized into a number of sub-projects. When we refer to JBoss Rules in the SOA Platform, what we're primarily talking about is the Drools "Expert" sub-project. This sub-project consists of the Rules API, the Rules engine, and Rules editing and debugging tools.

Rules-based programming, as its name implies, is built on the ability to define decision points and keep them separate from other program logic. OK, that sounds interesting, but why would I want to use this? In other words, what's the big deal? Here are two reasons why this is important:

First, it enables you to separate your application's business logic and decision point handling from the application code. This means that your business process specialists can concentrate on the business logic rules and your programmers can concentrate on the application code. This makes application development and maintenance easier and more effective.
Second, and don't take this as a personal criticism of your programming skills or mine, but the since the rules engine is designed and optimized to process rules, it is more efficient than any massive if-then-else statement that you can write. So, your application's performance can be improved. The JBoss Rules engine makes use of the Rete algorithm http://en.wikipedia.org/wiki/Rete_algorithm for efficient Rules processing.

When you define a rule, the model that you follow is not "if-then-else," but rather "when" and "then." The two constructs that you use in a rule are:

The Condition - This is the left hand side of the rule and covers the "when" aspects of the rule.
The Consequence - This is the right hand side of the rule and covers the "then" aspects of the rule.

Rules are written in the Drools Rule Language (drl). This language can be extended into a Domain Specific Language (dsl) to support application-specific requirements such as medical or financial procedures and terminology.

The general template for a rule is:

1:  rule “a simple rule”
2:  when (LHS)
3:    you need a rules-based app
4:  then (RHS)
5:    build it with JBoss Rules

How does a rule access information? Through Rules' working memory. The information that rules perform operations take the form of Java beans that are referred to as "facts." (The elements in these facts are accessed through the getter and setter methods.) What happens is that facts are inserted into working memory, updated in working memory, or removed from working memory, those changes to the facts in working memory can cause the Rules' "when" conditions to be true and the rules to be executed.

It's important to note that unlike procedural programming, changes to facts can cause more than one rule to reach true conclusions and be available to be executed at once. What happens then? Well, instead of hardcoding a sequence of rules, the rules engine adds each matching rule to its "Agenda" of rules to be executed. If the Agenda includes more than one rule, the rule engine performs conflict resolution on the rules and determines the sequence in which the rules should be executed. This conflict resolution is based on the rules' salience (you define this as a property when you write the rules), how often the rule has fired in the past, complexity (the more complex a rule the more likely the rule engine will consider it to apply to the current situation), and the order in which the rules are loaded.

Invoking Rules from a JBossESB Service in the SOA Platform

The Rules - JBossESB integration in the SOA Platform enables you to access rules from an service's actions. This is supported by the org.jboss.soa.esb.actions.BusinessRuleProcessor and the org.jboss.soa.esb.actions.DroolsRuleService action classes.

The BusinessRuleProcessor class uses rules loaded from rules files. Generally, you use this class for simple rules services as loading large numbers of rules from large numbers of rules files is difficult to manage and not efficient.

For production environments, where you will have complicated rules services that deal with hundreds or even thousands of rules, it's better to use the DroolsRuleService. This service uses the RuleAgent to either access packages of rules from files, or from a Business Rules Management System (BRMS) .

The JBoss BRMS Platform (http://www.jboss.com/products/platforms/brms/) combines a central repository for rules, with a web based rules authoring interface, and rules management that provides import/export/archiving, audit trail or edits, error log, automated test development and execution, rules analysis, status tracking, and version control. The BRMS Platform rules authoring "guided editor" enables non-programmers to more easily create rules while the Platform makes it easy for rules administrartors can maintain large numbers of rules and control their development and use by users. Here's a screenshot:

The SOA Platform supports rules services that are either stateless or stateful. In the stateless model, messages sent to the services contain all the facts to be inserted into the rules engine working memory, before the rules are executed. In the stateful model, where the execution of the rules may take place in a session over an extended time period, several messages may be sent to a rule service, and the rules may fire and update either the message or the facts until a final message causes the service to end the session. The best way to explain and illustrate the Rules - JBossESB integration in the SOA Platform is with one of the Platform's "quickstart" example programs. Let's take a look.

Rules Services in Action - The Quickstart

I never get tired of saying that one of the great features of the SOA Platform is its extensive, and always growing, set of "quickstart" programs. These programs go far beyond being simple examples as they clearly illustrate various features supported by the Platform. They also serve as a great resource for writing your own applications. For our example, we'll look at the "business_rules_service" quickstart. Before we walk through the configuration and execution of the quickstart, let's take a look at its (3) Rules files. It important to note that Rules are actually used in multiple ways in this quickstart as it simulates a customer making a purchase from an e-commerce site. The quickstart uses Rules to:

Calculate the priority of an incoming customer order
Calculate the discount to be applied to an order
And route the order to the appropriate service, based on the content of the order

It's also important to note that the quickstart illustrates how a message can be modified as it is processed through the SOA Platform's JBossESB action pipeline. Let's start with the "MyBusinessRules.drl" file, as it establishes the priority of the order. (Oh, wait. We'll jump ahead a bit here and explain that by default, every incoming order has a priority value of "1.")

1:  package com.jboss.soa.esb.routing.cbr
2:
3:  #list any import classes here.
4:  import org.jboss.soa.esb.message.Message;
5:  import org.jboss.soa.esb.message.format.MessageType;
6:  import org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.OrderHeader;
7:  import org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.Customer;
8:
9:   global java.util.List destinations;
10:
11:
12:
13:   rule "Logging"
14:   when
15:     order: OrderHeader()
16:     customer: Customer()
17:   then
18:     System.out.println("Customer Status: " + customer.getStatus());
19:     System.out.println("Order Total: " + order.getTotalAmount());
20:   end
21:
22:   rule "Customer Platinum Status"
23:    when
24:     customer: Customer(status > 50)
25:     order: OrderHeader(totalAmount > 50)
26:    then
27:     System.out.println("Platinum Customer - High Priority");
28:     order.setOrderPriority(3);
29:   end
30:
31:   rule "Customer Gold Status"
32:    when
33:     customer: Customer(status > 10, status <= 50)
34:     order: OrderHeader(totalAmount > 25)
35:    then
36:     System.out.println("Gold Customer - Medium Priority ");
37:     order.setOrderPriority(2);
38:   end
39:

Let's examine this Rules file line-by-line:

Line 1 - Similar to Java, a package is a related set of rules.
Lines 4-7 - These imports perform the same function as Java language imports. Note that we're importing both SOA Platform Message related packages and packages contained in the quickstart itself.
Line 9 - Make a mental note of this global definition as it will be used by the other Rules files and by the quickstart for content based routing.
Line 13-14 - The name for the first Rule and the start of its "when" clause.
Line 15 - This creates a Rule variable named "order" and initializes with the value of the OrderHeader fact (org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.OrderHeader) that is presented to the Rule.
Line 16 does the same for a Rule variable named customer and the Customer fact. Note that there is nothing conditional about these assignments. The rule will match every OrderHeader and Customer. This matching is actually an important concept to keep in mind as part of each "when" clause involves trying to match the facts passed to the rules.
Line 20 - A rule must always have an end statement.
Line 22 - This rule sets the status for the highest priority ("Platinum") customers.
Line 24-25 - Note the differences in these statements to those in lines 15 and 16. The rule will only be executed if:

Line 24 - The customer's status is greater that 50. If this is not the case, then the customer variable we set in line 16 will not be changed, and
Line 25 - The total amount of the order is also greater than 50. If this is not the case, then the order variable that we set in line 15 will not be changed.

Line 28 - Remember how I said that the default priority for each order was set to "1". Here's where we set the priority. Note that we are setting the value in the "order" Rule variable.
Lines 31-38 - This rule sets the status for the 2nd highest priority ("Gold") customers. What's interesting in this rule is line 33 as it includes two criteria that must both be met in order for the fact to match the rule.

The next Rules file that we'll look at picks up where MyBusinessRules.drl leaves off. This Rules file is named: MyBusinessRulesDiscount.drl

1:  package com.jboss.soa.esb.routing.cbr
2:
3:  #list any import classes here.
4:  import org.jboss.soa.esb.message.Message;
5:  import org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.OrderHeader;
6:  import org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.Customer;
7:
8:  global java.util.List destinations;
9:
10:
11:
12:  rule "Logging"
13:  salience 10
14:  when
15:    order: OrderHeader()
16:    customer: Customer()
17:  then
18:    System.out.println("Customer Status: " + customer.getStatus());
19:    System.out.println("Order Total: " + order.getTotalAmount());
20:  end
21:
22:  rule "Customer Platinum Status"
23:  salience 20
24:   when
25:    customer: Customer(status > 50)
26:    order: OrderHeader(orderPriority == 3)
27:   then
28:    System.out.println("Platinum Customer - High Priority - Higher discount");
29:    order.setOrderDiscount(8.5);
30:  end
31:
32:  rule "Customer Gold Status"
33:  salience 20
34:   when
35:    customer: Customer(status > 10, status <= 50)
36:    order: OrderHeader(orderPriority == 2)
37:   then
38:    System.out.println("Gold Customer - Medium Priority - discount ");
39:    order.setOrderDiscount(3.4);
40:  end

Lines 1-8 and the "Logging" rule should look familiar, so let's move on to the other rules defined in this file.
Line 13 - Remember how we talked about how rules are not executed in the exact sequence in which they can be viewed in a rules .drl file? This rule is assigned a salience property value of 10. Since this rule only prints out some logging information, it's assigned a lower salience than the other rules defined in the file.
Line 22 - This rule sets the discount level for the highest class of customers.
Line 23 - And, since we want to be sure that this rule fires, we assign it a salience property value of 20.
Lines 25-26 - This "when" clause is true when the rule is able to match both a Customer fact with a status greater than 50 and an OrderHeader fact with an orderPriority equal to 3. If both these conditions are true, then rule the customer and order variables are initialized from the Customer and and OrderHeader facts and the rule is fired.
Line 29 - Note that when the rule fires, the setOrderDiscount setter method is executed on the rule variable "order." The same setter method is executed on the OrderHeader fact in working memory. (Remember how we talked about how rules can both react to changes to facts in working memory and also cause changes on those facts? This is an example.) For the "Platinum" class of customers, we assign a generous discount.
Lines 32-39 - This rule follows the same pattern as the "Customer Platinum Status" rule. Note that we give the "Gold" class of customers a somewhat less generous discount. ;-)

The third and final Rules file used by the quickstart controls the content-based routing used by the quickstart to route messages to services. In the SOA Platform, Rules is one of the supported mechanisms for implementing content based routing. In contrast to more static routing approaches, this form of message routing is relies on the content in the messages to dictate the route that a message takes. (For background on content based routing, please refer to this blog post: http://jboss-soa-p.blogspot.com/2009/07/when-content-knows-way-content-based.html )

This rules file is aptly named: MyRoutingRules.drl

1:  package com.jboss.soa.esb.routing.cbr
2:
3:  #list any import classes here.
4:  import org.jboss.soa.esb.message.Message;
5:  import org.jboss.soa.esb.message.format.MessageType;
6:  import org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.OrderHeader;
7:
8:  #declare any global variables here
9:  global java.util.List destinations;
10:
11:
12:   rule "Highest Priority Orders"
13:
14:       when
15:           OrderHeader( orderPriority == 3 )
16:       then
17:           System.out.println("HIGHEST PRIORITY");
18:           destinations.add("SuperSpecialCustomerService");
19:
20:   end
21:
22:   rule "Medium Priority Orders"
23:
24:       when
25:           OrderHeader( orderPriority == 2 )
26:       then
27:           System.out.println("Medium Priority");
28:           destinations.add("SpecialCustomerService");
29:   end
30:
31:   rule "Low Priority Orders"
32:
33:       when
34:           OrderHeader( orderPriority == 1 )
35:       then
36:           System.out.println("Low Priority");
37:           destinations.add("RegularCustomerService");
38:   end
39:

Lines 1-6 - Once again, these import lines should look familiar.
Line 9 - Make note of the destinations List. We'll see this used when the messages are routed.
The rules in this rules file are pretty straight-forward. In each of the three rules we add the appropriate destination, based on the orderPriority in the OrderHeader, where that destination is a service that the quickstart deploys to the JBossESB in the SOA Platform.

OK, those are the rules that we'll use in the quickstart. Let's now step through the quickstart as it is run.

To deploy the quickstart, execute this ant target:

1:  ant deploy

And, we then see this written to the server log:

1:  22:20:57,568 INFO [QueueService] Queue[/queue/quickstart_Business_Rules_Request_GW] started, fullSize=200000, pageSize=2000, downCacheSize=2000
2:  22:20:57,580 INFO [QueueService] Queue[/queue/quickstart_Business_Rules_Request_ESB] started, fullSize=200000, pageSize=2000, downCacheSize=2000
3:  22:20:57,621 INFO [QueueService] Queue[/queue/quickstart_Business_Rules_ConciergeManager] started, fullSize=200000, pageSize=2000, downCacheSize=2000
4:  22:20:57,632 INFO [QueueService] Queue[/queue/quickstart_Business_Rules_DistributionManager] started, fullSize=200000, pageSize=2000, downCacheSize=2000
5:  22:20:57,643 INFO [QueueService] Queue[/queue/quickstart_Business_Rules_BasicShipping] started, fullSize=200000, pageSize=2000, downCacheSize=2000
6:  22:20:57,682 INFO [EsbDeployment] Starting ESB Deployment 'Quickstart_business_rules_service.esb'

And to run it, exceute this ant target:

1:  ant runtest

When the quickstart is run, here's what happens, step by step. Note that while we'll be examining most of the contents of the jboss-esb.xml file in detail, we'll be doing it in pieces or fragments so that it's easier to follow. The line numbers in each of these fragments will therefore be different from the actual (whole) file.

Step 1 - Create a Message and Pass it Through a Gateway to the Deployed Quickstart Application

Like many of the SOA Platform quickstarts, the business_rules_service quickstart initiates its actions when a message is inserted into a queue that is being watched by a gateway listener. What's a gateway? On the JBossESB in the SPA Platform, everything is either a service that generates or consumes messages, or a message. That is, a message that is in the form (org.jboss.soa.esb.message) that the ESB understands. Services that can understand messages in this form are referred to as being "ESB-aware."

How can you connect other, and potentially older, legacy applications over the ESB? By using gateways. A gateway (org.jboss.soa.esb.listeners.gateway) is a service that acts as a bridge between an ESB-aware and an ESB-unaware client and service. Gateways translate information between ESB and non-ESB message formats and EPRs. (EPR stands for endpoint reference.) Gateways are listener processes in that they "listen" for incoming communications. They are different from ESB-aware listeners in that they accept data in different formats such as objects in files or SQL tables. ESB-aware listeners can only accept messages in the org.jboss.soa.esb.message format.

The SOA Platform supports these gateways:

file gateways: local filesystem, ftp, sftp and ftps
JMS
HTTP/HTTPS
email (POP3)
SQL table
Hibernate

In the case of this quickstart, we'll use a JMS gateway to receive the JMS message. The gateway queue, and its corresponding ESB-aware queue are defined in the jms-provider section of the jboss-esb.xml file:

1:  <jms-bus busid="quickstartGwChannel">
2:    <jms-message-filter dest-type="QUEUE"
3:      dest-name="queue/quickstart_Business_Rules_Request_GW" />
4:  </jms-bus>
5:  <jms-bus busid="quickstartEsbChannel">
6:    <jms-message-filter dest-type="QUEUE"
7:      dest-name="queue/quickstart_Business_Rules_Request_ESB" />
8:  </jms-bus>

And the listener is defined at the top of the "Business_Rules_Service" service definition:

1:   <service category="Business_RulesServices"
2:     name="Business_Rules_Service" description="The main entry point">
3:     <listeners>
4:       <!-- Gateway -->
5:         <jms-listener name="TheGateway"
6:           busidref="quickstartGwChannel" is-gateway="true" />
7:         <jms-listener name="TheESBChannel"
8:           busidref="quickstartEsbChannel" >
9:         </jms-listener>
10:     </listeners>
11:     <actions mep="OneWay">

Note that on line 6, we identify the listener as a gateway.
Also note that on line 11, we define the mep, or "message exchange pattern." In the case of this quickstart, the pattern is "OneWay" which indicates that the message pattern is asynchronous. We're sending messages, but not waiting around (or blocking) for a response.

How do we generate this message? Take a look at the "runtest" target, specifically the classname, in the quickstart's ant build.xml file:

1:  <target name="runtest" depends="compile"
2:    description="willl receive JMS message to tigger the actions in the ESB">
3:    <echo>Runs Test JMS Sender</echo>
4:    <java fork="yes" classname="org.jboss.soa.esb.samples.quickstart.businessrules.test.SendJMSMessage" failonerror="true">
5:      <classpath refid="exec-classpath" />
6:    </java>

That's right - we're sending a JMS message with a program named "SendJMSMessage." It's hard to get simpler than that. ;-)

In order to simulate a realistic customer order in the message, SendJMSMessage builds the message from the quickstart's SampleOrder.xml file:

1:  <Order orderId="1" orderDate="Wed Nov 15 13:45:28 EST 2006" statusCode="0"
2:  netAmount="59.97" totalAmount="64.92" tax="4.95">
3:      <Customer userName="user1" firstName="Harry" lastName="Fletcher" state="SD"/>
4:      <OrderLines>
5:          <OrderLine position="1" quantity="1">
6:              <Product productId="364" title="The 40-Year-Old Virgin " price="29.98"/>
7:          </OrderLine>
8:          <OrderLine position="2" quantity="1">
9:              <Product productId="299" title="Pulp Fiction" price="29.99"/>
10:          </OrderLine>
11:      </OrderLines>
12:  </Order>

The SendJMSMessage class reads this file, creates a message object of type javax.jms.ObjectMessage (remember, this is an ESB-unaware message), and writes it to the queue (queue/quickstart_Business_Rules_Request_GW) on which our JMS gateway is listening. The listener receives the message and the ESB converts it to an ESB-aware message and then passes it onto the ESB through the queue/quickstart_Business_Rules_Request_ESB queue.

Now it starts to get more interesting.

Remember that our rules rely on certain types of facts (which are JavaBeans) being available in working memory. Where do these facts come from? We'll create them out of that message.

Step 2 - Transform the Message into Beans

The problem is that we have to have a way to create those facts out of the information in the message. Luckily, one of the tasks that the JBossESB in the SOA Platform performs is "transformation." The next action in the quickstart's action pipeline uses the smooks processing engine (http://www.smooks.org/) and the JBossESB's out-of-the-box "SmooksAction" action to perform the transformation of the information in the message into facts:

1:  <action name="transform"
2:    class="org.jboss.soa.esb.smooks.SmooksAction">
3:      <property name="smooksConfig" value="/smooks-res.xml" />
4:      <property name="resultType" value="JAVA" />
5:  </action>

The source code for the facts (remember that these are JavaBeans and have getter and setter methods) is in these source files in the quickstart:

In: src/org/jboss/soa/esb/samples/quickstart/businessrules/dvdstore

Customer.java
OrderHeader.java
OrderItem.java

The quickstart uses the smooks-res.xml file to perform the transformation. Let's take a look at this file.

1:  <?xml version='1.0' encoding='UTF-8'?>
2:  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
3:             xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.2.xsd">
4:
5:    <!-- Populate the OrderHeader -->
6:    <jb:bean beanId="orderHeader" class="org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.OrderHeader" createOnElement="order">
7:      <jb:value property="orderId"   data="Order/@orderId" />
8:      <jb:value property="orderDate"  data="Order/@orderDate" decoder="Calendar">
9:        <jb:decodeParam name="format">EEE MMM dd HH:mm:ss z yyyy</jb:decodeParam>
10:              <jb:decodeParam name="locale-language">en</jb:decodeParam>
11:        <jb:decodeParam name="locale-country">US</jb:decodeParam>
12:      </jb:value>
13:      <jb:value property="statusCode" data="Order/@statusCode" />
14:      <jb:value property="netAmount"  data="Order/@netAmount" />
15:      <jb:value property="totalAmount" data="Order/@totalAmount" />
16:      <jb:value property="tax"     data="Order/@tax" />
17:    </jb:bean>
18:
19:    <!-- Populate the Customer -->
20:    <jb:bean beanId="customer" class="org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.Customer" createOnElement="customer">
21:       <jb:value property="userName" data="customer/@userName" />
22:       <jb:value property="firstName" data="customer/@firstName" />
23:       <jb:value property="lastName" data="customer/@lastName" />
24:       <jb:value property="state"   data="customer/@state" />
25:    </jb:bean>
26:
27:    <!-- Populate the OrderItem list -->
28:    <jb:bean beanId="orderItemList" class="java.util.ArrayList" createOnElement="orderlines">
29:       <jb:wiring beanIdRef="orderItem" />
30:    </jb:bean>
31:
32:     <!-- Populate the OrderItem instance -->
33:     <jb:bean beanId="orderItem" class="org.jboss.soa.esb.samples.quickstart.businessrules.dvdstore.OrderItem" createOnElement="orderlines/orderline">
34:       <jb:value property="position" data="orderline/@position" />
35:       <jb:value property="quantity" data="orderline/@quantity" />
36:       <jb:value property="productId" data="orderline/product/@productId" />
37:       <jb:value property="title"   data="orderline/product/@title" />
38:       <jb:value property="price"   data="orderline/product/@price" />
39:    </jb:bean>
40:
41:   </smooks-resource-list>

That's right - it's using XPath (http://www.w3.org/TR/xpath/) to parse the information in the message into Customer (starting at line NN), OrderHeader (starting at line NN), and OrderItem.java (starting at line NN) JavaBeans and a java.util.ArrayList object that contains a list of the orders.

Step 3 - And Add the Beans Back into the Message

What happens next? Well, we have the original message, and some JavaBeans. But, remember that on the JBossESB in the SOA Platform, everything is either a message or a service. What we need is some way to get those JavaBeans back into the message. The way that we do this is with the next action in the action pipeline:

1:  <action name="map_order_components" class="org.jboss.soa.esb.actions.scripting.GroovyActionProcessor">
2:    <property name="script" value="/map_order_components.groovy" />
3:  </action>

GroovyActionProcessor is another of the SOA Platform's out-of-the-box actions. The groovy script referenced by the action takes the JavaBeans that we just created and adds them (note the use of the beanId's that we defined in the smooks-res.xml file) back into the message with property names that match the bean IDs. The script is very short - lines 3 and 4 add the orderHeard and customer to the message body:

1:    // Need to map down the orderHeader and customer beans onto the message
2:    // to make them available to the ObjectMapper...
3:    message.getBody().add("orderHeader", message.getBody().get().get("orderHeader"));
4:    message.getBody().add("customer", message.getBody().get().get("customer"));

Now we have the JavaBeans in the message. What happens next? The quickstart updates the customer status (it's set to a value of "0" in the JMS message that started the quickstart) with the "UpdateCustomerStatus" custom action:

1:  <!-- Update Customer Status -->
2:  <action name="updateCustomerStatus"
3:    class="org.jboss.soa.esb.samples.quickstart.businessrules.UpdateCustomerStatus">
4:      <property name="status" value="60"/>
5:  </action>

We'll set this to a value of 60 as the customer is in the platinum customer class. (Hint: For extra credit, try the quickstart with different status values.)

Here's the output in the log - this line is printed by the org.jboss.soa.esb.samples.quickstart.businessrules.UpdateCustomerStatus custom action:

1:  21:42:15,793 INFO [STDOUT] { Updated customer status to 60}

Step 4 - Process the Message with the BusinessRulesProcessor

OK - now we can see the BusinessRulesProcessor execute in the next action:

1:    <!-- Use the BRP to calculate the order priority -->
2:     <action
3:      class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
4:        name="BRP">
5:          <property name="ruleSet"
6:            value="MyBusinessRules.drl" />
7:          <property name="ruleReload" value="true" />
8:          <property name="object-paths">
9:            <object-path esb="body.orderHeader" />
10:           <object-path esb="body.customer" />
11:          </property>
12:    </action>
13:
14:    <action name="reviewMessage1"
15:      class="org.jboss.soa.esb.samples.quickstart.businessrules.ReviewMessage">
16:        <property name="stuff" value="After Order Priority"/>
17:    </action>

Line 1 - Comments are always good things! ;-)
Line 2 - Here's the start of the action that makes use of the BusinessRulesProcessor.
Line 3 - And here's the reference to the BusinessRulesProcessor class.
Lines 5-6 - And, here's the reference to the Rules file that we want to execute.
Line 7 - This property causes the Rule to be if the file changes.
Lines 8-11 - And, here are the objects that we added to the message - remember the map_order_components.groovy file?

So, what just happened? We made the orderHeader and customer objects available to the Rules defined in MyBusinessRules.drl and executed the Rules. The net effect of this is that the priority of the order defined in the message should have changed. The next action in the action pipeline writes this to the log:

1:  21:42:15,931 INFO [STDOUT] Platinum Customer - High Priority
2:  21:42:15,932 INFO [STDOUT] Customer Status: 60
3:  21:42:15,932 INFO [STDOUT] Order Total: 64.92

The first three lines are printed by the rules. Remember how the rules all included System.out.prinln statements? And how the logging rule that prints the customer status and order total has a lower value salience property than the rules that set and print the customer priority? That explains the order in which the statements are printed to the log.

And then these lines are printed by the org.jboss.soa.esb.samples.quickstart.businessrules.ReviewMessage cusom action:

1:  21:42:15,932 INFO [STDOUT] { ================ After Order Priority
2:  21:42:15,933 INFO [STDOUT] Customer: user1,Harry,Fletcher,SD,60
3:  21:42:15,933 INFO [STDOUT] Order Priority: 3
4:  21:42:15,933 INFO [STDOUT] Order Discount: 0.0
5:  21:42:15,933 INFO [STDOUT] Order Total: 64.92
6:  21:42:15,933 INFO [STDOUT] } ================ After Order Priority

The rule "Highest Priority Orders" defined in MyBusinessRules.drl has set the order priority to 3.

Next, the quickstart calls the BusinessRulesProcessor again, this time to determine the order discount:

1:   <!-- Use the BRP to calculate the order discount -->
2:   <action
3:     class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
4:       name="BRP2">
5:       <property name="ruleSet"
6:         value="MyBusinessRulesDiscount.drl" />
7:       <property name="ruleReload" value="true" />
8:       <property name="object-paths">
9:         <object-path esb="body.orderHeader" />
10:         <object-path esb="body.customer" />
11:       </property>
12:    </action>
13:
14:    <action name="reviewMessage2"
15:      class="org.jboss.soa.esb.samples.quickstart.businessrules.ReviewMessage">
16:      <property name="stuff" value="After Order Discount"/>
17:    </action>

Line 6 - The rule "Customer Platinum Status" defined in the MyBusinessRulesDiscount.drl file is executed as our customer has both the highest priority as well as the status value of 60. That rule and the logging rule print out these statements to the log in this order:

1:  21:42:16,062 INFO [STDOUT] Platinum Customer - High Priority - Higher discount
2:  21:42:16,063 INFO [STDOUT] Customer Status: 60
3:  21:42:16,063 INFO [STDOUT] Order Total: 64.92

Next, the org.jboss.soa.esb.samples.quickstart.businessrules.ReviewMessage custom action is executed to print these statements to the log:

1:  21:42:16,063 INFO [STDOUT] { ================ After Order Discount
2:  21:42:16,063 INFO [STDOUT] Customer: user1,Harry,Fletcher,SD,60
3:  21:42:16,064 INFO [STDOUT] Order Priority: 3
4:  21:42:16,064 INFO [STDOUT] Order Discount: 8.5
5:  21:42:16,064 INFO [STDOUT] Order Total: 64.92
6:  21:42:16,064 INFO [STDOUT] } ================ After Order Discount

And there we see our generous 8.5% discount.

Next, the quickstart prints the entire message to the log with this out of the box action:

1:  <action name="sout" class="org.jboss.soa.esb.actions.SystemPrintln" />

And here's how it appears in the server.log:

1:  21:42:16,064 INFO [STDOUT] Message structure:
2:  21:42:16,064 INFO [STDOUT] [{orderHeader=1, java.util.GregorianCalendar[time=1163616328000,areFieldsSet=true,areAllFieldsSet=false,lenient=true,zone=sun.util.calendar.ZoneInfo[id="US/Eastern",offset=-18000000,dstSavings=3600000,useDaylight=true,transitions=235,lastRule=java.util.SimpleTimeZone[id=US/Eastern,offset=-18000000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=1,minimalDaysInFirstWeek=1,ERA=?,YEAR=2006,MONTH=10,WEEK_OF_YEAR=?,WEEK_OF_MONTH=?,DAY_OF_MONTH=15,DAY_OF_YEAR=?,DAY_OF_WEEK=4,DAY_OF_WEEK_IN_MONTH=?,AM_PM=?,HOUR=?,HOUR_OF_DAY=13,MINUTE=45,SECOND=28,MILLISECOND=?,ZONE_OFFSET=-18000000,DST_OFFSET=0], 0, 59.97, 64.92, 4.95, , orderItemList=[1,1,364,The 40-Year-Old Virgin ,29.98, 2,1,299,Pulp Fiction,29.99], orderItem=2,1,299,Pulp Fiction,29.99, customer=user1,Harry,Fletcher,SD,60}].

That's a little hard to read. Let's take out the order date/time so that we can better see the customer and orderHeader Beans that we added to the message:

1:  {
2:  orderHeader=1, 0, 59.97, 64.92, 4.95,
3:  orderItemList=[1,1,364,The 40-Year-Old Virgin ,29.98, 2,1,299,Pulp Fiction,29.99],
4:  orderItem=2,1,299,Pulp Fiction,29.99,
5:  customer=user1,Harry,Fletcher,SD,60
6:  }

Step 5 - Route the Message to its Destination Based on its Content

At this point, the quickstart has finished using the BusinessRulesProcessor, but it's not yet done using Rules. Remember how I said that on the JBossESB in the SOA Platform everything is either a message or a service? Well, one of the main functions performed by the ESB is to route messages to the correct service. These routes can be static, or they can be dynamic, based on the content of a message. Here's where content based routing with Rules comes in. The routing rules are defined in the MyRoutingRules.drl file. Remember how the rules in this file designated the "destinations" of the messages? This next action uses invokes the org.jboss.soa.esb.actions.ContentBasedRouter class to route the messages to their intended destinations.

1:  1  <!-- Use the CBR to route the "scored" order to the appropriate service team -->
2:  2  <action
3:  3    class="org.jboss.soa.esb.actions.ContentBasedRouter"
4:  4     name="ContentBasedRouter">
5:  5       <property name="ruleSet" value="MyRoutingRules.drl" />
6:  6       <property name="ruleReload" value="true" />
7:  7       <property name="destinations">
8:  8         <route-to
9:  9           destination-name="SuperSpecialCustomerService"
10:  10          service-category="ConciergeManager" service-name="ConciergeService" />
11:  11       <route-to
12:  12         destination-name="SpecialCustomerService"
13:  13         service-category="DistributionManager" service-name="DistributionService" />
14:  14       <route-to
15:  15         destination-name="RegularCustomerService"
16:  16         service-category="BasicShipping" service-name="ShipperService" />
17:  17       </property>
18:  18       <property name="object-paths">
19:  19         <object-path esb="body.orderHeader" />
20:  20         <object-path esb="body.customer" />
21:  21       </property>
22:  22 </action>

Lines 107-109, 110-112, and 113-115 define the routes. Since our message now has the highest priority, it is routed to the ConciergeService.

Here's what the log shows us. Again, the first line is printed by the rule:

1:  21:42:16,210 INFO [STDOUT] HIGHEST PRIORITY

And the remaining lines are printed by the org.jboss.soa.esb.samples.quickstart.businessrules.ReviewMessage custom action as invoked by the ConciergeService.

1:  21:42:16,309 INFO [STDOUT] { ================ Concierge
2:  21:42:16,309 INFO [STDOUT] Customer: user1,Harry,Fletcher,SD,60
3:  21:42:16,309 INFO [STDOUT] Order Priority: 3
4:  21:42:16,309 INFO [STDOUT] Order Discount: 8.5
5:  21:42:16,310 INFO [STDOUT] Order Total: 64.92
6:  21:42:16,310 INFO [STDOUT] } ================ Concierge

Well, the customer's order was delivered to the very posh ConciergeService, and the quickstart's execution is complete.

Closing Thoughts

OK, let's review what happened. The quickstart defines multiple business rules to examine and modify a message as it is processed by actions executed by ESB services, then it routes that message to the correct destination service. The rules are maintained in .drl files, separate from the services' custom action code, which makes it easier to maintain them.

And, notice what the quickstart did not have to do - the rules were executed and the content based routing was performed through out of the box actions provided by the SOA Platform's JBossESB. This made it possible for the quickstart to concentrate on the Rules business logic.

Acknowledgements

As always, I want to thank the JBoss SOA Platform team and community (especially Kevin Conner and Mark Proctor for their timely review input for this blog post).

References

JBoss SOA Platform (http://www.jboss.com/products/platforms/soa/)
JBoss BRMS Platform (http://www.jboss.com/products/platforms/brms/)
JBossESB Project (http://www.jboss.org/jbossesb)
JBoss Drools Project (http://www.jboss.org/drools)
JBoss Smooks Project (http://www.smooks.org)
JBoss Drools Business Rules by Paul Browne (published by Packt Publishing) (https://www.packtpub.com/jboss-drools-business-rules/book)

SOA Governance

2010-04-29T14:42:00.001-07:00

I wrote an article on SOA Governance last year but they forgot to let me know it had been published. Better late than never.

Cross Posting to DZone

2010-04-20T19:35:00.000-07:00

The previous post - on JMS Transactions - is now also on DZone:

http://soa.dzone.com/articles/jms-transactions-soa-platform

JMS Transactions and the SOA Platform

2010-04-14T07:19:00.000-07:00

The Server's Down - And What's Worse, I Lost my Money!

Regardless of how carefully you plan, it's inevitable that the software you build will encounter a situation or chain of events that you did not anticipate, and experience some type of failure. (Trust me on this. I work in software testing and spend most of my waking hours either causing software failures, or debugging them.) Since it is impossible to avoid every failure, the ability to recover from failures is a crucial part of every software system design.

A classic type of failure involves moving money between bank accounts. It's a 2-phase set of actions. First, money is withdrawn from one account and, second, the money is deposited into a second account. This sounds simple, right? Well, suppose that the the system encounters a failure after it has withdrawn the money from the first account, but before it has had a chance to deposit into the second account? What happens to the money? How can you avoid losing this money? The answer is that you enclose these two actions into a transaction.

Transactions and ACID Properties

What exactly is a "transaction?" Like a lot of things in software, it's a buzzword that is overused. But beyond that, a transaction is a logical grouping of actions into a single larger action, where this larger action is performed, or not performed, based on an all-or-nothing evaluation of the results of the individual actions[1]. In the case of the transfer of money example we just mentioned, wrapping the two transfers into a transaction would ensure that if either transfer failed, your money would not be lost, and both accounts would be restored to their original condition.

Transactions are frequently described in terms of having an "ACID"[2] set of properties:

Atomicity - When we talk about wanting a transaction to be "atomic" what we mean is that we want the transaction, which will be made up of a set of individual actions, to be treated as a single atomic unit. If any of these actions fails, such as one of the bank account transfers in our example, then the entire transaction is canceled. (The term used for this is "rolled back.") A transaction is an all-or-nothing construct. All the actions enclosed by the transaction must be completed successfully before the transaction itself is completed (or "committed.")
Consistency - Transactions don't leave the data that it works on in a partially finished state. If a transaction rolls back, the data or database in question is returned to the (consistent) state that it was in before the transaction started.
Isolation - In the context of a transaction, "isolation" refers to how any conditions or state created by a transaction are not visible to any other transaction. For example, if our bank account transfer was executed in a transaction, then while it was executing, any other transactions or operations would not be able to see any of results of the transaction until the entire transaction had completed.
Durability - One of the dangers of the bank account transfer example, if it were to be attempted outside of a transaction, is that if something went wrong, data (or even worse, money!) would be lost. Because a transaction guarantees the consistency of the data, that data is durable. If the transaction rolls back, the original data is restored.

Transactions and the SOA Platform's JBossESB

OK, this is all interesting, but it sounds like something better suited to databases than Service Oriented Architecture. How does a transactional model apply to the JBossESB in the SOA Platform where everything is either a message or a service?

Here's how: some transports supported by the Platform (InVM[3] and JMS) support a transactional delivery of messages. The actual delivery of that message will not happen until the transaction is committed. How can you cause a rollback of a transaction in an action pipeline to occur? By configuring the application and its services to include the transaction and then by raising a RuntimeException in the action pipeline. The best way to explain and illustrate how this is with one of the SOA Platform's "quickstart" example programs. Let's take a look.

The Quickstart

One of the great features of the SOA Platform is its extensive, and always growing, set of "quickstart" programs. These programs illustrate various features supported by the Platform and serve as a great resource for writing your own applications. For our example, we'll look at the aptly named "jms_transacted" quickstart.

This quickstart illustrates using the JMS transport with the JBossESB in the SOA Platform to handle transactions. The quickstart also shows how message redelivery can be performed with the JMS transport. Before we examine the quickstart's code, configuration files, and actual output, it's important that we make note of the quickstart's use of JCA (Java Connector Architecture) [4]. JCA provides a standardized way to connect to JMS providers. For the JBossESB in the SOA Platform, jms-jca-providers provide transaction support for the action pipeline by enclosing actions in a JTA [5] transaction. These transactions ensure that messages are handled within an enclosing transaction. If something goes wrong in the transaction, the messages are put back into the JMS queues to be reprocessed. We'll see this in action when we run the quickstart.

The sequence of actions that the quickstart performs is:

Like many of the SOA Platform's quickstarts, things begin by having a JMS message routed to a service to start the action pipeline.
The first time that the pipeline is entered, a row is inserted into the quickstart's HSQLDB database. Note that while the SOA Platform supports multiple databases such as MySQL, Oracle, PostgreSQL and others, in production environments, it includes a fully functional HSQLDB database for demonstration purposes.
Then, the org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction class is called to raise an exception. This action class is configured to raise the exception (5) times, so as to force a rolback of the transaction that encloses the writes to the database. Each time that the exception is raised, the JCA adapter rolls back the transaction. The exception is also propagated to the JCA adapter and written error messages to the log.
After the configured limit of (5) rollbacks is reached, the org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction class completes and the transaction is committed by the SOA Platform's JBossESB's org/jboss/soa/esb/common/JBossESBTransactionService class so that the net result is only one row written to the database.

Now, we'll take a detailed look at how this transaction is configured, and just what happens as the quickstart runs.

The Quickstart - In Detail

The transaction in quickstart includes both JMS messaging and writing to a database. Let's start by examining the connection to the HSQLDB database that the quickstart uses. First, we need to create a datasource definition to connect to the database.

In file: quickstart-ds.xml

1   <datasources>
2   <local-tx-datasource>
3      <jndi-name>JmsTransactedDB</jndi-name>
4      <connection-url>jdbc:hsqldb:hsql://localhost:1706</connection-url>
5      <driver-class>org.hsqldb.jdbcDriver</driver-class>
6      <user-name>sa</user-name>
7      <password></password>
8      <min-pool-size>5</min-pool-size>
9      <max-pool-size>20</max-pool-size>
10     <idle-timeout-minutes>0</idle-timeout-minutes>
11     <depends>jboss:service=JmsTransactedDB</depends>
12     <prepared-statement-cache-size>32</prepared-statement-cache-size>
13  </local-tx-datasource>
14
15  <mbean code="org.jboss.internal.soa.esb.dependencies.HypersonicDatabase"
16     name="jboss:service=JmsTransactedDB">
17     <attribute name="Port">1706</attribute>
18     <attribute name="BindAddress">localhost</attribute>
19     <attribute name="Database">JmsTransactedDB</attribute>
20     <attribute name="Silent">true</attribute>
21     <attribute name="Trace">false</attribute>
22     <attribute name="No_system_exit">true</attribute>
23     <attribute name="DataDir">${jboss.server.data.dir}</attribute>
24  </mbean>
25  </datasources>

Some items to make note of here are:

Line 3 - We're defining a local-tx-datasource as we will want a JCA connection with transaction support[6].
Line 4 - We're use this JNDI name to reference the datasource.
Lines 5-13 - DB driver class, connection, URL, username/password, etc. for the database connection
Line 12 - MBean interface for running Hypersonic in the same VM with JBoss - note that the service name and the JNDI name as we'll refer to them later.

OK, we have a datasource that we can use to get to the HSQLDB database, and get us there in a mode that supports transactions. What's next? We have to ensure that our database actually exists before we try to use it! Luckily, the SOA Platform has a class that can initialize our database when the .esb application is deployed.

In file: jbossesb-service.xml

1  <?xml version="1.0" encoding="UTF-8"?>
2
3  <server>
4  <mbean code="org.jboss.internal.soa.esb.dependencies.DatabaseInitializer"
5      name="jboss.esb:service=JmsTransactedDatabaseInitializer">
6     <attribute name="Datasource">java:/JmsTransactedDB</attribute>
7     <attribute name="ExistsSql">select * from jms_transacted_table</attribute>
8     <attribute name="SqlFiles">
9       hsqldb/create.sql
10    </attribute>
11   <depends>jboss.jca:name=JmsTransactedDB,service=DataSourceBinding</depends>
12  </mbean>
13 </server>

There are (3) interesting things in this file:

Line 4 - This MBean creates the database on startup. How does it connect to the database? See line 6.
Line 6 - Here's a reference to our datasource. Note the JNDI name that we observed in the datasource definition file. How does the DatabaseInitializer know what the database schema look like? See line 9.
Line 9 - Here's a reference to the quickstart's src/hsqldb/create.sql file. This file create a very simple table in our database for the quickstart to use:

In file: src/hsqldb/create.sql:

create table jms_transacted_table
(
unique_id INTEGER GENERATED BY DEFAULT AS IDENTITY(START WITH 1) NOT NULL PRIMARY KEY,
data_column VARCHAR(255) NOT NULL
);

What else does the quickstart's database need? The service that creates the database (JmsTransactedDatabaseInitializer) has to be deployed. This is handled in the deployment.xml file (as are the JBoss Messaging queues that the quickstart will use):

<jbossesb-deployment>
<depends>jboss.esb.quickstart.destination:service=Queue,name=quickstart_jms_transacted_Request_esb</depends>
<depends>jboss.esb.quickstart.destination:service=Queue,name=quickstart_jms_transacted_Request_gw</depends>
<depends>jboss.esb:service=JmsTransactedDatabaseInitializer</depends>
</jbossesb-deployment>

And finally, the jbossesb-service.xml quickstart-ds.xml files have to be included in the quickstart's .esb application archive file. This is handled by the "additional.deploys" property in the quickstart's build.xml file and the ../conf/base-build.xml file that is used by all the quickstarts.

cat -n build.xml | grep quick
<property name="additional.deploys" value="jbossesb-service.xml quickstart-ds.xml" />

OK, that takes care of the database. Now, let's look at how we configure the quickstart to take advantage of the transaction support on the JBossESB in the SOA Platform. As always, the place to begin is the jboss-esb.xml file.

In file: jboss-esb.xml

1  <?xml version = "1.0" encoding = "UTF-8"?>
2  <jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd" parameterReloadSecs="5">
3  
4   <providers>
5     <jms-jca-provider name="JBossMessaging" connection-factory="XAConnectionFactory">
6
7       <jms-bus busid="quickstartGwChannel">
8         <jms-message-filter
9           dest-type="QUEUE"
10          dest-name="queue/quickstart_jms_transacted_Request_gw"
11          transacted="true"
12      />
13      </jms-bus>
14      <jms-bus busid="quickstartEsbChannel">
15        <jms-message-filter
16          dest-type="QUEUE"
17          dest-name="queue/quickstart_jms_transacted_Request_esb"
18          transacted="true"
19      />
20      </jms-bus>
21      <activation-config>
22        <!-- The maximum number of times a message is redelivered before it is sent to the DLQ -->
23        <property name="dLQMaxResent" value="5"/>
24      </activation-config>
25
26    </jms-jca-provider>
27  </providers>
28
29  <services>
30    <service
31      category="JMSSecuredESB"
32      name="SimpleListener"
33      description="JMS Secured quickstart sample">
34      <listeners>
35        <jms-listener name="JMS-Gateway"
36          busidref="quickstartGwChannel"
37          is-gateway="true"/>
38        <jms-listener name="jmssecured"
39          busidref="quickstartEsbChannel"/>
40      </listeners>
41      <actions mep="OneWay">
42
43        <action name="printMessage" class="org.jboss.soa.esb.actions.SystemPrintln">
44          <property name="message" value="JMS Transacted Quickstart entered. Message body"/>
45          <property name="printfull" value="false"/>
46        </action>
47
48        <action name="insertDBAction" class="org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction">
49          <property name="datasource-name" value="java:JmsTransactedDB"/>
50          <property name="db-insert-sql" value="insert into jms_transacted_table(data_column) values(?)"/>
51        </action>
52
53        <!--
54          Will throw an Exception for the configured number of rollbacks. This should trigger the transaction to be
55          rolledback and the message placed back onto the JMS queue.
56        -->
57        <action name="throwExceptionAction" class="org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction">
58          <property name="rollbacks" value="5"/> <!-- if greater than dLQMaxResent then message goes to the JMS DLQ -->
59        </action>
60
61        <action name="printMessageDone" class="org.jboss.soa.esb.actions.SystemPrintln">
62          <property name="message" value="JMS Transacted Quickstart processed successfully. Message body"/>
63          <property name="printfull" value="false"/>
64        </action>
65
66        <!-- The next action is for Continuous Integration testing -->
67        <action name="testStore" class="org.jboss.soa.esb.actions.StoreMessageToFile"/>
68      </actions>
69    </service>
70  </services>
71
72  </jbossesb>

Line 2 - Before we go any further, we should look at the XSD (XML schema definition) for jboss-esb.xml files. The schema definition is available here: http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd. If you're going to be working with the SOA Platform, it's a good idea to become familiar with this XSD as all the elements that you work with in jboss-esb.xml are defined there. The two main elements are of course, providers and services. Let's look at the providers first. Two types of providers are supported. Schedule providers define schedule driven listeners that pull messages from queues at (you guessed it) scheduled time periods. In contrast, bus providers such as the jms-jca-providers that we're using in this quickstart, are associated with listeners that have messages pushed to them. [7]
Line 5 - Here's the start of our jms-jca-provider. Note that the XAConnectionFactory provides support for distributed transactions
Lines 7-13 - This is a reference to the channel and JMS queue that will be used when a JMS message that is sent to a JMS gateway to initiate the quickstart. Let's stop for a second and talk about the forms in which data is moved onto and across the JBossESB in the SOA Platform. One of the primary functions performed by JBossESB is the routing of messages between services. (I said it before, and I'll say it again; remember that, on an ESB, everything is either a message or a service.) The messages that JBoss ESB handles conform to org.jboss.soa.esb.message.Message. Service endpoints that can process messages in this format are described as being "ESB-aware." This is all well and good for services and applications that were designed and written with this message format in mind, but what about other services, including legacy applications, that communicate through other non-ESB aware data formats? JBossESB handles connecting services that communicate in non-ESB aware message formats through its gateway listeners. These listeners route incoming messages from outside the ESB to ESB services. The ESB's set of gateway listeners (generally referred to as "gateways") support a variety of message formats such as files, FTP, and JMS. These gateways accept messages in a non-ESB aware format onto the ESB and then convert them (actually, they wrap the message payload) into ESB-aware messages before sending them to their service's action pipeline.
Line 11 - Remember, we want the service to process messages within a transaction.
Lines 14-20 - Gateways are intended to enable the JBossESB to communicate to external data sources. The gateways themselves don't move data across the ESB. Accordingly, for each Gateway channel that we define, we have to define a corresponding ESB-aware channel to be used to route messages within the ESB.
Line 21 - The activation-config defines how we link to the JCA. In the case of this quickstart, the interesting property is: dLQMaxResent. As the comment indicates, the “DLQMaxResent” controls how many times the JCA adapter resends the message before it is sent to the dead letter queue. This is a JBossESB service that handles messages for transports when the messages cannot be delivered. (The JMS transport actually has its own dead letter queue as JBoss Messaging is shipped with a set of pre-configured destinations defined in destinations-service.xml including: <mbean code="org.jboss.jms.server.destination.Queue" name="jboss.messaging.destination:service=Queue,name=DLQ") In this quickstart, the JCA adapter will try to send the message 5 times.

After our providers are defined, we can define our services.

A service is where thing happen. Each service definition includes a set of listeners and a sequential set of actions referred to as an "action pipeline." The listeners "listen" for incoming messages for the service and route those messages to the action pipeline.

After the service name and category are defined on lines 31 and 32, we define the service's listeners:

Lines 35-37 - Here's the JMS gateway listener definition. Notice how it references the bus ID of the channel that we defined in earlier in the provider definition. Also, notice how it's "is-gateway" property is set to true to indicate that this listener is a gateway.
Lines 38-39 - And here is the ESB-aware listener that corresponds to the gateway listener.

So much for the listeners, now let's look at the actions.

Line 41 - This is the start of the definitions of the sequence of actions that we referred to as the action pipeline. The message exchange pattern (or "mep") indicates that the messages are not being exchanged in a request/response pattern, but rather are being sent in only one direction. (In contrast, web services exposed on the ESB would follow a synchronous request/response pattern.)
Lines 43-46 - This action invokes the simplest of the JBossESB's many useful out-of-the-box actions (http://soa.dzone.com/articles/works-great-right-out-box) to write some messages to the server log.
Lines 48-51 - Here's where things start to get interesting. This custom action writes a row to our database table. Remember the "java:JmsTransactedDBdatasource" that we defined? Here's where gets used.
Line 57 - Remember how we talked about how to cause a rollback of a transaction in the action pipeline to occur? We configured the .esb to include a transaction, and now we raise a RuntimeException in the action pipeline. The action defined here raises an exception of a type that we define in the org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction class. The ActionProcessingPipeline will catch the exception and pass it up the stack to its caller, the JMS/JCA adapter. The Adapter then causes the transaction to rollback and the message is redelivered.
Line 58 - When we defined the jms-jca-provider's activation-config, we specified a dLQMaxResent value of 5 to indicate that if the transaction was rolled back more than 5 times, the message processed in the transaction should be sent to the JMS dead letter queue. In line 58, we also set the value of the rollbacks property equal to 5, to ensure that the transaction can complete after 5 rollbacks, and the message is not sent to the dead letter queue service. As the comment helpfully explains, setting the rollbacks property to be greater than dLQMaxResent will send the message to the dead letter queue service.
Lines 61-64 This action is only reached after the rollbacks have been performed and the transaction is able to complete. The action writes the message body to the server log.

Yogi Berra once said that "In theory there is no difference between theory and practice. In practice there is."[8] OK. Enough theory, let's run the quickstart and watch what happens.

After the SOA-P server is started, the quickstart, is deployed with this command: ant deploy

When the quickstart is deployed, the following is to the server.log:

2010-04-07 09:26:22,117 INFO  [org.jboss.resource.connectionmanager.ConnectionFactoryBindingService] (HDScanner) Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=JmsTransactedDB' to JNDI name 'java:JmsTransactedDB'
2010-04-07 09:26:22,157 INFO  [org.jboss.internal.soa.esb.dependencies.DatabaseInitializer] (HDScanner) Initializing java:/JmsTransactedDB from listed sql files
2010-04-07 09:26:22,326 INFO  [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (HDScanner) Starting ESB Deployment 'Quickstart_JMS_Transacted.esb'

Note how the JmsTransactedDB database is initialized by org.jboss.internal.soa.esb.dependencies.DatabaseInitializer class the when the quickstart is deployed.

Next, we run the quickstart with this command: ant runtest

When the ant runtest target is executed, the following chain reaction is started:

The org.jboss.soa.esb.samples.quickstart.jmstransacted.test.SendJMSMessage class sends a (non-ESB aware) JMS message to the quickstart_jms_transacted_Request_gw queue. The message is routed through that queue's corresponding ESB-aware queue (quickstart_jms_transacted_Request_esb) to the SimpleListener service and the action pipeline is initiated.

The first time that the action pipeline is started, the org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction class inserts a row into the database through the HSQLDB datasource. This results in the following messages being written to the server.log:

Then, the org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction runtime exception is thrown.

Since this exception is thrown from inside the action pipeline, the JMS/JCA adapter rolls back the enclosing transaction. The exception is propagated to the JMS/JCA adapter as the exception is passed up the stack from the action pipeline to its the caller (which is the adapter). The exception is caught by the JBossESB's org.jboss.soa.esb.listeners.message.ActionProcessingPipeline, and is propagated up the stack to the JMS/JCA adapter (which is the action pipeline's caller). The adapter causes the transaction to rollback. This results in the row being removed from the database and in the original message being redelivered. Remember what we said about a transaction being an "all or nothing" event?

The transaction/rollback sequence then repeats until the configured number of rollbacks are performed. You can see a counter (maintained by the org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction class) of the number of times the action is attempted.

The printMessage action prints the message to the log:

2010-04-07 09:26:35,340 INFO  [STDOUT] (WorkManager(2)-9) JMS Transacted Quickstart entered. Message body:
2010-04-07 09:26:35,340 INFO  [STDOUT] (WorkManager(2)-9) [Hello Transacted JMS World]].

And the insertDBAction action writes the row to the database - note the counter value of [1]:

2010-04-07 09:26:35,415 INFO  [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction] (WorkManager(2)-9) Successfully inserted [Hello Transacted JMS World] counter[1]] into jms_transacted_table

But wait! Then our exception is raised:

2010-04-07 09:26:35,488 ERROR [org.jboss.resource.adapter.jms.inflow.JmsServerSession] (WorkManager(2)-9) Unexpected error delivering message delegator->JBossMessage[5204569273565185]:PERSISTENT, deliveryId=0
java.lang.IllegalStateException: [Throwing Exception to trigger a transaction rollback]
at org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction.process(ThrowExceptionAction.java:75)

The JMS/JCA adapter rolls back the transaction, and the message is delivered again, and another row is written to the database. The counter is incremented to [2] this time and the exception is raised again.

2010-04-07 09:26:36,435 INFO  [STDOUT] (WorkManager(2)-10) JMS Transacted Quickstart entered. Message body:
2010-04-07 09:26:36,435 INFO  [STDOUT] (WorkManager(2)-10) [Hello Transacted JMS World]].
2010-04-07 09:26:36,438 INFO  [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction] (WorkManager(2)-10) Successfully inserted [Hello Transacted JMS World] counter[2]] into jms_transacted_table
2010-04-07 09:26:36,442 ERROR [org.jboss.resource.adapter.jms.inflow.JmsServerSession] (WorkManager(2)-10) Unexpected error delivering message delegator->JBossMessage[5204569273565185]:PERSISTENT, deliveryId=1
java.lang.IllegalStateException: [Throwing Exception to trigger a transaction rollback]
at org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction.process(ThrowExceptionAction.java:75)

When the rollback counter number is reached, the action pipeline completes and the transaction commits so that the row is finally written to the database. The following messages are written to the servler.log - This sequence repeats (5) times until the counter is passed and the row is actually written to the database:

2010-04-07 09:26:40,489 INFO  [STDOUT] (WorkManager(2)-14) JMS Transacted Quickstart entered. Message body:
2010-04-07 09:26:40,489 INFO  [STDOUT] (WorkManager(2)-14) [Hello Transacted JMS World]].
2010-04-07 09:26:40,490 INFO  [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.DBInsertAction] (WorkManager(2)-14) Successfully inserted [Hello Transacted JMS World] counter[6]] into jms_transacted_table
2010-04-07 09:26:40,490 INFO  [STDOUT] (WorkManager(2)-14) JMS Transacted Quickstart processed successfully. Message body:
2010-04-07 09:26:40,490 INFO  [STDOUT] (WorkManager(2)-14) [Hello Transacted JMS World]].

Now, as I mentioned in the beginning of this post, I work as a software QE engineer. One of the basic tenents of software QE is to never trust anything. Let's take a closer look at what happens when the quickstart runs.

Server logs are goldmines for gathering debugging information. Let's restart the server, but this time set the server logging level to DEBUG:

./run.sh -Djboss.server.log.threshold=DEBUG

And then rerun the quickstart. The server.log will be much more verbose this time, but if you look closely, you can see the rollback counter in action:

grep  nr-of-rollbacks server.log
2010-04-07 23:14:19,776 DEBUG [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction] (WorkManager(2)-11) rollbackCounter [0], nr-of-rollbacks [5]
2010-04-07 23:14:20,804 DEBUG [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction] (WorkManager(2)-12) rollbackCounter [1], nr-of-rollbacks [5]
2010-04-07 23:14:21,819 DEBUG [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction] (WorkManager(2)-13) rollbackCounter [2], nr-of-rollbacks [5]
2010-04-07 23:14:22,833 DEBUG [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction] (WorkManager(2)-14) rollbackCounter [3], nr-of-rollbacks [5]
2010-04-07 23:14:23,848 DEBUG [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction] (WorkManager(2)-15) rollbackCounter [4], nr-of-rollbacks [5]
2010-04-07 23:14:24,858 DEBUG [org.jboss.soa.esb.samples.quickstart.jmstransacted.test.ThrowExceptionAction] (WorkManager(2)-16) rollbackCounter [5], nr-of-rollbacks [5]

Before we move on, let's look at one more thing and verify that only one row is actually written to the database. Now, the quickstart is very tidy and always cleans up after itself by removing rows from the database. Let's disable this cleanup by removing this target from the quickstart's build.xml file:

cat build.xml | grep truncate

And, let's start the server again, but with one additional command line option: sh ./run.sh -Djava.awt.headless=false

Why "headless=false?" After we run the quickstart again, the row that was written to the database should still be there. We'll look at it with the HSQL DB Manager service. This service requires the server to not be started in its default "headless" mode, as the service opens up a Java UI application. We invoke the DB Manager from the JMX console - see screenshot - the service tag is: database=jbossesb,service=Hypersonic.

Once the DM Manager application UI launches, we just connect to the "JmsTransactedDB" database - see screenshot - and execute a query to return all rows in the "jms_transacted_table" - see screenshot.

And, there is our one record!

Before we move on, it's worthwhile to note what we did NOT have to do to execute a transaction with the SOA Platform.

We did not have to write transaction specific code. The JBossESB in the Platform did the dirty work for us. All we had to do is to define the .esb application's configuration in its jboss-esb.xml file to include the transaction-relevant properties and reference a JMS/JCA adapter and the Platform did the rest. This is what makes middleware so useful. You could write the code to handle transactions all on your own, but wouldn't you rather concentrate on solving your own business problems instead of build infrastucture plumbing? [9]

Closing Thoughts

The value that using transactions adds to an application is pretty obvious (just keep your bank account in mind). The value added by middleware in implementing transactions should also be obvious. You could write your own code to handle atomicity, consistency, isolation and durability, but, this would not be an easy task, and it would also take away a lot of time from your being able to concentrate on solving your own business logic problems. The SOA Platform's support for transactions over the JBossESB enables you to provide a higher level of reliability and durablity to your service based applications.

References

[1] http://qconlondon.com/london-2010/file?path=/qcon-london-2010/slides/MarkLittle_TransactionsOverUsedOrJustMisunderstood.pdf

[2] Little, Mark, Maron, Jon, Pavlik, Greg. Transaction Processing: Design and Implementation, Upper Saddle RIver, new Jersey: Prentice Hall/Hewlett-Packard Professional Books, 2004.

[3] http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/5.0.0/html-single/Programmers_Guide/index.html#sect-SOA_ESB_Programmers_Guide-What_is_a_Service-InVM_Transport

[4] http://java.sun.com/j2ee/connector/

[5] http://java.sun.com/javaee/technologies/jta/index.jsp

[6] http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Server_Configuration_Guide/4/html/Connectors_on_JBoss-Configuring_JDBC_DataSources.html

[7] http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/5.0.0/html-single/Programmers_Guide/index.html#sect-SOA_ESB_Programmers_Guide-Configuration-Providers

[8] http://en.wikiquote.org/wiki/Yogi_Berra

[9] http://magazine.redhat.com/2008/03/11/what-is-middleware-in-plain-english-please

Acknowledgments

As always, I want to thank the JBoss SOA Platform team and community (especially Kevin Conner for his timely review input for this blog post).

SOA and Cloud

2010-03-26T04:51:00.000-07:00

I may not agree with Anne that SOA is dead, but she's spot on with this analysis!

SOA Platform 5.0 Announced

2010-03-22T09:11:00.000-07:00

Big news today!

JBoss Enterprise SOA Platform v5.0 and JBoss Developer Studio V3.0 were formally announced today. This major release of the SOA Platform is built on JBoss Enterprise Application Platform v5 and provides multiple development productivity and management enhancements including new management consoles, updates to the enterprise services bus to support a new XSLT transformation tool, easier content based routing, enhanced protocol listeners, better web services integration, a new rules engine that can be managed by JBoss Enterprise BRMS (business rules management system), enhanced registry (UDDI v3). JBoss Developer Studio V3.0 is built on the latest major release of Eclipse 3.5 and includes enhancements to make it easier to create SOA services and data transformations.

The press release is here - http://www.redhat.com/about/news/prarchive/2010/soa-enhanced.html

And, Pierre Fricke has written a blog post on the SOA Platform release here: http://blogs.jboss.org/blog/pfricke/

Out-of-the box actions post picked up by DZone...

2009-09-16T18:29:00.001-07:00

Here it is:

http://soa.dzone.com/articles/works-great-right-out-box

Works Great Right Out of the Box

2009-09-14T16:43:00.000-07:00

In reviewing my last two posts to this blog, I realized that I've actually been describing several of the SOA Platforms out-of-the-box actions in an ad hoc manner. I thought that this might be a good time to take a step back and review the platform's full set of out of the box actions.

Which got me thinking about how useful it is when a tool works "right of of the box" and how disappointing it can be when it doesn't.

In his book "Diary of a Wimpy Kid, The Last Straw,"[1] author Jeff Kinney has the main character, angst-ridden middle school student Greg Heffley, finds an ad for "personal hovercraft" in a comic book. Greg imagines himself as the coolest kid in school if he could get his own hovercraft, so he sends all his saved-up money away for one. He is, of course, disappointed when he opens the box and finds not a functioning personal hovercraft, but the plan to build one.

Step one in the plan reads: "Acquire an industrial twin-turbine engine."

In contrast, the SOA Platform provides an extensive set of actions[2] that work right out of the box. The SOA Platform also supports the creation of custom actions, but, when you are designing how your application will make use of the Platform, the place to start is the out-of-the-box actions. These have all been tested so you can depend on the results they will achieve, and they've also been documented and illustrated in the quickstart sample programs. (On a personal note, my introduction to the SOA Platform included my spending several hours building an action, when an out of the box action for the same task already existed!)

The out-of-the-box actions implemented in the SOA Platform are divided into the following functional groups:

Transformers and Converters - converting message data from one form to another
Business Process Management - integrating with JBoss jBPM
Scripting - automating tasks in supported scripting languages
Services - integration with EJBs
Routing - moving message data to the correct services
Notifier - sending data to ESB unaware destinations
Webservices/SOAP - the name says it all - support for Webservices

(There's also a Miscellaneous group that includes only one action - org.jboss.soa.esb.actions.SystemPrintln. This action prints of a message.)
Let's take a quick look at all of these actions, and then a more in-depth look at a couple of them.

Transformers and Converters

These actions are needed to enable services that expect data in different forms to communicate with each other. What transformers and converters do is to translate message payloads into different forms. Let's stop for a minute and review the contents of messages as they are passed over the JBossESB in the SOA Platform. Messages implement the org.jboss.soa.esb.message.Message interface. From the point of view of a service, the data in a message, in other words, the message "payload" consists of the message body plus attachments and properties. The default way for an action to get or set a message payload is the MessagePayloadProxy utility class. This class is important as it provides a standard way to get the message payload.

The actions in the Transformers and Converters actions group (yes, the names are pretty self-explanatory) are:

ByteArrayToString (org.jboss.soa.esb.actions.converters.ByteArrayToString) - This action converts a byte[] message payload into a Java String
LongToDateConverter (org.jboss.soa.esb.actions.converters.LongToDateConverter) - And this action converts a Java long message payload into a java.util.Date
ObjectInvoke (org.jboss.soa.esb.actions.converters.ObjectInvoke) - Things start to get a little more interesting with the ObjectInvoke converter. This action takes a serialized object, which constitutes the entire Message payload, and passes it to a configured processer class. The processed results become the new message payload. The action lets you use your own POJOs as the message payloads.
ObjectToCSVString (org.jboss.soa.esb.actions.converters.ObjectToCSVString) - This action converts a message into a comma separated string based on a list of property names that you supply.
ObjectToXStream (org.jboss.soa.esb.actions.converters.ObjectToXStream) - This action is similar to the ObjectInvoke action, except that it converts the object to XML using XStream[3]. You've probably already guessed that the XStreamToObject action converts XML to an object using XStream.
SmooksAction (org.jboss.soa.esb.smooks.SmooksAction) - This action enables you to use a powerful set of Smooks[4] operations within the SOA Platform. Transformations are probably the first type of operation that you think of with Smooks, but with the SmooksAction you can also make use of Smooks operations such as splitting and routing message payloads[5]. We'll take a closer look at this action later in the post. (Note that the SmooksTransformer action is being deprecated in favor of the SmooksAction action.)
PersistAction (org.jboss.soa.esb.actions.MessagePersister) - This action doesn't really transform or convert a message, it writes it to the persistent message store. The most common use of the action is that it is how the SOA Platform itself writes messages to the dead letter queue (DLQ), but it can be used in any situation when you want to store a message.

Business Process Management

This action group contains only one out of the box action (org.jboss.soa.esb.services.jbpm.actions.BpmProcessor), but that one action supports the JBossESB - jBPM integration in the SOA Platform. This integration enables your services to make calls into a jBPM process through the jBPM Command API. Of the commands in the command API, the following (3) are available for use from ESB:

NewProcessInstanceCommand creates a new ProcessInstance using a process definition that has already been deployed to jBPM. The process instance is left in the start state so that tasks referenced by start node are executed.
StartProcessInstanceCommand is the same as NewProcessInstanceCommand, except that the process instance that is created is moved from the start position to the first node in the process graph.
As its name implies, CancelProcessInstanceCommand cancels a process instance.

But, this is only part of the JBossESB - jBPM integration. The integration also supports the orchestration of services from jBPM processes. For a fuller description of the integration, see: http://jboss-soa-p.blogspot.com/2009/06/hanging-together-on-soa-platform.html

Scripting

This group of actions makes it possible for you to create custom actions using scripting languages. As of release 4.3 of the SOA Platform, scripting actions in Groovy and Bean Scripting Framework (BSF) are supported.

GroovyActionProcessor (org.jboss.soa.esb.actions.scripting.GroovyActionProcessor) - which uses Groovyscripts
ScriptingAction (org.jboss.soa.esb.actions.scripting.ScriptingAction) - which uses the Bean Scripting Framework and supports BeanShell, Jython and JRuby scripts

Both these actions accept the message payload and configuration data such as a Log4J logger as variables for the script that is executed by the action. In addition, they both support having scripting contained within the message itself.

Services

There's only one action in this group, but it's an important one.

The EJBProcessor (org.jboss.soa.esb.actions.EJBProcessor) action accepts a message and uses it to locate and invoke an EJB. (The SOA Platform supports both EJB2 and EJB3 through this action.) In order to find the correct EJB and invoke the correct method, you specify information such as the jndi-name, initial-context-factory, provider-url, method name and and other configuration specific to the EJB as message properties

Routing

One of the major tasks that the JBoss ESB in the SOA Platform performs is the routing of messages to services. (Remember that in an ESB, everything is either a message or a service.) In an earlier post, I described how to use JBoss Rules to perform content based routing (CBR), where the content of an incoming message determines its routing. The full set of routing actions are:

Aggregator (org.jboss.soa.esb.actions.Aggregator) - This is an interesting one. The Aggregator, as its name indicates, aggregates information together. This action enables you to combine information from multiple messages into one message. The Aggregator action is an implementation of the Aggregator Enterprise Integration Pattern[6].
EchoRouter (org.jboss.soa.esb.actions.routing.EchoRouter) - In contrast, the EchoRuter just logs and returns the incoming message.
HttpRouter (org.jboss.soa.esb.actions.routing.HttpRouter) - The HttpRouter routes the incoming message to a URL that you specify in the action definition.
JMSRouter (org.jboss.soa.esb.actions.routing.JMSRouter) - This action routes the incoming message to JMS. For example, to a JMS queue where a service can then retrieve the message asynchronously. In order to find the correct JMS queue or topic, you specify values for properties such as jndi-name, initial-context-factory, and jndi-URL in the action definition.
ContentBasedRouter (org.jboss.soa.esb.actions.ContentBasedRouter) - I described content based routing with JBoss Rules in an earlier post to this blog http://jboss-soa-p.blogspot.com/2009/07/when-content-knows-way-content-based.html). Content based routing is a flexible approach to message routing in that the content in a message is actually the determining factor in determining the route a message takes.
StaticRouter (org.jboss.soa.esb.actions.StaticRouter) - As its name implies, this router establishes static routes that do not change based on the content of the messages or a set of routing rules.
StaticWiretap (org.jboss.soa.esb.actions.StaticWiretap) - Maybe it's the comic book fan in me, but this is my favorite name for an action. There's something film noir-ish about a "wiretap." You can almost imagine Humphrey Bogart sitting it the back room of a bar listening in on a wiretapped SOA action. (On black and white film, of course.) In practice, it's not all that exciting. This action implements the Enterprise Integration Pattern for a wiretap[7]. The goal of a wiretap is to inspect each message, without affecting the operation of the action chain. This can be a useful action to use to aid in debugging a service.

Notifiers

Just as a gateway listener enables you to move ESB-unaware messages (in other words, messages in a format other than (org.jboss.soa.esb.message.Message) onto the SOA Platform's ESB, notifiers (org.jboss.soa.esb.actions.Notifier) enable you to move ESB-aware messages from the ESB to ESB-unaware services. The notifiers convert the ESB-aware messages into data into formats that these services can understand.

One thing to keep in mind is that the action pipeline has two stages, first normal processing and then outcome processing. Notifiers do not perform any processing of messages during that first stage. They send notifications during the second stage. The notification occurs after the processing of the action pipeline. This means that you cannot use notifiers to alter the results of any action processing. The data sent by the notifier is the ESB message that is processed by the action pipeline. The following notification targets (the names are very self-explanatory) are supported by the SOA Platform:

NotifyConsole - Prints the contents of the ESB message to the server log
NotifyFiles - Prints the message contents to a file or files
NotifySQLTable - Inserts the message contents into an existing database table
NotifyFTP - Prints the message contents to a file and then sends the file to a server via FTP
NotifyQueues and NotifyTopics - Writes the message contents into a JMS message and adds the JMS message to a specified JMS queue or topic
NotifyEmail - Sends the message contents in a mail message

Webservices/SOAP

When you're considering web services and the SOA Platform, you actually have two separate goals to achieve; you want to be able to expose webservice endpoints as services and you also want to be able to invoke web services from actions defined in a service.

There are (3) out of the box actions that support web services:

SOAPProcessor (org.jboss.soa.esb.actions.soap.SOAPProcessor) - This action is only available for use on the SOA Platform embedded server. You use this action to expose webservice endpoints. To do this, you write a "service wrapper webservice" that conforms to the JSR 181[8] ("Web Services Metadata for the Java Platform") standard. JSR 181 enables you to create webservices from a POJO by adding annotations such as @WebService and @WebMethod to it. This service wrapper webservice wraps calls to your service and exposes that service through JBossESB listeners. Your service can also be accessed through other transports (FTP, JMS, etc.) supported by the JBossESB in the SOA Platform. These 3 types of JBossWS webservice endpoints can be exposed through JBoss ESB listeners using this action:
- Webservice bundled into a JBossESB .esb archive - When the webservice .war is bundled into a deployed .esb archive
- Webservice bundled into an .ear - When the .war is bundled into a deployed .ear
- Standalone webservice - When the webservice .war is deployed
WISE SOAPClient (org.jboss.soa.esb.actions.soap.wise.SOAPClient) - This action uses the WISE[9] client service (org.jboss.wise.core.client.WSService) to create a JAX-WS (Java API for XML Web Services) client class and then call the target service. WISE stands for "Wise Invokes Services Easily" and enables the dynamic generation of a client to access web services, without your having to write the code for the client. (This is referred to as "zero-code web service invocation").
SOAPClient (org.jboss.soa.esb.actions.soap.SOAPClient) - This action, uses the soapUI Client Service (org.jboss.soa.esb.services.soapui.SoapUIClientService) to create a message and then route that message to the target service.

Examples

We've already walked through how to use some of the out of the box actions (Business Process Management, Routing, Notifiers) in earlier posts to this blog. Now, let's look at some examples of other types of out of the box actions. As always, the "quickstart" programs in the SOA Platform provide the example code.

Transformation

We'll start by looking at transformations and the SmooksAction out of the box action. But first, let's take a look at Smooks. It's common to refer to Smooks as a transformation engine, but that's not the full story. Smooks is really a more general purpose processing framework that is capable of dealing with with fragments of a message. Smooks accomplishes this with "visitor logic", where a "visitor" is Java code that performs a specific action on a specific fragment of a message. This enables Smooks to perform different actions on different fragments of messages. As is stated by the Smooks project[10]:

Smooks supports these types of message fragment processing:

Templating: Transform message fragments with XSLT or FreeMarker
Java Binding: Bind message fragment data into Java objects
Splitting: Split messages fragments and rout the split fragments over multiple transports and destinations
Enrichment: "Enrich" message fragments with data from databases
Persistence: Persist message fragment data to databases
Validation: Perform basic or complex validation on message fragment data

The SOA Platform SmooksAction out-of-the-box action provides you access to all these Smooks capabilities.

Let's look at a very simple example, the aptly named "transform_XML2XML_simple" quickstart. This quickstart performs a message transformation by applying an XSLT (EXtensible Stylesheet Language Transformations) to an XML message. The message is transformed into XML in a different form. The interesting parts of the quickstart's jboss-esb.xml file are:

25  <actions mep="OneWay">
26      <action name="print-before" class="org.jboss.soa.esb.actions.SystemPrintln">
27          <property name="message" value="[transform_XML2XML_simple] Message before transformation" />
28      </action>
29      <action name="simple-transform" class="org.jboss.soa.esb.smooks.SmooksAction">
30          <property name="smooksConfig" value="/smooks-res.xml" />
31          <property name="reportPath" value="/tmp/smooks_report.html" />
32      </action>
33      <action name="print-after" class="org.jboss.soa.esb.actions.SystemPrintln">
34          <property name="message" value="[transform_XML2XML_simple] Message after transformation" />
35      </action>

Line 25: This line is not specific to transformations, but it's worth mentioning. "mep" stands for "message exchange pattern." The pattern used by this quickstart is "one-way" in that the requester invokes a service (by sending it a message) and then does not wait for a response.
Lines 26-28, 33-35: These lines simply cause the message to be written to the server log before and after its transformation. (org.jboss.soa.esb.actions.SystemPrintln, is, incidentally, the only out-of-the-box action in the Miscellaneous action group.)
Line 29: Here's where we specify that we want to invoke a SmooksAction
Line 30: And here is the XSLT that will be executed. We'll examine this file in a moment.
Line 31: This line is actually not in the quickstart. I've added the reportPath property it so that we can review the resulting report. Note that generating this report does require some processing resources, so it should not be used in production environments. See below for screen-shots of this report.

Now, let's look at smooks-res.xml:

1  <?xml version='1.0' encoding='UTF-8'?>
2  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.0.xsd">
3
4      <resource-config selector="OrderLine">
5          <resource type="xsl">
6              <![CDATA[<line-item>
7                  <product><xsl:value-of select="./Product/@productId" /></product>
8                  <price><xsl:value-of select="./Product/@price" /></price>
9                  <quantity><xsl:value-of select="@quantity" /></quantity>
10              </line-item>]]>
11          </resource>
12          <param name="is-xslt-templatelet">true</param>
13      </resource-config>
14  </smooks-resource-list>

Line 2: The namespace referenced here is the Smooks XML Schema Definition
Line 4: The resource-config element corresponds to an org.milyn.cdr.SmooksResourceConfiguration object[11]
Lines 7-9: These XPath (XML Path Language) [12] statements locate the Product element's productId and price attributes and the OrderLine element's quantity attributes. XPath is used by XSLT to find or reference data in XML documents.

When you run this quickstart, you'll see the XML message as defined in SampleOrder.xml displayed before and after it undergoes the XSLT transformation.

Web Services

Another important feature of the SOA Platform is its ability to publish web services as services. Remember how we talked about how the JBossESB included in the SOA Platform made it possible to deploy web service endpoints as endpoints on the ESB? The services can then also be accessed through other transports (FTP, JMS, etc.) supported by the JBossESB in the SOA Platform.

We'll look first at the webservice_producer quickstart. This quickstart demonstrates how to expose a JSR181 web service endpoint on the JBossESB within the SOA Platform by using the org.jboss.soa.esb.actions.soap.SOAPProcessor action.

Let's begin by looking at these lines in jboss-esb.xml:

37  <actions>
38      <action name="print-before" class="org.jboss.soa.esb.actions.SystemPrintln">
39          <property name="message"
40              value="[Quickstart_webservice_producer] BEFORE invoking jbossws endpoint"/>
41      </action>
42      <action name="JBossWSAdapter" class="org.jboss.soa.esb.actions.soap.SOAPProcessor">
43          <property name="jbossws-endpoint" value="GoodbyeWorldWS"/>
44      </action>
45      <action name="print-after" class="org.jboss.soa.esb.actions.SystemPrintln">
46          <property name="message"
47              value="[Quickstart_webservice_producer] AFTER invoking jbossws endpoint"/>
48      </action>
49      <action name="testStore" class="org.jboss.soa.esb.actions.TestMessageStore"/>
50  </actions>

Lines 38 and 45: As we discussed earlier, the SystemPrintln action displays the message to the server.log
Lines 42,43: Here is where we invoke the SOAPProcessor action to generate the JSR181 web service from the specified class, GoodbyeWorldWS

17  @WebService(name = "GoodbyeWorldWS", targetNamespace="http://webservice_producer/goodbyeworld")
21  @WebMethod
22  public String sayGoodbye(@WebParam(name="message") String message) {
23
24      Message esbMessage = SOAPProcessor.getMessage();
25      if(esbMessage != null) {
26          System.out.println("**** SOAPRequest perhaps mediated by ESB:\n" + esbMessage.getBody().get());
28      }
29      System.out.println("Web Service Parameter - message=" + message);
30      return "... Ah Goodbye then!!!! - " + message;
31  }

(Remember how we talked about having to write a "service wrapper webservice" that conforms to the JSR 181 ("Web Services Metadata for the Java Platform") standard? You do this by adding @WebService and @WebMethod annotations.)

Line 17: The definition of the web service.
Lines 24-31: The definition of the method in the web service to be invoked when the action is triggered.

The following lines in jboss-esb.xml are tangential to the goal of demonstrating exposing the webservice endpoint. But it is interesting as is shows some of the paths and protocols that can be used to inserting a message into the JBossESB withing the SOA Platform:

6   <providers>
7       <jms-provider name="JBossMQ" connection-factory="ConnectionFactory">
8           <jms-bus busid="quickstartGwChannel">
9               <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_webservice_producer_gw"/>
10          </jms-bus>
11          <jms-bus busid="quickstartEsbChannel">
12              <jms-message-filter dest-type="QUEUE" dest-name="queue/quickstart_webservice_producer_esb"/>
13          </jms-bus>
14      </jms-provider>
15
16      <jbr-provider name="JBR-Http" protocol="http" host="localhost">
17              <jbr-bus busid="Http-1" port="8765" />
18          </jbr-provider>
19
20          <jbr-provider name="JBR-Socket" protocol="socket" host="localhost">
21              <jbr-bus busid="Socket-1" port="8888" />
22      </jbr-provider>
23  </providers>
30  <listeners>
31      <jms-listener name="JMS-Gateway" busidref="quickstartGwChannel" is-gateway="true"/>
32      <jbr-listener name="Http-Gateway" busidref="Http-1" is-gateway="true"/>
33      <jbr-listener name="Socket-Gateway" busidref="Socket-1" is-gateway="true"/>
34      <jms-listener name="JMS-ESBListener" busidref="quickstartEsbChannel"/>
35  </listeners>

The last quickstart we'll look at is webservice_consumer1 - as you can guess by its name, this quickstart demonstrates how to access (or "consume") a JSR181 Web Service in an ESB action by using the org.jboss.soa.esb.actions.soap.SOAPClient action.

This quickstart requires that a web service be deployed for the SOAPClient to access. The webservice is very simple and is deployed in a .war. In HelloWorldWS.java we see the definition of the web service:

28  @WebService(name = "HelloWorld", targetNamespace = "http://webservice_consumer1/helloworld")
29  public class HelloWorldWS
30  {
31     @WebMethod
32     public String sayHello(@WebParam(name = "toWhom")
33     String toWhom)
34     {
35
36        String greeting = "Hello World Greeting for '" + toWhom + "' on " + new java.util.Date();
37
38        return greeting;
39
40     }
41  }

Pay attention to the "toWhome" parameter. We'll look for this in the web service request.

In MyRequestAction.java, we see that toWhome parameter added as the key in a hashmap for the msg body:

44  /*
45   * Convert the message into a webservice request map.
46   */
47  public Message process(Message message) throws Exception
48  {
49     logHeader();
50     String msgBody = (String) message.getBody().get();
51     HashMap requestMap = new HashMap();
52
53     // add parameters to the web service request map
54     requestMap.put("sayHello.toWhom", msgBody);
55
56     // The "paramsLocation" property was set in jboss-esb.xml to
57     // "helloworld-request-parameters"
58     message.getBody().add(requestMap);
59     System.out.println("Request map is: " + requestMap.toString());
60
61     logFooter();
62     return message;
63  }

Line 54 - The towhome parameter added as the key in a hashmap for the msg body. The key of the HashMap is an Object-Graph Navigation Language (OGNL)[13] expression that identifies the SOAP parameter to be populated with the key's corresponding value. OGNL is an expression language for getting and setting Java objects properties.

Then, MyResponseAction.java retrieves the message and displays the response - see lines 54-55:

44  /*
45   * Retrieve and output the webservice response.
46   */
47  public Message process(Message message) throws Exception
48  {
49
50     logHeader();
51
52     // The "responseLocation" property was set in jboss-esb.xml to
53     // "helloworld-response"
54     Map responseMsg = (Map) message.getBody().get(Body.DEFAULT_LOCATION);
55     System.out.println("Response Map is: " + responseMsg);
56
57     logFooter();
58     return message;
59  }

In jboss-esb.xml:

36  <actions mep="OneWay">
37      <action name="request-mapper"
38          class="org.jboss.soa.esb.samples.quickstart.webservice_consumer1.MyRequestAction">
39      </action>
40      <action name="soapui-client-action"
41          class="org.jboss.soa.esb.actions.soap.SOAPClient">
42              <property name="wsdl"
43                  value="http://127.0.0.1:8080/Quickstart_webservice_consumer1/HelloWorldWS?wsdl" />
44              <property name="responseAsOgnlMap" value="true" />
45              <property name="SOAPAction" value="sayHello"/>
46      </action>
47      <action name="response-mapper"
48               class="org.jboss.soa.esb.samples.quickstart.webservice_consumer1.MyResponseAction">
49      </action>
50      <action name="testStore" class="org.jboss.soa.esb.actions.TestMessageStore"/>
51  </actions>

Line 41: The SOAPClient class makes the call to the webservice. This is the "zero-code web service invocation" that we mentioned earlier in the post.
Line 43: The reference to the web service's wsdl
Line 44: The parameter responseAsOgnlMap tells the JBossESB move the SOAP response data into that OGNL-based map and attach it to the message.
Line 45: The reference to the method to be invoked in the web service.

Closing Thoughts

It can be daunting to attempt to create a new service based application from scratch. The SOA Platform's combination of out-of-the-box actions and quickstart can make this task much easier. Even without a jet turbine engine. ;-)

Resources

[1] Kinney, Jeff, Diary of a Wimpy Kid, The Last Straw, Amulet Books; 1st edition (January 2009), ISBN-10: 0810970686, ISBN-13: 978-0810970687

[2] http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html/Programmers_Guide/chap-SOA_ESB_Programmers_Guide-Out-of-the-box_Actions.html

[3] http://xstream.codehaus.org/

[4] http://www.smooks.org/mediawiki/index.php?title=Main_Page

[5] http://www.milyn.org/javadoc/v1.0/smooks/org/milyn/container/plugin/PayloadProcessor.html

[6] http://www.enterpriseintegrationpatterns.com/Aggregator.html The patterns described at this site and in the corresponding book were created to assist designers and implementers in creating enterprise software solutions. The patterns are platform and language agnostic, so they can be very helpful across many systems.

[7] http://www.enterpriseintegrationpatterns.com/WireTap.html

[8] http://jcp.org/en/jsr/summary?id=181

[9] http://jboss.org/wise

[10] http://www.smooks.org/mediawiki/index.php?title=Why_Smooks_was_Created

[11] http://www.milyn.org/javadoc/v1.0/smooks/org/milyn/cdr/SmooksResourceConfiguration.html

[12] http://www.w3.org/TR/xpath

[13] http://www.opensymphony.com/ognl/

Acknowledgments

As always, I'd like to thank the members of the SOA Platform project for their help and timely review comments! Also, this post relies heavily on the extensive SOA Platform documents and the quickstarts.

Another post picked up by DZone...

2009-07-23T08:51:00.000-07:00

The recent post on Gateways and Notifiers in the SOA Platform was just reposted to DZone here:

http://soa.dzone.com/news/soa-platform-gateways-and

SOA Platform Gateways and Notifiers

2009-07-19T18:45:00.000-07:00

One of the strengths of the SOA Platform is how it enables you to connect legacy applications together. How are these connections made? To answer that question, we have to think about awareness.

In this context, "awareness" refers to whether or not your application clients and services are "ESB-aware" or, in other words, whether they can understand the message formats and transport protocols used by the JBossESB in the SOA Platform. If you (as a programmer) are ESB-aware, then you can simply code any new clients and services that you write to also be ESB-aware. ESB-aware clients and services communicate with each other using messages. ESB-aware services are identified using Endpoint References (EPRs). These ESB-aware messages take the form defined by the org.jboss.soa.esb.message interface.

An ESB-aware message [1] consists of the following components:

Header: the header information contains information such as the destination EPR, the sender EPR, and where the reply goes--general message-level functional information.
Context: additional information that further explains the message; for example, transaction or security data, the identity of the ultimate receiver, or HTTP-cookie-like information.
Body: the actual payload of the message.
Fault: any error information associated with the message.
Attachment: any attachments (additional files) associated with the message.
Properties: any message specific properties (for example the jbossesb.message.id property is a unique value for each message.

But...

What about cases where legacy clients and services that are not ESB-aware? This is suddenly getting complicated. It sounds like you will have to build lots of custom plumbing adapters to get all these combinations of clients and services to talk to each other. But don't panic and don't start building home-grown infrastructure. Supporting interoperability between different clients and services is one of the goals of the SOA Platform.

Interoperability through ESB adapters

One of the ways that the SOA Platform makes this interoperability possible is though gateway adapters. A gateway (org.jboss.soa.esb.listeners.gateway) is a service that acts as a bridge between an ESB-aware and an ESB-unaware client and service. Gateways translate information between ESB and non-ESB message formats and EPRs. (EPR stands for endpoint reference.) Gateways are listener processes in that they "listen" for incoming communications. They are different from ESB-aware listeners in that they accept data in different formats such as objects in files or SQL tables. ESB-aware listeners can only accept messages in the org.jboss.soa.esb.message format.

The SOA Platform supports these gateways:

file gateways: local filesystem, ftp, sftp and ftps
JMS
HTTP/HTTPS
email (POP3)
SQL table
Hibernate

When a gateway listener hears something (incoming data), it converts the non-ESB messages that it receives into the org.jboss.soa.esb.message format. How this conversion happens depends on the gateway type. For example, the file gateway takes the contents of the file and puts it into the location named "BytesBody.BYTES_LOCATION" within the message body.

Let's look at an example.

A quick start (with a quickstart)

One of the helpful features included in the SOA Platform is the set of "quickstart" sample applications. The quickstarts demonstrate SOA Platform functions and integrations. The goals of the quickstarts are to serve as learning tools and as a starting point for your own application coding. We'll examine one of these quickstarts to view the operation of a gateway.

Let's assume that you have a legacy application that stores data in text files. What you want to do is to create an ESB-aware service to read these files and process them as they are created. You could write infrastructure code that periodically polls a target directory to determine when a new file is deposited there. With the SOA Platform, however, you can simply use a file gateway.

The quickstarts are distributed under the samples/quickstarts directory. Let's take a look at helloworld_file_action.

cd samples/quickstarts/helloworld_file_action

Deploy the test to the server and run it with these simple commands:

ant deploy
ant runtest

The server log should look something like this:

16:42:22,744 INFO [STDOUT] Message structure:
16:42:22,744 INFO [STDOUT] [Hello World In A File].
16:42:22,746 INFO [STDOUT]
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
16:42:22,746 INFO [STDOUT] Body: Hello World In A File
16:42:22,746 INFO [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
16:42:22,747 INFO [STDOUT] Message structure:
16:42:22,747 INFO [STDOUT] [ message: [ JBOSS_XML ]

What just happened here? Let's take a look. The "runtest" ant target invokes CreateTestFile.java program. As its name implies, this program creates a test file. The file contains this text: "Hello World In A File"

For what happens next, we need to look at how the test application is configured. A SOA Platform application's primary configuration file is named jboss-esb.xml. In the case of this quickstart, that file is generated at run time so that the SOA Platform install directory can be determined. So, we need to look at the source of the generated file, which is this file: jboss-esb-unfiltered.xml

The first part of the file that we're interested in looks like this:

1  <fs-provider name="FSprovider1">
2      <fs-bus busid="helloFileChannel" >
3          <fs-message-filter
4              directory="@INPUTDIR@"
5              input-suffix=".dat"
6              work-suffix=".esbWorking"
7              post-delete="false"
8              post-directory="@OUTPUTDIR@"
9              post-suffix=".sentToEsb"
10             error-delete="false"
11             error-directory="@ERRORDIR@"
12             error-suffix=".IN_ERROR"
13         />
14     </fs-bus>
15 </fs-provider>

The lines that we're most interested in are:

Line 4,5: This is the definition for the input file directory and extension that the listener "listens for."
Line 6: When the message in the file is being processed, a work file with this extension is created by the listener.
Lines 7-9: And, when that processing is complete, the message is written to a file in the output directory. The file is retained after the listener is complete.
Lines 10-12: Unless something goes wrong, then the message is written to an error file.

This is the definition of the file gateway that we'll use. Note the directory names. In this example, they are filled in at run time from values determined by the directory in which you installed the SOA Platform.

Now, remember how we said that everything is either a message or a service? Scroll down in the file and we'll see our service.

1  <service
2      category="myCategory"
3      name="myFileListener"
4      description="Hello World File Action (esb listener)" >
5
6      <listeners>
7          <fs-listener name="FileGateway"
8              busidref="helloFileChannel"
9              maxThreads="1"
10             is-gateway="true"
11             poll-frequency-seconds="10"
12         />
13         <jms-listener name="helloWorldFileAction"
14             busidref="quickstartEsbChannel"
15             maxThreads="1"
16         />
17     </listeners>
18 
19     <actions mep="OneWay">
20         <action name="testAction" class="org.jboss.soa.esb.actions.SystemPrintln" />
21         <action name="action1"
22             class="org.jboss.soa.esb.samples.quickstart.helloworldfileaction.MyAction"
23             process="displayMessage,playWithMessage"
24         />
25         <action name="dump" class="org.jboss.soa.esb.actions.SystemPrintln">
26         <property name="printfull" value="true"/>
27     </actions>
28 </service>

Let's look at this service description.

Lines 7-12: First, the listeners. Note the definition of the file system (fs) listener. This is our gateway. The "busidref" field references the "fs-provider" that we discussed a minute ago. Did you notice a second listener? This is an ESB-aware JMS listener. It is there because the SOA Platform requires that each gateway have a corresponding ESB listener defined.
Lines 19: Let's look at the actions. The "mep" definition of "OneWay" refers to the action pipeline (the sequence of actions) explicitly not sending a response. (You can find more detail about these definitions in the SOA Platform Programmers' Guide [2].)
Lines 20, 25-26: The actions named "testAction" and "dump" write the message to the server log.
Lines 21-23: The action that we're most interested in is "action1." The methods (displayMessage, playWithMessage) in the class referred to by this action (org.jboss.soa.esb.samples.quickstart.helloworldfileaction.MyAction) receive the data in the input file as an ESB-Aware message, extract that information, and process it. In the case of your application, you would replace “MyAction” with your own business logic code.

So, in summary, what happens when this quickstart is run?

The file system gateway is initialized.
A file is created in the input directory defined in its fs-provider definition.
The gateway reads the file, transforms it into an ESB-aware message, and passes the message to the methods in the action class defined in the action definition.
These methods process the message (in the case of the quickstart, they write the message contents to the server log).5. The gateway moves the file to the output directory defined in its fs-provider definition.

It's important to note that the only new code that had to be written is the action class. The infrastructure code to listen for and transform the file into a message in the format that the SOA Platform can process is all part of the gateway.

From the perspective of an application developer, this is a plus as you can concentrate on writing code to fulfill the business process requirements of your application.

From the perspective of a QE engineer, this is a real plus as it means that less code has to be written. And, the less code, the fewer opportunities for bugs!

The Data is in the SOA Platform, Now What?

The gateway listeners make it possible for your legacy applications to get data into the SOA Platform's ESB and have that data transformed into ESB-aware messages, so that the ESB can route the data to the desired destination service. However, that's only have the battle if the destination service is another legacy application that is also not ESB-aware. How can you easily transform the messages into a form that a legacy application can process?

The answer is to use one of the SOA Platform's notifiers. Just as a gateway listener enables you to move ESB-unaware messages onto the SOA Platform's ESB, notifiers enable you to move ESB-aware messages from the ESB to ESB-unaware services. The notifiers convert the ESB-aware messages into data into various forms that your services can understand. The SOA Platform supports these notifiers:

NotifyConsole
NotifyFiles
NotifySQLTable
NotifyFTP
NotifyQueues
NotifyTopics
NotifyEmail

Let's add some of these notifiers to the helloworld_file_action quickstart. Note that while there are other quickstarts dedicated to illustrating notifiers, our expanding on the helloworld_file_action quickstart is in keeping with one of the goals of the quickstarts; to give you a starting point for developing your own customer applications.

One thing to keep in mind is that the action pipeline has two stages, first normal processing and then outcome processing. Notifiers do not perform any processing of messages during that first stage. They send notifications during the second stage. The notification occurs after the processing of the action pipeline. This means that you cannot use notifiers to alter the results of any action processing. The data sent by the notifier is the ESB message that is processed by the action pipeline. [3]

Let's insert the following statements (without the line numbers) into the service defined in the quickstart's jboss-esb-unfiltered.xml file:

1  <action name="notificationAction" class="org.jboss.soa.esb.actions.Notifier">
2      <property name="okMethod" value="notifyOK" />
3      <property name="notification-details">
4          <NotificationList type="ok">
5              <target class="NotifyConsole"/>
6              <target class="NotifyFiles">
7                  <file append="false" URI="@OUTPUTDIR@/notify.txt"/>
8                  <file append="true" URI="@OUTPUTDIR@/results.log"/>
9              </target>
10             <target class="NotifyEmail" 
11                 from="soauser@server.com" 
12                 sendTo="user@server.com.com"
13                 ccTo="admin@server.com"
14                 subject="Test was successful" 
15                 message="See attached file">
16                 <attachment>@OUTPUTDIR@/notify.txt</attachment>
17             </target>
18         </NotificationList>
19         <NotificationList type="err">
20             <target class="NotifyConsole"/>
21             <target class="NotifyFiles">
22                 <file append="true" URI="@ERRORDIR@/error.log"/>
23             </target>
24         </NotificationList>
25     </property>
26 </action>

Before we re-deploy and rerun the quickstart, we'll walk through these new statements:

Line 1: Note the reference to the Notifier class
Line 2: The okMethod enables the server to notify about success or failure at each action in the action pipeline
Line 4: These notifications will happen if the processing of the action pipeline is successful
Line 5: The simplest notifier - the ESB message is sent to the server console log
Line 6: Since we started the quickstart by creating a file, we'll generate another file with the NotifyFiles notifier.
Line 7: The ESB message is written to a file named "notify.txt" in the output dir. Note that if a file with this name already exists, it is overwritten.
Line 8: We'll also append the ESB message to a log file.
Line 10: And, we'll send that same ESB message in an email - the ESB message will be in the email
Line 11: But, just to be sure, we'll also send the notify.txt file as an attachment to the email
Line 19: Finally, if the action pipeline processing encounters an error, these notifiers will execute

At this point, redeploy the quickstart and execute "ant runtest" again.

The server log should look something like this:

 2009-07-18 22:45:33,291 INFO  [STDOUT] ConsoleNotifier 2009/07/18 10:45:33.291<
BEFORE
Hello World In A File
AFTER
>
2009-07-18 22:45:33,292 INFO  [org.jboss.soa.esb.helpers.Email] Initialising mail server session. Properties: {mail.smtp.port=25, mail.smtp.auth=true, mail.smtp.host=localhost}

For the console and email notifier. An email will be sent to the addresses you specified and you should also see a file named notify.txt and results.log in the output directory. If you run the test again, you'll see the results.log file include the ESB message twice.

Closing Thoughts

With the SOA Platform's gateways and notifiers, it's possible to reuse existing applications as services that are ESB-unaware, without having to rewrite the applications' code. The applications can continue to communicate via files or FTP or database records or other data formats. The gateways and notifiers take care of getting data into the SOA Platform (where you can route it to the intended service - see the previous post on content based routing) and then back out. And, that is a lot easier than having to rewrite legacy applications. COBOL anybody? ;-)

Resources

[1] Look in this file in the javadocs installed with your SOA Platform server: jboss/soa/esb/message/Message.html
[2] http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html/Programmers_Guide
[3] http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html/Programmers_Guide/ch11s06.html

Acknowledgments

As always, I'd like to thank the members of the SOA Platform project for their help and timely review comments! Also, this post relies heavily on the extensive SOA Platform documents and the quickstarts. The information on listeners in this post was originally published in Red Hat Magazine (http://magazine.redhat.com/2008/05/22/adapters-for-an-esb). I'd like to thank everyone at the magazine for their help over the past few years, especially the magazine editor, Bascha Harris.

DZone Reposts Content Based Routing Post

2009-07-14T10:34:00.000-07:00

The recent post on Content Based Routing with JBoss Rules in the SOA Platform was just reposted to DZone here: http://soa.dzone.com/news/when-content-knows-way-content?mz=3006-jboss

It's a bit recursive - posting a post about a post - but it's good to see this subject in DZOne too!

When the Content Knows the Way - Content Based Routing in the SOA Platform

2009-07-06T19:15:00.000-07:00

In my last post to this blog, I examined the ESB-jBPM integration in the SOA Platform. This time, we'll take a look at one aspect of the integration with JBoss Rules.

Introduction

The routing of data from one place to another is one of the most basic, and common, problems facing any networked software application. This routing can take many forms, such as email being sent to the correct recipient or network traffic being routed around the globe based on system names defined in DNS.

In the context of an Enterprise Service Bus such as the JBoss ESB in the SOA Platform, where everything is either a message or a service, routing means getting messages delivered to the correct services. There are multiple ways to route data to a service. It's possible to define these routes statically, which can make sense for an application where some type of data is always directed to a set endpoint. But, this approach will fail if a destination service is unavailable or is moved. You can control the route that the messages take across the ESB in a number of ways. In this post, we'll examine routing messages based on message content with the content based routing pattern as illustrated in one of the SOA Platform "quickstart" sample programs.

JBoss Rules

One of the great challenges in developing business application software is the separation between the business logic, or the "rules" that you want to govern the application, and the technical programming tasks necessary to actually build the application. What's more, it can be expensive and difficult to maintain application code, and keep it in synch with constantly changing business conditions and while not destroying the original design and turning the code into a set of ever more complex if-then-else statements. What's needed is a mechanism to define the business rules and then execute the rules without having to hardcode the rules into the application code.

What's needed is a rules engine. JRS-94[1] defines the standard for a Java rules engine API. The standard defines the API to register, retrieve and execute rules. JBoss Drools[2] (referred to as JBoss Rules in the SOA Platform) is based on this standard, but more than just a rules API and rules programming language, Drools is a complete enterprise platform for rules-based application development, workflow, administration, and event processing. It also provides an integration with JBossESB to support content based routing.

Let's start by examining at the term "content based routing."[3] The routing part of the term is easy; we're talking about getting messages routed to the correct service. When we talk about "content based" routing, what we want to have happen is to have the ESB examine a message, and based on its content, select the correct routing path. But, we don't want to have the code to make these routing decisions built into the services or the ESB itself. We want to use a rules-based approach, where we can take advantage of the power and flexibility of a rules definition language to construct the decision making routing. We also want to take advantage of the efficiency of a rules engine to perform this routing, instead of coding complex and hard to maintain if-then-else statements into the application.

OK. It's time to look at a working example.

One of the great features of the SOA Platform is its extensive set of "quickstart" programs. These programs illustrate various features supported by the ESB. For our example, we'll look at the fun_cbr quickstart.

Like many of the quickstarts, fun_cbr starts by placing a message into a queue. A service listening to that queue then takes that message and sends it to a destination service. What we're interested in looking at in this quickstart, is how the content of that message determines the route that the message takes to one of three defined destination services.

Let's start by examining with the message and its content. When you run the quickstart, the "SampleOrder.xml" (for a mythical DVD store) is file is read into the message that is sent. The file looks like this:

In SampleOrder.xml:


    1  <Order xmlns="http://org.jboss.soa.esb/Order" orderId="1" statusCode="0"
    2      netAmount="59.97" totalAmount="64.92" tax="4.95">
    3    <Customer userName="user1" firstName="Harry" lastName="Fletcher" state="SD"/>
    4      <OrderLines>
    5        <OrderLine position="1" quantity="1">
    6        <Product productId="364" title="The 40-Year-Old Virgin " price="29.98"/>
    7      </OrderLine>
    8      <OrderLine position="2" quantity="1">
    9        <Product productId="299" title="Pulp Fiction" price="29.99"/>
   10      </OrderLine>
   11    </OrderLines>
   12  </Order>

Nothing in this content is that unusual (except perhaps for Harry's taste in movies). Make a mental note of the "statusCode" element on line #1. We'll come back to this in a bit.

OK, we have build a message that contains this content and place that message in a queue so that a service can receive it and execute an action on it. Now what?

Let's look at that action in the "jboss-esb.xml" file. (This file defines the configuration of, and the actions performed, by the quickstart.)

In jboss-esb.xml:


   44    <action class="org.jboss.soa.esb.actions.ContentBasedRouter" name="ContentBasedRouter">
   45      <property name="ruleSet" value="FunCBRRules-XPath.drl"/>
   46      <property name="ruleLanguage" value="XPathLanguage.dsl"/>
   47      <property name="ruleReload" value="true"/>
   48      <property name="destinations">
   49        <route-to destination-name="blue"  service-category="BlueTeam"  service-name="GoBlue" />
   50        <route-to destination-name="red"   service-category="RedTeam"   service-name="GoRed" />
   51        <route-to destination-name="green" service-category="GreenTeam" service-name="GoGreen" />
   52      </property>
   53    </action>

Let's examine this section of the file line-by-line:

Line 44: The org.jboss.soa.esb.actions.ContentBasedRouter class is one of the SOA Platform's predefined "Out-of-the-box Actions." The SOA Platform provides a set of these actions, that you can always augment by writing your own custom actions[4]. Before you write your own, you should take a look at the out-of-the-box actions as you may find one that meets your application's needs.

Line 45: Here's where we define the set of rules that govern the content based routing. Remember that in this context, the rules are defined as JBoss Rules. We'll examine these rules in just a minute.

Line 46: In order to be able to parse information out of XML data in a message, the SOA Platform includes a domain specific language (DSL) implementation to use XPath to traverse the XML. This is defined in the jboss-as/server/production/deploy/jbrules.esb/XPathLanguage.dsl file. If you're unfamiliar with XPath[5], it's really worth learning as it has many useful applications. For example, some GUI automation tools such as Selenium support using XPath to locate UI elements if you are unable to rely on the UI elements having static ID's. Also note that XPathLanguage.dsl supports both namespace specific and non-namespace specific syntaxes. In this quickstart, a namespace specific syntax is used.

Line 47: This property allows you to specify if the rules should be reloaded each time they are used. This has no effect on the small set of rules used in the quickstart, but it can cause a performance hit on a large set of rules. So, setting this to "true" enables you to modify the rules as defined in the copy of FunCBRRules-XPath.drl deployed to the server without having to redeploy the quickstart to the SOA-P server. Modifying the local copy of the rules file will not cause the rules to be reloaded. You have to update the drl file that is deployed with the quickstart.

Lines 49-51: These are the routes to the destination services.

Now it's time to take a look at the rules that are defined in FunCBRRules-XPath.drl

In FunCBRRules-XPath.drl:


    1  package com.jboss.soa.esb.routing.cbr
    2
    3  #list any import classes here.
    4  import org.jboss.soa.esb.message.Message;
    5  import org.jboss.soa.esb.message.format.MessageType;
    6
    7  expander XPathLanguage.dsl
    8
    9  #declare any global variables here
   10  global java.util.List destinations;
   11
   12  rule "Blue Routing Rule using XPATH"
   13    when
   14      xpathEquals expr "/order:Order/@statusCode", "0" use namespaces "order=http://org.jboss.soa.esb/Order"
   15    then
   16      Log : "Blue Team";
   17      Destination : "blue";
   18  end
   19
   20  rule "Red Routing Rule using XPATH"
   21    when
   22      xpathEquals expr "/order:Order/@statusCode", "1" use namespaces "order=http://org.jboss.soa.esb/Order"
   23    then
   24      Log : "Red Team";
   25      Destination : "red";
   26  end
   27
   28  rule "Green Routing Rule using XPATH"
   29    when
   30      xpathEquals expr "/order:Order/@statusCode", "2" use namespaces "order=http://org.jboss.soa.esb/Order"
   31    then
   32      Log : "Green Team";
   33      Destination : "green";
   34  end

Line 7: Here is the reference to the XPath definitions.

Line 10: The destinations global variable is the point of integration to the destinations defined in the jboss-esb.xml file.

The rules are all the same, except for the status code value, so we'll only examine one of them. (In the process, we'll walk through a short lesson in writing a rule.)

Line 12: The start of a rule definition.

Line 13: The start of the "when" construct of a rule. Each rule definition includes a "when" construct (the criteria that must be met) and a "then" construct (the action to take if the "when" construct is met).

Line 14: The XPath syntax translates to "starting at the root of the document, find an Order element with a statusCode attribute equal to 0."

Line 15: The then construct starts here.

Line 16: Generate a log message

Line 17: Add a destination's name to the global list called "destinations, " which is then evaluated by org.jboss.soa.esb.actions.ContentBasedRouter that invoked the rule.

If you're getting a little lost now, this diagram may shows how things are connected.
So what happens when the quickstart is deployed and run?

An incoming message is placed into the queue that is watched by the listener configured with the ContentBasedRouter action
That action is configured with the rule set defined in FunCBRRules-XPath.drl
The action class puts the message into the Rules' working memory and fires the rules
Based on the results of the rules, a list of destinations is created
And the message is sent to the services at those destinations - in the case of this test, the message is sent to the blue team

(There's actually a bit more to it for the incoming message. JBoss ESB actually routes ESB formatted messages to services. The ESB supports adapters to enable other formats for incoming messages. These adapters operate with "gateway" services to enable you to connect existing services to the SOA Platform.[6])

Closing Thoughts

As we discussed in the introduction, one of the great strengths of the SOA Platform is the set of integrations that it supports. With its integration with JBoss Rules, you can deploy Rules-based services to the SOA Platform server and utilize JBoss Rules for content based routing. With content based routing, the information in the messages themselves determine the messages' destinations.

References

[1] http://jcp.org/en/jsr/detail?id=94
[2] http://www.jboss.org/drools
[3] http://www.jboss.org/jbossesb/docs/4.3.GA/manuals/html/services/ContentBasedRouting.html
[4] http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/html/Programmers_Guide/ch11s05.html
[5] http://www.w3schools.com/XPath/default.asp
[6] http://magazine.redhat.com/2008/05/22/adapters-for-an-esb

Acknowledgments

As always, I'd like to thank the members of the JBossESB (see http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/Contributors.txt), JBoss Rules projects, SOA Platform project - especially Burr Sutter, Mark Little, Mark Proctor and Jarek Kijanowski - for their help and timely review comments! Also, this article relies heavily on the extensive JBossESB and JBoss Rules user documents and the quickstarts.

Hanging Together on the SOA Platform - Introduction to the ESB-jBPM Integration

2009-06-15T07:49:00.000-07:00

One of the great strengths of the SOA Platform is its wealth of software integrations. In this post, I'll examine the JBoss ESB - jBPM integration in the SOA Platform and how it can be used to connect business processes to services.

JBosssESB

Service Oriented Architecture (SOA) is not a single program or technology. It’s really a matter of software architecture or design. In hardware terms, a “bus” is a physical connector that ties together multiple systems or subsystems. Instead of having a large number of point-to-point connectors between pairs of systems, you connect each system to the bus once. An Enterprise Service Bus (ESB) does the same thing, logically, in software.

Instead of passing electric current or data over the bus to and from the connections (or “endpoints”) on the ESB, the ESB logically sits in the architectural layer above a messaging system. The messaging system allows for asynchronous communications between services over the ESB. In fact, when you are working with an ESB, everything is either a service (which in this context is your application software) or a message being sent between services. It’s important to note that a “service” is not automatically a web service. Other types of applications, using transports such as FTP or JMS, can also be services. Is an ESB the same thing as SOA? (Service Oriented Architecture) Not exactly. An ESB does not provide a Service Oriented Architecture, but it does provide the tools than can be used to build one–especially loose-coupling and asynchronous message passing. SOA is a series of principles, patterns, and best practices.

JBossESB [2] is an open source ESB implementation that supports multiple transports, protocols, a listener-action model for loose coupling of services, content based routing with JBoss Rules (Drools), and workflow management with jBPM.

JBoss jBPM

Business process management (BPM) is an often misused or misunderstood term.[3] There are many definitions for BPM, but the best and simplest that I can think of is that it is a systematic approach to improving business processes. What's a business process? It's important for us to understand that in this context, a "process" is not an instance of a running software program, such as the set of processes that are displayed when you type "ps" on a Unix system. In this context, a business process is the set of tasks that are performed by the systems AND the people in an organization in order to achieve that organization's goals. For example, some business processes for an insurance company would be determining risk for selling hurricane insurance in the south eastern USA, preparing actuarial tables for different demographic groups, or deciding on which pieces of junk mail to send to other demographic groups. These processes can be performed by a person, groups of people acting together, people and software services working together, or groups of services working together.

JBoss jBPM [4] is an open source business process management development environment and workflow management system. jBPM includes: a process definition language (jPDL) that combines Java and process definition, a graphical process design tool (GPD) that is implemented as an eclipse plugin, a process engine runtime (deployed to an application server) that supports long-running tasks in business processes, and a web-based console for end users to access the business process' supporting application. The GPD enables users to create process definitions by manipulating a graphic representation of the process.

A business process definition as defined in jPDL and represented in a graph in the GPD consists of multiple types of nodes that can represent tasks or a state in the process, actions which are Java code that is executed when events happen in the process, and transitions between nodes.

It's important to note the importance of state and waiting as supported by jBPM. In a long-running business process, where actions are performed by people and systems, it's often the case that the application program that supports the process has to wait for a person to do something. For example, if the process governs a company's purchasing department, the process may have to pause and wait for a person to manually approve a large purchase. Typically, when you write an application, you want function #1 to call function #2 and so on without introducing wait times. Bur, what if your application has to wait for a person to review some information and do something? We'll walk through an example of how jBPM handles waiting later on in this post. The JBossESB - jBPM integration also enables you to to "orchestrate" ESB services by invoking those services from a process definition. In this context, "orchestration" refers to combining services into a greater whole (application) while retaining some central control. Sort of like how an orchestra is comprised of many different instruments, all under the leadership of a conductor. In contrast, service "choreography" is more in the form of a collection of equal peers or partners.

In reviewing the JBossESB - jBPM integration, the three topics to consider are:

* Making Calls From the ESB to the process definition in jBPM
* Orchestrating ESB Services From jBPM to the ESB
* Exception Handling

JBossESB and jBPM Integration - Making Calls From the ESB to jBPM

Calls from the JBoss ESB into jBPM use the BpmProcessor action. This action actually uses the jBPM command API [5] to execute the calls into jBPM. Of the commands in the command API, the following (3) are available for use from ESB:

NewProcessInstanceCommand creates a new ProcessInstance using a process definition that has already been deployed to jBPM. The process instance is left in the start state so that tasks referenced by start node are executed.

StartProcessInstanceCommand is the same as NewProcessInstanceCommand, except that the process instance that is created is moved from the start position to the first node in the process graph.

As its name implies, CancelProcessInstanceCommand cancels a process instance.

All of these commands requires ESB action attributes such as process ID to be defined. The action definitions can also specify additional information in action configuration properties. For example, the "esbToBpmVars" property defines the variables that are to be extracted from the message from the ESB and set in the jBPM context. We'll look at this property when we examine a JBossESB-jPBM quickstart later in this post.

JBossESB and jBPM Integration - Orchestrating ESB Services from jBPM

Remember how we described jBPM actions as Java code that is executed when selected events happen in the business process? Well, the ESB-jBPM integration handles orchestrating ESB services from a jBPM process with the EsbActionHandler and EsbNotifier action classes. The classes are similar in that they each send a message to the target ESB service. (Don't forget that in the ESB, everything is either a message or a service.) Where they differ is that the EsbActionHandler class blocks the process and waits for a response to the message that it sends to the service. The EsbNotifier follows an asynchronous model and does not block the process and wait for a response.

How are EsbActionHandler and EsbNotifier action classes used? Since the EsbNotifier does not wait for a response to the message that it sends to a service, it should be attached to a jBPM process node's outgoing transition. This will allow the jBPM process to proceed while the message (request) sent to the target ESB service can be processed by a different thread. The EsbActionHandler, in contrast, uses a request/response asynchronous model and should be attached to a jBPM process node. When the EsbActionHandler is called, the node that is attached to waits for it to respond with a transition signal. When the node receives this signal, usually from the JBossESB callback service, the jBPM process can then continue.

JBossESB and jBPM Integration - Exception Handling - When Something Goes Wrong

A common source of problems in when you integrate products together is handling errors. In the JBossESB-jBPM integration, exceptions are handled in different ways, depending on whether a message is being passed from the ESB to jBPM, or from jBPM to the ESB.

JBossESB to jBPM exception handling is the simpler of the two. The jBPM command API (remember that the integration includes these 3 API calls: NewProcessInstanceCommand, StartProcessInstanceCommand, and CancelProcessInstanceCommand) an throw a JbpmException. The exception is not caught by the integration, but rather it goes to the ESB action pipeline, which sends the letter to the DeadLetterService and logs the message. An error message can also be sent to the ESB faultTo EPR if that property is set on the message. You define the handling of the exception by configuring an aptly-named ExceptionHandler to the jBPM process node.

jBPM to JBossESB exception handling is more complicated. If the delivery of the message to the ESB fails, then a MessageDeliveryException is thrown by the ESB ServiceInvoker. Both the EsbActionHandler and EsbNotifier actions can throw this type of exception. If the message is received by the target ESB service, but then a failure happens when it is being processed by the service, then what happens to the exception depends on whether we used an EsbActionHandler or EsbNotifier action. Remember that an EsbNotifier does not wait for a response to the message that it sends to a service. Instead, the jBPM business process continues after the message is sent to the ESB service. So, for an EsbNotifier action, the exception is not sent back to the jBPM process. If, however, an EsbActionHandler was used to send the message to the ESB service, then the jBPM business process is waiting for a response. You define the handling of the exception with a jBPM exception-transition for the EsbActionHandler.

Let's look at this integration in action by examining one of the JBossESB-jBPM quickstarts. The quickstart programs that ship with JBossESB are a great resource for learning about how to use the ESB and its integrations. At first glance, these programs may look like simple examples. But, they are much more than that. They are an extensive set of well documented models of working code that you can use as the starting point for writing your own SOA applications.

Before we examine the quickstart, we have one more setup task to perform. Now, we can run the quickstart with ESB alone installed, but anytime that you work with jBPM, you really have to look at the Graphic Process Design (GPD) tool. One of the most useful and instantly recognizable features of jBPM is how it enables you to construct a visual (graphic) representation of your business process. The process is defined in a file named "processdefinition.xml" You can always view and edit the process definition in the XML source, but its much easier to do so with the GPD.

The quickstart that we'll look at is bpm_orchestration2. This quickstart illustrates how jBPM can control a business process that executes multiple JBoss ESB processes. This quickstart makes use of synchronous calls from jBPM into the JBoss ESB processes. Let's start by looking at the quickstart's source code and its process diagram. To begin, import the quickstart as an existing project into your workspace in JBoss Developer Studio (JBDS). After the project is created, open the processdefinition.xml file to view the process design in the GPD.

One thing that you should remember when you view the process design in the GPD is that you are not looking at a static picture of the process. What you are looking at is a dynamic graphic representation of the process. Any changes that you make to the process in the GPD are reflected in the process definition source.

As I mentioned a minute ago, the bpm_orchestration2 quickstart demonstrates jBPM controlling the execution of JBossESB processes. The quickstart does this by simulating a purchase order placement and approval process. Let's examine just how this happens. To do this, we'll look at two files in the quickstart; processdefinition.xml and the JBoss ESB configuration file, jboss-esb.xml file:

jboss-esb.xml, lines 74-82:


      <action  name="start_a_new_process_instance"
                 class="org.jboss.soa.esb.services.jbpm.actions.BpmProcessor">
                  <property name="command" value="StartProcessInstanceCommand" />
                  <property name="process-definition-name" value="bpm_orchestration2Process"/>
                   <property name="esbToBpmVars">
                      <mapping esb="eVar1" bpm="counter"  value="45" />
                      <mapping esb="BODY_CONTENT" bpm="theBody" />
                  </property>
      </action>

The execution of this quickstart, like almost all of the JBossESB quickstarts, is started when a message is received by a listener defined in the ESB. In this quickstart, when that message is received by the listener, a jBPM process is started and moved from the start position to the first node in the process graph when the StartProcessInstanceCommand jBPM API call is executed.

At this point, let's switch over the the processdefinition.xml to see what happens in the start node. Open the processdefinition.xml file and switch to the "source" tab.

processdefinition.xml, lines 5-21

   <start-state name="start">
    <transition name="" to="Receive Order"></transition>
 </start-state>

 <node name="Receive Order">
       <action name="esbAction" class="org.jboss.soa.esb.services.jbpm.actionhandlers.EsbActionHandler">
          <esbCategoryName>BPM_Orchestration2_Service1</esbCategoryName>
          <esbServiceName>Service1</esbServiceName>
          <bpmToEsbVars>
              <mapping bpm="theBody" esb="BODY_CONTENT" />
          </bpmToEsbVars>
          <esbToBpmVars>
              <mapping esb="BODY_CONTENT" bpm="theBody" />
          </esbToBpmVars>
       </action>
      <transition to="Credit Check"></transition>
  </node>

The start node simply transitions to the "Receive Order" node. This node defines an action using the EsbActionHandler action class. This tells us that the invocation of the action is synchronous in nature and that the jBPM process will wait for the service referenced in the action (in this case, the service named "Service1") to complete before the jBPM process continues. The rest of the quickstart continues this pattern where the jBPM process executes actions that in turn invoke JBossESB services in a synchronous manner.

At this point, let's run the quickstart and see what happens. To do this, the steps are:

Deploy the JBoss ESB archive (/build/Quickstart_bpm_orchestration2.esb) - to do this, execute "ant deploy"
Deploy the jBPM process archive (the contents of the /processDefinition directory) - to do this, execute "ant deployProcess"
Start the process - to do this, execute "ant startProcess"

After the process is started, you should see this in the server log:

20:04:36,886 INFO  [STDOUT] ** Begin Receive Order - Service 1 **
20:04:37,399 INFO  [STDOUT] In: Getting Started
20:04:37,400 INFO  [STDOUT] Out: Getting Started 'Receive Order'
20:04:37,400 INFO  [STDOUT] ** End Receive Order - Service 1 **
20:04:38,952 INFO  [STDOUT] ** Begin Credit Check - Service 3 **
20:04:38,952 INFO  [STDOUT] In: Getting Started 'Receive Order'
20:04:38,953 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'
20:04:38,953 INFO  [STDOUT] ** End Credit Check - Service 3 **
20:04:40,443 INFO  [STDOUT] ** Begin Validate Order - Service 2 **
20:04:40,444 INFO  [STDOUT] In: Getting Started 'Receive Order'  'Credit Check'
20:04:40,444 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'
20:04:40,444 INFO  [STDOUT] ** End Validate Order - Service 2 **
20:04:42,704 INFO  [STDOUT] ** Begin Inventory Check - Service 4 **
20:04:42,704 INFO  [STDOUT] In: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'
20:04:42,705 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'
20:04:42,705 INFO  [STDOUT] ** End Inventory Check - Service 4 **
20:04:45,093 INFO  [STDOUT] ** Begin Los Angeles - Service 5 **
20:04:45,093 INFO  [STDOUT] In: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'
20:04:45,094 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'  'Los Angeles'
20:04:45,094 INFO  [STDOUT] ** End Los Angeles - Service 5 **
20:04:45,381 INFO  [STDOUT] ** Begin Atlanta - Service 7 **
20:04:45,382 INFO  [STDOUT] In: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'
20:04:45,382 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'  'Atlanta'
20:04:45,382 INFO  [STDOUT] ** End Atlanta - Service 7 **
20:04:45,660 INFO  [STDOUT] ** Begin Dallas - Service 6 **
20:04:45,661 INFO  [STDOUT] In: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'
20:04:45,661 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'  'Dallas'
20:04:45,661 INFO  [STDOUT] ** End Dallas - Service 6 **
20:04:49,357 INFO  [STDOUT] ***** Ship It *****
20:04:49,369 INFO  [STDOUT] In: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'
20:04:49,369 INFO  [STDOUT] Out: Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'  'Shipped'
20:04:49,370 INFO  [STDOUT] ***** End Ship It *****
20:04:49,392 INFO  [STDOUT] SUCCESS!:
20:04:49,392 INFO  [STDOUT] [Getting Started 'Receive Order'  'Credit Check'  'Validate Order'  'Inventory Check'  'Shipped' ].

Now, remember that what's happening is that the jBPM process is invoking a JBossESB service, waiting for the process to complete, and then invoking the next JBossESB services until all the services have been invoked and the jBPM process completes. Hmm. I don't know about you, but since I started working in QE, I've become skeptical of just about anything when it seems to "just work." The JBoss ESB services in this quickstart are implemented in simple groovy scripts. The scripts all run very quickly, so it's a little difficult to verify that the jBPM process is actually waiting for each service to complete before invoking the next service in the sequence defined in processDefinition.xml

So, let's make the delay to the jBPM process a little more obvious. If we add the following lines to scripts/service1.groovy and then deploy the ESB and jBPM process archive and run the quickstart again, we should see more obvious delay in the log:

println "Added new println - waiting .........."
for ( i in 0..1000 ) {
  print i + " "
}
println "Added new println - done waiting .........."

To make the change effective, execute "ant undeploy" then redeploy the JBossESB archive and jBPM process archive and run the quickstart again. The server log shows:

21:45:04,966 INFO  [STDOUT] ** End Receive Order - Service 1 **
21:45:04,966 INFO  [STDOUT] Added new println - waiting ..........
21:45:05,105 INFO  [STDOUT] 0
21:45:05,105 INFO  [STDOUT] 1
21:45:05,105 INFO  [STDOUT] 2
21:45:05,106 INFO  [STDOUT] 3
21:45:05,106 INFO  [STDOUT] 4
.
.
.
21:45:05,312 INFO  [STDOUT] 997
21:45:05,312 INFO  [STDOUT] 998
21:45:05,312 INFO  [STDOUT] 999
21:45:05,313 INFO  [STDOUT] 1000
21:45:05,313 INFO  [STDOUT] Added new println - done waiting ..........

And then, the rest of the JBossESB services are invoked in sequence, so, yes, the call to the service was synchronous and the process waited for the service to complete before it continued.

Closing Thoughts

As we discussed in the introduction to this post, one of the great strengths of the SOA Platform is the set of integrations that it supports. With its integration with jBPM you can combine a service oriented architecture implemented through the ESB with the flexibility of building applications based on your business processes designed with the jBPM graphical process designer. And, by using the JBossESB-jBPM integration, your applications can handle awkward situations where the application has to wait for a service, or a person, to perform an action. (So, unlike what Tom Petty said, waiting is not the hardest part... ;-)

References

[1] http://www.ushistory.org/franklin/quotable/quote71.htm
[2] http://www.jboss.org/jbossesb/
[3] Business Process Management definitions: http://searchcio.techtarget.com/sDefinition/0,,sid182_gci1088464,00.html
http://en.wikipedia.org/wiki/Business_process_management
[4] jBPM: http://www.jboss.org/jbossjbpm/ and the JBossESB jBPM Integration Chapter in the JBoss ESB Services Guide: http://www.jboss.org/jbossesb/docs/4.5.GA/manuals/html/ServicesGuide.html
[5] http://docs.jboss.com/jbpm/v3.2/javadoc-jpdl/

Acknowledgements

I want to thank the members of the JBossESB (see http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/Contributors.txt) and jBPM projects and the SOA Platform - especially Burr Sutter, Mark Little, Kurt Stam, and Tom Baeyans - for their help and review comments. Also, this post relies heavily on the extensive JBossESB and jBPM user documents and the quickstarts. (And, I'd also like to thank Bascha Harris for her feedback on the post!)

SOA Platform Talk At SOA Symposium

2009-03-05T10:20:00.001-08:00

I'm talking about Open Source and SOA at the SOA Symposium on Government and Industry Best Practices. Come along if you get a chance.

SOA Patterns podcast

2009-02-24T05:53:00.000-08:00

I did a podcast with one of my ESB/SOA book co-authors to publicize the work we did with Thomas Erl around the SOA Patterns book. I can't remember what we discussed, but I'm sure it's interesting ;-)

ESB Architecture for SOA

2009-02-09T12:51:00.000-08:00

I've been writing a book on ESB and SOA for a while now as part of Thomas Erl's SOA series. The publishers have finally put up a page for the book. From my own perspective the content of the book is influenced heavily by what you will find in the JBoss SOA Platform and its roadmap. Of course it's not a technology specific book because it needs to be able to stand on its own, so it is no replacement for the SOA-P documentation. However, you should be able to read it and think "Ah, now that makes sense from a standards perspective", or "OK, so I'd be better of using this pattern here".

When the book is finally released we'll make sure to mention it here. In the meantime you can always go out and get another good book on enterprise SOA.

Dog food tastes good!

2009-01-18T12:24:00.000-08:00

We've got quite a few success stories referenced on the SOA Resource Center. There are more in the works, but if you've ever worked on success stories before you'll know that writing them up is often difficult for a number of reasons, e.g., they can't be too technical and companies are often concerned about divulging internal secrets.

Anyway that's not the point of this posting: we're working on a couple of success stories that are based on our own internal use of the SOA Platform. Of course external readers will view these as slightly less important than "real" customers, but to be honest I think that's a bad thing. If anything they show our commitment to 'put our money where our mouth is'. In each case we've taken critical systems that have been running continuously for years based on competitor technologies and replaced them with our own products. It may seem like an obvious thing to do, but you'd be surprised how many companies don't do that. The feedback we've had from those development teams has been extremely positive and hopefully I'll be able to point at the relevant success story soon. Congratulations to everyone involved!

SOA Design Patterns

2009-01-18T12:17:00.001-08:00

I've been writing a book on SOA and ESB for a while with a couple of friends. It's due to be part of Thomas Erl's SOA series later this year. While writing it Thomas asked us to produce some patterns for his book on SOA. Well the finished book, SOA Design Patterns, is now out and it's well worth a read. A number of people throughout the industry have helped to contribute some of the patterns within it so this is definitely a cross-industry collaborative effort. Thomas also wants it to be a live-work in as much as new patterns can be contributed by anyone. So take a look at the book and if you see something missing consider contributing it. Many of the patterns are influenced by our work with the JBoss SOA Platform.

SOA Platform 4.3 released

2008-10-31T01:16:00.000-07:00

We're pleased to announce that version 4.3 of our SOA Platform has just been released. We've made quite a few improvements since the first release, including closer integration with JON to provide runtime governance of services, more transport support, performance improvements etc. There's a white paper that goes into some detail on a few of the key improvements we've made, so check it out. Since the first release of the platform earlier this year, we've been working closely with customers and the community to ensure that this release is more than just a delta over the last. Of course we're not finished, but if the last year has been anything to go by this definitely going to be an adventure people will want to be involved with!

Red Hat and SOA Platform in the news.

2008-07-15T05:43:00.001-07:00

Only a week late, but worth a look.