The team responsible for the core JBI runtime in Project Open ESB recently embarked on a quest to purge all platform-specific dependencies from the runtime. Most of these dependencies had already been hidden behind an abstraction that could be ported across platforms, but dependencies can be sneaky and they have a habit of creeping in through unexpected channels. One of the most common scenarios involving platform-specific dependencies is when an application server or framework provides a set of libraries as part of its platform classloader. Application and container code can evolve to take advantage of features provided in these libraries that may not be portable to other platforms. This obviously creates trouble when you want to switch from one platform to another (e.g. switching application servers). Hoping to avoid this type of pitfall, our runtime team defined a set of platform-independent interfaces to represent our dependencies, and got back to a point where none of the core runtime code had a direct dependency on the underlying platform.
In order to test the implementation, we decided to provide an implementation of the platform interfaces for a Java SE environment. As we played around with Open ESB in this "stand-alone" mode, we began to realize that it was quite useful in a number of situations. The install footprint is small and the installation itself can be built up and torn down quite easily. You can perform a series of tests, delete the instance directory, and run again with a fresh JBI runtime. It's great for testing components, particularly if you want to determine if you have platform dependencies in your component implementation. ;-)
So we think it's cool and now we want to know if our user and developer communities think it's cool too. The current implementation of Open ESB for Java SE should be viewed as a proof of concept. The core runtime itself is still robust (it's the same JBI runtime that you get with Glassfish), but the platform wrapper implementation for Java SE is still a work in progress. The intent here is to bring this work out early to get feedback from users and solicit help from our developer community. We want to hear what you think: good, bad, or indifferent. So please give Open ESB for Java SE a try and help us make it better.
Now that we have all the background context out of the way, I'm going to walk you through the steps to run a stand-alone version of Open ESB using Java SE as the underlying platform.
This blog entry is pretty long, so here's a quick overview of the steps involved:
1) Download the Open ESB for Java SE distribution.
2) Install Open ESB for Java SE.
3) Start the JBI runtime.
4) Configure and test the Ant client interface.
5) Run a quick end-to-end test scenario.
NOTE: These instructions assume Unix-style path and environment conventions. If you are running in a different environment (DOS for example), be sure to use '\' instead of '/'. I provide specific instructions below for commands that have slightly different syntax between between Windows and Unix environments.
STEP 1: Download the Open ESB for Java SE distribution
Open ESB for Java SE is available for download as a single JAR file from the Project Open ESB site. Click on the link for jbi-javase.jar from the Nightly Builds section of the site.
STEP 2: Install Open ESB for Java SE
Installation is incredibly simple. All you have to do is copy the jar file into a directory of your choice and extract it.
$ cd /
$ jar -xvf jbi-javase.jar
created: jbise/
created: jbise/schemas/
inflated: jbise/schemas/service-assembly-info-list.xsd
inflated: jbise/schemas/managementMessage.xsd
inflated: jbise/schemas/component-info-list.rnc
inflated: jbise/schemas/jbi.rnc
inflated: jbise/schemas/service-assembly-info-list.rnc
inflated: jbise/schemas/managementMessage.rnc
inflated: jbise/schemas/jbi-registry.xsd
inflated: jbise/schemas/component-info-list.xsd
inflated: jbise/schemas/jbi.xsd
created: jbise/bin/
inflated: jbise/bin/jbi_admin.xml
created: jbise/lib/
inflated: jbise/lib/jbi-ant-tasks.jar
inflated: jbise/lib/jbi.jar
inflated: jbise/lib/jsr173_api.jar
inflated: jbise/lib/jta-1_1-classes.zip
inflated: jbise/lib/jaxb-impl.jar
inflated: jbise/lib/jbi-admin-common.jar
inflated: jbise/lib/jbi-ext.jar
inflated: jbise/lib/jbi_rt.jar
inflated: jbise/lib/xbean.jar
inflated: jbise/lib/activation.jar
inflated: jbise/lib/jaxb-api.jar
inflated: jbise/lib/jbise_framework.jar
inflated: jbise/checksum.log
Note that I have chosen to extract the JAR into my root directory. This means that my Open ESB install root is now /jbise. If you extract the JAR into a different directory, keep that in mind when performing the rest of the steps in this walkthrough. You will have to adjust the directory path used with certain commands accordingly.
STEP 3: Start the JBI runtime
Now comes the hard part - starting the runtime.
$ cd /jbise
$ java -jar lib/jbise_framework.jar start
May 4, 2007 8:30:49 AM com.sun.jbi.framework.jse.JSEJBIFramework createJMXConnectorServer
INFO: remote JMX connector available at service:jmx:rmi:///jndi/rmi://localhost:8699/jmxrmi
May 4, 2007 8:30:49 AM com.sun.jbi.framework.JBIFramework startup
INFO: JBIFW0010: JBI framework ready to accept requests.
May 4, 2007 8:30:50 AM com.sun.jbi.framework.JBIFramework ready
INFO: JBIFW0012: JBI framework startup complete.
Your Open ESB for Java SE installation is now up and running. Before we continue, this is probably the right place to discuss the shutdown procedure. At present, the java process created in this step will not return control back to the caller. This actually becomes our hook to shutdown JBI. When you are done having fun, just interrupt the process with ^C.
^C
Unloading JBI framework in response to VM termination.
JBI framework shutdown complete.
Not the prettiest solution, but it will do in a pinch. This is a proof of concept, after all.
STEP 4: Configure and test the Ant client interface
You're at step 4, so I'm guessing that you didn't get a heap of horrendous stack dumps in step 3. Woo-hoo! Time to build on your success and verify that your installation is fully operational. In addition to the core runtime, we also package an implementation of the JSR 208-defined Ant administration tasks in the Open ESB for Java SE distribution. You can find a friendly wrapper for these tasks in <install.root>/bin/jbi_admin.xml. You can call these targets directly from your own ant scripts or through the command-line. I will be using the command-line mode for steps 4 and 5. Before we get started, let's make sure your environment is ready to go.
Verify that your PATH and JAVA_HOME variables are setup correctly for Ant (use %JAVA_HOME% on Windows):
$ echo $JAVA_HOME
/jdk1.5.0_11
$ ant -version
Apache Ant version 1.7.0 compiled on December 13 2006
Make things easier on yourself. Set your CLASSPATH to include the required JBI client jars and hide some of the nasty Ant options behind an alias (or doskey if you are using DOS):
On Solaris:
$ export CLASSPATH="/jbise/lib/jbi-ant-tasks.jar:/jbise/lib/jbi-admin-common.jar"
$ alias jbiant="ant -q -f /jbise/bin/jbi_admin.xml -Djbi.port=8699"
On Windows:
C:\jbise> set CLASSPATH=\jbise\lib\jbi-ant-tasks.jar;\jbise\lib\jbi-admin-common.jar
C:\jbise> doskey jbiant=ant -q -f \jbise\bin\jbi_admin.xml -Djbi.port=8699 $*
Time to run a JBI administration command using Ant:
$ jbiant list-binding-components
[jbi-list-binding-components] ============================================================
[jbi-list-binding-components] List of Binding Components for Target "server"
[jbi-list-binding-components] ============================================================
[jbi-list-binding-components] Binding components were not found for the specified query.
[jbi-list-binding-components] ------------------------------------------------------------
BUILD SUCCESSFUL
Total time: 0 seconds
'Nuff said.
If you have your own JBI components and applications to play with, then go and install and deploy them. If you are new to JBI or want some more background on how to administer the JBI runtime using Ant, proceed to step 5.
STEP 5: Run a quick end-to-end test scenario
Things are going so well, we might as well push our luck and look for trouble. Let's try and run an end-to-end scenario with a couple of Open ESB components and a simple composite application. The Open ESB for Java SE distribution does not contain any components, shared libraries, or sample applications, so we are going to have to scavenge. The setup for this will be a bit painful because we don't have the ability to download individual component builds (yet). If you don't already have sun-file-binding and sun-bpel-engine components laying around in your environment, you can download jbi_components_installer.jar (which contains the two components we want and many more) from the Milestone Builds section on the Project Open site. Once you have the JAR, you need to run the following command to extract the component zip:
jar -xvf jbi_components_installer.jar JBI_COMPONENTS.zip
Use your favorite zip utility to extract the following JBI archives from this zip: encoderlib.jar, filebc.jar, bpelserviceengine.jar. You also need a composite app to drive the end-to-end scenario. You have jumped through enough hoops up to this point, so I have attached a sample app to my blog here. The rest of the commands in this section assume that the archives have been extracted to /tmp. Please adjust the path used in the commands if you use a different location.
Whew! We have everything we need now, so let's get down to business. Here is the command sequence (output omitted to save room):
$ jbiant -Djbi.install.file=/tmp/encoderlib.jar install-shared-library
$ jbiant -Djbi.install.file=/tmp/filebc.jar install-component
$ jbiant -Djbi.install.file=/tmp/bpelserviceengine.jar install-component
$ jbiant -Djbi.component.name=sun-bpel-engine start-component
$ jbiant -Djbi.component.name=sun-file-binding start-component
$ jbiant -Djbi.deploy.file=/tmp/CompositeApp1.zip deploy-service-assembly
$ jbiant -Djbi.service.assembly.name=CompositeApp1 start-service-assembly
If you made it through this sequence without any failures, you are now ready to make some magic happen. Prepare to witness the power of a fully armed and operational JBI runtime.
mkdir /temp
echo "Open ESB rules!" > /temp/input.txt
Wait a couple of seconds and check out the /temp directory. Voila! The file should have been renamed to input.txt_processed and there should be a new file called output.txt.
