As we stated in the Preface, JBoss ESB is JBoss' open source Enterprise Service Bus. JBoss ESB enables you to quickly integrate new and legacy systems, exposing their combined functionality through services "plugged" into the service bus. JBoss ESB takes care of routing and processing service requests while you concentrate on your system's design and development.
In this chapter we will:
Discuss the choices that you have for which distribution of JBoss ESB to run
Show where you can find the distributions, and how to install them
We'll also introduce you to the ESB's Administrative Console
Walk you through how to locate services in the console
Show you how to debug server errors
In short, you'll learn how to get JBoss ESB up and running. Okay, it's time to get hands-on with JBoss ESB!
One of the ways in which JBoss projects make it easy to get started is that they are easy to install and get running. In most cases, you simply download a ZIP file, and remember, since these are Java projects, you can use the same ZIP project file on any supported operating system and with any supported JVM. Unzip the file to a directory, and run a shell script or .bat file coincidentally named run, and you're off and, well, running. You can install JBoss ESB into any directory that you choose. You can even have multiple installations on the same system.
Note
Please note that in the examples and illustrations in this book, we will download to, and install software into the /opt directory, which is a standard Unix directory for optional software packages. All references to download and installation directories will be relative to /opt. Please note that you may install the JBoss Application Server and JBoss ESB into any directory you want.
Let's begin by looking at how you can download the bits for JBoss ESB.
At the time of this writing, the download page for JBoss ESB was aptly named http://www.jboss.org/jbossesb/downloads. The webpage is as follows:
If you explore around this page, you'll find several older releases of JBoss ESB. The newest releases are always displayed at the top of the page. This is the release (4.10) that we'll install and use throughout the remainder of the book. We'll use the 4.10 release as, at the time of this writing, it was the most up-to-date release, and it includes many features and bug fixes that were not present in earlier releases.
Before we go any further with JBoss ESB, we have to download the application server on which JBoss ESB will run. It's really something of a misnomer to say that you run a JBoss ESB server. What you really do is deploy JBoss ESB to an application server and then deploy your services to JBoss ESB.
So, let's get ourselves an application server.
Application servers provide many functions, such as clustering, supporting resource pooling and sharing (for example database connections), caching, transaction support, and persistence. We'll use JBoss Application Server (JBoss AS) as the application server onto which we'll deploy JBoss ESB.
The version of JBoss AS that we will use in this book is version 5.1.0.GA. We'll use this version of JBoss AS as it has been widely used and tested with JBoss ESB 4.10.
Follow these steps to download and install JBoss AS release 5.1.0.GA:
Go to the following page: http://www.jboss.org/jbossas/downloads. Go to Projects | Servers | Application Server. Click on Download, and you should reach the following page:
When the download is finished, move the
jboss-5.1.0.GA.zipfile to the directory where you want to install and run the server. For the remainder of the book, we'll use the/optdirectory.Unzip the
jboss-5.1.0.GA-jdk6.zipfile. Unzipping the file will create a directory namedjboss-5.1.0.GA-jdk6. Under this directory, you'll see the following directories:conf: Configuration files are stored here.data*: Information used by the server, such as references to deployed service endpoints are stored here.deploy: We've already seen this directory, this is where deployed archives are kept.deployers: These are the deployer binaries that initialize the deployed archives and services.deploy-hasingleton: You're probably already noticing files with a prefix of "ha". In this context, "ha" indicates "high availability". In other words, something to do with running your server and applications in a cluster. A clustered singleton service is deployed to servers in a cluster, but is only available on one of those servers. These "ha-singleton" services are deployed in this directory.farm: The clustered services that are available on multiple servers in a cluster are deployed in this directory.lib: The server's.jarfiles are kept here.log*: The logs are kept here.tmp*andwork*: Temporary files used by the server are kept in these directories.
In a terminal/shell window, go to that directory, and then the
binsub-directory, and executerun.sh.(Note that on Windows, you would execute a file namedrun.batin the same directory.) The server will start up and write logging information to the screen. When you see a message that looks like this, then the server is up and running:19:52:22,708 INFO [ServerImpl] JBoss (Microcontainer) [5.1.0.GA (build: SVNTag=JBoss_5_1_0_GA date=200905221634)] Started in 44s:251msYou can check that the server has started successfully by going to
http://localhost:8080/. Here you'll see the top-level JBoss AS server page:
Note
A complete description of JBoss AS and all its capabilities is beyond the scope of this book. Our primary interest in the server is as a platform where we can deploy JBoss ESB. For additional information on JBoss AS see http://www.jboss.org/jbossas/
As we discussed earlier in this chapter, you don't really "run" a JBoss ESB server. You deploy it to an application server. Therefore, before we could do anything with JBoss ESB, we needed an application server. Based on its wide adoption and its integration with JBoss ESB, we choose JBoss AS as our application server. Now, it's time for us to select a JBoss ESB distribution, download, and install it.
There are a number of different choices for the distribution you may use for JBoss ESB. We'll discuss those now to give you a better idea what you may want to start with.
jbossesb-server-4.10.zip: Thejbossesb-serverbinary distribution is a pre-configured JBoss AS server distribution. The ESB Server comes pre-installed with JBoss Messaging, JBoss Webservices, all of the base ESB capabilities and is the best choice for those who want to get started quickly.Note that the ESB server is configured with version 4.2.3 of JBoss AS. While this distribution makes it easy to get started, we won't spend much time with it as this configuration is based on an older version of JBoss AS. What's not in this distribution? Well, this is not a full-blown Java EE server. As such, this distribution does not include support for clustered configurations, hibernate, or transactions and is probably not suited to being run in a large production environment.
jbossesb-4.10-src.zip: This is the next distribution you might want to consider and it is the source code distribution for JBoss ESB. You can use this distribution to build your own copy ofjbossesb-server-4.10.zip. Because JBoss ESB, like all the other JBoss projects, is open source, you can examine all the source code, learn from it, modify it, and even make contributions to it.As you've probably already guessed, we're following the Goldilocks principle here. The first one was the simplest to get started with, but was limited. The second one didn't have those limitations, but is more complicated to get started with.
jbossesb-4.10.zip: (This is referred to on the download page as the "binary" distribution), it is a standalone distribution of JBoss ESB. The binary distribution comes with installation scripts allowing it to be installed into a full JEE application server. We'll install this distribution into our JBoss AS 5.1.0.GA server and use it for the bulk of work in this book.
Okay. Enough with the preliminaries. It's time for the main event. Let's look at the jbossesb binary distribution. This is the distribution that we'll use for the remainder of the book.
As was the case with our installation of JBoss AS, to install JBoss ESB 4.10, simply select the file for download, save the file, and then unzip it.
Unzipping the jbossesb-4.10.zip file creates a directory named jbossesb-4.10 under our current directory. (Remember that we are using the /opt directory for our work with JBoss ESB.)
When you unzip the jbossesb-4.10.zip file, you'll see the following directory tree under the jbossesb-4.10 directory:
Contributors.txt: These are the names of the people who have contributed to JBoss ESB.install: This is the directory from which you'll install JBoss ESB into the JBoss AS server. We'll get back to this directory in a minute.javadocs: The code is open source, so here are the javadocs so that you can easily view the classes and methods.JBossEULA.txt: What's an EULA? The acronym stands for "End User License Agreement". These are the rules that govern how you can use or repackage JBoss ESB, and its supporting software, for commercial use.lib: This directory contains all the Java.jarfiles needed by JBoss ESB.README_FIRST.txt: The title says it all. This file includes a brief introduction to JBoss ESB, and a pointer to the community user forum.samples: These are the "quickstart" example programs. We'll describe the quickstarts in detail, and walk through how to run them, later in the book.xml: This directory deserves a closer look. If you look in this directory, you'll see a number of XSD (XML Schema Definition) files. These files define the elements used to construct JBoss ESB services.
The files named jbossesb-<version number>.xsd are especially interesting as these define the full set of JBoss ESB service configuration attributes. We'll explore these attributes, such as service providers, gateways, IDs for services, and so on in the next chapter when we take a close look at a JBoss ESB service. We'll also revisit these files when we start to use the ESB editor in JBoss Developer Studio (JBDS).
Okay, now it's time to install JBoss ESB into the JBoss AS server we installed previously. But, wait. Before we do that, let's examine just what it means to "deploy" JBoss ESB to an application server. "Deploying" something to the application server means putting it in a location where the application server can recognize it, control it, and start the application's lifecycle. Follow these steps to deploy JBoss ESB:
The first step is to set our current directory to the
installdirectory under thejbossesb-4.10directory:cd installBefore we deploy JBoss ESB, we need to tell it where it will be deployed. You'll find a file named
deployment.properties-examplein the install directory. Copy this file to a file nameddeployment.properties:cp deployment.properties-example deployment.propertiesNext, we have to define the location of the JBoss AS server directory in the
deployment.propertiesfile. Open up your favorite text editor and define these properties in that file:org.jboss.esb.server.home=/opt/jboss-5.1.0.GA-jdk6 org.jboss.esb.server.config=all
Note
You probably noticed that we just referenced a property named
org.jboss.esb.server.config. What's a server config?Each JBoss server profile consists of a set of server configurations (to control the level of logging detail, server start up memory requirements, and so on) and the set of services to install. JBoss AS 5.1.0.GA is shipped with these profiles:
all: starts all available servicesdefault: a base Java EE serverminimal: a bare, slimmed down configuration, the minimum for starting the application serverproduction: a profile designed for use in production environmentsstandard: a Java EE certified configuration of servicesweb: a small set of services designed to mimic a web profile
We'll use either the
defaultorallprofile for most of our work in this book.Before we actually deploy JBoss ESB to our JBoss AS server, it's a good idea to save a copy of the server, in the event that we ever want to reset the server to its original configuration. There's another useful aspect of the server profiles that's important to keep in mind; they are very easy to copy. To save a copy of the original
allconfiguration, just copy its directory tree:cp -pR all all.originalApache Ant is used for many JBoss AS and JBoss ESB deployment tasks. This book assumes you use Apache Ant version 1.8.1 with JBoss ESB 4.10. The
antcommand to deploy JBoss ESB to JBoss AS is very simple:ant deploy
We accomplished two tasks in this section, namely:
We protected ourselves from any problems that we might inadvertently introduce in modifying a JBoss AS server's configuration profile by making and saving a copy of that profile. This is an easy thing to do as it only requires a copy command. You might never need to use the copy, but as a backup system for your PC, it's a nice (and easy) insurance policy.
We deployed JBoss ESB to our JBoss AS server, and in the process, made our first use of Apache Ant to administer JBoss ESB. We'll make a lot more use of
antlater in the book, when we work with the JBoss ESB quickstarts and other example code.
But, what exactly does this invocation of ant deploy actually do? In the context of this installation, just what JBoss ESB bits are installed? The installed JBoss ESB bits are:
server/default/deployers/esb.deployer: The name is a dead giveaway here. This component enables the server to deploy.esbarchives.server/default/deploy/jbossesb-registry.sar: This service archive contains ESB's integration to its service registry. A registry is used to look up service endpoints at runtime; a repository is used to store and manage the life cycle of services. We'll describe the registry, how it works, and how you use it in a subsequent chapter.server/default/deploy/jbossesb.esb: This ESB archive contains internal support for messages and message redelivery.server/default/deploy/jbpm.esb: This ESB archive contains the JBoss ESB integration to the jBPM Business Process Management system.server/default/deploy/jbrules.esb: This ESB archive contains the JBoss ESB integration to JBoss Rules for building rules-based services.server/default/deploy/smooks.esb: This ESB archive contains the JBoss ESB integration to the Smooks message transformation and routing engine.server/default/deploy/soap.esb: This ESB archive contains the JBoss ESB support for hosting Web Services.server/default/deploy/spring.esb: This ESB archive contains the JBoss ESB support for applications built with the Spring framework.
You may want to experiment with a "slimmed" configuration where you can reduce the server's memory use by removing services. The ability to modify the configuration of a JBoss server is actually one of its most important features. You can remove features that you don't use to save memory, or CPU resources, or to enhance the security of your installation by reducing complexity and the number of features. But, before you start modifying a profile, you should make a copy of it, so, in the event you make some mistakes in your modifications, you can easily restore the original profile.
For example, to modify the default profile, just make a copy of it first:
cp -pR server/default server/default_original
Then hack away at the default profile, secure in the knowledge that you can easily restore it.
What types of artifacts are deployable to application servers?
There are several, namely:
.jar: This is a Java archive. A JAR file is used to distribute multiple Java classes in one file..war: This is a web application archive. A WAR file* is used to deploy web applications such as JavaServer Pages (JSPs) and Servlets..ear: This is an enterprise application archive. An EAR file is used to deploy enterprise applications which include such assets as EJBs..sar: This is a JBoss service archive. A SAR file is used to deploy a service to a JBoss application server..esb: This is a JBoss ESB service archive. An ESB file is used to deploy a JBoss ESB service to an application server that has JBoss ESB deployed.* WAR, EAR, SAR, and ESB can be deployed either as files where the file format is actually a compressed file, or as a directory with the same
.war, or other extension in its name. If the compressed file has been uncompressed into a directory, it is referred to as an "exploded" WAR, EAR, and so on.
In a nutshell, the act of deploying JBoss ESB to an application server deploys these archives to the server.
The following steps will demonstrate how to start our server allowing us to test the installation:
We'll start by running the JBoss AS server
allprofile. Change to thebindirectory and enter the following command to start the server using theallserver profile:sh ./run.sh -c allAt this point, many, many lines of logging information are written to the screen. Near the end of the display, you should see lines that look like this:
19:52:20,592 INFO [TomcatDeployment] deploy, ctxPath=/admin-console 19:52:20,670 INFO [config] Initializing Mojarra (1.2_12-b01-FCS) for context ‘/admin-console' 19:52:22,410 INFO [TomcatDeployment] deploy, ctxPath=/ 19:52:22,452 INFO [TomcatDeployment] deploy, ctxPath=/jmx-console 19:52:22,672 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080 19:52:22,697 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009 19:52:22,708 INFO [ServerImpl] JBoss (Microcontainer) [5.1.0.GA (build: SVNTag=JBoss_5_1_0_GA date=200905221634)] Started in 44s:251ms
(If you are not seeing this, but you are seeing lots of lines of text that include
ERROR, then skip ahead a few sections to the section named And what to do if you see an error.)
We had previously started the JBoss AS server without specifying a server profile. This time, we used the -c option to select the server profile into which we had deployed JBoss ESB.
So far, so good. The server seems to be running, based on a quick look—correct at the surface. Now, let's look a little deeper and see what you can do to verify that the JBoss ESB installation is correct and that you will be able to use it for the remainder of the book.
You might be tempted to think about server logs with the same enthusiasm that you would have approached a college course in financial accounting: probably useful, but definitely boring.
Don't fall into this trap. The server logs are a gold mine of useful information. You'll see in the logs the results of both successful and failed operations. We'll be examining server logs in detail as we work through the examples in this book.
Let's start by finding the logs.
You saw a lot of logging information displayed on the screen when you started the server a few minutes ago. The problem with this information, however, is that it scrolled by faster than anyone could read and analyze it. Fear not. The same information, and actually, more information, was also written to log files.
Within the all server profile, you'll see a log directory. This directory contains the following log files:
boot.log: This shows the actual boot sequence followed by the server.server.log: The primary server log file which tracks the lifecycle of managed resources as well as output and error messages written from those resources. The JBoss ESB logger is based on Apache log4j (http://logging.apache.org/log4j/). The level of detail written to the server.log is configurable in each server'sjboss-log4j.xmlfile.
The degree of detail of information that is written to the logs is defined in the server/[profile]/conf/jboss-log4j.xml file as JBoss AS and ESB make use of the Java Log4J library. Log4J defines:
Appenders that enable you to have logging messages sent to a console or different files
Log message levels such as
INFO,WARNING,ERROR,DEBUG, andFATALCategories that enable you to filter log messages based on a package
We found the logs. Well, this was pretty easy, seeing as how they are in the logs directory. But, seriously, make a mental note as to the location of the logs as you will be returning to them frequently to diagnose problems, or to confirm that your server is running as expected.
What sort of things can you see in the server.log? Here's a simple example. Remember how we described the .esb archives that were added to the server when we deployed JBoss ESB? Let's look to see if they were initialized successfully when the server was started.
The following steps will show the deployment of an application in the server.log:
There they are, the very .esb archives that we discussed earlier:
2011-04-14 21:21:40,998 INFO [org.jboss.resource.connectionmanager.ConnectionFactoryBindingService] (main) Bound ConnectionManager ‘jboss.jca:service=DataSourceBinding,name=JBossESBDS' to JNDI name ‘java:JBossESBDS' 2011-04-14 21:21:41,009 INFO [org.jboss.internal.soa.esb.dependencies.DatabaseInitializer] (main) Initializing java:/JBossESBDS from listed sql files 2011-04-14 21:21:41,132 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘jbossesb.esb' 2011-04-14 21:21:42,788 INFO [org.quartz.impl.StdSchedulerFactory] (main) Quartz scheduler ‘ESBScheduler:jbossesb.esb' initialized from an externally provided properties instance. 2011-04-14 21:21:42,789 INFO [org.quartz.core.QuartzScheduler] (main) Scheduler ESBScheduler:jbossesb.esb_$_NON_CLUSTERED started. 2011-04-14 21:21:45,645 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘jbpm.esb' 2011-04-14 21:21:52,498 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘jbrules.esb' 2011-04-14 21:21:53,567 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘slsb.esb' 2011-04-14 21:21:53,614 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘smooks.esb' 2011-04-14 21:21:56,000 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘soap.esb' 2011-04-14 21:22:07,005 INFO [org.jboss.soa.esb.listeners.deployers.mc.EsbDeployment] (main) Starting ESB Deployment ‘spring.esb'
The main goal of this book is to help you to create your own JBoss ESB services. At this point in the book, however, we haven't done that yet, so we'll look at some of the ESB's services to verify that the server is running and that the deployment of JBoss ESB was successful. Let's start by looking at the server's Java Management Extension (JMX) console. You access the console here: http://localhost:8080/jmx-console/ JMX Console JMX Console
JMX is a Java technology that makes it possible to monitor and administer assets such as servers or software. You do this with JMX by defining Managed Beans (MBeans) that abstract/represent the managed objects.
How do they help us? MBeans monitor and control many attributes of the services and actions you will be building and using. They are a wonderful diagnostic tool in situations where you want to track what is happening on your server, and help you examine and control your deployments.
Let's look at one service that is accessed through an MBean. JBoss AS also has an administration console. This console is part of the JBoss "RHQ" project (http://www.jboss.org/jopr) and is the newest administrative tool for JBoss AS. This console provides a system and server-level interface and enables you to monitor and manage resources such as deployed applications, JMS queues and topics, and the server system itself (for example, memory use).
Problems can happen in the best of families, and software is no exception. If you see an error when you start the server, or when you deploy your own JBoss ESB service what should you do? Here's a set of steps that you should take: an easy way to start is to try to reconstruct the steps that you took before the error occurred. It may be that the root cause of the error was a configuration change or some other form of action that you performed. Remember that if you made a copy of the server profile before you started making changes, you can easily restore it.
If you can't easily identify or remember the cause of the error, then it's time to do some investigation of the logs.
First, examine the server log. Look at the messages that were displayed before or after the error occurred. What sort of things might be in the log? The following are a few examples:
"Class not found" (CNF) exceptions: These problems may be caused by a missing
.jar, or an incomplete deployment. The root cause of this may be that theCLASSPATHenvironment is not set correctly. Note that, in order to start the server, you don't have to haveCLASSPATHpre-defined. The start-up scripts will do it for you."Java not found" exceptions : The root cause of this problem may be that the
PATHenvironment variable is not set correctly. Try to verify that you can invoke the Java runtime from the command line and check its version (java -version)."Address already in use" exceptions : The root cause of this problem is that another server is already running on the port that the server you are starting is trying to use. By default, JBoss AS, with or without JBoss ESB deployed, runs on port 8080. If you see this error when you are trying to start the server, it's because another server is already running.
"Illegal state" exceptions : These problems may be caused by an invalid configuration file. Examine the error in the log and if it specifies an ESB validation error, check your
jboss-esb.xmlfile for errors.
If the error that you see doesn't make sense to you, you can always use a search engine to query pertinent information about your error, or ask a question on the user forum and attach your server.log to the post.
Before we move on, it's time to see what you've learned. Pencils ready? Let's begin!
JBossESB can run in standalone mode, without being deployed to an application server. True or false?
Name the (3) JBossESB distributions.
You can always get 24/7 support for all JBoss community projects simply by calling a super secret 1-800 telephone number. True or false?
The best way to get help on a question you have on JBoss community projects is to immediately make a vague post to the projects' forum. True or false?
What is a server "profile"?
How do you make a copy of a server profile, and why would you want to have a copy if the software is free?
The server logs are a waste of disk space. You should always delete the log files. True or false?
What is an MBean? And how does the JBoss JMX make it easy for you to use them?
Congratulations! You're off to a great start. You have a running JBoss AS with JBoss ESB installed. Application servers are very cool things. But, what makes them even more cool is that they are the vehicle on which you can build and run your own applications and servers.
In the next chapter, we'll take a close look at what a running service looks like and how you can start to build your own. Can you say "helloworld"?
