JBoss SOA Platform With JBoss Developer Studio Workshop
JBoss SOA Platform With JBoss Developer Studio Workshop
J Bo s s SOA Platform 4.3
with
JBoss Developer Studio 2.0
Workshop
1
JBoss SOA Platform with JBoss Developer Studio Workshop
Table of Contents
Introduction...................................................................................................................................................................................3
Lab #1: Install and Configure SOA Platform.............................................................................................................................4
Lab #2: SOA Platform Quickstarts..............................................................................................................................................5
Lab #3: Installation of JBDS.......................................................................................................................................................11
Lab #4: Configure SOAP in JBDS.............................................................................................................................................17
Lab #5: Creating First ESB Project............................................................................................................................................23
Lab #6: Adding a Custom ESB Action......................................................................................................................................30
Lab #7: Installing SoapUI For WS Testing................................................................................................................................35
Lab #8: Create a JSR 181 Web Service.......................................................................................................................................36
Lab #9: Proxy Web Service with ESB........................................................................................................................................43
Lab #10: Adding XSLT to WS Proxy on ESB............................................................................................................................53
Lab #11: Adding CBR to WS Proxy on ESB..............................................................................................................................58
Lab #12: Using jBPM..................................................................................................................................................................62
Conclusion...................................................................................................................................................................................77
2
JBoss SOA Platform with JBoss Developer Studio Workshop
Introduction
Overview
JBoss SOA Platform is a collection of technologies designed to meet an organization's SOA needs. SOAP includes an
ESB, BPM engine (jBPM), Rules engine (JBoss Rules), UDDI Registry (jUDDI), as well as a full JEE application server.
To cover each of these areas in depth is beyond the scope of this workshop. Instead, this workshop is designed to give
you an overview of the SOA Platform as well as some experience using JBoss Developer Studio to create and deploy
SOAP applications.
SOAP ESB Architecture
Understanding the SOAP ESB architecture is important to really understanding what is happening in the following
labs. Here is an architecture overview of the SOAP ESB that we will discuss.
The typical scenario for ESB messages is that a message comes in from the left through a “Gateway”. A Gateway can
be any of the protocols listed in the gateways box above or a custom gateway implementation. Any type of message
can come into a gateway: text, binary, image, XML, SOAP, etc. The gateway's job is to get the message, wrap it in a
JBoss ESB internal message structure and pass it to a “Listener”. The listeners in this context are expecting a JBoss
ESB Message structure. They will take the message they are given and hand it to a service. Depending on the ser
vice, this may include security authorization or schema validation. Assuming both of those are ok, the message will
travel to the action chain for the service. The action chain is simply a chain of Java actions that can perform pro
cessing on the message. The type of processing that can be done on the message is limited only by Java. Some Java
actions may do transformations, some may execute scripts, some may log, some may call out to external systems like
3
JBoss SOA Platform with JBoss Developer Studio Workshop
web services, etc. In the end, the last action in the chain is invoked. This is definitely an over simplification of the
process, but will hopefully give some context to the terminology that will be used throughout the workshop.
Included Files
Several files are included with this workshop. There is a copy of SOAP 4.3 CP02 (platform agnostic). There are cop
ies of JBoss Developer Studio for Windows, Mac, and Linux. There are also copies of SoapUI for Windows, Mac, and
Linux.
System Expectations
It is expected that you have a Windows, Linux, or Mac notebook and you are comfortable working and running Java
programs on it. It is expected you will have the environment PATH set to include a JDK 5.0 to use for these labs. It is
also a good idea to have JAVA_HOME set to your JDK that you plan on using. Please make sure you do this before
running any of the labs. You should be able to run “java version” from a command line and have it list the version of
Java that you have installed and configured. Ant is also required to complete lab #2, but the later labs do not need
Ant.
What is Expected of You
Please feel free to raise your hands with any questions that you have about the lab, why it is you are doing something,
or if something does not seem right. Please know that all care was made in creating this user guide, but all screen
shots and steps along the way might still be off by just a little so please be patient with any issues.
Lab #1: Install and Configure SOA Platform
Installing SOA-P is pretty straight forward. We just need to change directories into the directory we
want SOA-P installed, and unzip it
export LAB_DIR=/home/apestel/lab
cd $LAB_DIR
jar xvf soa4.3.0.GA.zip
4
JBoss SOA Platform with JBoss Developer Studio Workshop
By default, SOA-P is shipped without an administration user configured. We we want to enable that de-
fault user for this lab by editing $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/server/default/conf/props/soa-
users.properties and removing the “#” to uncomment the admin user.
NOTE: If using JDK 1.6: You must do one more thing. Copy the following files as shown below:
cp $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/client/jboss-jax* $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/lib/endorsed
cp $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/client/jboss-saaj.jar $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/lib/endorsed
cp $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/client/jaxb-api.jar $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/lib/endorsed
Lab #2: SOA Platform Quickstarts
Now you've got SOA-P installed, but where do you go from here? There are so many things people
want to do with a SOA Platform – mediation, web services, jms, transformations, orchestration, secur-
ity, routing, ftp, and a host of other things. Wouldn't it be nice if there were a single place that had a
working example of pretty much every piece of functionality that could be done? SOA-P has that in the
form of “quickstarts”. A quickstart is a complete working project (with complete source) that can be
build with a single ant task, deployed with a single ant task, and run with a single ant task. You can
5
JBoss SOA Platform with JBoss Developer Studio Workshop
run the examples to see them work and then look at the code (or even modify it) to see what is really
happening under the covers.
So, let's go look at the quickstarts with SOA-P. They are in $LAB_DIR/jboss-soa-p.4.3.0/jboss-
as/samples/quickstarts.
Before we run one of these quickstarts to see how they work, we need to start our SOA-P server. For
this lab, we're going to start it from the command line. Later on, we'll show starting it from JBDS.
cd $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/bin
chmod 777 run.sh
./run.sh -c default
The “-c default” tells the start script to run the “default” server configuration. There is also an “all”,
6
JBoss SOA Platform with JBoss Developer Studio Workshop
You'll know the server is up when you see the line that is highlighted below. Leave the server running.
Now that we have the server running, we can try running a quickstart. First, we need to setup the
quickstart configuration. So, you'll need to do this in a new console window:
cd $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/samples/quickstarts/conf
mv quickstarts.properties-example quickstarts.properties
Then, edit the new quickstarts.properities with your favorite file editor (VI, Emacs, Notepad, etc.).
As shown above, there are four things you need to change in this file:
7
JBoss SOA Platform with JBoss Developer Studio Workshop
Now that we've set the quickstart configurations, we can try running a quickstart. So, change director-
ies to $LAB_DIR/jboss-soa-p.4.3.0/jboss-as/samples/quickstarts/helloworld
Most all the quickstarts are setup similarly. All source code for the complete example is in this direct-
ory.
To build and deploy the example, we need to run “ant deploy” as shown below. If you don't have Ant
installed, you can skip to the end of this lab, but you'll probably want to try it later as these quickstarts
have a wealth of examples in them.
If you look in your server window, you should see the the example deployed:
This particular example creates a very simple ESB service that has a JMS gateway and sends a JMS
message with the text “Hello World”.
8
JBoss SOA Platform with JBoss Developer Studio Workshop
To run the client that publishes the message for the ESB to pick up, just run “ant runtest” from the
quickstart window. Resulting output is shown below:
If you again look at your server console window, you'll see that the ESB received the message and
printed out the contents (including the entire ESB message):
So, what was in that ESB deployment? There is not too much, actually. It's just a single “.esb” file that
was deployed to the server's deploy directory. We can see what's in that file by running “jar tvf
$LAB_DIR/jboss-soa-p.4.3.0/jboss-as/server/default/deploy/Quickstart_helloworld.esb” as shown below.
9
JBoss SOA Platform with JBoss Developer Studio Workshop
So there are three Java classes. The two in the test directory are actually only client classes used to
send the JMS message and not needed in the ESB deployment. The MyJMSListenerAction is a custom
action that prints out what we saw in the server console. The jbm-queue-service.xml file defines the
JMS queues that get deployed. deployment.xml declares that the ESB services depend on those
queues, and jboss-esb.xml defines the services. That's it! Please feel free to look over this example in
more detail. You can even change the source code in the quickstart directory and “ant deploy” will re-
compile and re-deploy.
To undeploy the example, just run “ant undeploy” from the quickstart directory as shown below:
Look at the server console window should show that the ESB deployment was undeployed:
10
JBoss SOA Platform with JBoss Developer Studio Workshop
Congratulations on deploying, running, and undeploying your first SOA-P quickstart and first SOA-P de-
ployment! You will likely find the other quickstarts to be a wealth of excellent examples as you start
creating more complex ESB services.
Lab #3: Installation of JBDS
JBDS is Eclipse based, so there is a different installer for different platforms. Please select the correct
installer for the platform you have:
11
JBoss SOA Platform with JBoss Developer Studio Workshop
This should open a GUI installer. We'll now walk through the steps of that installer.
Select the Next Button and this will get you to this screen:
12
JBoss SOA Platform with JBoss Developer Studio Workshop
Select the “I accept....” radio button and click the “Next” button.
Select the folder you want JBDS installed in and click “Next”
13
JBoss SOA Platform with JBoss Developer Studio Workshop
Select “Next”.
Click “Next” (EAP may be used for the Seam lab, so we'll include it in case you do that lab as well).
14
JBoss SOA Platform with JBoss Developer Studio Workshop
Click Next
Your screen will likely say 3/3 instead of 2/2 as in this older screenshot. Click “Next”.
15
JBoss SOA Platform with JBoss Developer Studio Workshop
Click “Next”.
16
JBoss SOA Platform with JBoss Developer Studio Workshop
Lab #4: Configure SOAP in JBDS
The SOA Platform can be configured as a “server” in Eclipse just like any other JEE server. In this way, we can deploy
JEE applications to the server and/or ESB applications to the server. To set this up, we first need to start JBDS.
This can be done via the shortcuts created during installation or via the command line. We'll show starting via com
mand line below:
We need to select a workspace where our projects will be stored. Select your desired workspace location and click
“OK”.
17
JBoss SOA Platform with JBoss Developer Studio Workshop
This is the default screen for a new workspace. In this lab, we want to go straight to the Workbench by clicking
“Workbench”.
This is an empty workspace. The first thing we want to do is change to the “JBoss AS”. To do this, select “Window |
Open Perspective | Other... | JBoss AS” and click “OK”. Now the JBDS window should look like this below:
18
JBoss SOA Platform with JBoss Developer Studio Workshop
We need to create a new server for SOA-P. The first thing we want to do is create a runtime for that
server. We could just right-click in the JBoss Server View and create a new server. However, the
screenshots for that will differ depending on if you already have an EAP server configured shown above
or if you do not. So, we're going to do it a different way – which will help you learn about server
runtimes anyhow. So, click “Window | Preferences” and select the “Server | Runtime Environments” as
shown below.
19
JBoss SOA Platform with JBoss Developer Studio Workshop
We need to add a runtime for our SOA-P server. So, click the “Add” button. Make sure to select the
“JBoss Enterprise Middleware | JBoss Enterprise Application Platform 4.3 Runtime” AND select the “Cre-
ate a new local server” checkbox as shown below.
Click “Next”. Now, give the local server we are creating for this runtime a name as shown below.
20
JBoss SOA Platform with JBoss Developer Studio Workshop
Click “Finish”.
Click “OK” to complete the creation of the SOA-P 4.3 runtime. Now, we should have the SOA-P 4.3
Server in the JBoss Server View as shown below.
21
JBoss SOA Platform with JBoss Developer Studio Workshop
Before starting this server, please make sure you have stopped the server that was started in Quick-
start lab #2. If we try to start it again while it is already running, we'll get port conflicts. You can kill
the other server by pressing CTRL-C in servers command window.
To start this server from JBDS, we need to right-click on it and choose “Start”. Sometimes the console
tab does not show the output of the server. If it does not, click on the “Console” tab, select the drop-
down icon in the top right corner of the console tab and choose “Java Stack Trace Console”. Then, you
should see more icons to the left of the dropdown you selected. Select the next dropdown to the left
and choose “SOA-P 4.3 Server”. We will want to be able to see the server output in the console as
shown below.
22
JBoss SOA Platform with JBoss Developer Studio Workshop
Please raise your hand if you do not see the console output. Congratulations, you have successfully
started the SOA-P server from JBDS. Now, we can create our first ESB project.
Lab #5: Creating First ESB Project
The first ESB project we are going to create is going to be a simple project with one ESB service. This ESB service will
poll a directory looking for a file with a given suffix. When a matching file is placed in the poll directory, it will read
the contents of the file and send them as a message on the ESB.
To create our ESB project, we need to select “File | New | Other”. This will give us the dialog below.
As shown above, navigate to the “ESB” folder and select “ESB Project”. Click “Next”.
23
JBoss SOA Platform with JBoss Developer Studio Workshop
There are three things we need to specify as shown above. 1.) Provide a name “FilePollerProject”. 2.) Select the Tar
get Runtime from the dropdown (“SOAP 4.3” that we created earlier), 3.) Choose the ESB version which is 4.4 for
this lab. After specifying these options, click “Finish”.
You should see that the project was created and the ESB configuration editor was automatically opened. This is actu
ally the editor for the jbossesb.xml file which you can find in the project by navigating to “esbcontent | METAINF |
jbossesb.xml” in the project explorer on the left of the JBDS window. It is highlighted in the screenshot above.
Now we need to create a gateway “provider”. This is how we get messages onto the ESB. There are providers for
HTTP, JMS, FTP, File, Email, JCA, Database, and a host of others – including the ability to create your own custom
provider. We are going to create a fsprovider (File System) gateway. So, rightclick on the “Providers” folder in the
JBoss ESB Editor and select “New | FS Provider...”. You should see a dialog like this.
24
JBoss SOA Platform with JBoss Developer Studio Workshop
Give the provider a name “File Provider Gateway” as shown above and select “Next”.
The Channel ID is the identifier that will be used later when a service declares that it wants to get messages from this
gateway. I named the Channel ID the same as the provider name “File Poller Gateway”. Click “Finish”.
Now the file gateway provider has been added to our ESB configuration. However, we need to specify a filter so that
the file gateway will know what files to look for. So, expand the File Poller Gateway tree as shown above and select
the “Filter” node. This will allow us to configure a host of options. In this case, we only want to specify the directory
25
JBoss SOA Platform with JBoss Developer Studio Workshop
to be polled and the suffix of the files we will be looking for. I am polling “/tmp” and looking for files that have an
“esbfile” suffix.
Now that we have a gateway provider, we need to create an ESB service to consume messages from our provider.
Rightclick on the “Services” folder of the ESB Editor and select “Add Service...”.
Enter the information as shown above and click “Finish”.
We should see the service selected as above. The only thing we need to do here is select “GLOBAL” for the InVM
scope (highlighed in the above screenshot). Basically, the InVM scope is an optimization that allows the gateway pro
vider we created to send messages directly to the service without have to go through an additional nongateway pro
vider.
26
JBoss SOA Platform with JBoss Developer Studio Workshop
We now have our provider setup and we have a service created. It's now time to tell our service that we want it to re
ceive any messages that come into the provider we created. This might initially seem an unnecessary step. But, not
all services have just one provider. For example, we might have a service that accepted a SOAP document from a file
system, FTP, JMS, and HTTP. In this case, we would still only have to create one service but could link it to four dif
ferent gateway providers.
To link this service to the gateway provider we created, rightclick on the “listeners” folder under the service we cre
ated and choose “New | FS Listener”.
We need to name the listener and select the “File Poller Gateway” that we previously created by choosing it from the
dropdown. Click “Finish”.
Now we have the service pointing to our gateway provider. Make sure that you set the “Is Gateway” to “true” as
27
JBoss SOA Platform with JBoss Developer Studio Workshop
highlighted above. This means that the listener is a “Gateway” and can therefore accept messages of any type (binary,
ASCII, XML, etc.). If we did not specify that this was a gateway, it could only accept JBoss ESB specific messages.
The ESB service is actually created now and would work. But, since we don't have any actions specified on the ser
vice, we wouldn't see much when the service was invoked. So, we're going to add a “Print Ln” action to our service
that will print the contents of whatever message we send to this service. To do this, rightclick on the “Actions” folder
under our service and select “New | System Println...”
We need to give the action a unique name and specify the label we will print in front of the actual message that is on
the ESB. Click “Finish”.
Now we are ready to deploy this ESB project to our server, just like we would any other JBDS (Eclipse) project. Let's
save the project first: “File | Save”.
28
JBoss SOA Platform with JBoss Developer Studio Workshop
Now, rightclick on our “SOAP 4.3 Server in the lower left JBoss Server View and select “Add and Remove Projects...”.
Click the “Add All >>” button to move the FilePollerProject to the list of configured projects. Click “Finish”.
You'll see in the console that when we added our project to the server, JBDS created a “.esb” archive (simliar to a .war
archive) and deployed it to our SOAP server. Now it's time to test it!
29
JBoss SOA Platform with JBoss Developer Studio Workshop
So, we need to create a file with the suffix we specified in the directory we specified. You can do this with any editor
like VI, Notepad, Emacs, etc. I'm going to just “echo” some text to a file below like this:
Now if we go back to JBDS and look in the console view, we should see that the ESB received our message.
Sure enough, there is our message with the label we specified in our System Println action!
If you do not see this message printed out in your console, please raise your hand.
30
JBoss SOA Platform with JBoss Developer Studio Workshop
Lab #6: Adding a Custom ESB Action
ESB services have listeners and actions. Thus far, we have created a service with a file poller listener and a single Sys
tem Println action. Now, we're going to add a custom Java action. An ESB action has full access to the ESB message.
It can read the message, modify the message, forward to other services, call out to external systems, anything that can
be done from a Java class.
To create a custom Java action, we first need to create the Java class. So, rightclick on the “src” folder under the File
PollerProject at the left of the JBDS window and select “New | Class”.
Here we've specified that the Package will be “com.jboss.lab”, the Classname will be MyEsbAction, and
most importantly, it will be a subclass of org.jboss.soa.esb.actions.AbstractActionLifecycle. Click “Fin-
ish”.
31
JBoss SOA Platform with JBoss Developer Studio Workshop
By default, the class is created with no methods. We want to add a constructor and a “process” meth-
od that will be invoked when the ESB service gets to this action. We could name the method some-
thing other than “process” and then specify the method name when we reference the action in the
ESB's configuration. But by default, the ESB will look for a “process” method that accepts a “Message”
parameter and returns a “Message” parameter.
---------------------------------------------------------------------------------------------
package com.jboss.lab;
import org.jboss.soa.esb.actions.AbstractActionLifecycle;
import org.jboss.soa.esb.helpers.ConfigTree;
import org.jboss.soa.esb.message.Message;
Note that this action is printing out the current contents of the message and then modifying
32
JBoss SOA Platform with JBoss Developer Studio Workshop
the message. We are casting the default message body to a byte[] and storing in a String so
that it will print correctly. Without that, it would just print the address of the byte array (de-
fault toString() implementation).
Now that we've created the custom action, we need to reference it from the ESB service con-
figuration. In JBDS, click back on the jboss-esb.xml editor. Right-click on the “Actions” folder
under our ESB service and select “New | Generic Action”.
The Process field is where we would specify a different method name if we used something other than
“process” in our Java class. Click “Finish”.
By default, our new action will be added below the Println Action. So, click on the new custom action
and drag it above the Println Action so that it will be executed before the Println Action. In this way, we
should be able to see if our custom action really modified the ESB message.
Now we just need to save the project “File | Save All” and redeploy. To redeploy, we need to expand
the “SOA-P 4.3 Server” in the JBoss Server View (lower left panel of JBDS). Inside there, we right-click
33
JBoss SOA Platform with JBoss Developer Studio Workshop
on FilePollerProject and select “Full Publish”. This will ensure that changes to Java source files get build
and re-deployed to the server.
The console should show that the FilePollerProject was redeployed, as shown above. Now we just need
to create another message (placing file in poller directory) to kick off the ESB service.
Now we need to take a look at the console panel in JBDS to see if the message made it through our two
actions in our ESB service.
34
JBoss SOA Platform with JBoss Developer Studio Workshop
Sure enough, we see the "Default message body is" message from our custom action. Then, we see that our second
action (System Println) printed out a message that is surrounded by "***" which was done by our custom action.
Congratulations, you've now created a custom action and added it to your ESB service! You could modify this action
to do anything that Java can do – which gives you a lot of flexibility.
Lab #7: Installing SoapUI For WS Testing
SoapUI is a wonderful tool for working with web services. In the simplest case, it provides a GUI to parse a WSDL,
generate an editable test client, and invoke the web service. In more complex cases, SoapUI can be used to create
elaborate and multthreaded load test scenarios. For this lab we will only be using it for the most simple case.
First, we need to install SoapUI. Please find the correct zip for your platform (Linux, Mac, or Windows) and extract it
as shown below.
35
JBoss SOA Platform with JBoss Developer Studio Workshop
We should be able to start SoapUI by running the start script as shown below. On non Windows plat-
forms, you made need to change the permissions on the start script so that it is executable.
Don't worry about the file not found error if you are not online. As long as SoapUI has started as
above, we're good to go. Please close the Starter Page panel though as other panels sometimes seem
to get hidden behind it.
Lab #8: Create a JSR 181 Web Service
One of the most common use cases for an ESB is to mediate web services. The client sends a request
to the ESB, the ESB may do specialized security, transformations, routing, or a host of other actions,
and then the ESB routes to a backend web service implementation.
In this lab, we will create a simple JSR 181 web service and show invoking it from SoapUI. In the next
lab, we'll proxy this web service with the ESB and show invoking the proxy via SoapUI.
Creating a JSR 181 web service is quite easy with JBDS. First, we'll create a new Dynamic Web Project
“File | New | Dynamic Web Project”.
36
JBoss SOA Platform with JBoss Developer Studio Workshop
You can switch to the Java EE perspective if desired, but I prefer to stay in the JBoss AS perspective.
So, click “No”.
37
JBoss SOA Platform with JBoss Developer Studio Workshop
Now we have our Web Service Project. But, we need to add our web service Java class. To do this,
right-click on the “src” folder in our MyWebServiceProject and choose “New | Class”.
We need to give this class a package “com.jboss.lab” and a name “MyWebService” as shown above,
then click “Finish”.
38
JBoss SOA Platform with JBoss Developer Studio Workshop
JSR 181 makes it pretty easy to create a web service – add a method with some annotations and you're
done! Here is the listing for the class that is shown above.
--------------------------------------------------------------------------------------
package com.jboss.lab;
import javax.jws.WebMethod;
import javax.jws.WebService;
@WebService()
public class MyWebService {
@WebMethod()
public String sayHello(String name) {
return "Hello " + name + "!";
}
}
--------------------------------------------------------------------------------------
That's all the Java we have to write to create the web service. Now, we just need to list this as a ser-
vlet in our web.xml. To do this, go the the project explorer on the left side of JBDS and open the “Web
Content / WEB-INF” folders and double click on web.xml.
39
JBoss SOA Platform with JBoss Developer Studio Workshop
We need to add a servlet, so click the “Servlets” folder in the Web XML Editor and add information for
our servlet as shown below. You'll have to click the “Add” button to add the servlet and “Add” button to
add the servlet mapping.
40
JBoss SOA Platform with JBoss Developer Studio Workshop
Now it is time to deploy this web service. So, save the project “File | Save All”. Then, right-click on the
“SOA-P 4.3 Server” in the JBoss Server View (lower left corner of JBDS) and select “Add and Remove
Projects...”.
As shown above, we'll want to add the MyWebServiceProject to our list of Configured projects. Click
“Finish”.
By looking in the JBDS console view, we should see that our web service was deployed and a WSDL
was created in the filesystem – highlighted below.
41
JBoss SOA Platform with JBoss Developer Studio Workshop
The last thing we need to do is test this web service by invoking it via SoapUI. So, start SoapUI if not
already started and choose “File | New soapUI project”.
As shown above, navigate to “Request 1” in the tree on the left and double click on “Request 1”. This
should open the Request 1 frame shown on the right. Enter your name instead of “?” for arg0 of the
request and click the green triangle button above the request. You should see the “Hello <name>!”
response in the panel on the right. Congratulations, you invoked a web service from SoapUI! Now, we
need to proxy this service with the ESB.
42
JBoss SOA Platform with JBoss Developer Studio Workshop
Lab #9: Proxy Web Service with ESB
Now that we have our web service working, we want to create an ESB service that proxies this web
service. In this way we can provide different security, versioning, transformation, routing, etc. for ex-
ternal clients coming in through the ESB than we do for internal clients accessing the web service dir-
ectly.
At a high level, all we need to do here is create an HTTP gateway provider, create a service to use that
provider, and add an HttpRouter action to that service to forward the web service request on to our JSR
181 web service implementation. In our case, we will also add a System Println action to our sevice
just to see that the web service is passing through the ESB.
First, we are going to create a new ESB project. We could use the existing ESB project and just add an
additional service to it, but I'd like to keep these labs as independent as possible. So in JBDS, select
“File | New | Other...”.
Make sure to give the project a name, select the SOA-P 4.3 runtime, and select ESB version 4.4 as
shown above. Click “Finish”.
43
JBoss SOA Platform with JBoss Developer Studio Workshop
This should look familiar. We have our EsbWebServiceProxy in the explorer on the left and have our
jboss-esb.xml file opened on the right with our JBoss ESB Editor.
The first thing we need to do is create an HTTP provider gateway that the client will send web service
requests to. Right-click on “Providers” in the JBoss ESB Editor and select “New | JBR Provider...”. JBR
stands for JBoss Remoting and is one of two ways to create an HTTP gateway. EBWS (ESB Based Web
Service) is the other way and will not be shown in this lab.
44
JBoss SOA Platform with JBoss Developer Studio Workshop
Provide the Channel ID (I use provider name again) and a port that this HTTP gateway will listen on.
Click “Finish”.
Now we have our provider and need to create a service to use it. So, right-click on “Services” and se-
lect “Add Service...”.
45
JBoss SOA Platform with JBoss Developer Studio Workshop
Now we have our service shown above. Make sure to set InVM Scope to “GLOBAL” as shown above or
we would need to create another non-gateway provider in order to use this service.
We now need to add our HTTP Gateway Provider as a listener for this service. So, right-click on “Listen-
ers” under our service and select “New | JBR Listener...”.
Name the listener and select our provider from the drop drown box as shown above and click “Finish”.
46
JBoss SOA Platform with JBoss Developer Studio Workshop
Now we have our listener setup, but make sure to set Is Gateway to “true” as shown above.
Next, we need to add some actions to print out the message (proving we're in the ESB) and to route to
the JSR 181 web service we created earlier.
Name the action and specify the label that will be printed prior to the message contents. Click
“Finish”.
47
JBoss SOA Platform with JBoss Developer Studio Workshop
Lastly, we need to add an action that will route the ESB message to our actual web service implement-
ation. Right-click on Actions and choose “New | Generic Action...”.
You can type the class name in by hand or click “Browse” and start typing “HttpRouter”. It will show
you the full class name that you can select. Once the dialog box is filled in as above, click “Finish”.
48
JBoss SOA Platform with JBoss Developer Studio Workshop
This action we just created needs some configuration by specifying properties. Other actions (includ-
ing custom actions) can take advantage of having properties passed in as well. For the HttpRouter ac-
tion, we need to specify the following properties:
endpointUrl=http://localhost:8080/MyWebServiceProject/MyWebService
method=POST
To do this, click the “Add” button in the properties section of the Http Router Action. When done, the
action configuration should look like this:
49
JBoss SOA Platform with JBoss Developer Studio Workshop
If you have any problems adding these properties, please raise your hand.
That's all we have to do in order to create the proxy in the ESB configuration. Now, we need to save
(File | Save All) and publish this ESB project to our server. In the JBoss Server View (lower left portion
of JBDS), right click on “SOA-P 4.3 Server” and choose “Add and Remove Projects...”.
Make sure the “EsbWebServiceProxy” project is in the Configured projects list and click “Finish”.
50
JBoss SOA Platform with JBoss Developer Studio Workshop
As highlighted in the console above, you should see that the HTTP gateway was started listening on
port 9999.
Now, we need to see if we can go back to SoapUI and pass the same request to the ESB that we had
been passing to our JSR 181 web service.
Notice that the web service URL here is pointing to “localhost:8080”. Select that URL drop list and
choose “Add new endpoint”. Change the port to 9999 as shown below.
51
JBoss SOA Platform with JBoss Developer Studio Workshop
Click “OK” and notice that the endpoint in our SoapUI window is now pointing at localhost:9999 and we
haven't changed anything else about the webservice.
Now click the green arrow button to run the web service. It should give us the same response, but
have been passed through the ESB instead of directly invoking the JSR 181 web service. How can we
know it went through the ESB? Let's look at our server console again in JBDS.
52
JBoss SOA Platform with JBoss Developer Studio Workshop
Next, we will add a transformation to show how the ESB can modify the message on the bus before or
after invoking the back end web service.
Lab #10: Adding XSLT to WS Proxy on ESB
JBoss SOA-P currently uses Smooks for transformations. Smooks can support many types of transform-
ations (XML to XML, Java to XML, XML to Java, Java to Java, etc.). For this lab, we are going to show us-
ing Smooks to apply a simple XSLT transformation to the response coming back to the SoapUI client
after the ESB receives the response from the back end web service.
First thing we need to do is add a new Smooks action to our action chain for our HTTP Proxy service.
So, right-click on “Actions” under the HTTP Proxy Service and select “New | Generic Action...”.
Add a name and the SmooksAction class as shown above and click “Finish”.
53
JBoss SOA Platform with JBoss Developer Studio Workshop
Now we have our Smooks action, but need to add a property to it telling it where the Smooks configur-
ation file is. So, click the “Add...” button in the properties section of this action and add this property:
smooksConfig=/smooks.xml
Now, we need to create the smooks.xml file that we just referenced. If you just saved the project and
got an error because the file wasn't there, don't worry, we'll fix that now. So, on the left side of JBDS in
the project explorer, right-click on “esbcontent” and choose “New | Other...”.
54
JBoss SOA Platform with JBoss Developer Studio Workshop
Name the file “smooks.xml” as shown above and click “Finish”. This will open an empty XML file editor
like shown below.
Make sure to select the “Source” tab of this editor. Now, past the following XML into that source tab.
55
JBoss SOA Platform with JBoss Developer Studio Workshop
--------------------------------------------------------------------------------------
<?xml version='1.0' encoding='UTF-8'?>
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.0.xsd">
<resource-config selector="$document">
<resource type="xsl">
<![CDATA[
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<ns2:sayHelloResponse xmlns:ns2="http://lab.jboss.com/">
<return>MODIFIED</return>
</ns2:sayHelloResponse>
</env:Body>
</env:Envelope>
</xsl:template>
</xsl:stylesheet>
]]>
</resource>
</resource-config>
</smooks-resource-list>
--------------------------------------------------------------------------------------
This is not a terribly interesting XSLT, it's basically changing all the XML. But folks that are good with
XSLT can obviously do more more interesting and useful things in their XSLT.
56
JBoss SOA Platform with JBoss Developer Studio Workshop
Now, we need to save the project via “File | Save All” and republish. To republish, go to the lower left
of JBDS in the JBoss Server View and right-click on EsbWebServiceProxy and choose “Full Publish”. The
console should show that the ESB service was redeployed as highlighted below.
Now, we just need to go back to SoapUI and hit this web service on the ESB once more and we'll see
that the ESB transforms the result to be “MODIFIED” regardless of what name we send as a parameter
as shown below.
57
JBoss SOA Platform with JBoss Developer Studio Workshop
Lab #11: Adding CBR to WS Proxy on ESB
For this lab, we are going to add two simple print line services to our EsbWebServiceProxyProject. In
addition we will add a very simple XPath content based router action to our existing ESB service that
will route to one of the two new services depending on the SOAP message passed in.
We could go through and add the services as we have done in the past, but for this lab, we're just go-
ing to add the services by editing the jboss-esb.xml file manually. In some cases, copy/paste in the
source view of jboss-esb.xml can be more convenient than using the graphical ESB editor.
Below is the new jboss-esb.xml file (you can copy/paste the entire file - changes are two new services
and new content based router action) into the “Source” tab of the jboss-esb.xml file:
58
JBoss SOA Platform with JBoss Developer Studio Workshop
<?xml version="1.0"?>
<jbossesb parameterReloadSecs="5"
xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd">
<providers>
<jbr-provider name="HTTP Gateway Provider" protocol="http">
<jbr-bus busid="HTTP Gateway Provider" port="9999"/>
</jbr-provider>
</providers>
<services>
<service category="lab services"
description="Service to proxy web services" invmScope="GLOBAL" name="HTTP Proxy Service">
<listeners>
<jbr-listener busidref="HTTP Gateway Provider" is-gateway="true" name="HTTP Listener"/>
</listeners>
<actions>
<action class="org.jboss.soa.esb.actions.SystemPrintln" name="Println Action">
<property name="message" value="Message in ESB ->"/>
</action>
<action class="org.jboss.soa.esb.actions.ContentBasedRouter" name="ContentBasedRouter">
<property name="ruleSet" value="cbr.drl"/>
<property name="ruleLanguage" value="XPathLanguage.dsl"/>
<property name="ruleReload" value="true"/>
<property name="destinations">
<route-to destination-name="ServiceA" service-category="category" service-name="ServiceA"/>
<route-to destination-name="ServiceB" service-category="category" service-name="ServiceB"/>
</property>
</action>
<action class="org.jboss.soa.esb.actions.SystemPrintln" name="after cbr">
<property name="message" value="after cbr"/>
</action>
<action class="org.jboss.soa.esb.actions.routing.http.HttpRouter" name="Http Router Action">
<property name="endpointUrl" value="http://localhost:8080/MyWebServiceProject/MyWebService"/>
<property name="method" value="POST"/>
</action>
<action class="org.jboss.soa.esb.smooks.SmooksAction" name="Smooks XSLT Action">
<property name="smooksConfig" value="/smooks.xml"/>
</action>
</actions>
</service>
<service category="category" description="asdf" invmScope="GLOBAL" name="ServiceA">
<actions>
<action class="org.jboss.soa.esb.actions.SystemPrintln" name="ServiceA">
<property name="message" value="ServiceA"/>
</action>
</actions>
</service>
<service category="category" description="asdf" invmScope="GLOBAL" name="ServiceB">
<actions>
<action class="org.jboss.soa.esb.actions.SystemPrintln" name="ServiceB">
<property name="message" value="ServiceB"/>
</action>
</actions>
</service>
</services>
</jbossesb>
Please note that the only thing ServiceA and ServiceB do is print out the service name and the body of
the ESB message. Also, please note that this content based router is placed before the http router.
59
JBoss SOA Platform with JBoss Developer Studio Workshop
This means that the http router will never get invoked, so when we invoke this service, we won't get
the response from the actual web service. In a real world situation, a CBR would probably be the last
action in the action chain.
You should also notice that the CBR action is referring to a cbr.drl file. This is the file that will actually
contain the routing rules that are based on JBoss Rules. You'll need to add this file by right-clicking on
“esbcontent” in the explorer tab of the ESB project and selecting “New | Other...”.
60
JBoss SOA Platform with JBoss Developer Studio Workshop
That should open the new empty file in a text editor and you can copy/paste the following text in the
editor:
------------------------------------------------------------------------------------------------------------------
package com.jboss.soa.esb.routing.cbr
expander XpathLanguage.dsl
This is what the XPath routing rules look like. You'll see there are two routing rules. The first sets the
routing destination to ServiceA if we say hello to “Aaron” in the SOAP message. Else, it routes to Ser-
viceB. You can also do CBR without XPath if the payload of the ESB message were not XML.
Next we, need to redeploy. So select “File | Save All” and then right-click on the
“ESBWebServiceProxy” deployment under the SOA-P 4.3 Service in the JBoss AS view on the lower left
of the JBDS window and select “Full Publish”.
Now, we can invoke this service again from SoapUI as shown below.
61
JBoss SOA Platform with JBoss Developer Studio Workshop
But, we can look at the server console log to see what ESB service got routed to.
As shown above, you'll notice that ServiceA was invoked. Now, go back to SoapUI and change the
parameter to something other than “Aaron” and you should see in the server log that ServiceB was in-
voked instead of ServiceA.
Lab #12: Using jBPM
For our last lab, we're going to create a simple jBPM project. We could do a whole workshop on jBPM,
so we're clearly not going to cover all the features in this single lab. However, the goal of this lab is
help you gain the fundamental skills necessary to create a basic jBPM project, deploy the project to the
server, and test the service in the jBPM administration console.
The first thing we need to do is create a new jBPM project. So, select “File | New | Other...”.
62
JBoss SOA Platform with JBoss Developer Studio Workshop
Select a JBoss jBPM Process Project as shown above and click “Next”.
63
JBoss SOA Platform with JBoss Developer Studio Workshop
Fill out the runtime information as shown above (the version should be filled in automatically after spe-
cifying the location), and click “Finish”.
This will create a new jBPM Project and you can view the main jBPM process diagram by double clicking
the process definition file from the project explorer as shown below. You may see a warning when
opening the process. If so, just select “Convert and Open”.
64
JBoss SOA Platform with JBoss Developer Studio Workshop
So, we now have a process! It's not terribly interesting, but we can deploy it as is to test the deploy-
ment mechanism. So, click the “Deployment” tab at the bottom of the jBPM process diagram editor.
You will see something like shown below.
All the defaults should be correct, so we can just click the “Deploy Process Archive...” button.
So, where did this process get deployed? Well, it actually invoked the jBPM application on the applica-
tion server, passed in the process we defined, and stored it in the database configured under jBPM.
There are four ways to deploy jBPM processes: 1.) From JBDS, as we just did, 2.) From the jBPM ad-
ministration console, which we'll be looking at next, 3.) From an Ant task, and 4.) From Java code.
Now, we can open a browser window and go see this jBPM process that we deployed by going to this
URL and logging in as admin/admin: http://localhost:8080/jbpm-console
65
JBoss SOA Platform with JBoss Developer Studio Workshop
There is the jBPM process “definition” we created – version #1. The default process name is “simple”.
We can click the “Examine” link to see more information about this process.
There are no process “instances” for this process “definition”. If there were, we'd see them in the Pro-
cess Instances table. So, let's create an instance of this process by selecting the “Start a new instance
of this process” on the left.
66
JBoss SOA Platform with JBoss Developer Studio Workshop
This created a new instance called “ID 1” that you can see next to “Instance Link” on the left under
Process Instance Summary”. In a real scenario, this process would likely have been created by an ESB
service or via the jBPM Java API. We can now click the “Process Image” link to see the what state this
process is currently in.
You'll notice that we are still in the first node, since it is highlighted blue. You can also see the vari-
ables associated with a process instance by clicking on the “Process Variables” link.
67
JBoss SOA Platform with JBoss Developer Studio Workshop
This simple process does not have any variables, but if it did, you would see them here – as we'll see
shortly.
Ok, now that we've got some of the fundamentals down, let's go back to JBDS and add a simple user
task to our jBPM process.
First, click back on the “Diagram” tab of the process editor as shown below.
Now you'll get to use your drag and drop skills because we want want to add a “Task Node” with trans-
itions between the “start” and “first” nodes. Click “Task Node” and then click on the palate where you
want it. Select the “to_state” transition and move it to the new task-node1. Then, click “Transition”
68
JBoss SOA Platform with JBoss Developer Studio Workshop
and click the task-node1 node and drag to the State node titled “first”. It should look like below when
done.
To edit the properties of the task node, we need to select the “Properties” tab at the bottom of the
screen and then select the “task-node1” node. You should see this below.
In the Properties tab, we want to select the “Tasks” sub-tab. As shown below.
69
JBoss SOA Platform with JBoss Developer Studio Workshop
Now, right-click in the little window to the right of “Tasks” and select “New Task”.
70
JBoss SOA Platform with JBoss Developer Studio Workshop
Here, we want to click “Generate Form...” to create a simple form for this task.
71
JBoss SOA Platform with JBoss Developer Studio Workshop
Fill out the form as shown below and be sure to press “Enter” after typing the variable name and label
– otherwise, it won't accept the text you typed.
We could create transition buttons as well, but we're trying to keep this lab as simple as possible.
Press “OK”.
That's all we have to do! Now make sure to do “File | Save All”. Then click the “Deployment” tab of
the main process editor to see the view shown below.
Now, click the “Deploy Process Archive” button and OK on the confirmation dialog.
72
JBoss SOA Platform with JBoss Developer Studio Workshop
Now our process is deployed and we can see the new version by going to a http://localhost:8080/jbpm-
console in a browser as shown below.
Let's click “Examine” on our version #2 of the “simple” process definition. You'll see that there are no
processes, because we haven't created any process instances for this version of the process definition.
So, click the “Start a new instance of this process” link.
As shown above, there are no tasks for this new process instance. Why not? It's because the process
is still in the “start” state and not in our task state yet. So, click on the “Tokens” link on the left which
will show our Tokens (logical threads) for this process.
73
JBoss SOA Platform with JBoss Developer Studio Workshop
This token is in the “start” node. We can signal it to move to the next node by clicking “Signal
to_state” link on the right.
Now if we click on the “Process Image” link on the left, we'll see that we are in the task node as shown
below.
We can also click the “Tasks” link on the left and we'll see that we have a task as shown below.
74
JBoss SOA Platform with JBoss Developer Studio Workshop
Fill in you name as shown above and click the “Save” button.
Now, click the “Variables” link on the left and you'll see two variables as shown below.
75
JBoss SOA Platform with JBoss Developer Studio Workshop
The “Name” variable came from our form. Where did the “message” variable come from? That will be
left as an exercise for the reader. But for a hint, go back to JBDS and look at the source tab of the jBPM
editor as shown below.
Congratulations, you've now created your first jBPM project with a user task! There is so much more
that can be done with jBPM - invoking ESB services, getting invoked by ESB services, sending emails,
creating custom actions, forks, joins, conditions, timers, and much, much more. Hopefully this lab has
given you enough background that you will have a head start looking into these other capabilities.
76
JBoss SOA Platform with JBoss Developer Studio Workshop
Conclusion
We hope that this lab has been useful for you and increased your interest in JBoss SOA Platform. There is much func
tionality that we were not able to cover in this short workshop. Here are some areas for recommended reading:
http://www.redhat.com/docs/soaplatform
http://www.jboss.com/soaplatform
http://www.jboss.org/soapwiki
Also, if you are interested in how JBoss is going to support BPEL in the future, you are encouraged to look at our
jboss.org Riftsaw project that will be the basis for our BPEL platform to be released in early 2010.
http://www.jboss.org/riftsaw
Thank you for taking the time to work through this lab. Please support open source!
77