Before we take an in-depth look at one quickstart, it's important to understand the deployment requirements for any JBoss ESB service-based application. When we discussed the types of archives that are deployable to the JBoss AS servers in the first chapter, we briefly talked how in addition to WAR files (.war), EAR files (.ear), and SAR files (.sar), JBoss ESB added the .esb archive. Let's now take a look at just what has to be in a .esb archive, in order for it to be deployed.
Note that the quickstarts all create complete and deployable .esb archives. The base-build.xml file includes the definition of the "deploy" task and this creates the deployable .esb archives.
If you look inside a JBoss ESB .esb archive, you'll see a similar directory tree of files and directories:
The most important part of the configuration file for an .esb archive is jboss-esb.xml. Depending upon the complexity of your application, jboss-esb.xml can be an intimidating file to edit, but if you keep in mind that despite the complexity of any application, the goals of this file are to define the application's providers, listeners, and services.
We've discussed services already in this book, but who are these providers? And, what do they provide?
Providers are servers or packages that exist outside of JBoss ESB that—for the lack of a better word—"provide" resources to the services defined in the .esb archive. You define the endpoints through which the services access these resources in jboss-esb.xml. Some examples of the types of resources that providers make available are JMS topics and queues, FTP servers, or SQL access to a database.
Let's take a high-level look at what a jboss-esb.xml file looks like. We'll take a much more in depth look at a specific quickstart's jboss-esb.xml, and other configuration files, in the next section of this chapter. For now, we'll ease into the water and save the detailed XML for a later chapter. The following image describes the connection of the services contained within the jboss-esb.xml file:
The file is divided into two main sections: Providers and Services.
Each provider definition includes:
- A Name, and, depending on the type of the provider, Attributes. For example, FTP providers will include the FTP server name as an attribute.
- A busid that is important to make note of, as this ID will be used in the service and listener definitions later in the
jboss-esb.xmlfile. This ID is used to reference the endpoint that the provider defines, and is used instead of the provider name, to reference that endpoint. - A Message filter is used to specify details about the resource made available by the provider. For example, for a JMS provider, the filter will reference the JMS queue provided, and for an FTP provider, the filter will reference the FTP server, directories, and so on.
- For schedule-related providers, you define the details of the schedule, such as
cronsettings.
Each service definition includes:
- Category, Name, and Description, the combination of these are used in the service registry.
- Listeners; a service definition contains one or more listeners. What's interesting to note here is that just as the providers must define ESB-aware providers to correspond to non-aware providers, the listeners must also define ESB-aware listeners to correspond to the non-aware providers.
Note
What does it mean to be "ESB-aware?"
It refers to being able to handle messages in the format used by the ESB as opposed to any message format such as JMS or HTTP. The providers that you define work in pairs. The ESB-unaware provider helps you to bring messages "onboard" onto the ESB, and the ESB-aware provider handles messages once they are on the ESB. The ESB-unaware providers work with processes that we refer to as "gateways" to "onboard" messages onto the ESB. We'll discuss this in detail in Chapter 5 and Chapter 6 when we look at message delivery and gateways.
- In the event that a listener is a gateway listener and corresponds to a provider, then the listener will include this property
is-gateway="true". - Each listener will cross reference the
busidof the provider on which it relies. - Actions; the sequential action pipeline. These are the actions that are performed by the service.
In addition to jboss-esb.xml, some quickstarts include other deployment-related files, for example, deployment.xml.
When an .esb archive is deployed, the sequence of actions is that message queues are deployed first, then ESB-aware services, and finally the gateways. This sequence is important so the application services are always running before any clients can push data to them. After this, the registry is updated, so that clients and other services can find the deployed services (http://community.jboss.org/wiki/JBossESBDeploymentStrategies). This requirement is specified by the deployment.xml file. This file defines the exact order in which the message queues are deployed. In addition, you can use this file to make your .esb deployment dependent on other deployments. In this way you can be sure that your .esb will have all the resources that it needs to run when it is deployed.
Depending on the types of resources that your .esb requires, there may be additional configuration files. One type of file that you'll see with many of the quickstarts is used to define the service dependencies needed by JMS queues. These files are named jbm-queue-service.xml (where "jbm" stands for JBoss Messaging).
Let's stop looking at quickstarts in the abstract and examine a quickstart in detail. The tasks that the quickstart performs are very simple, but every configuration and operational characteristic of the quickstart is used and expanded upon by the other quickstarts or custom applications that you build. The quickstart that we'll look at is the ESB version of the classic programming example; helloworld.
In this section, we'll walk through running a quickstart. This will give you hands on experience in deploying, running, reviewing the operations that the quickstart performs, and then undeploying an .esb archive.
In keeping with programming tradition, the simplest of the quickstarts is "helloworld". It's a small program, but there are those who love it!
Note
Apologies to Daniel Webster
"It is, as I have said, a small college, and yet there are those who love it."
http://www.dartmouth.edu/~dwebster/speeches/dartmouth-peroration.html
What does this quickstart do? It performs one of two functions, depending on how the quickstart is invoked. It either receives a message through a JMS gateway listener and passes that message to the gateway's corresponding ESB-aware listener, or it skips the gateway and receives the message directly at an ESB-aware listener. After that, the quickstart writes the message to the server log and exits.
While, at first glance, the helloworld quickstart may appear too simple to serve as an useful example of a .esb archive, it is a fully functioning and deployable .esb. As it is simple, it will let us concentrate on the configuration, deployment, and execution of .esb archives, without being distracted by examples of JBoss ESB many features or integrations.
Let's start with the deployment.