Red Hat Training

A Red Hat training course is available for JBoss Enterprise SOA Platform

Chapter 6. Basic Operation Tutorial

6.1. Running the JBoss Enterprise SOA Platform for the First Time

Introduction

In the following section you will learn how to launch and run the JBoss Enterprise SOA Platform for the first time. The simplest thing you can do is run the demonstration code found in the "Hello World" quick start.

As you run this quick start, you will be taught how it works.

6.2. Start the JBoss Enterprise SOA Platform

Prerequisites

The following software must be installed:

  • JBoss Enterprise SOA Platform

Procedure 6.1. Start the JBoss Enterprise SOA Platform

  • Start the SOA server in a server window

    • Red Hat Enterprise Linux

      1. Open a terminal and navigate to the bin directory by entering the command cd SOA_ROOT/jboss-as/bin.
      2. Enter ./run.sh to start the SOA server. (Because you are not specifying a server profile, "default" will be used.)

    • Microsoft Windows

      1. Open a terminal and navigate to the bin directory by entering the command chdir SOA_ROOT\jboss-as\bin.
      2. Enter run.bat to start the SOA server. (Because you are not specifying a server profile, "default" will be used.)
Result

The server starts. Note that this will take approximately two minutes, depending on the speed of your hardware.

Note

To verify that there have been no errors, check the server log: less SOA_ROOT/jboss-as/server/PROFILE/log/server.log. As another check, open a web browser and go to http://localhost:8080. Make sure you can login to the admin console with the user name and password you have set.

6.3. Troubleshooting the Boot Process

Errors in the server.log are indicated by the keyword "ERROR". If you see an error in the log, look through this list to find the cause:
  1. "Address already in use" - There is already a server running on port 8080.
  2. "Java not found" - The Java JRE may not be installed, or if it is, your PATH environment variable is not set to locate the java runtime.
  3. "Class not found" - The CLASSPATH environment variable is not set properly. You really don't need to set this variable as the server startup script sets it for you.
  4. If you see any of these errors, examine the server.log messages that come before and after the error message for additional information regarding the root cause of the error.

6.4. Running the "Hello World" Quickstart

6.4.1. Quickstart

The quickstarts are sample projects. Each one demonstrates how to use a specific piece of functionality in order to aid you in building services. There are several dozen quickstarts included in the SOA_ROOT/jboss-as/samples/quickstarts/ directory. Build and deploy every quickstart by using Apache Ant.

6.4.2. Important Notes About Quickstarts

When intending to run a quickstart, remember the following points:
  1. Each quickstart needs to be built and deployed using Apache Ant.
  2. Each quickstart uses the samples/quickstarts/conf/quickstarts.properties file to store environment-specific configuration options such as the directory where the server was installed. You must create a quickstarts.properties file that matches your server installation. An example properties file (quickstarts.properties-example) is included.
  3. Each quickstart has different requirements. These are documented in their individual readme.txt files.
  4. Not every quickstart can run under every server profile.
  5. The jBPM quickstarts require a valid jBPM Console user name and password. Supply these by adding them as properties in the SOA_ROOT/jboss-as/samples/quickstarts/conf/quickstarts.properties file: 
    # jBPM console security credentials
jbpm.console.username=admin 
jbpm.console.password=adminpassword
    The quickstarts that are affected by this requirement are bpm_orchestration1, bpm_orchestration2, bpm_orchestration3 and bpm_orchestration4.
  6. You can only execute some of the quickstarts (such as groovy_gateway) if the server is not running in headless mode. (The JBoss Enterprise SOA Platform is configured to launch in headless mode by default.)

    Important

    Red Hat recommends that you run production servers in headless mode only.

6.4.3. Deploy the "Hello World" Quickstart on Your Test Server

Prerequisites

  • Check that the setting in SOA_ROOT/jboss-as/samples/quickstarts/conf/quickstarts.properties-example matches the server configuration (default in a testing environment).

Procedure 6.2. Deploy the "Hello World" Quickstart

  1. Check that the server has fully launched.
  2. Open a second terminal window and navigate to the directory containing the quick start: cd SOA_ROOT/jboss-as/samples/quickstarts/helloworld (or chdir SOA_ROOT\jboss-as\samples\quickstarts\helloworld in Microsoft Windows).
  3. Run ant deploy to deploy the quickstart. Look for messages such as this to confirm if the deployment was successful: 
    deploy-esb:
     [copy] Copying 1 file to
/jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy

deploy-exploded-esb:

quickstart-specific-deploys:
     [echo] No Quickstart specific deployments being made.

display-instructions:
     [echo] 
     [echo] ******************
     [echo] Quickstart deployed to target JBoss ESB/App Server at
'/jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy'.
     [echo] 1.  Check your ESB Server console to make sure the deployment was
executed without errors.
     [echo] 2.  Run 'ant runtest' to run the Quickstart.
     [echo] 3.  Check your ESB Server console again.  The Quickstart should
have produced some output.
     [echo] ******************

deploy:

BUILD SUCCESSFUL
    Also, check for this in the SOA_ROOT/jboss-as/server/default/log/server.log: 
    10:58:52,998 INFO  [NamingHelper] JNDI InitialContext properties:{}
11:00:58,154 INFO  [QueueService]
Queue[/queue/quickstart_helloworld_Request_esb] started, fullSize=200000,
pageSize=2000, downCacheSize=2000
11:00:58,186 INFO  [QueueService]
Queue[/queue/quickstart_helloworld_Request_gw] started, fullSize=200000,
pageSize=2000, downCacheSize=2000
11:00:58,427 INFO  [EsbDeployment] Starting ESB Deployment
'Quickstart_helloworld.esb'
  4. Run the quickstart by issuing this command: ant runtest. When the quickstart is run, messages such as this are written to the SOA_ROOT/jboss-as/server/default/log/server.log: 
    11:03:02,190 INFO  [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
11:03:02,191 INFO  [STDOUT] Body: Hello World
11:03:02,191 INFO  [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
11:03:02,192 INFO  [STDOUT] Message structure: 
11:03:02,192 INFO  [STDOUT] [Hello World].
Result

The words "Hello World" will appear on the server terminal. This message will also be appended to the SOA_ROOT/jboss-as/server/default/log/server.log file.

6.4.4. ant deploy

ant deploy compiles a quickstart's source code in the build directory, then generates an .ESB file (such as Quickstart_helloworld.esb) in the server profile's deploy directory. (Note that it generates .JAR files for BPEL quickstarts.) The server detects the presence of the new .esb archive and deploys it. In the .ESB archive is a deployment.xml file that ant deploy uses to configure a queue.
ant deploy also uses an XSL template to transform generic JMS queue names into the specific JMS queues needed by the target server's messaging provider. Ant selects the correct messaging provider by examining the server for a messaging provider deployment. Only JBoss Messaging, JBoss MQ, and HornetQ are detected by the build script. Other messaging providers are not supported by the quick start. Ant then puts the deployment.xml file into the build/META-INF directory before including it in the same .ESB archive as the rest of the quickstart.

6.4.5. ant runtest

ant runtest sends an ESB-unaware "Hello World" message (which is a plain String object) to the JMS Queue (queue/quickstart_helloworld_Request_gw). It instructs Java to run the sender class (in the case of the "Hello World" quick start, this is called org.jboss.soa.esb.samples.quickstart.helloworld.test.sendJMSMessage). By doing so, it sends a message directly to the deployed process.

6.4.6. ant sendesb

The ant sendesb command sends an ESB message to the SOA Server. It sends the ESB-aware message directly to the ESB listener, meaning that it does not have to utilize a gateway.

6.4.7. Undeploy the "Hello World" Quickstart

Procedure 6.3. Task

  1. Navigate to the quickstart's directory: cd SOA_ROOT/jboss-as/samples/quickstarts/helloworld (or chdir SOA_ROOT\jboss-as\samples\quickstarts\helloworld if you are running Microsoft Windows).
  2. Run the ant undeploy command. You should see messages such as this displayed: 
    undeploy:
[delete] Deleting:
/jboss/local/53_DEV2/jboss-soa-p-5/jboss-as/server/default/deploy/Quickstart_helloworld.esb

BUILD SUCCESSFUL
    And messages such as this written to the server.log: 
    11:10:08,205 INFO  [EsbDeployment] Stopping 'Quickstart_helloworld.esb'
11:10:08,577 INFO  [EsbDeployment] Destroying 'Quickstart_helloworld.esb'

6.5. Stop the JBoss Enterprise SOA Platform Server

Procedure 6.4. Stop the JBoss Enterprise SOA Platform Server

  • Stop the SOA server

    Press ctrl-c in the server window (the terminal window where the SOA server was started).
Result

The server will shut down. Note that this process will take a few minutes. Look for this line in the server.log file to confirm that the server has shut down successfully: 

        12:17:02,786 INFO  [ServerImpl] Shutdown complete

6.6. Examining the "Hello World" Quickstart

6.6.1. Overview of How the "Hello World" Quickstart Works

Image

Figure 6.1. Image

  1. The JBoss Enterprise SOA Platform server is launched in Window1 and then the FirstServiceESB:SimpleListener service is added to the Service Registry service when the helloworld quickstart is deployed.
  2. A JMS client sends an ESB-unaware "Hello World" message, (it is a plain String object), to the JMS Queue (queue/quickstart_helloworld_Request_gw).
  3. The JMS Gateway Listener receives the ESB-unaware message and creates from it an ESB-aware message for use by ESB-aware end-points.
  4. The JMS Gateway Listener uses the service registry to find the FirstServiceESB:SimpleListener service's end-point reference (EPR). In this case, the EPR is the queue/quickstart_helloworld_Request_esb JMS queue.
  5. The JMS Gateway Listener takes the new ESB-aware message and sends it to the queue/quickstart_helloworld_Request_esb JMS queue.
  6. The FirstServiceESB:SimpleListener service receives the message.
  7. The FirstServiceESB:SimpleListener service extracts the payload from the message and outputs it to the console.

6.6.2. ESB Message

An ESB message is a message that takes the form defined by the org.jboss.soa.esb.message interface. This standardized format consists of a header, body (payload) and attachments. All ESB-aware clients and services communicate with one another using messages.

6.6.3. Components of an ESB Message

An ESB message is made up of the following components:
Header
The header contains such information as the destination end-point reference, the sender end-point reference, and where the reply goes. This is all general message-level functional information.
Context
This is additional information that further explains the message; for example, transaction or security data, the identity of the ultimate receiver or HTTP-cookie information.
Body
The actual contents of the message.
Fault
Any error information associated with the message.
Attachment
Any attachments (additional files) associated with the message.
Properties
Any message-specific properties.(For example, the jbossesb.message.id property specifies a unique value for each message).
Here is a code representation: 
    <xs:complexType name="Envelope">
	<xs:attribute ref="Header" use="required"/>
	<xs:attribute ref="Context" use="required"/>
	<xs:attribute ref="Body" use="required"/>
	<xs:attribute ref="Attachment" use="optional"/>
	<xs:attribute ref="Properties" use="optional"/>
	<xs:attribute ref="Fault" use="optional"/>
</xs:complexType>

6.6.4. How Message Objects are Sent to the Queue

Overview

The JBoss Enterprise SOA Platform product uses a properties object that is populated with parameters to identify the presence of JNDI on the local server. It is then used as the parameter for a call to create a new Naming Context which is used to obtain the ConnectionFactory. The Connection Factory, in turn, creates the QueueConnection, which creates the QueueSession. This QueueSession creates a Sender object for the Queue. The Sender object is used to create an ObjectMessage for the sender and to then send it to the Queue.

6.6.5. Properties Object

The Properties object is a container for a generic list of keys and values. You should populate the Properties object with the parameters needed to identify JBoss JNDI on the local server and then use it as the parameter for a call to create a new Naming Context.

6.6.6. Naming Context

A Naming Context is an object that connects to a directory and allows the user to obtain objects by name reference.

6.6.7. ConnectionFactory

The ConnectionFactory is an object (org.jboss.jms.client.JBossConnectionFactory) that creates a QueueConnection. The Naming Contect obtains the ConnectionFactory from JNDI.

6.6.8. QueueConnection

The QueueConnection is an object created by the ConnectionFactory. It is used to create and start a QueueSession.

6.6.9. QueueSession

The QueueSession is created by the QueueConnection. It creates a Sender object for the queue and an ObjectMessage containing a string.

6.6.10. SOA_ROOT/jboss-as/samples/quickstarts/helloworld/build.xml

The build.xml file contains the instructions used by ant deploy to compile the quickstart's source code in the build directory. You can edit this file to add your own custom instructions.

6.6.11. SOA_ROOT/jboss-as/samples/quickstarts/helloworld/deployment.xml

The deployment.xml file is used by ant runtest to create and configure a messaging queue.
ant deploy generates the deployment.xml file in the build/META-INF directory during the compilation process. It then populates it when it determines which of the hard-coded JMS queues should be used. Once populated, the file is packaged as part of the .ESB archive. (Ant uses an XSL template to transform generic JMS queue names into the specific JMS queues required by the target server's messaging provider. It is from this template that the deployment.xml file is created.)

6.6.12. Messaging Queues

A message queue is a queue that is generated when an application is deployed. Messages are sent to these queues where they await the message listener.

6.6.13. Message Listeners

Message listeners encapsulate the communications end-points needed to receive SB-aware messages. Listeners are defined by services and their role is to monitor queues. They receive any messages as they land in those queues. When a listener receives a message, the ESB server calls the appropriate action class defined in the action definition. The methods in this class process the message. In other words, listeners act as inbound routers, directing messages to the action pipeline. When the message has been modified by the actions on the pipeline, the listener sends the result to the replyTo end-point.
You can configure various parameters for listeners. For instance, you can set the number of active worker threads.
There are two types of listeners: ESB-aware listeners and gateway listeners. Gateway listeners are different from ESB-aware listeners in that they accept data in different formats (such as objects in files, SQL tables and JMS messages). They then convert them from these formats to the ESB messaging format. By contrast, ESB-aware listeners can only accept messages that are in the org.jboss.soa.esb.message.Message format. Each gateway listener must have a corresponding ESB listener defined.
With ESB-aware listeners, RuntimeExceptions can trigger rollbacks. By contrast, with a gateway listener, the transaction simply sends the message to the JBoss ESB. The message is then processed asynchronously. In this way, message failures are separated from message receipts.

6.6.14. ESB-Awareness

If application clients and services are referred to as being ESB-aware, this means that they can understand the message format and transport protocols used by the SOA Platform's enterprise service bus.

6.6.15. Gateway Listener

A gateway listener is used to bridge the ESB-aware and ESB-unaware worlds. It is a specialized listener process that is designed to listen to a queue for ESB-unaware messages that have arrived through an external (ESB-unaware) end-point. The gateway listener receives the messages as they land in the queue. When a gateway listener "hears" incoming data arriving, it converts that data (the non-ESB messages) into the org.jboss.soa.esb.message.Message format. This conversion happens in a variety of different ways, depending on the gateway type. Once the conversion has occurred, the gateway listener routes the data to its correct destination.

6.6.16. Senders

Senders are created by QueueSessions. There is a sender for each queue. The Sender's send method is called by its QueueSession's ObjectMessage when ant runtest is executed. When this happens, the client sends a message to the queue.

6.6.17. Learn More About a Quickstart

To learn more about a particular quickstart:

Procedure 6.5. Task

  1. Study the quickstart's readme.txt file.
  2. Run the ant help command in the quickstart's directory.

6.7. The "Hello World" Quickstart's Source Code

6.7.1. SOA_ROOT/jboss-as/samples/quickstarts/helloworld/src

The "Hello World" quickstart's src directory contains the uncompiled programming instructions. The classes are in files nested in subdirectories. ant deploy compiles this source code.

6.7.2. SOA_ROOT/jboss-as/samples/quickstarts/helloworld/lib

The lib directory contains the classes needed by ant deploy, (in addition to the source code), to compile the quick start.

6.7.3. SOA_ROOT/jboss-as/server/SERVER_PROFILE/deploy

ant deploy moves the compiled version of a quick start (in the form of an .ESB archive file) from the build directory to the /jboss-as/server/default/deploy/ directory. The JBoss Enterprise SOA Server is polling this directory and, when it detects the presence of a new .ESB file, it deploys it.