1. Quickstart Guide

This quick start guide is about getting the first message run though the UltraESB. It also observes the message flow to get an understanding of the UltraESB, as well as message mediation. This will introduce the AdroitLogic SOA Toolbox which will be used to form the back end server, and the client that invoke the UltraESB. Further this guide will also introduce the management tools of the UltraESB including the UConsole (Web based management console) and the UTerm (CLI based management terminal) for management and monitoring aspects.

This exercise will use the default configuration, and help you understand the UltraESB and its behaviour. Developing a solution with the UltraESB is not covered in this chapter, which has been discussed in-detail under the Solution Development on User Guide.

The quick start guide contain the following sections;

At the end of this quick start guide, you will understand the basic message flow and the main functionality in the UltraESB. A basic knowledge on the SOA Toolbox, UConsole, UTerm and the relationship of those to the UltraESB will also be explained. The SOA Toolbox, UConsole and UTerm will be discussed in-detail under the relevant sections of the documentation.

The next chapter of the documentation briefs on the UltraESB integration solution development and testing/debugging with its User Guide.

1.1. Running UltraESB

This section describes the various options available for running your UltraESB instance, which you have installed by following the Installation Guide.

UltraESB is shipped with a default server configuration (which could be found at conf/ultra-root.xml) and a deployment unit named "default", which could be found at conf/deployments directory of the UltraESB installation.

While the ultra-root.xml provides the more static server configurations like transports, management/monitoring, clustering, caching etc. the deployment units provide the dynamic service and mediation configurations. While it is possible to have proxy services and mediation configuration also in the ultra-root.xml (which is the approach taken in sample configurations to make it easily runnable and switchable between samples), keeping those dynamic elements only at the deployment units is vital in supporting the graceful configuration updates and configuration provisioning, which you will see how to effectively do in the Configuration and Administration section of the documentation.

Default Configuration
The default configuration is configured to start the HTTP/S transport listeners (8280/8443) and the default deployment unit exposes 2 sample proxy services named echo-proxy, a proxy service, which proxies the sample echo service running at port 9000 and echo-back, a mock service which echo the request itself as the response from the ESB.

There are 3 different ways in running the UltraESB standalone server;

Running UltraESB within the IDE will be discussed in-detail under the User Guide, and this sections introduces to the first and third options in running the UltraESB.

Webapp Deployment
UltraESB also supports webapp deployment, apart from the standalone UltraESB server, which is covered under the Deployment Guide section of the documentation.

1.1.1. Running UltraESB with start-up script

This is the more common way of running the UltraESB at development phase, and it directly starts the server with the default configuration and any available deployment units.

For starting the UltraESB with the default configuration, on Linux based systems, use a command line shell to navigate to the ULTRA_HOME/bin directory and execute the ultraesb.sh script.

$ cd /opt/ultraesb-2.0.0/bin
$ ./ultraesb.sh

For starting the UltraESB with default configuration on Windows based systems, navigate to the ULTRA_HOME/bin directory using the file browser and double click on the ultraesb.bat script.

Upon firing the above command to execute the ultraesb.sh or by double clicking on the ultraesb.bat script, the following output will be displayed on the console.

Starting AdroitLogic UltraESB …
Using JAVA_HOME  : /opt/jdk1.6.0_23
Using ULTRA_HOME: /opt/ultraesb-2.0.0
Reading configuration from : /opt/ultraesb-2.0.0/conf/ | Current directory is : /opt/ultraesb-2.0.0/.
2013-08-01 10:16:37,003 [-] [main]  INFO ServerManager ServerManager initializing..
2013-08-01 10:16:37,365 [-] [main]  INFO UltraServer UltraESB JAR file version/s : [2.0.0-414d1fa69e01]
2013-08-01 10:16:37,374 [-] [main]  INFO LicenseManager Server ID : d1e42001-8d94-4893-b6c0-ed11599daa86
2013-08-01 10:16:37,374 [-] [main]  INFO LicenseManager You are currently using this software under an evaluation license of 30 days. To obtain a full license free of charge, please visit http://adroitlogic.org
2013-08-01 10:16:38,152 [-] [main]  INFO PooledMessageFileCache Directory : /opt/ultraesb-2.0.0/tmp/ruwan_localhost locked for file cache
2013-08-01 10:16:38,589 [-] [main]  INFO ConfigurationImpl Starting UltraESB/2.0.0 (GA) (c) 2010-2013 AdroitLogic. All Rights Reserved - localhost
2013-08-01 10:16:38,589 [-] [main]  INFO ConfigurationImpl Server name : localhost
2013-08-01 10:16:40,285 [-] [main]  INFO ConfigurationImpl Pre-initialization of the engine..
2013-08-01 10:16:41,110 [-] [main]  INFO TransformationUtils Initializing Transformation feature
2013-08-01 10:16:41,128 [-] [main]  INFO XMLFeatures Initializing the XML feature
2013-08-01 10:16:41,213 [-] [main]  INFO MediationImpl Initializing the Mediation feature
2013-08-01 10:16:41,490 [-] [main]  INFO CryptoSupport Initializing the Security and Crypto features
2013-08-01 10:16:41,542 [-] [main]  INFO FastInfosetUtils Initializing the Fast-Infoset feature
2013-08-01 10:16:41,546 [-] [main]  INFO JSONUtils Initializing the JSON feature
2013-08-01 10:16:41,572 [-] [main]  INFO ServerManager Starting server …
2013-08-01 10:16:41,647 [-] [main]  INFO ServerManager Linux - amd64 [3.2.0-49-generic] / Processors : 4
2013-08-01 10:16:41,649 [-] [main]  INFO ServerManager Total physical memory : 7,971,384K (623,080K free)  Heap max : 1,004,928K
2013-08-01 10:16:41,649 [-] [main]  INFO ServerManager Java HotSpot™ 64-Bit Server VM, Sun Microsystems Inc. [19.0-b09]
2013-08-01 10:16:41,667 [-] [main]  INFO ServerManager Clustering is disabled
2013-08-01 10:16:41,668 [-] [main]  INFO HttpsNIOSender Https transport sender : https-sender using default identity keystore
2013-08-01 10:16:41,668 [-] [main]  INFO HttpsNIOSender Https transport sender : https-sender using the default trust keystore
2013-08-01 10:16:41,819 [-] [HttpsNIOSender-https-sender]  INFO HttpsNIOSender Starting NIO Sender : https-sender …
2013-08-01 10:16:41,826 [-] [HttpNIOSender-http-sender]  INFO HttpNIOSender Starting NIO Sender : http-sender …
2013-08-01 10:16:41,847 [-] [main]  INFO fileCache Memory mapping is enabled for : 8192 bytes of each file
2013-08-01 10:16:41,847 [-] [main]  INFO fileCache Initialized cache of : 200 files at : /opt/ultraesb-2.0.0/tmp/ruwan_localhost
2013-08-01 10:16:41,856 [-] [main]  INFO SimpleQueueWorkManager Started Work Manager : default
2013-08-01 10:16:41,856 [-] [main]  INFO ServerManager Initializing transport listeners
2013-08-01 10:16:41,864 [-] [main]  INFO ServerManager Starting Proxy Services, Endpoints and Sequences
2013-08-01 10:16:41,874 [-] [main]  INFO Address Started Address : address of endpoint : echo-service
2013-08-01 10:16:41,874 [-] [main]  INFO echo-service Started endpoint : echo-service
2013-08-01 10:16:41,877 [-] [main]  INFO Address Started Address : address of endpoint : mediation.response
2013-08-01 10:16:41,877 [-] [main]  INFO Endpoint Started endpoint : mediation.response
2013-08-01 10:16:42,786 [-] [main]  INFO error-handler Sequence : error-handler started
2013-08-01 10:16:42,846 [-] [main]  INFO health-check-inSequence Sequence : health-check-inSequence started
2013-08-01 10:16:42,847 [-] [main]  INFO health-check Proxy service : health-check started
2013-08-01 10:16:42,847 [-] [main]  INFO ServerManager UltraESB root deployment unit started successfully
2013-08-01 10:16:42,849 [-] [main]  INFO DeploymentUnitBuilder Using the hot-swap class loading of libraries for deployment unit default
2013-08-01 10:16:42,892 [-] [main]  INFO DeploymentUnitBuilder Successfully created the deployment unit : default
2013-08-01 10:16:42,992 [-] [main]  INFO echo-back-inSequence Sequence : echo-back-inSequence started
2013-08-01 10:16:42,992 [-] [main]  INFO echo-back Proxy service : echo-back started
2013-08-01 10:16:43,062 [-] [main]  INFO echo-proxy-outSequence Sequence : echo-proxy-outSequence started
2013-08-01 10:16:43,064 [-] [main]  INFO Address Started Address : address of endpoint : echo-proxy-inDestination
2013-08-01 10:16:43,064 [-] [main]  INFO echo-proxy-inDestination Started endpoint : echo-proxy-inDestination
2013-08-01 10:16:43,069 [-] [main]  INFO Address Started Address : address of endpoint : echo-proxy-outDestination
2013-08-01 10:16:43,069 [-] [main]  INFO echo-proxy-outDestination Started endpoint : echo-proxy-outDestination
2013-08-01 10:16:43,069 [-] [main]  INFO echo-proxy Proxy service : echo-proxy started
2013-08-01 10:16:43,069 [-] [main]  INFO ConfigurationImpl Successfully added the deployment unit : default
2013-08-01 10:16:43,069 [-] [main]  INFO ServerManager Starting transport listeners
2013-08-01 10:16:43,088 [-] [main]  INFO HttpsNIOListener Identity keystore loaded from : conf/keys/identity.jks
2013-08-01 10:16:43,095 [-] [HttpNIOListener-http-8280]  INFO HttpNIOListener Starting NIO Listener : http-8280 on port : 8280 …
2013-08-01 10:16:43,111 [-] [main]  INFO HttpsNIOListener Trust keystore loaded from : conf/keys/trust.jks
2013-08-01 10:16:43,112 [-] [main]  INFO ConfigurationImpl UltraESB/2.0.0-SNAPSHOT (GA) - localhost started with root configuration..
2013-08-01 10:16:43,116 [-] [HttpsNIOListener-https-8443]  INFO HttpsNIOListener Starting NIO Listener : https-8443 on port : 8443 …

Stopping the just started server is a matter of terminating the program by pressing Ctrl+C on the command line.

The UltraESB installation installs itself on first execution for an evaluation period of 30 days. You should then submit the generated Server ID reported by the LicenseManager and the following details to license@adroitlogic.com in-order to obtain a full production license for perpetual use on any number of instances, FREE OF CHARGE.

[Required]
Name of the Licensee: *
Number of Instances you wish to use: *
Server ID: *

[Optional]
Contact Name
Contact Email address
Description of use :
Comments and Feedback :

Production License
Typically you will receive your license key within one business day. Your current 'Server ID' is printed on the console as the UltraESB starts.

While this approach is more common in starting/stopping ESB in development mode which will report any errors on the console for easy resolution, almost all of the production deployments prefer starting the UltraESB as a daemon on Linux with Java Service Wrapper.

1.1.2. Running UltraESB in production

In production you might want the server to run as a UNIX daemon and you also want to guarantee the availability (i.e. if the server crashes an instance will automatically be started) and so forth. UltraESB uses Java Service Wrapper to run the server as a UNIX daemon.

Note
Production deployments are only supported on Linux and hence the Java Service Wrapper is also configured only to run on Linux as a daemon and running the server on Windows as a service in production is not recommended.

Starting the server as a daemon is exposed with the ultraesb-daemon.sh. Execute the daemon script to see the command usages as follows;

$ ./ultraesb-daemon.sh

The usage of the daemon script will be displayed as follows;

Usage: ./ultraesb-daemon.sh \{ console | start | stop | restart | status | dump }

These options and there respective usage are as follows;

  • console - start the server on console, mostly equal to the previous start-up mode

  • start - starts the server as a daemon

  • stop - stop the server started as a daemon

  • restart - restart the server started as a daemon

  • status - check status of the server started as a daemon

  • dump - dump the JVM state with a thread dump to the wrapper log

For example to start the UltraESB instance use the following command

$ ./ultraesb-daemon.sh start

Then to stop the started server instance you can use

$ ./ultraesb-daemon.sh stop

Once the UltraESB is started and running, you could use the UltraESB management console (Uconsole) or the management terminal (Uterm) to manage/monitor the instance. The usages of the Uconsole and Uterm will be covered under relevant sections.

For advance options available for start-up commands please refer to the Configuration and Administration.

1.2. The Default Configuration

The default configuration is the configuration shipped in, in-factory with the Adroitlogic UltraESB. This section describes the key configuration elements of the default configuration in brief, while a more detailed configuration guide on each and every component is in discussion under the User Guide and Configuration and Administration sections of the documentation.

1.2.1. Root configuration walk through

The main configuration file that UltraESB looks for by default is the ultra-root.xml file which resides in the conf directory of the ULTRA_HOME. This particular file in brief is as follows;

Note
The following configuration only contains the required key elements. Comments and few other elements were cut off for the clarity in presenting it on the documentation. The actual file varies from this, but should contain all what is displayed here.

Root Configuration

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:u="http://www.adroitlogic.org/ultraesb"
       xmlns:s="http://www.springframework.org/schema/security"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-3.1.xsd
http://www.adroitlogic.org/ultraesb http://schemas.ultraesb.org/ultraesb-2.0.xsd">

    <bean id="fileCache" class="org.adroitlogic.ultraesb.core.PooledMessageFileCache">
        <constructor-arg value="tmp"/>
        <constructor-arg value="200" type="int"/>
    </bean>

    <bean id="http-8280" class="org.adroitlogic.ultraesb.transport.http.HttpNIOListener">
        <constructor-arg ref="fileCache"/>
        <property name="port" value="8280"/>
    </bean>

    <bean id="https-8443" class="org.adroitlogic.ultraesb.transport.http.HttpsNIOListener">
        <constructor-arg ref="fileCache"/>
        <property name="sslVerifyClient" value="optional"/>
        <property name="identityStorePath" value="conf/keys/identity.jks"/>
        <property name="identityKeyPassword" value="password"/>
        <property name="identityStorePassword" value="password"/>
        <property name="trustStorePath" value="conf/keys/trust.jks"/>
        <property name="trustStorePassword" value="password"/>
        <property name="port" value="8443"/>
    </bean>

    <bean id="http-sender" class="org.adroitlogic.ultraesb.transport.http.HttpNIOSender">
        <constructor-arg ref="fileCache"/>
    </bean>

    <bean id="https-sender" class="org.adroitlogic.ultraesb.transport.http.HttpsNIOSender">
        <constructor-arg ref="fileCache"/>
    </bean>

    <bean id="environment" class="org.adroitlogic.ultraesb.core.Environment">
        <constructor-arg value="dev" type="java.lang.String"/>
    </bean>

    <bean id="ultra-config" class="org.adroitlogic.ultraesb.core.ConfigurationImpl">
        <property name="environment" ref="environment"/>
    </bean>

    <import resource="ultra-custom.xml"/>
    <import resource="monitoring/ultra-metrics.xml"/>

</beans>

The UltraESB component configuration is a spring configuration with a set of spring beans defining each and every component as seen above. The above configuration contains the following bean definitions;

fileCache

The bean identified by the key "fileCache" is the file cache configuration to be used by the transport receivers and senders, for the time being let’s not worry about this. The guide discusses this concept in detail under the Architecture and Design and the configuration options under the Configuration and Administration.

http-8280

The bean identified by the key "http-8280" is the HTTP listener or the HTTP transport receiver of the UltraESB configured to be listening on the port 8280, as described by the property named port. Further the file cache bean is passed in to use it with the transport.

https-8443

The bean identified by the key "https-8443" is the HTTPS listener or the HTTPS transport receiver of the UltraESB configured to be listening on the port 8443, as described by the property named port. Apart from the port property there are few other properties which configure SSL. The complete configuration options will be discussed under the Transports configurations in Configuration and Administration. This also uses the same file cache bean as in the http transport listener that we have discussed previously.

http-sender

The bean identified by the key "http-sender" is the HTTP transport sender configured with the file cache bean as in the receiver.

https-sender

The bean identified by the key "https-sender" is the HTTPS transport sender configured with the file cache bean as in the receiver.

Note
In the above 4 bean identifiers there is no relation between there protocol and the listening port, just for the clear identification purposes they have given the names according to there protocol and the exposed ports, but they can be any arbitrary strings. While this is considered a best practice naming convention for transport listeners/senders there is absolutely no requirement to keep the protocol or port in the bean names. Further UltraESB can have more than one transport adapters for a given protocol, for example you can have 2 HTTP listeners running on port 8280 and 8290.
environment

The concept of an environment has been introduced to UltraESB from the 2.0.0 release onwards which basically is a single named configuration environment where certain features/optimizations be done based on the environment used. The environments and the set of available defined environments are discussed under the Configuration and Administration section of the documentation.

ultra-config

The bean identified by the key "ultra-config" is the bean which provides the main configuration into the UltraESB. It provides deployment units into the UltraESB and some other key configurations which we will be looking at in detail under the User Guide and Configuration and Administration sections of the documentation.

Deployment Units
The idea of having one or more Deployment Units defining the proxy services and the mediation is the ability to provide updates for the proxy services and mediation of a given deployment unit without any downtime. At a production deployment, user most of the time needs to update the above elements and not transports and so forth, which are treated as more static. So, extracting out the related dynamic element fragments into a separate deployment unit allows the ESB to update that deployment unit without affecting the other more static configurations, and most importantly with zero down time. For more information on this regard please refer to the Configuration and Administration.

The factory built UltraESB has only one deployment unit named "default", which is an expanded deployment unit resides in the conf/deployments/default directory of the ULTRA_HOME.

Deployment Unit Identification
Any directory resides in the conf/deployments directory of ULTRA_HOME is treated as an UltraESB deployment unit if that directory contains a file named "ultra-unit.xml" and that should have a spring configuration defining proxy services, endpoints and sequences.

1.2.2. Default Deployment Unit

This contains the more dynamic configuration elements such as proxy services, sequences, endpoints etc.. as pointed out earlier. The in-factory default deployment unit shipped should have a file named ultra-unit.xml which looks like follows;

Default Deployment Unit Configuraton

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:u="http://www.adroitlogic.org/ultraesb"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
http://www.adroitlogic.org/ultraesb http://schemas.ultraesb.org/ultraesb-2.0.xsd">

    <u:proxy id="echo-proxy">
        <u:transport id="http-8280"/>
        <u:target>
            <!--u:inSequence>
                <u:class name="sample.SimpleJavaMediation1"/>
            </u:inSequence-->
            <u:inDestination>
                <u:address>http://localhost:9000/service/EchoService</u:address>
            </u:inDestination>
            <u:outSequence>
                <u:java><![CDATA[
                    System.out.println("Reply payload : " + mediation.readPayloadAsString(msg));
                ]]></u:java>
            </u:outSequence>
            <u:outDestination>
                <u:address type="response"/>
            </u:outDestination>
        </u:target>
    </u:proxy>

    <u:proxy id="echo-back" pinnedServers="node1,localhost">
        <u:transport id="http-8280"/>
        <u:transport id="https-8443"/>
        <u:target errorSequence="error-handler">
            <u:inSequence>
                <u:java import="org.adroitlogic.ultraesb.api.transport.http.HttpConstants;"><![CDATA[
                        mediation.setPayloadFromString(msg,
                                "<response>" +
                                        "<method>" + mediation.getHTTPSupport().getMethod(msg) + "</method>" +
                                        "<uri>" + msg.getDestinationURL() + "</uri>" +
                                        "<query>" + mediation.getHTTPSupport().getQueryString(msg) + "</query>" +
                                        "<request>" + mediation.readPayloadAsString(msg) + "</request>" +
                                "</response>");
                        mediation.sendResponse(msg, 200);
                    ]]></u:java>
            </u:inSequence>
        </u:target>
    </u:proxy>

</beans>

This again is a spring configuration with a two custom bean configurations with proxy elements qualified with the UltraESB configuration namespace which is http://www.adroitlogic.org/ultraesb and the respective schema can be found at http://schemas.ultraesb.org/ultraesb-2.0.xsd

While the complete configuration and the schema discussion is available at the User Guide, a briefing of these proxy services are as follows.

echo-proxy

The first configuration element defines a proxy service with the name "echo-proxy", which is exposed on the transport identified by the key "http-8280", defined in the above described root configuration. This means that the proxy service is listening for messages on the port 8280 over the HTTP transport with the service URL being http://localhost:8280/service/echo-proxy.

That is about the external interface(s) of the proxy service. The internal mediation and destination configurations of the proxy service is defined in the target, encapsulated within the <u:target> element. This echo-proxy has the following configurations out of the following possible mediation/destination configurations.

  • in sequence - commented out, so not effective. The commented out in sequence how ever refers to a Java class type sequence.

  • in destination - refers to an external type address, http://localhost:9000/service/EchoService, meaning the message will be sent to the EchoService running on port 9000 after the specified incoming mediation.

  • out sequence - specified as a Java fragment type sequence, which prints the response from the EchoService back to the ESB, into the standard output.

  • out destination - specified as a response type address, meaning that the response from the EchoService is going to be sent back to the caller/client after the out going mediation.

Apart from that a proxy service can have meta-data configurations which we will discuss under the Configuration Guide of the proxy service.

The message flow described by this proxy service configuration can be visualize as follows;

drawing echo proxy flow2
echo-back

The second configuration element is also a proxy service and is identified by the key "echo-back". This is a special type of a proxy which belongs to the mock services category and the service exposed on the transports identified by the key "http-8280" and "https-8443", defined in the above described root configuration. It implies that this mock service is listening for messages on the port 8280 over the HTTP transport as well as on the port 8443 over the HTTPS transport, making it’s service URLs to be http://localhost:8280/service/echo-back and https://localhost:8443/service/echo-back.

The internal target of this echo-back proxy service contains only and in sequence and no destinations nor out sequence. The target in sequence is a Java fragment type sequence which takes over the message and handles it using the UltraESB Mediation API to provide the response back to the consumer.

The visualization of the echo-back proxy is as follows;

drawing echo back flow

That is the brief walk through of the default in-factory configuration of the UltraESB, and the next section will discuss how to Send a message through the UltraESB using the UltraESB tools.

1.3. Sending a Message through UltraESB

If you have followed the documentation in-order, you might have already started the UltraESB in the section on Running UltraESB, with the default configuration, in which case you can skip the "Start UltraESB" section. If not, you need to start the UltraESB to continue this section, which demonstrates how you can use the Adroitlogic SOA Toolbox to send a message through the UltraESB, running the default configuration described in the previous section.

SOA Toolbox
While this section introduces the SOA Toolbox it uses very few functions of the Toolbox to demonstrate the message flow through the UltraESB. For a complete reference on the SOA Toolbox please refer to the SOA Toolbox documentation.

1.3.1. Start UltraESB

To start the UltraESB with the default configuration, navigate to the bin directory of the ULTRA_HOME installation directory and fire the ultraesb.sh or the ultraesb.bat as appropriate, depending on your operating system.

On Linux based systems;

$ cd ULTRA_HOME/bin
$ ./ultraesb.sh

On Windows based systems, navigate to the bin directory of the ULTRA_HOME installation directory using a windows explorer and double click on the ultraesb.bat file

1.3.2. Introduction to SOA Toolbox

The SOA Toolbox provides many tools for running the UltraESB samples and some other general SOA utility tools. The SOA Toolbox chapter of the documentation will discuss the complete reference of the tools available in the SOA Toolbox, while this section will use the facility to start the sample back end server and will use the SOA client tools to send messages to the UltraESB.

SOA Toolbox shipped with UltraESB is a standalone Java swing application. To run the toolbox use the toolbox.sh or the toolbox.bat scripts as appropriate, depending on your operating system.

To start the toolbox on Linux based systems;

$ cd ULTRA_HOME/bin
$ ./toolbox.sh

On Windows based systems, use the windows explorer to navigate to the bin directory of the ULTRA_HOME installation directory and double click on the toolbox.bat file.

The toolbox should now be launched and you should see a Java swing application.

Running the sample EchoService

The echo-proxy as discussed in the previous sections forwards messages into a back-end service named EchoService running under the URL http://localhost:9000/service/EchoProxy. The SOA toolbox ha an easy option to start this sample service.

Click on the "File" menu and select New > Jetty Server from the cascading menu or alternatively the Ctrl+J shortcut key to create a new Jetty Server instance which hosts the sample services used by UltraESB.

toolbox jetty server menu

Now you should see the Jetty Server panel tab on the Toolbox application. Click on the "Start Jetty" button on the top of the pane just after the port as shown below by (1), to start the Jetty Server with the sample EchoService hosted on it;

toolbox jetty server pane scaled

You should see the Start Jetty button as a disabled button and the Stop Jetty button as an active button, once the sample Jetty server has completed starting. Once it is started, the EchoService on port 9000 having the service URL http://localhost:9000/service/EchoService should be ready.

Now you can invoke the echo-proxy, as the back-end sample server is up and running.

Sending a message to the UltraESB echo-proxy

Once again the SOA Toolbox can be used to send a message to the echo-proxy running at the service URL http://localhost:8280/service/echo-proxy.

Click on the "File" menu and select New > HTTP/S Client from the cascading menu or alternatively the Ctrl+C shortcut key to create a new HTTP/S client instance which can be used to post any HTTP/S message.

toolbox http client menu

Now you should see the HTTP/S Client panel tab on the Toolbox application. Using this client application we are going to invoke the echo-proxy deployed by the UltraESB default configuration. To invoke the echo proxy, follow the steps given below, and the respective action on the screen shot.

  1. Check the URL of the invoking service to be "http://localhost:8280/service/echo-proxy". The default value of the client application is the per said value and hence you do not need to edit it for this exercise.

  2. Check the HTTP method on the right side of the URL to be "POST" meaning that we are going to do a HTTP POST request to the given URL. Again you do not need to change this as the default value will be POST.

  3. Then select the HTTP message body to be sent to the service. There are 4 pre-sets available out of which we are going to use the first one, so click on the "1" pre-set message body.

  4. Observe the message body filled in with the pre-set message 1 on the request pane

  5. Click on the "Send" button in the middle of the request and response panes to invoke the echo-proxy service with the given message content.

toolbox http client pane

The send button click action sends a message to the echo-proxy and based on it’s configuration it forwards the request to the back-end sample EchoService and the response from that service gets forward to the client. Then you will see the response on the response pane as follows;

toolbox http client pane response

You have invoked the echo-proxy with the sample message which ran through the UltraESB to the back-end EchoService and the response delivered back to the client via UltraESB. The next section on the message execution flow shows you the facts to verify the execution flow and presents an analysis of it.

1.4. The Message Execution Flow

It is important that you understand and learn how to verify a mediation flow, whether it has been correctly executed. While UltraESB supports step through debugging of the mediation sequences, analyzing logs is far more easy and useful in verifying the flows in the development mode as well as in production deployments, provided that you have enabled logging.

Note
While it is not recommended to have logging enabled to print much information at production deployments, any ESB should support turning debug on dynamically to detect any suspicious activities or mis-behaviours of the flow. Further UltraESB is designed to run at INFO level logging at production.

1.4.1. External Analysis

Before going into analyzing the logs lets look at what we see from the clients perspective of this invocation. From the client side, we see it as the client sending the following HTTP POST request to the URL http://localhost:8280/service/echo-proxy with message body;

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.services.samples/">
   <soapenv:Body>
      <soap:getQuote>
         <request>
            <symbol>ADRT</symbol>
         </request>
      </soap:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

The HTTP response that is received by the client for this request is as follows;

HTTP/1.1 200 OK
port: 9000
Content-Type: text/xml; charset=utf-8
Date: Thu, 01 Aug 2013 06:56:19 GMT
Server: UltraESB/2.0.0 (GA)
Content-Length: 294
Connection: close

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.services.samples/">
   <soapenv:Body>
      <soap:getQuote>
         <request>
            <symbol>ADRT</symbol>
         </request>
      </soap:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

Now you can see that the response for this request came from UltraESB as the Server. HTTP header reflects it and also note that the exact same request that the client sent has been received by the client as the response.

Now if you look at the UltraESB command line console running the server, you can see the following printed on it.

Reply payload : <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.services.samples/">
   <soapenv:Body>
      <soap:getQuote>
         <request>
            <symbol>ADRT</symbol>
         </request>
      </soap:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

If you map this to the previously examined echo-proxy configuration, you will realize that this is the standard output print statement in the out sequence on the response path. That verifies the out sequence has been invoked. Another major verification from an external perspective to the UltraESB is monitoring the messages at the transport layer or in other words monitor the messages on the wire.

In this particular configuration, we are using the HTTP transport, meaning that we can use the TCP dump to verify the messages coming into and going out of the UltraESB from the client to the back end service. Normal TCP dump is a bit unreadable, but Adroitlogic SOA Toolbox addresses this issue as well and provides a readable TCP dump version apart from the raw dump. The following sub section shows, how to use the toolbox to verify the messages at the transport layer.

1.4.2. Using SOA Toolbox TCP dump

The TCP dump of the SOA Toolbox intercepts the message in the middle, so lets change the address of the in destination endpoint in the default configuration, to http://localhost:9001/service/EchoService, note the change in the port number from 9000 to 9001, and restart the UltraESB server for these changes to be effective.

Dynamic configuration provisioning and update
UltraESB supports dynamic deployment unit provisioning and update of a running server without requiring to restart. It actually has zero downtime configuration update support, which we will see in a later chapter under the Configuration and Administration. For this exercise we are restarting the server to activate the update to keep it simple for the quick start.

Once the UltraESB instance configuration update and restart is done, switch back to the Toolbox window and click on the "File" menu and select the New > TCP Dump from the cascading menu, to create a new TCP Dump instance.

toolbox tcpdump menu

Then you will get the TCP Dump pane and configure the TCP dump as follows;

  1. Check the "Listen Port" to be "9001" (this defaults to 9001, if you put some other port while updating the endpoint address put it as the listen port)

  2. Check the "Forward Host" to be "localhost" (this defaults to localhost)

  3. Check the "Forward Port" to be "9000" (this defaults to 9000, which is the actual port at which the back-end server is running)

  4. Change the radio button from "Hex" to "Text", by clicking on Text, as we want to see the messages on the wire in text format.

  5. Finally click on the "Start" button to start TCP Dump to listen on port 9001 and forward the message to the 9000 and vice-versa for the response.

toolbox tcp dump server

It is necessary to start the Jetty server on port 9000 via the tool box as explained in Sending a Message through UltraESB. Actually what happens  is that the message is forwarded to port 9001. The TCP Dump listening at 9001 will forward it to the back-end EchoService at port 9000. The following figure clearly depicts the scenario.

drawing intercepting

If you invoke the client once again (Switch to "HTTP/S Client" tab of the Toolbox and click on the "Send") you will now be able to see something like following;

toolbox tcp dump server trace

This shows the message went out from the UltraESB to the back-end server, in the upper box, and the response came into the UltraESB from the back-end server, in the lower box. This trace confirms that the message actually went into the back-end server running at http://localhost:9000/service/EchoService, and our second step in verification of the back-end service is complete.

While it has been proven that from an external point of view the UltraESB acts as expected with the above investigations, the internal operation is still not transparent for the user. Changing log level to DEBUG of the UltraESB loggers serves that apart from enabling debugging of the artifacts. In this guide we will look at how to use logging while artifact debugging will be covered in the Configuration and Administration.

1.4.3. Enabling logging at runtime

To get an idea of the internal message execution flow of the UltraESB, we can change the log level of its loggers to DEBUG, at runtime. While the user should selectively change log level for the specific loggers, for this exercise we will change the log level at the root logger of the UltraESB.

Debug logs and Artifact debugging
Changing log level to DEBUG from INFO gives you more and more information on what is happening inside the UltraESB on the console appender. While this is useful in pointing out issues, it is not recommended to have DEBUG logs enabled as that results in a considerable performance hit, on production deployments.

Even in case of an issue, you want to figure out the execution flow, changing log level to DEBUG has to be done selectively on the required loggers, but not on the root level. If the issue is specific to a particular artifact (configuration element, like proxy service or an endpoint) it is recommended to use the artifact debugging instead of changing the log level of the loggers. More information on this aspects will be discussed in the Configuration and Administration.

There are many options available to change the log level from INFO (which is the default log level) to DEBUG of the UltraESB, out of which straight forward way of doing this at runtime is via JMX management. We will be changing the log level of the root logger (root package name of the UltraESB) which is "org.adroitlogic.ultraesb".

JConsole (Java Management and Monitoring Console) will be used as the tool to invoke JMX management beans of the UltraESB. To open up JConsole, use the jconsole command from a command line console both in Linux and Windows operating systems.

$ jconsole

You will see a Java swing interface to connect to the UltraESB runtime. Use the "JConsole: New Connection" window to connect to the UltraESB runtime as follows;

  1. Select "Local Processes" radio button to connect to the locally running UltraESB instance

  2. Select the name "org.adroitlogic.ultraesb.UltraServer /opt/ultraesb-2.0.0/conf" from the local processes table.

  3. Click on the "Connect" button to connect to the runtime.

jconsole connect

Now you will see the UltraESB process JConsole pane, and open the "LoggerManagement" operations by;

  1. Select the "MBeans" tab to navigate the registered JMX management beans

  2. Expand the "org.adroitlogic.ultraesb" MBean group.

  3. Expand the "LoggerManagement" MBean view.

  4. Click on the "Operations" to open up the operation invocation pane of the LoggerManagement MBean.

jconsole logger operations pane

Now use the "changeLogLevel" operation to change the log level of the root logger to "DEBUG".

  1. Type "org.adroitlogic.ultraesb" for the p0 argument of the "changeLogLevel" method.

  2. Type "DEBUG" for the p1 argument of the "changeLogLevel" method.

  3. Click on the "changeLogLevel" button to invoke the operation.

jconsole invoke changeLogLevel

If the operation is successful you will see the following message box.

jconsole info message

This invocation changed the log level of the root logger to DEBUG, and now you should see the debug logs, on the command line console, if you invoke the client back again.

2013-08-01 15:22:47,962 [-] [L-I/O-dispatcher-2] DEBUG HttpNIOListener Connection open: http-incoming-2 Total connections : 1
2013-08-01 15:22:47,962 [-] [L-I/O-dispatcher-2] DEBUG LoggingNHttpServerConnection http-incoming-2: Consume input
2013-08-01 15:22:47,962 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> POST /service/echo-proxy HTTP/1.0
2013-08-01 15:22:47,962 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> Connection: close
2013-08-01 15:22:47,962 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> SOAPAction: urn:getQuote
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> Content-Length: 294
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> Content-Type: text/xml; charset=UTF-8
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> Host: localhost:8280
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 >> User-Agent: AdroitLogic (http://adroitlogic.org) - SOA Toolbox/1.5.0
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG UltraAsyncRequestConsumer handle() http request received
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG MessageImpl Created message with UUID : 3a13e5f3-961e-4a6f-aac5-0b42faced882
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG fileCache Served a file from cache : pooled_2.tmp total cache size : 200 available pool size : 199 peak usage : 2
2013-08-01 15:22:47,963 [-] [L-I/O-dispatcher-2] DEBUG UltraAsyncRequestConsumer =⇒ begin request entity receive to : tmp/ruwan_localhost/pooled_2.tmp
2013-08-01 15:22:47,964 [-] [L-I/O-dispatcher-2] DEBUG UltraAsyncRequestConsumer =⇒ contentAvailable() :: transferred : 294 to : tmp/ruwan_localhost/pooled_2.tmp
2013-08-01 15:22:47,964 [-] [L-I/O-dispatcher-2] DEBUG UltraAsyncRequestConsumer =⇒ end request entity size : 294 for : tmp/ruwan_localhost/pooled_2.tmp
2013-08-01 15:22:47,964 [-] [L-I/O-dispatcher-2] DEBUG UltraHttpAsyncRequestHandler handle() http request receipt has completed
2013-08-01 15:22:47,964 [-] [primary-3] DEBUG echo-proxy Proxy service : echo-proxy processing message with destination : /service/echo-proxy and UUID : 3a13e5f3-961e-4a6f-aac5-0b42faced882
2013-08-01 15:22:47,965 [-] [primary-3] DEBUG HttpNIOSender Preparing to send message : 3a13e5f3-961e-4a6f-aac5-0b42faced882 to : http://localhost:9000/service/EchoService
2013-08-01 15:22:47,965 [-] [primary-3] DEBUG HttpNIOSender Requesting the sending of message : 3a13e5f3-961e-4a6f-aac5-0b42faced882
2013-08-01 15:22:47,965 [-] [primary-3] DEBUG UltraNIOConnPool Request for connection to : http://localhost:9000 Stats : [leased: 0; pending: 0; available: 1; max: 2048]
2013-08-01 15:22:47,966 [-] [primary-3] DEBUG InternalKeepaliveStats Increment requested : 2
2013-08-01 15:22:47,966 [-] [primary-3] DEBUG LoggingNHttpClientConnection http-outgoing-1: Close connection
2013-08-01 15:22:47,966 [-] [primary-3] DEBUG InternalKeepaliveStats Increment created : 2
2013-08-01 15:22:47,966 [-] [primary-3] DEBUG UltraNIOConnPool Received a pool entry
2013-08-01 15:22:47,966 [-] [primary-3] DEBUG HttpNIOSender Submitted request to send message : 3a13e5f3-961e-4a6f-aac5-0b42faced882
2013-08-01 15:22:47,967 [-] [primary-3] DEBUG echo-proxy-inDestination Transport sender : http-sender result is : PENDING
2013-08-01 15:22:47,967 [-] [S-I/O-dispatcher-2] DEBUG UltraNIOConnPool Connect request completed : localhost/127.0.0.1:9000
2013-08-01 15:22:47,968 [-] [S-I/O-dispatcher-2] DEBUG UltraHttpAsyncRequestExecutor Connection open: http-outgoing-2
2013-08-01 15:22:47,968 [-] [S-I/O-dispatcher-2] DEBUG LoggingNHttpClientConnection http-outgoing-2: POST /service/EchoService HTTP/1.1
2013-08-01 15:22:47,969 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> POST /service/EchoService HTTP/1.1
2013-08-01 15:22:47,969 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> SOAPAction: urn:getQuote
2013-08-01 15:22:47,969 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> X-Forwarded-For: 127.0.0.1
2013-08-01 15:22:47,969 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> Content-Type: text/xml; charset=UTF-8
2013-08-01 15:22:47,969 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> Content-Length: 294
2013-08-01 15:22:47,970 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> Host: localhost:9000
2013-08-01 15:22:47,970 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> Connection: Keep-Alive
2013-08-01 15:22:47,970 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> User-Agent: UltraESB/2.0.0-SNAPSHOT (GA)
2013-08-01 15:22:47,970 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 >> Accept-Encoding: gzip
2013-08-01 15:22:47,970 [-] [primary-3] DEBUG MessageImpl Message ID : 3a13e5f3-961e-4a6f-aac5-0b42faced882 has completed processing under : echo-proxy Pending completion by : [\{echo-proxy-inDestination=405425933986884}]
2013-08-01 15:22:47,971 [-] [S-I/O-dispatcher-2] DEBUG LoggingNHttpClientConnection http-outgoing-2: Produce output
2013-08-01 15:22:47,971 [-] [primary-3] DEBUG echo-proxy Processing of message completed for proxy service : echo-proxy in state : Started current execution count : 0 current polling count : 0
2013-08-01 15:22:47,975 [-] [S-I/O-dispatcher-2] DEBUG LoggingNHttpClientConnection http-outgoing-2: Consume input
2013-08-01 15:22:47,975 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 << HTTP/1.1 200 OK
2013-08-01 15:22:47,975 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 << Content-Type: text/xml; charset=utf-8
2013-08-01 15:22:47,976 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 << port: 9000
2013-08-01 15:22:47,976 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 << Content-Length: 294
2013-08-01 15:22:47,976 [-] [S-I/O-dispatcher-2] DEBUG headers http-outgoing-2 << Server: Jetty(6.1.21)
2013-08-01 15:22:47,978 [-] [S-I/O-dispatcher-2] DEBUG fileCache Served a file from cache : pooled_3.tmp total cache size : 200 available pool size : 198 peak usage : 2
2013-08-01 15:22:47,978 [-] [S-I/O-dispatcher-2] DEBUG UltraAsyncResponseConsumer =⇒ begin response entity receive : tmp/ruwan_localhost/pooled_3.tmp
2013-08-01 15:22:47,978 [-] [S-I/O-dispatcher-2] DEBUG UltraAsyncResponseConsumer =⇒ contentAvailable() :: transferred : 294 to : tmp/ruwan_localhost/pooled_3.tmp
2013-08-01 15:22:47,978 [-] [S-I/O-dispatcher-2] DEBUG UltraAsyncResponseConsumer =⇒ end response entity : tmp/ruwan_localhost/pooled_3.tmp of size : 294
2013-08-01 15:22:47,979 [-] [S-I/O-dispatcher-2] DEBUG UltraConnectionReuseStrategy Connection kept alive : http-outgoing-2
2013-08-01 15:22:47,979 [-] [S-I/O-dispatcher-2] DEBUG UltraAsyncResponseConsumer Response completely received over connection : http-outgoing-2
2013-08-01 15:22:47,979 [-] [S-I/O-dispatcher-2] DEBUG MessageImpl Created response message with UUID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc
2013-08-01 15:22:47,979 [-] [S-I/O-dispatcher-2] DEBUG MessageImpl Message ID : 3a13e5f3-961e-4a6f-aac5-0b42faced882 has completed processing under : echo-proxy-inDestination Pending completion by : [\{}]
2013-08-01 15:22:47,980 [-] [S-I/O-dispatcher-2] DEBUG MessageImpl Releasing resources of message 3a13e5f3-961e-4a6f-aac5-0b42faced882
2013-08-01 15:22:47,980 [-] [S-I/O-dispatcher-2] DEBUG SimpleQueueWorkManager Message ID : 3a13e5f3-961e-4a6f-aac5-0b42faced882 has completed processing and is removed from the WIP map
2013-08-01 15:22:47,980 [-] [S-I/O-dispatcher-2] DEBUG fileCache Returned file for re-use : pooled_2.tmp pool size : 199
2013-08-01 15:22:47,980 [-] [S-I/O-dispatcher-2] DEBUG MessageImpl Message ID : 3a13e5f3-961e-4a6f-aac5-0b42faced882 has completed all processing
2013-08-01 15:22:47,981 [-] [S-I/O-dispatcher-2] DEBUG UltraNIOConnPool Socket : http-outgoing-2 can be kept alive for : 30000 ms as per HTTP/S sender configuration (or default)
2013-08-01 15:22:47,985 [-] [S-I/O-dispatcher-2] DEBUG UltraNIOConnPool Connection : http-outgoing-2 is reusable, and will be kept alive for : 25000 millis
2013-08-01 15:22:47,985 [-] [S-I/O-dispatcher-2] DEBUG SendActionCallback Completed
2013-08-01 15:22:47,985 [-] [primary-4] DEBUG echo-proxy Proxy service : echo-proxy processing message with destination : null and UUID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc
2013-08-01 15:22:47,985 [-] [primary-4] DEBUG echo-proxy-outSequence Executing sequence : echo-proxy-outSequence
Reply payload : <soapenv:Envelope link:[xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/]" link:[xmlns:soap="http://soap.services.samples/]">
   <soapenv:Body>
      <soap:getQuote>
         <request>
            <symbol>ADRT</symbol>
         </request>
      </http://soapgetQuote[soap:getQuote]>
   </soapenv:Body>
</soapenv:Envelope>
2013-08-01 15:22:47,986 [-] [primary-4] DEBUG MessageImpl Message ID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc has completed processing under : echo-proxy-outSequence Pending completion by : [\{echo-proxy=405425954733719}]
2013-08-01 15:22:47,986 [-] [primary-4] DEBUG echo-proxy-outSequence Finished executing sequence : echo-proxy-outSequence
2013-08-01 15:22:47,986 [-] [primary-4] DEBUG HttpResponseTrigger Submitting asynchronous response over connection : http-incoming-2
2013-08-01 15:22:47,987 [-] [primary-4] DEBUG MessageImpl Message ID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc has completed processing under : echo-proxy Pending completion by : [\{echo-proxy-outDestination=405425955525453}]
2013-08-01 15:22:47,987 [-] [L-I/O-dispatcher-2] DEBUG LoggingNHttpServerConnection http-incoming-2: Produce output
2013-08-01 15:22:47,987 [-] [primary-4] DEBUG echo-proxy Processing of message completed for proxy service : echo-proxy in state : Started current execution count : 0 current polling count : 0
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG LoggingNHttpServerConnection http-incoming-2: HTTP/1.1 200 OK
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << HTTP/1.1 200 OK
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << port: 9000
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << Content-Type: text/xml; charset=utf-8
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << Date: Thu, 01 Aug 2013 09:52:47 GMT
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << Server: UltraESB/2.0.0-SNAPSHOT (GA)
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << Content-Length: 294
2013-08-01 15:22:47,989 [-] [L-I/O-dispatcher-2] DEBUG headers http-incoming-2 << Connection: close
2013-08-01 15:22:47,990 [-] [L-I/O-dispatcher-2] DEBUG LoggingNHttpServerConnection http-incoming-2: Produce output
2013-08-01 15:22:47,990 [-] [L-I/O-dispatcher-2] DEBUG UltraAsyncResponseProducer responseCompleted()
2013-08-01 15:22:47,996 [-] [L-I/O-dispatcher-2] DEBUG MessageImpl Message ID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc has completed processing under : echo-proxy-outDestination Pending completion by : [\{}]
2013-08-01 15:22:47,996 [-] [L-I/O-dispatcher-2] DEBUG MessageImpl Releasing resources of message 2a15d30d-9880-4871-9a9e-8966cc8e65dc
2013-08-01 15:22:47,996 [-] [L-I/O-dispatcher-2] DEBUG SimpleQueueWorkManager Message ID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc has completed processing and is removed from the WIP map
2013-08-01 15:22:47,999 [-] [L-I/O-dispatcher-2] DEBUG fileCache Returned file for re-use : pooled_3.tmp pool size : 200
2013-08-01 15:22:47,999 [-] [L-I/O-dispatcher-2] DEBUG MessageImpl Message ID : 2a15d30d-9880-4871-9a9e-8966cc8e65dc has completed all processing
2013-08-01 15:22:47,999 [-] [L-I/O-dispatcher-2] DEBUG LoggingNHttpServerConnection http-incoming-2: Close connection
2013-08-01 15:22:48,000 [-] [L-I/O-dispatcher-2] DEBUG HttpNIOListener Connection closed: http-incoming-2

The above log gives you the information about the message starting from the transport receiving the connection from the client to, closing the connection to the client after delivering the response back. This log is very useful in pointing any issues if there are any in your execution flow.

Next section introduces UConsole and UTerm, the management interfaces available in managing/monitoring the UltraESB apart from the raw JMX (JConsole) View.

1.5. Introducing UConsole and UTerm

UltraESB has a lot of built in management and monitoring capabilities, for the user to select on there preference. All these options however goes via the raw Java Management Extension (JMX) interface. In other words the complete management and monitoring aspect of UltraESB is exposed only via JMX, while it has many mechanisms to connect to this interface. Those mechanisms are as follows;

  1. JMX management tool like JConsole

  2. UConsole

  3. UTerm

  4. Zabbix monitoring

  5. Invoking JSON/REST administration services.

While the use of JConsole to manage the UltraESB runtime has been briefly illustrated in the previous section, this section introduces the UConsole and Uterm. The Zabbix monitoring and JSON/REST service layer will be discussed under the Configuration and Administration and the JSON Management Service reference guide, respectively.

UConsole and Uterm - Brief Introduction
While this section very briefly introduces the users into the UConsole and UTerm, a descriptive introduction and a reference guide is available under the respective documentation on Ultra Console and Ultra Terminal.

1.5.1. Ultra Console (UConsole)

UConsole is the web based management console of the UltraESB, which is shipped in with the standard binary distribution. This sub section introduces the UConsole and it shows the usage of UConsole to manage the UltraESB instance.

Starting the UConsole is just a matter of running the uconsole script found in the bin directory of the ULTRA_HOME installation directory.

On Linux systems navigate to the "bin" directory of the installation home and execute the "uconsole.sh" script to start the UConsole.

$ cd $ULTRA_HOME/bin
$ ./uconsole.sh

On Windows based systems, navigate to the "bin" directory with the windows explorer and double click on the "uconsole.bat".Upon executing the UConsole start-up script you will be able to see the following log on the command line console.

Starting the Adroitlogic UltraESB Console
2013-08-01 15:29:45,368 [-] [main]  INFO log Logging to org.slf4j.impl.Log4jLoggerAdapter(org.mortbay.log) via org.mortbay.log.Slf4jLog
2013-08-01 15:29:45,671 [-] [main]  INFO log jetty-6.1.21
2013-08-01 15:29:45,786 [-] [main]  INFO log NO JSP Support for /uconsole, did not find org.apache.jasper.servlet.JspServlet
2013-08-01 15:29:49,306 [-] [main]  INFO log Started SslSocketConnector@http://localhost:8043[localhost:8043]
2013-08-01 15:29:49,307 [-] [main]  INFO ConsoleJettyServer UltraESB management console is running at https://localhost:8043/uconsole

As the log statement on the above log says, you can point your favourite web browser to the URL https://localhost:8043/uconsole to access the UConcole. You will get to the login page and the following steps will log you into the UConsole.

  1. Select the "Local instance" radio button and check to see whether the drop down has something like "localhost (XXXX)" selected.

  2. Type-in the default administrator username, "admin" in the Username field.

  3. Type-in the default administrator password, "admin" in the Password field.

  4. Click on the "Sign In" button to login to the UConsole

login

Upon logging in you will be directed to the "Dashboard" page of the UConsole, where you can see few gadgets with information on the UltraESB runtime. On the left navigation menu, you can find the management of nodes, clusters and monitoring top level menu structure with the sub menu items within them for managing and monitoring the UltraESB instance or a cluster.

As our focus for this exercise is on the echo-proxy service, lets navigate to the proxy services page with following instructions.

  1. Click on the "Node Management" top level menu to expand it.

  2. Click on the "Proxy Services" sub menu item.

uconsole menu

When you click on the "Proxy Services" the console content pane will give a list of available proxy services, in a tabular format, as follows;

proxy services

Now, if you click on the ID column link of any proxy service, you will be directed to the service information page. In the same manner, you can navigate to the sequences and endpoint destination pages with the available links on the relevant columns. Finally you can see the set of controls available on the right most column, where these controls change with the state of the proxy service. Since both these proxy services are in Started state, you can Stop or Enable Debug for those proxy services.

Click on the stop icon of the echo-proxy to stop the proxy service. Upon invoking this action you will see the following confirmation box and click OK to confirm that you want to stop the proxy service.

stop confirmation proxy

Once the action is confirmed, it will be invoked and you will see an information box stating whether the stop action was successful or not. Click on the OK button of the information box, and you will be able to see that the state of the proxy service getting changed from Started to Stopped, and the controls changes accordingly as follows;

proxy stop

You may send a message to the echo-proxy proxy service with the SOA Toolbox as described in the previous section on Sending a Message through UltraESB to verify the proxy service has stopped.

UConsole is capable of offering all the management and monitoring requirements for the UltraESB individual instances as well as clusters and this section just introduced you to the usage of the UConsole, please follow the Ultra Console documentation on a complete guide to working with UConsole.

1.5.2. Ultra Terminal (UTerm)

UTerm is the command line management client of the UltraESB, which is shipped in with the standard binary distribution. This sub section introduces the UTerm and it shows the usage of UTerm to manage the UltraESB.

Starting the UTerm is just a matter of running the uterm script found in the bin directory of the ULTRA_HOME installation directory.

On Linux systems navigate to the "bin" directory of the installation home and execute the "uterm.sh" script to start the UTerm.

$ cd $ULTRA_HOME/bin
$ ./uterm.sh

Upon executing the above script the uterm prompt displays on the command line as follows;

$ sh bin/uterm.sh

Welcome to the UltraESB UTerm (interactive mode)
'Type 'help' for the list of commands`
uterm>

With this UTerm has entered into the interactive mode of operation, and provided that the UltraESB instance is running locally you can now interact with the UltraESB instance.

Note
While this introduction uses the "Interactive mode" the UTerm is available in "Scriptable standalone mode" too, which will be useful in automated management with scripts. Further, if you want to manage a remote UltraESB instance you can use the "connect" command or the –server option to specify the connecting UltraESB instance. Follow the complete UTerm manual for more information on advance UTerm usages.

With the UTerm you can use the list proxy services (psl) command to list all the available proxy services of the connected (in this case locally running) UltraESB instance.

uterm> psl
echo-back
health-check
uterm>

Here, you will only see the "echo-back" proxy service, as the "echo-proxy" proxy service is stopped with the previous UConsole action.

List proxy services command defaults
List proxy services (psl) command by default lists the proxy services in the "Started" state. In order to list all proxy services use the "-a" option

So lets use the "-a" option to list all the proxy services.

uterm> psl -a
echo"-back
health-check
echo"-proxy
uterm>

Now we want to see which proxy services are started and running, and which are not. So lets include another option "-s" to print the state of each and every proxy service, while listing.

uterm> psl -as
echo"-back     Started
health-check  Started
echo"-proxy    Stopped
uterm>

Here you can see the echo-proxy is stopped and the echo-back is started. To get the complete information listing, as in the UConsole table, use the "-i" option instead of "-s".

uterm> psl -i
echo-back     Started  echo-back-inSequence     --                        --                      --                         false
health-check  Started  health-check-inSequence  --                        --                      --                         false
echo-proxy    Started  --                       echo-proxy-inDestination  echo-proxy-outSequence  echo-proxy-outDestination  false
uterm>

To start the proxy service "echo-proxy" that is being stopped with the UConsole the start proxy service (strps) command can be used.

uterm> psstr echo-proxy
Started proxy service echo-proxy
uterm>

Now if you list the services with there states you will be able to see that the "echo-proxy" is in started state.

uterm> psl -as
echo-back     Started
health-check  Started
echo-proxy    Started
uterm>

You may verify that the proxy service is running by sending a message to the proxy service with the SOA Toolbox as described in the previous section on Sending a Message through UltraESB.

Capabilities of UTerm are much more than what has been discussed in this introduction and it is used to manage a complete cluster gracefully with just one command and so forth. Please follow the Ultra Terminal documentation for all the commands and options available with UTerm.

Back to Home Page