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
Thursday, July 23, 2009
Sunday, July 19, 2009
SOA Platform Gateways and Notifiers
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:
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:
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.
Deploy the test to the server and run it with these simple commands:
The server log should look something like this:
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:
The lines that we're most interested in are:
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.
Let's look at this service description.
So, in summary, what happens when this quickstart is run?
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:
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:
Before we re-deploy and rerun the quickstart, we'll walk through these new statements:
At this point, redeploy the quickstart and execute "ant runtest" again.
The server log should look something like this:
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.
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.
Tuesday, July 14, 2009
DZone Reposts Content Based Routing Post
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!
It's a bit recursive - posting a post about a post - but it's good to see this subject in DZOne too!
Monday, July 6, 2009
When the Content Knows the Way - Content Based Routing in the SOA Platform
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:
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:
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:
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?
(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.
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.
Subscribe to:
Posts (Atom)