1. UltraESB Tooling

This section discusses the tooling available to facilitate the development, testing, deployment and monitoring of UltraESB.

1.1. Ultra Console

The UConsole executes as an independent Web Application, and allows the easy management of an UltraESB instance or Cluster of nodes. The UConsole maybe hosted in a data center, or started on-demand, even at a remote node (e.g. developer workstation) away from the UltraESB instances. It connects to the UltraESB nodes via JMX, and where its executed separately from the UltraESB instances, remote JMX must be enabled at the ESB nodes.

1.1.1. Server Management

The 'Server Manager' tab of the UConsole allows one to manage a single UltraESB node connected to via the UConsole. The 'Server Operations' tab shows the current state of the instance, and allows a node to be restarted, stopped (but do not exit JVM to allow a subsequent re-start), shutdown (stop and exit JVM), put into a maintenance mode (where new requests will be rejected, but already accepted messages processed) or shutdown gracefully (waiting for a specified time until an idle state is reached).

server operations

The 'Server Configurations' tab allows the user to load, unload or re-load a dynamic configuration fragment (e.g. conf/ultra-dynamic.xml). By default, the UltraESB configuration fragments found in the conf directory of the instance is shown, along with its current state and controls for management. A dynamic configuration update is performed atomically to ensure that a message flow does not see different versions of the configuration. Hence, after a configuration is unloaded, its retained in memory until the administrator explicitly purges such configurations after some time. Usually such outdated configurations consumes only a very small amount of RAM, and a purge is not required at all for almost all UltraESB production deployments.

server configurations

1.1.2. Proxy Service Management

The UConsole provides a graphical interface to view details and manage proxy services defined in the server.

Listing proxy services

This page shows a list of proxy services defined in the server with basic information such as proxy ID, sequences available if exists, the state (Started/Stopped), Access URL. Also starting/ stopping of proxy service , enabling/ disabling debug functions are supported under Control column. 

Selection 056
Proxy Service Details

To view details of a proxy service go through the link for proxy ID in proxy services list view. 

Proxy Service Configuration

Proxy service Configuration can be viewed in the Proxy Service Configuration tab under Proxy Service Details.

Selection 057
  1. Control Proxy Service - Allows to Start/Stop proxy service and Enable/Disable Debug 

  2. Access URLs

  3. Proxy Configuration - Includes configuration details such as Proxy ID, In-Sequence, In-Destination, Error Sequence, state(started/stopped), Debug(Enabled/Disabled).
    Links in list view to sequences can be used to view details about the sequences.

  4. Deployed Transports - One or more transports defined which proxy service expects to receive messages

1.1.3. Sequence Management

Enter the sequence management view

First click on the 'Node Management' link in the left navigation menu, and then click on the 'Sequences' link to view all defined sequences in the UltraESB instance.

got to sequences

The table displays primary information about each sequence. The info column show the type of the sequence and file used by the sequence (if the sequence uses an external file for mediation). The proxy column show the proxy service to which, the sequence belongs to. The state column shows the state of the sequence, if it is 'started' or 'stopped'.

Actions on sequences

Actions can be executed on the sequence either from the control column of the sequence table or by entering the management view of the sequence.

actions

The management view of a sequence is shown in the following image

management view
Start sequence

The start button for a sequence will appear in the control panel only if the the sequence is stopped.

start 1

In the management view the start button is always shown. A warning message would be shown, if it is attempted to start an already started sequence.

already started

On a successful start of the sequence a success message will be shown

success start
Stop sequence

The stop button for a sequence will appear in the control panel only if the the sequence is started.

stop 1

In the management view the stop button is always shown. A warning message would be shown, if it is attempted to stop an already stopped sequence.

already stopped

A confirmation message will be shown before stopping a sequence.

confirm stop

A success message will be shown if the sequence was stopped without errors

success stop
Enable debug for sequence

The enable debug (red lady bird) button for a sequence will appear in the control panel only if debugging is disabled for the sequence.

debug enable

In the management view the enable debug button is always shown. A warning message would be shown, if it is attempted to enable debug on already debug enabled sequence.

debug20already enable

A success message will be shown if debug is enabled successfully on the sequence

debug enable success
Disable debug for sequence

The disable debug (grey lady bird) button for a sequence will appear in the control panel only if debugging is enabled for the sequence.

debug disable

In the management view the disable debug button is always shown. A warning message would be shown, if it is attempted to disable debug on already debug disabled sequence.

debug20 already disable

A success message will be shown if the sequence was stopped without errors

debug disable success
Edit sequence

If the sequence is stopped, it is possible to start editing right away on the wisywig editor in the management view. If the sequence is started click on the edit button in the management view to start editing the sequence. A started sequence should be stopped prior to editing. A confirmation message will be shown whether to stop the sequence for editing or to discontinue editing.

confirm stop for editing

If clicked on 'Ok', the sequence will be stopped and the wysywig editor will become writable.

seq edit

After applying the changes, decide whether to reset all the statistics of this sequence. A statistic reset would clear all the history related with the sequence. Finally click on the save button to save the changes. Again a confirmation message will be displayed whether to start the sequence with the saved changes.

start confirm after editing

If clicked "Ok" the sequence will be started with the applied change, otherwise the changes will be saved and will be applied if the the sequence is manually started later.

Reset sequence statistics

Sequence statistics can bet reset by clicking on the rest button in the control column or the edit button in the management view. This action will clear the entire statistical history of the sequence.

reset stat

A success message will be shown upon a successful statistics reset of sequence

success reset stat

1.1.4. Endpoint Management

Overview

Endpoint management is an important feature in Ultra Console as it provide you the facility to view different endpoints associated with an ESB node and perform operations in order to control the behavior of it. To get this select 'Endpoints' under 'Node Management' as shown by (1) in the image below.

Selection 079

Then all the endpoints of the node are are listed in a table. This table has advanced options such as searching, limiting the maximum number of endpoints in the table at a time and view other endpoints when there is a large number of endpoints. First two columns of this table show the name and type of the endpoint. If you are not familiar with endpoint types you can find it from the documentation of the endpoints here. 'Addresses Active' is the number of addresses that have been associated with an endpoint. This value is 1 for an endpoint of type 'single' and higher value for other types (Ex: round-robin). 'Addresses Ready' is the number of addresses that are ready to respond. If one or more addresses are suspended in an endpoint, then you can view that count by next column. 'Messages Failed' shows the number of messages that failed in this particular endpoint. State shows whether this endpoint is started or stopped. Then you can perform different actions on an endpoint by the options available under 'Control'. There you have the following options.

  • If the state of the endpoint is started the you can stop it and vise versa.

  • Enable or disable log level of the endpoint to DEBUG.

  • Edit endpoint.

Edit endpoint

If you need to change the configuration of the selected endpoint you press edit button and then you will get a window similar to the following.

merged 2

As you can see above you have a set of controls at the beginning. These can be used to control the endpoint and some of them have been already introduced except the last one which is for resetting statistics of this endpoint which is discussed in the next section. Next you can view all the parameters of the endpoint with the values. You can edit the values for all the parameters except Endpoint Name and Type. In addition you can specify whether statistics of this endpoint is reset or not when the new values are saved. Finally you can view and add addresses for this endpoint.

Endpoint Addresses

The table at the bottom of Endpoint Details shows you the addresses that are associated with the selected endpoint and you can add more addresses if the type is not single. In case of type is single you have to first change and save it and then add new addresses. In order to get a detailed view of an address, select the address ID from the first column and then you will get a window as shown below.

Selection 085

Here you can start, stop, edit or remove the address or reset statistics associated with the address and for this you can use buttons available at the top of the page. Then you can view the details of the address. Endpoint shows the name of the endpoint to which this address belongs to and you are not allowed to modify this. Address type is a value of a predefined set of types which an endpoint address can be and you are allowed to change this type. You can find more details about address type here. State shows whether this address is active or stopped and you can change this state by the Start and Stop buttons mentioned above. And the value is the address’s to which request or response is sent and you can change this value dynamically.

1.1.5. File Cache

Overview

File cache provide you the information regarding the files created by the ESB to avoid garbage collection overhead due to creation of message files in the heap memory. This is a new concept introduced in UltraESB and you can find more information about it here. The cache files created by the UltraESB can be monitored via Ultra Console and for this select 'File Cache' under 'Node Management'. Then you will get the list of file caches available as shown below. 

Selection 098

This shows you the available file caches together with the total number of files created by them and available file count. Peak usage is the the maximum number of files of the cache that were used concurrently.

File Cache Details

If you need to view more details about any particular file cache, select the file cache ID from the table and then you will get a detailed view as following.

Selection 099

This consists of two main sections which are File Cache Configuration and File Cache Statistics. File Cache Configuration you can view the via

  1. ID - unique ID of the file cache according to the configuration in ultra-root.xml

  2. Status - This indicates whether this cache is started or stopped.

  3. Cache path - Absolute path of the cache directory  

  4. Warn threshold - Maximum number of files that are created without warning

  5. Stop threshold - Maximum number of files that are created. If the file count exceeds this limit, then the file cache terminates.

1.1.6. Work Managers

UConsole allows to list available Work Managers , control and update them and view details,statistics about each of them.

Listing Work Managers
Selection 075
Work Manager Details

To view details about a particular work manager go through the link in work manager Name in list view.

wcSelection 079

In the WorkManager Configuration tab conrols action provided to manage work manager are,

  1. Start - To start work manager

  2. Stop - To stop work manager

  3. Edit - Edit Work Manager configurations.

Work Manager Configuration
Work Manager Configuration details
Selection 080
  1. Work Manager Name -

  2. Status - Started / Stopped

Thread Pool Configuration details
Selection 082
  1. Primary Core Threads - Number of core threads in primary thread pool.

  2. Primary Max Threads - Maximum thread limit in primary thread pool

  3. Primary Keep alive Seconds - Thread keepalive time for primary thread pool.

  4. Primary Queue Size - Queue Size for primary thread pool

  5. Secondary Core Threads - Number of core threads in secondary thread pool.

  6. Secondary Max Threads - Maximum thread limit in secondary thread pool

  7. Secondary Keep alive Seconds - Thread keepalive time for secondary thread pool where excess threads will be terminated if they have been idle for more than the keepAliveTime

  8. Secondary Queue Size - Queue Size for secondary thread pool

1.1.7. Transport Listeners

UConsole allows to list available transports and view detailed statistics of each of them.

Listing Transport Listeners

This page shows a list of all the transport listeners configured for receiving messages. Proxy services are exposed on these transports. 

Selection 058
  1. ID - Transport identifier,  the spring bean identifier of the transport listener.

  2. State - Started/Stopped

  3. Received - Received data size in bytes, number of successful receives, number of failed receives.

  4. Sent - Total sent data size, number of successful sends, number of failed sends.

  5. Controls

Transport Listener Details

To view details about a particular transport listener go through the link in transport listener ID in list view.

Selection 061

Through this view you can control the transport. Control actions allowed are,

  1. Start - Start transport listener

  2. Stop - Stop transport listener

  3. Pause - Stops receiving new messages or establishing new connections and will respond to already established connections.

  4. Resume - Enable receiving messages again.

  5. Debug On - Enable debug which changes the the logger level.

  6. Debug Off - Disable debug which changes the the logger level.

  7. Maintenance Shutdown -  To stop transport listenerfor maintenance purposes. When you do a maintenance shut down, the transport will stop receiving new messages or establishing new connections and waits until finished responding and closed connections of already established connections. The delay time which you can specify in milliseconds allows you to specify a maximum time of waiting until all the connections are closed. After the delay time transport will shut down regardless of connections are closed or opened.

    Selection 059
  8. Reset Statistics - To reset all the statistics to zero. After resetting statistics information successfully the following information message will be shown .

Selection 060
Listener Configuration

Configuration details of the transport listener such as Transport ID, State, Time of statistics last reset, Metrics window are shown.

Selection 076
Transport Listener Metrics Dashboard

Received and sent bytes

Selection 067

Messages received and sent

Selection 068

Receiving and sending faults

Selection 069
Error Code

This table shows informations about errors codes used during transmission

Selection 072
  1. Type -

  2. Error Code
    Following is the list of error codes available.

    Error Code Description

    101000

    I/O error sending response to client

    101001

    I/O error receiving request from client

    101002

    HTTP protocol violation receiving request from client

    101003

    Read timeout receiving request from client

    101005

    Connection closed receiving request from client

    101006

    Connection closed sending response to client

    101500

    I/O error sending request to server

    101501

    I/O error receiving response from server

    101503

    Connect attempt to server failed

    101504

    Read timeout receiving response from server

    101505

    Connection closed receiving response from server

    101506

    HTTP protocol violation receiving response from server

    101507

    Connect attempt to server canceled

    101508

    Connect attempt to server timedout

    101510

    Response received from server temporarily rejected by validator

    101511

    Response received from server permanently rejected by validator

    101512

    connection [socket] timeout submitting the request to a remote party

  3. Error Count - Number of times this error occurred.

Keep Alive Stats

This table shows the statistics about keepAlive connections established with external servers.

Selection 073
  1. Server - Server URL with which the keepAlive connection is established. 

  2. Requested - Number of times requested

  3. Reused - Number of keepalive retransmissions done by reusing established connection.

  4. Forgot - Number of keepalive connections dropped.

  5. Open - Number of keepAlive connections opened with server

1.1.8. Transport Senders

UConsole allows to list available transport senders and view detailed statistics of each of them.

Listing Transport senders

This page shows a list of all the transport senders configured for sending messages. 

Selection 070
  1. ID - Transport identifier,  the spring bean identifier of the transport sender.

  2. State - Started/Stopped

  3. Received - Received data size in bytes, number of successful receives, number of failed receives.

  4. Sent - Total sent data size, number of successful sends, number of failed sends.

  5. Controls 

Transport Sender Details

To view details about a particular transport sender go through the link in transport sender ID in list view.

Selection 071

Through this view you can control the transport. Control actions allowed are,

  1. Start - transport sender

  2. Stop - transport sender

  3. Pause - Stops receiving new messages or establishing new connections and will respond to already established connections.

  4. Resume - Enable receiving messages again.

  5. Debug On - Enable debug which changes the the logger level.

  6. Debug Off - Disable debug which changes the the logger level.

  7. Maintenance Shutdown - To stop transport listenerfor maintenance purposes. When you do a maintenance shut down, the transport will stop receiving new messages or establishing new connections and waits until finished responding and closed connections of already established connections. The delay time which you can specify in milliseconds allows you to specify a maximum time of waiting until all the connections are closed. After the delay time transport will shut down regardless of connections are closed or opened.

    tsSelection 059
  8. Reset Statistics - To reset all the statistics to zero. After resetting statistics information successfully the following information message will be shown .

    tsSelection 060
Sender Configuration

Configuration details of the transport listener such as Transport ID, State, Time of statistics last reset, Metrics window are shown.

Selection 078
Transport Sender Metrics Dashboard

Received and sent bytes

Messages received and sent

Receiving and sending faults

Error Code

This table shows informations about errors codes used during transmission

tsSelection 072
  1. Type -

  2. Error Code
    Following is the list of error codes available.

    Error Code Description

    101000

    I/O error sending response to client

    101001

    I/O error receiving request from client

    101002

    HTTP protocol violation receiving request from client

    101003

    Read timeout receiving request from client

    101005

    Connection closed receiving request from client

    101006

    Connection closed sending response to client

    101500

    I/O error sending request to server

    101501

    I/O error receiving response from server

    101503

    Connect attempt to server failed

    101504

    Read timeout receiving response from server

    101505

    Connection closed receiving response from server

    101506

    HTTP protocol violation receiving response from server

    101507

    Connect attempt to server canceled

    101508

    Connect attempt to server timedout

    101510

    Response received from server temporarily rejected by validator

    101511

    Response received from server permanently rejected by validator

    101512

    connection [socket] timeout submitting the request to a remote party

  3. Error Count - Number of times this error occurred.

Keep Alive Stats

This table shows the statistics about keepAlive connections established with external servers.

tsSelection 073
  1. Server - IP of the server with which the keepAlive connection is established. 

  2. Requested - Number of times requested

  3. Reused - Number of keepalive retransmissions done by reusing established connection.

  4. Forgot - Number of keepalive connections dropped.

  5. Open - Number of keepAlive connections opened with server

1.1.9. Cluster Management

Cluster Management section in Ultra Console provides you the features required to maintain the proper operation of the cluster. This consists of both management and monitoring features and these are categorized under three major aspects Cluster Navigation, Control Panel and Command History. In order to start with select 'Cluster Management' from the Ultra Console menu. Then you will get the following window.

Selection 100

Cluster Navigation is mainly related to the nodes of the cluster. Control Panel can be used for executing different command in the cluster and Command History shows details regarding the executed commands. These are discussed in three different sections you can find them under Cluster Management or using the following references.

Cluster Navigation
Overview

Cluster Navigation can be used to browse the UltraESB instances that are running in a cluster and to view more detail about each node.

Selection 067

The image above shows the cluster navigator. In order to get this select 'Cluster Navigator' under 'Cluster Management' as shown by (1). Then ESB nodes are displayed in a tabular view as can be seen above. You can select whether the displayed nodes are only active nodes or all from the menu shown by (2). Further you can limit the number of nodes displayed at a time by changing the value by menu shown by (3). This is useful when there is a large number of nodes. In such a case you can browse nodes using the available search box (4) or page browser (5). In order to get the detailed view of a node select it as shown by (6). Then you will be redirected to the page of the particular node as show below.

Node Details
Selection 071

As you can see, this is a simple detailed view of a ESB node. Under the 'Node Information' it shows the name and the domain of the node as per the configuration in ultra-root.xml, and whether the node is running or not. Then under 'Node Sessions' you can view the sessions of the UltraESB node. This sessions are listed in a tabular view as discussed above and the columns Session ID, Start time, End time are self explanatory. 'Begin state' shows the number of commands executed at the start up. Similarly 'Final state' shows the number of the commands that have been executed by the end of the session. 'Failures' shows the number of command that were failed during the session. If you node to view more details about any session, select the particular Session ID as shown and then you will get a window similar to the following. 

Session Details
Selection 073

In this view 'Session Metadata' shows an overview of the session and the the Session Commands table shows the commands that were executed during the session. This table shows useful details regarding the command and the last column (’Control’) gives the option to retry the command in case of failure. If you need further details regarding the command you can select the relevant command as shown above. This redirects you to the detailed view of the command as shown below.

Command Details
merged 1

Each numbered item is described below.

  1. This gives you the option to archive the command and then this command will not be executed in next session.

  2. You can re-publish the command. This option is not available if the command is already archived.

  3. Command metadata shows command ID, time the node received this command and whether the command is live or archived.

  4. Shows the type of the command (StartCommand, StopCommand).

  5. This table shows the results of executing this command in the other nodes of the cluster.

Command History
Overview

Command History is used to view the details regarding the commands executed in the server. This is available under Cluster Management and it gives you a tabular view as shown below.

Selection 095

This shows you the all the commands that you executed in the cluster. You can use the menu shown by (1) to view commands that are live or archived or both. You can use this table to view different information regarding your commands. These information include the time at which the command received, command type (start command, stop command, etc.), number of nodes that this command was executed successfully, number of nodes that execution of this command failed and the state of the command (live or archived). Further you have the options to archive and republish the command to the cluster. These options are available only if the particular command is in live state.

Cluster Navigation

Command Details
merged 1

Each numbered item is described below.

  1. This gives you the option to archive the command and then this command will not be executed in next session.

  2. You can re-publish the command. This option is not available if the command is already archived.

  3. Command metadata shows command ID, time the node received this command and whether the command is live or archived.

  4. Shows the type of the command (StartCommand, StopCommand).

  5. This table shows the results of executing this command in the other nodes of the cluster.

Control Panel
Controlling Proxy Services, Endpoints and Sequence

Cluster Control Panel is the place where you can perform operations on proxy services, endpoints, sequences and servers in a cluster wide manner. You can go to the cluster control panel by selecting the 'Control Panel' under Cluster Management and then you will get the controls related to the proxy services as can be seen in the following figure.

Selection 086

Here you can start or stop any proxy service cluster wide easily. For this, you can select the proxy service by the drop down menu and do the corresponding operation. Further you can enable or disable DEBUG log level for a proxy service cluster wide. Similarly you can perform these operations on endpoints and sequences under Endpoint tab and Sequence tab respectively.

Controlling Servers

The Servers tab gives you the options for restarting ESB nodes in the cluster in 4 different manners and to refresh the cluster as shown below.

Selection 088
  • Round-Robin graceful restart of cluster

              Here you can perform a restart of all ESB nodes of a cluster in a manner which is Round-Robin and graceful. In a Round-Robin restart, servers are restarted one by one and so only one server undergo a restart at a time. When one server completes restart, next one is begins restarting. This ensures the availability of cluster during the restart. You can define the time gap that one server completes restart and next one begins restart by specifying the delay in milliseconds. Graceful restart is a safe restart that ensures no message will be dropped due to the restart. You can specify the grace period in milliseconds that the server is allowed to perform a graceful restart. In case of a timeout, the server is restarted hardly. Although the Round-Robin graceful restart is the most time consuming restart, it is the most safe restart available.
  • Round-Robin hard restart of cluster

              This guarantees the availability but some messages might be dropped during the restart. As this is not graceful, you can only specify the delay between restarts.
  • Graceful restart of complete cluster

              This type of restart does not guarantee the availability as all the nodes undergo restart approximately at the same time. Further the messages may be dropped during the restart as no server is ready for accepting messages. In this scenario graceful means that servers complete the processing of accepted messages if any. But this is guaranteed only if the grace period you specify is sufficient for processing the messages.
  • Hard restart of complete cluster

              This is the least time consuming restart type that you can perform. But this doesn’t guarantee either availability or that all the messages are processed properly.
  • Refreshing the cluster

              This is used for signaling an interceptor with human intervention. It is important to note that this operation does not reload the configuration nor restart the server.

You can find more details about these operation where the option is available.

1.1.10. Log Management

The UConsole provides useful features for managing UltraESB instances, and the Log Management aspects are described in this article. The Node Monitoring top level menu item includes facilities to manage the underlying Log4J Logger instances and Appenders, and also allows one to view the tail end of the log file via the UConsole, while allowing entries to be filtered easily on the severity level.

Loggers

This page shows the Log4J Loggers defined along with the parent, and the log level and additivity, which can be updated easily via the UI. The list can be easily filtered to search a logger instance by name, and by default is filtered to show the loggers specific to the UltraESB

loggers

The Add Logger button at the top right of the page will allow one to create a new logger. The logger name, logger level and the additivity should be specified to add a logger at runtime.

add logger
The Log Appenders

This page will display the list of appenders defined along with the conversion pattern and the threshold for each. By default the threshold is not set except for  the MEMORY_APPENDER. By specifying a threshold, only the log messages with a higher level than specified threshold will be appended in to the appender. When the threshold is not specified all the log messages in the logger hierarchy are appended to the appender.  

log appenders

The edit button in the control column leads to a page where a user can edit the appenders configuration. The appender conversion pattern and the threshold value can be updated.

update appender
The Log Viewer

The Log Viewer is disabled by default to prevent unwanted performance issues. If a user wishes to to view the tail end of the UltraESB log file via the UConsole, this feature can be enabled via the UConsole itself by setting a threshold value to the MEMORY_APPENDER. To enable this feature permanently, edit the conf/log4j.properties file

Do not expect to see log messages generated before the MEMORY_APPENDER was enabled, if it was enabled at runtime. Only those log messages that occur after the MEMORY_APPENDER is enabled will appear in the Log Viewer. The Log Viewer shows the tail end of UltraESB log messages. That is it will only display the last 500 log messages by default. This number may be customized by updating the  line log4j.appender.MEMORY_APPENDER.Size=500 in the conf/log4j.properties

log viewer

Using the Error, Warn, Info and Debug buttons at the top will filter the log file to only those entries whose severity is the selected level or higher. e.g. Selecting WARN will hide debug and info messages, and display only Warning and Error messages (if any).

1.1.11. Zabbix Monitoring

Overview

Enter the Zabbix monitoring view by first clicking on the monitoring link and then on the Zabbix Monitoring link in the left navigation menu bar.

go to zabbix

This will lead to a page which lists all the defined Zabbix templates.

Selection 001
  1. This drop down enable you to change the Zabbix version. The Uconsole currently supports Zabbix 1.8 and 2.X versions.  Templates used for these versions are different.

  2. Registration button leads to the Zabbix registration wizard. This is discussed further in Zabbix Registration.

  3. Synchronize action will register all the newly added proxy services at the Zabbix server

  4. The template registry or all the defined templates for registering UltraESB artifacts at the Zabbix server

Zabbix Template Management

Click on the template name link of the required template to enter the management view of the template.

enter management

The template management view is shown below:

template management view
  1. Enables to edit the template content shown by 12

  2. Enables the template. When a template is enabled it is used to register UlraESB artifacts at Zabbix server during the registration or synchronization process

  3. Disables the template. When a template is disabled it is not considered during the registration or synchronization of UltraESB artifacts at the Zabbix server

  4. Removes the template from the registry, thus it will not accessible or usable again 

  5. The unique identifier of the template

  6. The artifact type. E.g:  if group is graph/endpoint, this means a the template will be used to create graphs for all the registered endpoints

  7. The Zabbix item type

  8. The Zabbix template registry has a hierarchy. This field shows the template which the current template inherited certain attributes

  9. The UltraESB artifact type which uses the current template

  10. ???

  11. The state of the template

  12. The content of the template. This is the actual json message needed by the Zabbix API to register elements at the Zabbix server

Zabbix Registration
Selection 003

1.1.12. Connecting to multiple servers or nodes of a cluster

The UConsole application is designed to be hosted externally to the ESB nodes, for ease of administration and the lowest foot print and resource usage on the actual ESB nodes. Thus one can host UConsole, as a common separately hosted application in the data centre, or even as a locally started web application on a developer workstation etc. The UConsole can also be hosted on a server where one or more UltraESB instances are executing.

Connecting to local instances

Whenever the UConsole application is started on a host which also runs one or more local UltraESB instances, one can easily connect to such instances using the "Local instance" selection, without any further configuration. This works the same way the standard "jconsole" application of the Java Development Kit works. However, on certain non-Linux based operating systems, this might not work due to limitations imposed on the Java process. If so, please enable remote JMX and connect via the remote JMX URL instead.

1
Enabling Remote JMX

To enable remote JMX, edit the conf/ultra-root.xml and uncomment the following block defining the "serverConnector" and the "registry" for use by the JMX connection. The "serviceUrl" is your JMX URL to connect to the ESB instance, and the "jmx.remote.x.password.file" and the "jmx.remote.x.access.file" values point to the location of a file containing the actual credentials to be used. This is the standard Java mechanism for secured remote JMX connectivity. If you are running more than one ESB instance on the same server, change the port values to enable both servers to expose JMX connectivity. (i.e. change 9994 and 1099 in the below example, and replace with suitable values for each instance)

<bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean" depends-on="registry">
    <property name="objectName" value="connector:name=iiop"/>
    <property name="serviceUrl" value="service:jmx:rmi://localhost:9994/jndi/rmi://localhost:1099/ultra"/>
    <property name="threaded" value="true"/>
    <property name="daemon" value="true"/>
    <property name="environment">
        <map>
            <entry key="jmx.remote.x.password.file" value="conf/management/jmxremote.password"/>
            <entry key="jmx.remote.x.access.file" value="conf/management/jmxremote.access"/>
        </map>
    </property>
</bean>
<bean id="registry" class="org.springframework.remoting.rmi.RmiRegistryFactoryBean">
    <property name="port" value="1099"/>
</bean>

Once remote JMX is enabled, the ESB node will print this URL on its start-up log file.

2013-01-22 11:32:25,395 [-] [main]  INFO ServerManager Instance available for management via JMX at : service:jmx:rmi://localhost:9994/jndi/rmi://localhost:1099/ultra
Connecting to an ESB instance via remote JMX

To connect to any [remote] UltraESB instance via secured remote JMX, enter its JMX URL ("1"), and the secured JMX credentials ("2") defined in the "jmx.remote.x.password.file" and "jmx.remote.x.access.file" of the ESB node you are connecting to. Finally, you will also need to authenticate to the UConsole application ("3")

2
Defining ESB instances to UConsole

One can pre-define the JMX URLs and credentials to the UConsole instance to ease the login and subsequent switching between multiple ESB nodes. After logging into the UConsole, you can configure these by clicking the "Settings" link at the top right hand corner. This area will also show you your currently connected ESB instance, and also a link to switch the connected server which we will discuss later.

3

From the "Settings" link, you can view any currently defined servers, as well as define new instances to easily connect to later on.

4

To add a new entry, press the "Add Server" button, and provide the instance ID, JMX URL and credentials to use.

5

Once added, this server appears on your list of instances from the "Switch Server" link at the top right hand corner of the UConsole.

6

One may also pre-define ESB instances by editing the file "uconsole/WEB-INF/classes/uconsole.properties" before starting up the UConsole application. This would be a quick and secure way to connect to multiple instances from a developers’ workstation hosted UConsole.

Logging into pre-defined servers

One can login to a pre-defined server with a single click, and without having to provide the JMX credentials (as they are already saved to the UConsole) by selecting the instance desired during login time.

7

1.1.13. Proxying Requests to UConsole with an Apache Reverse Proxy

Applies to CentOS / RHEL - but configuration maybe relevant to other Linux variations. Steps below have been tested on CentOS 6.4

This configuration steps aims to guide a user in setting up an Apache Web server in front of one or more UConsole instances deployed. These steps have been kept short and clear, and system administrators are expected to perform required optimizations over these steps. In this configuration the end users are directed to an Apache Web server listening over HTTPS. This server configures the SSL certificate (refer to standard Apache Web server documentation) and all other connection parameters, and uses mod_proxy to pass HTTP traffic over a private network (or localhost) to the actual UConsole instance. For this purpose, we first make the UConsole listen over plain HTTP instead of HTTPS, as the Apache Web server will now handle the SSL connectivity.

  1. Make UConsole Jetty server listen for HTTP over the localhost or private interface between the the Apache web server and the UConsole node uconsole/conf/jetty.xml

    <Call name="addConnector">
        <Arg>
            <!--New class="org.mortbay.jetty.security.SslSocketConnector">
                << DELETE or Comment out this section to stop UConsole Jetty server listening on port 8043 for SSL >>
            </New-->
            <New class="org.mortbay.jetty.nio.SelectChannelConnector">
               <Set name="Port">8043</Set>
               <Set name="Host">localhost</Set>
            </New>
        </Arg>
    </Call>
  2. Install Apache
    yum install httpd

  3. Set Apache to start on server startup
    chkconfig –levels 235 httpd on

  4. Install mod_ssl
    yum install mod_ssl

    1. To stop Apache listening on port 80 for plain HTTP traffic, comment the line "Listen 80" from /etc/httpd/conf/httpd.conf

    2. To configure certificates for SSL refer to standard Apache certificate configuration documentation

  5. Ensure that mod_proxy is enabled + /etc/httpd/conf/httpd.conf

    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
    LoadModule proxy_http_module modules/mod_proxy_http.so
  6. Add proxy

    1. Add a non-load balancing proxy
      Configure the proxy by adding the following entries at the end of the VirtualHost definition /etc/httpd/conf.d/ssl.conf

      </VirtualHost ...>
          ...
          ProxyPreserveHost On
          ProxyPass /uconsole http://localhost:8043/uconsole
          ProxyPassReverse /uconsole http://localhost:8043/uconsole
      </VirtualHost>
    2. Add a load balancing proxy Configure the proxy by adding the following entries at the end of the VirtualHost definition /etc/httpd/conf.d/ssl.conf

      NameVirtualHost *:443
      ServerName <<replace-with-server-name>>
      
      </VirtualHost ...>
          ...
          ProxyPass /uconsole balancer://mycluster/uconsole
      </VirtualHost>
      
      <Proxy balancer://mycluster>
          Order deny,allow
          Allow from all
          BalancerMember http://node1:8043 route=node1
          BalancerMember http://node2:8043 route=node2
      </Proxy>
    3. To allow Apache to connect to the localhost and port of the UConsole, on SELinux execute the following as root
      #setsebool -P httpd_can_network_connect 1

  7. Start apache
    service httpd restart

1.2. Ultra Terminal

Ultra Terminal, shortened as UTerm is a management terminal for the UltraESB. It is a CLI (Command Line Interface) to interact with a remote UltraESB server or a complete UltraESB cluster to manage those nodes with a unified set of commands.

UTerm has 2 operational modes,

1.2.1. Standalone, scriptable command execution

This mode of operation is very convenient for automated management of the ESB instances as it execute the command in one go and gives the result if there is any. It is expected to be used by scripts, but no limitation for a human using this to get the result of an execution in one go.

Scriptable commands to manage/monitor ESB nodes
You can use UTerm commands or a combination of those to automate certain management tasks with scripts, as it operates as a standalone command to be executed to manage/monitor the ESB instances

To run the UTerm with this mode, you need to pass the "-command" or "–command" option, if this option is not passed in it defaults to run the UTerm in the interactive mode.

Running UTerm with standalone mode

Running the UTerm with the standalone, scriptable mode can be done by executing the uterm.sh or the uterm.bat, depending on your operating system with the following options.

On Linux based systems, use a command line shell to navigate to the ULTRA_HOME/bin directory and execute the uterm.sh script with the –command or -command option to see the set of available commands.

$ cd /opt/ultraesb-1.6.0/bin
$ ./uterm.sh -command help

Upon executing this you will see the list of commands available to be executed with the –command or the -command option. The displayed command set has a short command, long command and a description, printed in-order separated by a comma. You could use the short or the long form of the command with the above option as you feel convenient. For example to list the UltraESB instances running locally on the same host, the "ls" or the "list-servers" command could be used with the –command or -command option as follows.

$ sh bin/uterm.sh -command ls

The list of complete commands available can be found in the UTerm Command Reference. Alternatively, you can find various options available with the command set printed by the previous "help" command by using the –help or -h option with each and every command. For example to see the possible options with the list-servers command, you can execute;

$ sh bin/uterm.sh -command ls -h

You will be able to see the help of the "list-servers" command with the possible options. You can replace the ls command with any valid command to get the help with the options of those respective commands.

Except for the list-servers command, all the other commands when running in standalone mode requires the –server option, to specify the JMX service URL of the UltraESB instance against which this command to be executed. If this option is not provided UTerm tries to connect to a locally running UltraESB instance.

For example to list the proxy services running on the remote UltraESB instance with the JMX service URL "http://loft:8280/service:jmx:rmi:/10.100.8.1:9994/jndi/rmi:/10.100.8.1:1099/ultra[service:jmx:rmi://10.100.8.1:9994/jndi/rmi://10.100.8.1:1099/ultra]"

$ sh bin/uterm.sh -command lps --server service:jmx:rmi://10.100.8.1:9994/jndi/rmi://10.100.8.1:1099/ultra

If you just need to check the list of proxy services on the UltraESB instance running locally, you can use the same command without the –server option and the URL.

Named service URL configuration
If you have a set of well-known JMX service URLs of the UltraESB instances that you will be managing (which is the case in most of the production deployments), you can name them and use the given name while executing the command instead of the complete URL. See the UTerm Configurations for more information on how to specify named service URLs and use them to invoke the commands.

In the same manner, if you have more than one local UltraESB instances, you can use the ls command first to find the name of the server and then use it to manage that specific local UltraESB instance.

In production deployments of the UltraESB, it is recommended to secure the JMX access, with username password authentication, and in those circumstances you will have to specify the username and the password to connect to the give JMX service URL. For that matter, you can use the "–username" ad "–password" options to specify the username and password.

For example to execute the same previous command over a secured remote JMX connection, secured with "admin" username and "admin" password (which are the default username and password of the UltraESB remote JMX connection)

$ sh bin/uterm.sh -command lps --server service:jmx:rmi://10.100.8.1:9994/jndi/rmi://10.100.8.1:1099/ultra --username admin --password admin

If you try to invoke a command over secure JMX connection without specifying the username and the password, you will get the message "Authentication failed! Credentials required".

Associate security credentials for named JMX service URL
You can associate a username and password to be used with a given server name, and when using the name as the –server option those credentials are used automatically by the tool. See UTerm Configurations for information on how to configure this.

You can view all these available options for running the UTerm with the –help or -h option of the UTerm as follows;

$ sh bin/uterm.sh -h

This will print the help including all the above options and its usage.

1.2.2. Interactive command execution

This mode of operation is very convenient for human operators/system administrators, and is designed to manage sessions of multiple command executions after connected to a server. Also you can switch between server from the same UTerm console, without logging out from the tool, etc..

Interactive mode supports named JMX service URL
With the interactive mode, you can specify the server to connect to with –server option as in the standalone mode at launching the terminal or can connect to a given server after launching the terminal with the "con" command. This mode also supports the named server URLs and connecting to a node by there name. For secure connections the username and password can be configured with the given server name  as in the standalone mode or can be passed at launching time or after launching with the "con" command.

To run the UTerm in this mode, you do not need any option, unless you specify the –server, –username and the –password options at launching time.

Running UTerm with interactive mode

Running the UTerm with the interactive mode can be done by executing the uterm.sh or the uterm.bat, depending on your operating system.

On Linux based systems, use a command line shell to navigate to the ULTRA_HOME/bin directory and execute the uterm.sh script.

$ cd /opt/ultraesb-1.6.0/bin
$ ./uterm.sh

This will launch the UTerm and you will be given the UTerm prompt to interact with the tool on the CLI.

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

uterm>

Type "help" to see the list of available commands on the prompt and hit enter. You will be able to see the list of commands in-order with short command, long command and the description separated by a comma.

To see available options or help on any individual command type the command with the –help or -h option as follows;

uterm> con -h

This command is a special command used in the interactive mode to connect to a given server or to switch to a new server, where you can use the –username or -u option to specify the username and the –password or -o option to specify the password with the server to connect to. This command also supports the named server URLs and the username and password association to a named service URL.

Command auto completion
Note the auto completion of the commands, on typing the "tab" key.

After using the "con" command to connect to a given server, launching the UTerm with the –server option or if you have a locally running UltraESB instance without any of the above, you can execute any command from the set of available commands. Check the help of command and the options available with the –help or -h option before executing the command for the first time.

For example to connect to the server and to retrieve the list of proxy services;

uterm> con service:jmx:rmi://111.223.149.143:9994/jndi/rmi://111.223.149.143:1099/ultra -u admin -p admin
Successfully connected to the UltraESB instance!
uterm> lps
echo-back
echo-proxy
uterm>

If there is any command that has a clustering presence (most of the operation commands does) you can use the "–cluster-wide" or the "-w" option to invoke the command on the complete cluster, from the instance to which you are connected to.

All about UTerm is covered in this section and have a look at the command reference to learn each and every command in action.

1.2.3. UTerm Command Reference

This is the command reference of the UTerm, with commands arranged to the related groups. The complete list of available commands are as follows;

Server management commands
Short Command Long Command Description

sl

server-list

list the locally running UltraESB instances

srfr

server-refresh

refresh the server

con

connect

connects to the specified address, use the server name (as displayed by the 'ls' command) to connect to local servers

sstchk

server-state-check

check the state of the UltraESB server

srstr

server-restart

restarts the UltraESB server or Cluster

sstp

server-stop

stops the UltraESB server

sstr

server-start

starts the UltraESB server

sshd

server-shutdown

shutdown the UltraESB server

shcsn

show-connected-server-name

show name of the currently connected server

shcsa

show-connected-server-address

show name of the currently connected server

stpact

stop-acting-as

stop acting as the given server name

stract

start-acting-as

start acting as the given server name

sudscg

server-user-defined-status-code-get

check the user defined status code for the UltraESB server

sudscs

server-user-defined-status-code-set

set the user defined status code for the UltraESB server

Configuration management commands
Short Command Long Command Description

duau

deployment-unit-add-or-update

add new child configuration or update existing child configuration

dupa

deployment-unit-purge-all

purge all outdated deployment units

duu

deployment-unit-unload

unload executing deployment unit/

Proxy service management commands
Short Command Long Command Description

psl

proxy-service-list

list the proxy services of the UltraESB server

psv

proxy-service-view

get the String serialization of the specified proxy service

psdbd

proxy-service-debug-disable

disable debug for the specified proxy service

psdbe

proxy-service-debug-enable

enable debug for the specified proxy service

psstrst

proxy-service-statistics-reset

reset statistics for the specified proxy service

psstp

proxy-service-stop

stop the specified proxy service

psstr

proxy-service-start

start the specified proxy service

Endpoint management commands
Short Command Long Command Description

epl

endpoint-list

list the endpoints of the UltraESB server

getep

get-endpoint

get the String serialization of the specified endpoint

epdbd

endpoint-debug-disable

disable debug for the specified endpoint

epdbe

endpoint-debug-enable

enable debug for the specified endpoint

epstrst

endpoint-statistics-reset

reset statistics for the specified endpoint

epstp

endpoint-stop

stop the specified endpoint

epstr

endpoint-start

start the specified endpoint

Sequence management commands
Short Command Long Command Description

sql

sequence-list

list the sequences of the UltraESB server

sqv

sequence-view

get the String serialization of the specified sequence

sqdbd

sequence-debug-disable

disable debug for the specified sequence

sqdbe

sequence-debug-enable

enable debug for the specified sequence

sqstrst

sequence-statistics-reset

reset statistics for the specified sequence

sqstp

sequence-stop

stop the specified sequence

sqstr

sequence-start

start the specified sequence

Logger management commands
Short Command Long Command Description

llch

log-level-change

change the log level of a logger

lls

logger-list

listing log levels of loggers

lad

logger-add

adding a new logger

ach

additivity-change

change additivity of a logger

lgw

log-watch

watch logs of the connected UltraESB server

apu

appender-update

update appender pattern and threshold of the specified appender

Zabbix Commands
Short Command Long Command Description

zr

zabbix-register

register the zabbix elements for the current configuration

zrs

zabbix-reg-stat

prints the Zabbix registration status

Utility commands
Short Command Long Command Description

help

help

prints this command help

quit

exit

exit from the uterm

JMSClient Commands
Short Command Long Command Description

jmssend

jms-connect-and-send

connects to the specified connection factory, send messages from the specified producer and receive messages from the consumer specified in the properties file. If a consumer is not specified the command exists after delivering the message

jdelall

jms-delete-all

deletes all the messages in the queue specified by the queue jndi name

jread

jms-read

reads immediate message in the specified queue

jreadAll

jms-read-all

reads all the messages in the specified queue

Server Management Commands

Server management commands are used to manage and monitor an running UltraESB instance or a cluster of UltraESB instances. This section describes each and every command in the server management category.

The commands of UTerm under server management are;

List servers

List servers command lists the locally running UltraESB instances. The short form of the command is ’ls` which is equivalent to calling it’s long form'list-servers

Short command

sl

Long command

server-list

Available options for the list servers command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-s

–service-url

shows the service-url with the server name

If no options were given it lists only the servers name followed by the process id separated with a hyphen (-), you can use this command to discover the UltraESB instances running locally on the same host.

This command is useful in identifying a specific instance, to connect to with the connect command, when there are more than one instances running locally on the same host.

Related Commands

connect

Local instance connection is not mandatory
You do not need use the connect command if there is only one local UltraESB instance running on the same host, upon giving the first command, UTerm automatically establishes the connection with that instance of UltraESB, if it is not already connected to any instance.
Connect

Connect command connects to the specified UltraESB instance over its Java Management Extension (JMX) address. The short form of the command is ’con` which is equivalent to calling it’s long form'connect

Short command

con

Long command

connect

Available options for the connect command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-p <arg>

–password <arg>

password to be used in connecting

-u <arg>

–username <arg>

username to be used in connecting

Use the JMX URL of the UltraESB instance to connect to it. If connecting to a locally running UltraESB instance, use the server name (as displayed by the 'ls' command) to connect to local servers. If no address or server name is provided the connect command tried to connect to a locally running UltraESB instance.

If connecting to a remote UltraESB instance over remote JMX with security, the username and password options should be given with the corresponding username and password to be used in password authentication at connection time. If wrong credentials or no credentials were given in connecting to an UltraESB instance with remote secure JMX access, the connection will fail.

Related Commands

server-list

Configure UTerm to connect by passing the server name
You could configure the JMX addresses with credentials in the uterm.properties file and use a given server name to connect to a remote UltraESB instance, which is very convenient. See the UTerm Configuration for more information.
Refresh the server

Refreshes the specified UltraESB server. The short form of the command is ’con` which is equivalent to calling it’s long form'connect

Short command

 srfr    

Long command

server-refresh

Available options for the connect command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

 -w

–cluster-wide

refresh all the servers in the cluster

Related Commands

connect

Check server state

Check server state command is used to check the UltraESB server status. The short form of the command is ’sstchk` which is equivalent to calling it’s long form'server-state-check

Short command

sstchk

Long command

server-state-check

Available options for the check server state command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

Using the check server state with a script to periodically check it, you can check the status of the UltraESB server. This command prints the server status as one of the following strings with the respective meaning.

  • Started - server is started and running

  • Stopped - server is stopped and not running

  • Paused - server is paused, do not accept any new work

  • Failed - server has failed to start

  • Starting - server is being started, didn’t accept work until it become started

  • Stopping - server is being stopped, do not accept any new work, already accepted work might be in progress

  • Pausing - server is being pause, do not accept any more new work

Restart server

Restart server command is used to restart the running UltraESB instance or a cluster of UltraESB instances. The short form of the command is ’srstr` which is equivalent to calling it’s long form'server-restart

Short command

srstr

Long command

server-restart

Available options for the restart server command are described in the following table.

Short option key Long option key      Description

-f

–forced-instant

forced restart the server instantly, applies only for non-clustered restarts

-g <arg>

–grace-period <arg>

restart gracefully in the given grace period in seconds

-h

–help

prints the command help

-r <arg>

–rr-delay <arg>

applies in cluster-wide execution, round-robin restart with the specified delay

in seconds, between 2 server restarts in the cluster

-w

–cluster-wide

restart the complete cluster

Using the restart command you can restart a server in 2 possible options.

  1. Graceful restart - where the accepted requests are processed until the grace period exceeds to trying to deliver the response.

  2. Hard/forced restart - instant hard restart without worrying about the messages in-flight.

Normal restart is graceful
Restart server command without any option is graceful too, but the grace period is the default one which is 30 seconds.

The restart server command used with clustering by passing '-w' option allows the cluster restart to be done in a round robin fashion with the specified round robin delay between 2 server restarts in the cluster.

Round-Robin graceful cluster restart
Round-Robin graceful cluster restart allows the cluster to be restarted in a manner that the complete cluster has no down time.

This command is very useful in managing a complete cluster.

Related Commands

stop-server

start-server

Stop server

Stop server command is used to stop the running UltraESB instances. The short form of the command is ’stps` which is equivalent to calling it’s long form'stop-server

Short command

stps

Long command

stop-server

Available options for the stop server command are described in the following table.

Short option key Long option key      Description

-f

–forced-instant

forced stop the server instantly, applies only for non-clustered stops

-g <arg>

–grace-period <arg>

stop gracefully in the given grace period in seconds

-h

–help

prints the command help

-w

–cluster-wide

stop the complete cluster

Using the stop command you can stop a server in 2 possible options.

  1. Graceful stop - where the accepted requests are processed until the grace period exceeds to trying to deliver the response.

  2. Hard/forced stop - instant hard stop without worrying about the messages in-flight.

Normal stop is graceful
Stop server command without any option is graceful too, but the grace period is the default one which is 30 seconds.

This command is useful in managing a cluster, where as a server can be stopped and wait for some action to take place and then start the server without terminating the JVM.

Related Commands

start-server

restart-server

Start server

Start server command is used to start a stopped UltraESB instance. The short form of the command is ’strs` which is equivalent to calling it’s long form'start-server

Short command

strs

Long command

start-server

Available options for the start server command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

-w

–cluster-wide

start the complete cluster

This command is useful in starting a server or a cluster and waiting for some action to take place and then start the server without terminating the JVM.

Related Commands

stop-server

restart-server

Shutdown server

Shut down server command is used to shut down the UltraESB instances. The short form of the command is ’sshd` which is equivalent to calling it’s long form'server-shutdown’

Short command

sshd

Long command

server-shutdown

Available options for the stop server command are described in the following table.

Short option key Long option key      Description

-f

–forced-instant

forced shut down the server instantly, applies only for non-clustered stops

-g <arg>

–grace-period <arg>

shut down server gracefully in the given grace period in seconds

-h

–help

prints the command help

-w

–cluster-wide

shutdown the complete cluster

Using the shutdown command you can stop a server in 2 possible options.

  1. Graceful shutdown - where the accepted requests are processed until the grace period exceeds to trying to deliver the response.

  2. Hard/forced shutdown - instant hard stop without worrying about the messages in-flight.

Show connected server name

Show connected server name command is used the check currently connected server name of the Uterm. The short form of the command is ’shcsn` which is equivalent to calling it’s long form'show-connected-server-name’

Short command

shcsn

Long command

show-connected-server-name

Available options for the show-connected-server-name command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

This command is useful to check whether Uterm is connected to the required server and if not user can connected to relevant node using connect command.

Related Commands

show-connected-server-address

Show connected server address

Show connected server name command is used the check currently connected server address of the Uterm. The short form of the command is ’shcsa` which is equivalent to calling it’s long form'show-connected-server-address’

Short command

shcsa

Long command

show-connected-server-address

Available options for the show-connected-server-address command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

This command is useful to check whether Uterm is connected to the required server and if not user can connected to relevant node using connect command.

Related Commands

show-connected-server-name

Stop acting-as

Stop acting-as command is used to stop an UltraESB instance acting-as the given server name of an UltraESB node which this node previously started to act as. The short form of the command is ’stpact` which is equivalent to calling it’s long form'stop-acting-as

Short command

stpact

Long command

stop-acting-as

Available options for the stop acting-as command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

This command is useful in stopping pinned proxy services that this node is running pinned to another server (may be because of a failure of that node), in a non clustered environment.

Automatically happen in a clustered deployment
In a clustered environment, if the fail-over nodes are configured, this transition automatically happens once the failed node came back online and joins the cluster back.
Related Commands

start-acting-as

Start acting-as

Start acting-as command is used to start an UltraESB instance acting-as the given server name of an UltraESB node which needs to be acted as. The short form of the command is ’stract` which is equivalent to calling it’s long form'start-acting-as

Short command

stract

Long command

start-acting-as

Available options for the start acting-as command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

This command is useful in transferring pinned proxy services of a failed node into a running UltraESB instance, in a non clustered environment.

Automatically happen in a clustered deployment
In a clustered environment, if the fail-over nodes are configured, this transition automatically happens once a node fails and gets removed from the cluster.
Related Commands

stop-acting-as

Check defined status code

Check the user defined status code for the UltraESB server. The short form of the command is ’sudscg` which is equivalent to calling it’s long form'server-user-defined-status-code-get

Short command

 sudscg

Long command

server-user-defined-status-code-get

Available options for the start acting-as command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

Related Commands

server-user-defined-status-code-set

Set defined status code

Check the user defined status code for the UltraESB server. The short form of the command is ’sudscs` which is equivalent to calling it’s long form'server-user-defined-status-code-set

Short command

 sudscs

Long command

server-user-defined-status-code-set

Available options for the start acting-as command are described in the following table.

Short option key Long option key      Description

-h

–help

prints the command help

 -sc

–status-code <arg>

value of the user defined status code

Related Commands

server-user-defined-status-code-get

Check the user defined status code for the UltraESB server

Deployment Unit Management Commands

Deployment unit management commands are used to manage dynamic configurations of an UltraESB instance or a cluster of UltraESB instances. This section describes each and every command in the deployment unit management category.

The commands of UTerm under deployment unit management are;

Add or update deployment unit

Add or update deployment unit command adds new deployment unit or update an existing deployment unit via a dynamic sub context of an UltraESB instance or a cluster of instances. The short form of the command is ’duau` which is equivalent to calling it’s long form'deployment-unit-add-or-update

Short command

duau

Long command

deployment-unit-add-or-update

Available options for the add or update deployment unit command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

add/update cluster wide

-n

–name <arg>

name of the deployment unit to be added

To invoke this command it is mandatory to specify the deployment unit name as the name argument, this provides the folder name of the deployment unit to look for configurations to be added or updated.

This command is useful in updating the configuration of a production UltraESB cluster or a single instance without any down time, yet the transition being completely graceful (live updates of the UltraESB).

Related Commands

deployment-unit-purge-all

deployment-unit-unload

Note
Once this command is invoked it result in the previously running deployment units to be stale after some time (after completing the processing of all the messages accepted by this deployment unit) this consumes a little it of memory and hence, you could use the deployment-unit-purge-all command to remove these stale deployment units.
Purge all deployment units

Purge all deployment units command removes outdated deployment units of an UltraESB instance or a cluster of instances. The short form of the command is ’dupa` which is equivalent to calling it’s long form'deployment-unit-purge-all

Short command

dupa

Long command

deployment-unit-purge-all

Available options for the purge all deployment units command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

purge all outdated deployment units cluster wide

To remove stale deployment units which are being stacked due to execution of deployment-unit-add-or-update command, use this command. This command removes all the outdated deployment units at the execution point. The execution of this command should be done after making sure all the messages accepted by the deployment unit before the last update.

This command is useful in removing stale deployment units of a production UltraESB cluster to gain a little bit of memory.

Related Commands

deployment-unit-add-or-update

deployment-unit-unload

Best Practice - Purge as late as possible after an update
As a best practice, make sure to give the previous configuration a good long time to complete its messages, after an update. A configuration shouldn’t take much memory, so it is OK to purge even after a day or just before the next update.
Unload deployment unit/s

Unload deployment command unloads an existing live deployment unit of an UltraESB instance or a cluster of instances. The short form of the command is ’duu` which is equivalent to calling it’s long form'deployment-unit-unload

Short command

duu

Long command

deployment-unit-unload

Available options for the unload configuration command are described in the following table.

Short option key Long option key Description

-a

–all

unload all deployment units

-h

–help

prints the command help

-n

–name <arg>

name of the deployment unit to be unloaded

-w

–cluster-wide

unload cluster wide

To invoke this command the '-a' or '-n' option is mandatory. The '-a' option unloads all the executing deployment units. The '-n' option  will unload only the deployment unit, which is specified as the argument.

This command is useful in unloading a particular deployment unit or all the deployment units of an UltraESB cluster or a single instance in an integration environment.

Proxy Service Management Commands

Proxy service management commands are used to manage and monitor proxy service artifacts deployed in a running UltraESB instance or a cluster of UltraESB instances. This section describes each and every command in the proxy service management category.

The commands of UTerm under proxy service management are;

List proxy services

List proxy services command lists the proxy services deployed on a running UltraESB instance. The short form of the command is ’psl` which is equivalent to calling it’s long form'proxy-service-list

Short command

psl

Long command

proxy-service-list

Available options for the list proxy services command are described in the following table.

Short option key Long option key Description

-a

–all

list all the proxy services

-h

–help

prints the command help

-i

–with-info

list proxy services with there respective information

-s

–with-state

list proxy services with there respective states

If no options were given it lists only the proxy services in the started state, you can use this command with '-a' option to list all the proxy services regardless of the state. You can get a tabular dataset describing the proxy while listing it by passing the '-i' option.

If '-i' option is passed, the '-s' option makes no sense as it already prints the state.

Related Commands

proxy-service-view

Proxy service view

Get proxy service command gives a representation of a proxy service with the given identifier deployed on a running UltraESB instance. The short form of the command is ’psv` which is equivalent to calling it’s long form'proxy-service-view

Short command

psv

Long command

proxy-service-view

Available options for the get proxy service command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

This command is useful in scripting where you want to get certain attributes of a proxy service to automate some action.

Related Commands

proxy-service-list

Disable debug of proxy service

Disable debug of proxy service command disables debugging of the proxy service with the given identifier deployed on a running UltraESB instance. The short form of the command is ’ddbps` which is equivalent to calling it’s long form'proxy-service-debug-disable

Short command

psdbd

Long command

proxy-service-debug-disable

Available options for the disable debug of proxy service command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

disable debug for proxy service cluster wide

This command is useful to disable debug for a specific proxy service that has been enabled debug previously to figure out some situation with that proxy, cluster wide, both in integration as well as production environments.

Related Commands

proxy-service-debug-enable

Enable debug of proxy service

Enable debug of proxy service command enables debugging of the proxy service with the given identifier deployed on a running UltraESB instance. The short form of the command is ’psdbe` which is equivalent to calling it’s long form'proxy-service-debug-enable

Short command

psdbe

Long command

proxy-service-debug-enable

Available options for the enable debug of proxy service command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

enable debug for proxy service cluster wide

This command is useful to enable debug for a specific proxy service that needs to examine the debug logs to figure out some situation with that proxy, cluster wide, both in integration as well as production environments.

Related Commands

proxy-service-debug-disable 

Reset statistics of proxy service

Reset statistics of proxy service command resets the collected statistics at that point of the proxy service with the given identifier deployed on a running UltraESB instance. The short form of the command is ’psstrst` which is equivalent to calling it’s long form'proxy-service-statistics-reset

Short command

psstrst

Long command

proxy-service-statistics-reset

Available options for the reset statistics of proxy service command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

reset statistics for proxy service cluster wide

This command is useful to reset statistics for a specific proxy service collected so far (or to set the statistics meter to zero) that needs to examined, cluster wide, on production environments.

Clear the statistics frame to start looking at the current behaviour
You may reset the statistics of a proxy service cluster wide and then monitor them again to see any more messages failing or any specific error which is occurring.
Stop proxy service

Stop proxy service command is used to stop a running proxy service deployed on an UltraESB instance. The short form of the command is ’psstp` which is equivalent to calling it’s long form'proxy-service-stop

Short command psstp

Long command

proxy-service-stop

Available options for the stop proxy service command are described in the following table.

Short option key Long option key      Description

-h

–help

prints this command help

-w

–cluster-wide

stop proxy service cluster wide

This command is useful in stopping a specific proxy service in a single instance or a cluster of instances which needs to be stopped for maintenance.

Related Commands

proxy-service-start

Start proxy service

Start proxy service command is used to start a stopped proxy service deployed on a running UltraESB instance. The short form of the command is ’psstr’ which is equivalent to calling it’s long form 'proxy-service-start'

Short command

psstr

Long command

proxy-service-start

Available options for the start proxy service command are described in the following table.

Short option key Long option key      Description

-h

–help

prints this command help

-w

–cluster-wide

start proxy service cluster wide

This command is useful in starting a proxy service in a single instance or a cluster of instances which has been stopped previously for some maintenance.

Related Commands

proxy-service-stop

Endpoint Management Commands

Endpoint management commands are used to manage and monitor endpoint artifacts deployed in a running UltraESB instance or a cluster of UltraESB instances. This section describes each and every command in the endpoint management category.

The commands of UTerm under endpoint management are;

List endpoints

List endpoints command lists the endpoints deployed on a running UltraESB instance. The short form of the command is ’lep` which is equivalent to calling it’s long form'list-endpoints

Short command

epl

Long command

endpoint-list

Available options for the list endpoints command are described in the following table.

Short option key Long option key Description

-a

–all

list all the endpoints

-h

–help

prints the command help

-i

–with-info

list endpoints with there respective information

-s

–with-state

list endpoints with there respective states

If no options were given it lists only the endpoints in the started state, you can use this command with '-a' option to list all the endpoints regardless of the state. You can get a tabular dataset describing the endpoints while listing it by passing the '-i' option.

If '-i' option is passed, the '-s' option makes no sense as it already prints the state.

Related Commands

get-endpoint

Get endpoint

Get endpoint command gives a representation of an endpoint with the given identifier deployed on a running UltraESB instance. The short form of the command is ’getep` which is equivalent to calling it’s long form'get-endpoint

Short command

getep

Long command

get-endpoint

Available options for the get endpoint command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

This command is useful in scripting where you want to get certain attributes of a endpoint to automate some action.

Related Commands

endpoint-list

Disable debug of endpoint

Disable debug of endpoint command disables debugging of the endpoint with the given identifier deployed on a running UltraESB instance. The short form of the command is ’ddbep` which is equivalent to calling it’s long form'disable-debug-endpoint

Short command

 epdbd

Long command

endpoint-debug-disable

Available options for the disable debug of endpoint command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

disable debug for endpoint cluster wide

This command is useful to disable debug for a specific endpoint that has been enabled debug previously to figure out some situation with that endpoint, cluster wide, both in integration as well as production environments.

Related Commands

endpoint-debug-enable

Enable debug of endpoint

Enable debug of endpoint command enables debugging of the endpoint with the given identifier deployed on a running UltraESB instance. The short form of the command is ’edbep` which is equivalent to calling it’s long form'endpoint-debug-enable

Short command

epdbe

Long command

endpoint-debug-enable

Available options for the enable debug of endpoint command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

enable debug for endpoint cluster wide

This command is useful to enable debug for a specific endpoint that needs to examine the debug logs to figure out some situation with that endpoint, cluster wide, both in integration as well as production environments.

Related Commands

endpoint-debug-disable

Reset statistics of endpoint

Reset statistics of endpoint command resets the collected statistics at that point of the endpoint with the given identifier deployed on a running UltraESB instance. The short form of the command is ’rststep` which is equivalent to calling it’s long form'endpoint-statistics-reset

Short command

epstrst

Long command

endpoint-statistics-reset

Available options for the reset statistics of endpoint command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

reset statistics for endpoint cluster wide

This command is useful to reset statistics for a specific endpoint collected so far (or to set the statistics meter to zero) that needs to examined, cluster wide, on production environments.

Clear the statistics frame to start looking at the current behaviour
You may reset the statistics of a endpoint cluster wide and then monitor them again to see any more messages failing or any specific error which is occurring.
Stop endpoint

Stop endpoint command is used to stop a running endpoint deployed on an UltraESB instance. The short form of the command is ’epstp` which is equivalent to calling it’s long form'endpoint-stop

Short command

epstp

Long command

endpoint-stop

Available options for the stop endpoint command are described in the following table.

Short option key Long option key      Description

-h

–help

prints this command help

-w

–cluster-wide

stop endpoint cluster wide

This command is useful in stopping a specific endpoint in a single instance or a cluster of instances which needs to be stopped for maintenance.

Related Commands

start-endpoint

Start endpoint

Start endpoint command is used to start a stopped endpoint deployed on a running UltraESB instance. The short form of the command is ’epstr` which is equivalent to calling it’s long form'endpoint-start

Short command

epstr

Long command

endpoint-start

Available options for the start endpoint command are described in the following table.

Short option key Long option key      Description

-h

–help

prints this command help

-w

–cluster-wide

start endpoint cluster wide

This command is useful in starting a endpoint in a single instance or a cluster of instances which has been stopped previously for some maintenance.

Related Commands

stop-endpoint

Sequence Management Commands

Sequence management commands are used to manage and monitor sequence artifacts deployed in a running UltraESB instance or a cluster of UltraESB instances. This section describes each and every command in the sequence management category.

The commands of UTerm under sequence management are;

List sequences

List sequences command lists the sequences deployed on a running UltraESB instance. The short form of the command is ’sql` which is equivalent to calling it’s long form'sequence-list

Short command

sql

Long command

sequence-list

Available options for the list sequences command are described in the following table.

Short option key Long option key Description

-a

–all

list all the sequences

-h

–help

prints the command help

-i

–with-info

list sequences with there respective information

-s

–with-state

list sequences with there respective states

If no options were given it lists only the sequences in the started state, you can use this command with '-a' option to list all the sequences regardless of the state. You can get a tabular dataset describing the sequences while listing it by passing the '-i' option.

If '-i' option is passed, the '-s' option makes no sense as it already prints the state.

Related Commands

sequence-view

Get sequence

Get sequence command gives a representation of a sequence with the given identifier deployed on a running UltraESB instance. The short form of the command is ’sqv` which is equivalent to calling it’s long form'sequence-view

Short command

sqv

Long command

sequence-view

Available options for the get sequence command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

This command is useful in scripting where you want to get certain attributes of a sequence to automate some action.

Related Commands

sequence-list

Disable debug of sequence

Disable debug of sequence command disables debugging of the sequence with the given identifier deployed on a running UltraESB instance. The short form of the command is ’sqdbd` which is equivalent to calling it’s long form'sequence-debug-disable

Short command

sqdbd

Long command

sequence-debug-disable

Available options for the disable debug of sequence command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

disable debug for sequence cluster wide

This command is useful to disable debug for a specific sequence that has been enabled debug previously to figure out some situation with that sequence, cluster wide, both in integration as well as production environments.

Related Commands

sequence-debug-enable

Enable debug of sequence

Enable debug of sequence command enables debugging of the sequence with the given identifier deployed on a running UltraESB instance. The short form of the command is ’ sqdbe` which is equivalent to calling it’s long form'sequence-debug-enable

Short command

 sqdbe

Long command

sequence-debug-enable

Available options for the enable debug of sequence command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

enable debug for sequence cluster wide

This command is useful to enable debug for a specific sequence that needs to examine the debug logs to figure out some situation with that sequence, cluster wide, both in integration as well as production environments.

Related Commands

sequence-debug-disable

Reset statistics of sequence

Reset statistics of sequence command resets the collected statistics at that point of the sequence with the given identifier deployed on a running UltraESB instance. The short form of the command is ’sqstrst` which is equivalent to calling it’s long form'sequence-statistics-reset

Short command

sqstrst

Long command

sequence-statistics-reset

Available options for the reset statistics of sequence command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-w

–cluster-wide

reset statistics for sequence cluster wide

This command is useful to reset statistics for a specific sequence collected so far (or to set the statistics meter to zero) that needs to examined, cluster wide, on production environments.

Clear the statistics frame to start looking at the current behaviour
You may reset the statistics of a sequence cluster wide and then monitor them again to see any more messages failing or any specific error which is occurring.
Stop sequence

Stop sequence command is used to stop a running sequence deployed on an UltraESB instance. The short form of the command is ’sqstp` which is equivalent to calling it’s long form'sequence-stop

Short command

sqstp

Long command

sequence-stop

Available options for the stop sequence command are described in the following table.

Short option key Long option key      Description

-h

–help

prints this command help

-w

–cluster-wide

stop sequence cluster wide

This command is useful in stopping a specific sequence in a single instance or a cluster of instances which needs to be stopped for maintenance.

Related Commands

sequence-start

Start sequence

Start sequence command is used to start a stopped sequence deployed on a running UltraESB instance. The short form of the command is ’sqstr` which is equivalent to calling it’s long form' sequence-start

Short command

sqstr

Long command

sequence-start

Available options for the start sequence command are described in the following table.

Short option key Long option key      Description

-h

–help

prints this command help

-w

–cluster-wide

start sequence cluster wide

This command is useful in starting a sequence in a single instance or a cluster of instances which has been stopped previously for some maintenance.

Related Commands

sequence-stop

Logger Management Commands

Logger management commands are used to manage loggers. This section describes each and every command in the logger management category.

The commands of UTerm under server management are;

Change logger level

Change logger level command can be used to change the level of a logger. The short form of the command is ’llch` which is equivalent to calling it’s long form'log-level-change

Short command

llch

Long command

log-level-change

Available options for the list servers command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-l

–logger-level <arg>

new log level of logger

To invoke this command the '-l' option is mandatory where you have to give the new logger level as the argument. As an example , to change the log level of logger org.adroitlogic.ultraesb.core.ConfigurationImpl from INFO to WARN use command 

llch -l WARN org.adroitlogic.ultraesb.core.ConfigurationImpl
List loggers

List loggers command lists the loggers available in given  . The short form of the command is ’lls` which is equivalent to calling it’s long form'logger-list

Short command

lls

Long command

logger-list

Available options for the list loggers command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-p

–package

show log level of given package

If no option was given it lists all the loggers available in given package level as well as loggers of sub package levels.

As an example to view loggers of all the sub packages of  org.adroitlogic.ultraesb.core, use lls  org.adroitlogic.ultraesb.core which shows shows log levels of o.a.u.core.helper.LoggerUtilsManager,

o.a.u.core.mgt.EndpointManagement, o.a.u.core.Sequence.error-handler . To view the package level logger use,

lls  -p org.adroitlogic.ultraesb.core
Add new logger

Add new logger command can be used to add a new command . The short form of the command is ’lad` which is equivalent to calling it’s long form'logger-add

Short command

lad

Long command

logger-add

Available options for the list loggers command are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-l

–level <arg>

set level of the logger

-a

–additivity

sets whether the additivity of logger is true or false

To invoke this command the '-l' option is mandatory where you have to define the log level of the newly creating logger as an argument. Option '-a' is used to set the additivity of the logger. If you use option '-a' additivity will set to 'true' otherwise to 'false'. As an example to create a new logger with loglevel 'INFO' and additivity 'true' use,

lad -a -l INFO  org.adroitlogic.ultraesb.core.myPackage

Change logger additivity

Change logger additivity command can be used to change the additivity. The short form of the command is ’ach’ which is equivalent to calling it’s long form 'additivity-change'

Short command

ach

Long command

additivity-change

Available options for the change logger additivity are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-a

–additivity <arg>

new additivity of logger

To invoke this command the '-a' option is mandatory where you have to define the additivity you want to change to(true/false) as an argument. As an example, to change the additivity of the logger org.adroitlogic.soapbox.CryptoSupport from false to true use

ach -a true org.adroitlogic.soapbox.CryptoSupport
Watch logs

Watch logs command can be used to watch logs of the connected UltraESB server. The short form of the command is ’lgw’ which is equivalent to calling it’s long form 'log-watch'

Short command

lgw

Long command

log-watch

Available options for the watch logs are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-i

–refresh-interval <arg>

set the refresh time interval for log fetching in seconds, which defaults to 3 seconds

If no options were given it use default refresh interval which is 3 seconds for log fetching. You can define a custom refresh interval as well. As an example , to watch logs with refresh interval 4 use

lgw -i 4
Update log appender

Update log appender command can be used to update the Log appenders defined for logging. The short form of the command is 'apu' which is equivalent to calling it’s long form 'log-watch'

Short command

apu

Long command

appender-update

Available options for the update log appender are described in the following table.

Short option key Long option key Description

-h

–help

prints the command help

-p

–appender-pattern <arg>

new appender pattern

-t

–appender-threshold <arg>

new appender threshold

To change the appender pattern user option '-p' with pattern as parameter. To change the appender thresholdI use option '-t' with threshold as a parameter. You can use one or both options at a time.

As an example to update the appender MEMORY_APPENDER with new pattern %m%n and new threshold WARN use, 

apu -p %m%n -t WARN MEMORY_APPENDER
JMS Client Commands

MS Client Commands provides the functionality to send and/or receive messages from JMS queues, and to delete messages containing in a queue. Before using the JMSclient commands it is necessary to copy the jar files needed by the JMS provider which is used. (E.g: for Websphere JMS provider com.ibm.ws.ejb.thinclient_X.jar, com.ibm.ws.orb_X.jar and com.ibm.ws.sib.client.thin.jms_X.jar are needed)

JMS Client commands will optionally need a profile. The specified profile will be looked up in the conf/management/uterm.properties file. A fragment of the uterm.properties file with a profile will be as follows

ultra.jms.providerUrl.prod=iiop://localhost:2809
ultra.jms.initialContextFactory.prod=com.ibm.websphere.naming.WsnInitialContextFactory
ultra.jms.connectionFactory.prod=jms/QCF.Test
ultra.jms.sendingDestination.prod=EsbIn
ultra.jms.receivingDestination.prod=EsbOut

The above profile is the "prod" profile. To create a like wise profile, simply replace "prod" with your preferred name and change the configuration values. Uterm is shipped with the default profile.  However configuring these ultra.jms.* properties is optional if the corresponding values are specified via the corresponding command options. In the case where the profile is configured and the command option also provided, the value in the profile will be overwritten by the value specified by the command option.

JMS Connect And Send

JMS connect and send command connects to the specified connection factory, send messages from the specified producer and receive messages from the consumer specified in the properties file. If a consumer is not specified the command exists after delivering the message. The short form of the command is ’jmssend` which is equivalent to calling it’s long form'jms-connect-and-send

Short command

jmssend

Long command

jms-connect-and-send

Available options for the jms send command are described in the following table.

Short option key Long option key Description

prfl

profile

config to be used to load the host name, port, connection factory jndi name, producer jndi name and the consumer jndi name

t

send-type

type of the message to be sent eg: map or text

p

properties

properties to be set for the message, specified as key values pairs separated by commas

s

strings

string values to be sent, specified as key values pairs separated by commas

bf

byte-files

files to be sent as bytes, specified as key values pairs separated by commas

sf

string-files

files to be sent as strings, specified as key values pairs separated by commas

url

provider-url

the jms provider url - if the config file is provided this is optional

initCntxFac

init-context-factory

InitialContextFactory which is used to lookup JMS connection factory objects as well as destination objects - if the config file is provided this is optional

konFac

kon-factory-jndi-name

jndi name of the connection factory - if the config file is provided this is optional

sender

sender-jndi-name

message producer’s jndi name - if the config file is provided this is optional

receiver

receiver-jndi-name

message consumer’s jndi name - if the config file is provided this is optional

Use Cases

  1. Sending a message to a JMS queue using configuration profile
    Configure the profile with only the following properties
    ultra.jms.providerUrl.prod=iiop://localhost:2809
    ultra.jms.initialContextFactory.prod=com.ibm.websphere.naming.WsnInitialContextFactory
    ultra.jms.connectionFactory.prod=jms/QCF.Test
    ultra.jms.sendingDestination.prod=EsbIn
    Issue the command : jmssend -t map -prfl prod -s name:foo,age:24 -sf description:/home/Desktop/about.txt -bf cv:/home/Desktop/resume.pdf

  2. Sending a message to a JMS queue using command options
    Issue the command :  jmssend -t map -s name:foo,age:24 -sf description:/home/Desktop/about.txt -bf cv:/home/Desktop/resume.pdf  -url iiop://localhost:2809 -konFac  jms/QCF.Test  -sender EsbIn  -initCntxFac com.ibm.websphere.naming.WsnInitialContextFactory
     

  3. Sending and receiving message using the configuration profile and command options
    If the profile in 1. is used, it does not specify the receiver destination. The receiver destination can be specified via command option
    Issue the command : jmssend -t map -prfl prod -s name:foo,age:24 -sf description:/home/Desktop/about.txt -bf cv:/home/Desktop/resume.pdf -receiver EsbOut

Delete All Messages

JMS delete all command deletes all the messages in the queue specified by the queue jndi name. The short form of the command is ’jdelall` which is equivalent to calling it’s long form'jms-delete-all

Short command

jdelall

Long command

jms-delete-all

Available options for the jms delete all command are described in the following table.

Short option key

Short option key Long option key Description

prfl

profile

the configuration to be used to load the provide url, initial context factory, connection factory JNDI name and the destination queue JNDI name. If the remaining options are provided

q

queue-jndi-name

JNDI name of the queue, where the messages are to be deleted - if the queue name is provided in the config file. However if specified value in the configuration file will be overridden

konFac

kon-factory-jndi-name

JNDI name of the connection factory - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

url

provider-url

the jms provider url - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

initContxFac

init-context-factory

InitialContextFactory which is used to lookup JMS connection factory objects as well as destination objects - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

Use Cases

  1. Deleting messages using the profile
    Configure the profile with only the following properties
    ultra.jms.providerUrl.prod=iiop://localhost:2809
    ultra.jms.initialContextFactory.prod=com.ibm.websphere.naming.WsnInitialContextFactory
    ultra.jms.connectionFactory.prod=jms/QCF.Test
    ultra.jms.ReceivingDestination.prod=EsbOut
    NOTE: The queue which the messages to be deleted should be configured as ultra.jms.ReceivingDestination.profileName
    Issue the command : jdelAll -prfl prod

  2. Deleting messages using the profile and command options
    Issue the command : jdelAll -prfl prod -q EsbIn
    The "EsbOut" queue destination configured in the profile will  be overridden by EsbIn

Read Next

The read next command reads immediate message in the specified queue. The short form of the command is ’readNextMsg` which is equivalent to calling it’s long form'jms-read-next

Short command

readNextMsg

Long command

jms-read-next

Available options for the jms read next command are described in the following table.

 
Short option key Long option key Description

prfl

profile

the configuration to be used to load the provide url, initial context factory, connection factory JNDI name and the destination queue JNDI name. If the remaining options are provided

q

queue-jndi-name

JNDI name of the queue, where the messages are to be deleted - if the queue name is provided in the config file. However if specified value in the configuration file will be overridden

konFac

kon-factory-jndi-name

JNDI name of the connection factory - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

url

provider-url

the jms provider url - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

initContxFac

init-context-factory

InitialContextFactory which is used to lookup JMS connection factory objects as well as destination objects - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

msgid

message-id

specify the identifier of the message which is needed to be read

Use Cases

  1. Reading a messages using the profile
    Configure the profile with only the following properties
    ultra.jms.providerUrl.prod=iiop://localhost:2809
    ultra.jms.initialContextFactory.prod=com.ibm.websphere.naming.WsnInitialContextFactory
    ultra.jms.connectionFactory.prod=jms/QCF.Test
    ultra.jms.ReceivingDestination.prod=EsbOut

    NOTE: The queue which the messages to be read, should be configured as ultra.jms.ReceivingDestination.profileName Issue the command : readNextMsg -prfl prod

Read All

The read all command reads all the messages in the specified queue. The short form of the command is ’jreadAll` which is equivalent to calling it’s long form'jms-read-all

Short command

readAllMsg

Long command

jms-read-all

Available options for the read all command are described in the following table.

Short option key Long option key Description

prfl

profile

the configuration to be used to load the provide url, initial context factory, connection factory JNDI name and the destination queue JNDI name. If the remaining options are provided

q

queue-jndi-name

JNDI name of the queue, where the messages are to be deleted - if the queue name is provided in the config file. However if specified value in the configuration file will be overridden

konFac

kon-factory-jndi-name

JNDI name of the connection factory - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

url

provider-url

the jms provider url - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

initContxFac

init-context-factory

InitialContextFactory which is used to lookup JMS connection factory objects as well as destination objects - if the config file is provided this is optional. However if specified value in the configuration file will be overridden

1.2.4. UTerm Configurations

This section provides a complete reference of possible customizations and configurations available for the UTerm. This document discusses command configurations like providing UltraESB instance connection configurations to the connect command and UTerm preferences.

All these configurations are done via the uterm.properties file located in the conf directory of the UltraESB installation.

UltraESB server instance definition

You can define UltraESB instances that the UTerm is connecting frequently as named server instances via the uterm.properties file.

In a usual connect command you need to provide the complete remote JMX URL of the UltraESB instance. This has major drawbacks like you have to remember the JMX URL, or at least copy-paste it every time you want to monitor an UltraESB instance. Situation gets worst when the remote JMX access is secured with password authentication (which is the usual case in any production deployment), where you have to specify the –username and the –password options too.

While this might be convenient if you just need to connect to a random UltraESB instance just to check something, if you have a well known UltraESB instance or a cluster of instances that you monitor/manage day-today, or even once a week, it is more convenient for you to be able to ask the UTerm to connect to that instance passing a identifier.

The server instance definition in the uterm.properties file addresses exactly this. You can assign a server name or an identifier with a well-known UltraESB instance and optionally define credentials to be used when connecting to that instance. Once configured connecting to that UltraESB instance from the UTerm just requires the identifier or the server name that you used to define that UltraESB instance.

Best Practice - Use hostname as the instace Identifier
Use the hostname of the machine running the UltraESB instance when defining the individual instances, if you have a cluster, so that you can connect to any individual node by using the hostname passed to the connect command.

The definition of the JMX URL of an UltraESB instance should be configured as follows on the uterm.properties file.

ultra.jmx.url.<identifier>=<UltraESB-instance-JMX-URL>

Here the identifier could be any string, which can be used to connect to the specified JMX URL as follows.

uterm> con <identifier>

If the remote JMX access is secured the username and the password can be configured with the following properties in addition to the URL.

ultra.jmx.username.<identifier>=<JMX-username>
ultra.jmx.password.<identifier>=<JMX-password>

Multiple instances can be configured for different identifiers and the identifier can be used to connect to the specific instance.

For example the following configuration defines an UltraESB instance with the identifier "esb1";

ultra.jmx.url.esb1=service:jmx:rmi://esb1:9994/jndi/rmi://esb1:1099/ultra
ultra.jmx.username.esb1=admin
ultra.jmx.password.esb1=admin

Now to connect to the UltraESB instance running on esb1 from UTerm, you just need to use;

uterm> con esb1

The identifier "default" is treated as a special identifier, if configured, the UTerm treats it as the default connection URL and credentials. UTerm doesn’t require an explicit connection to the default instance, any command query will be executed over the default instance if you are not connected to any instance.

Default instance doesn’t require connect command
Default instance, if configured doesn’t require a connection. If you have only one UltraESB instance or if you have a preferred instance in a cluster which you most of the time connects to, you can define that as the default, so that you do not need to use the connect command before to query that instance.

Note that even if you have a cluster you could manage all the nodes in the cluster from any single node so having a default server to connect in the cluster will be quite useful too.

UTerm preferences

This sub sections introduces the preferences for the UTerm, where you can customize the behaviour and the look and feel of the UTerm.

Unlike in most of the UNIX based commands UTerm uses a print width of 120 characters by default. As the UTerm is intended to be run on your desktop to manage and monitor the UltraESB instances and today monitor resolutions support lot more than 80 characters (which is the UNIX default print-width), UTerm by default prints 120 characters per line.

However in case of a requirement to run UTerm on a server terminal with lessor resolution, or if you feel comfortable with any other print-width, you can do so by configuring the print-width property in the uterm.properties file.

The exact property name is "ultra.terminal.print-width" and you can assign any sensible integer as the value.

ultra.terminal.print-width=<Width-as-Integer>

You may also increase the print width beyond 120 characters, using the print-width property.

1.2.5. Extending UTerm

UTerm provides you all the required bits and pieces to monitor and manage the UltraESB instance on a command line. Given that, sometimes users have there own custom requirements to monitor there solutions/applications deployed on the UltraESB, in which case the UTerm custom extension capability can be used to include new commands into the UTerm.

Writing a custom command

Writing a custom command just requires writing the logic that you want to expose as a command. This class should have the methods which contain the commands that you want to expose annotated with the UTerm runtime runtime annotations.

This sub section shows how to write a command class exposing two commands to the users via the UTerm. Before starting the exercise, there are few things that needs your attention. You need to take a dependency on the ultraesb-uterm library.

Extend from CommandsBase

If your command talks to any of the UltraESB MXBeans exposed over JMX, which is most likely to be the case, extending from the abstract CommndsBase class is helpful, as it provides very convenient way of accessing the MXBean interfaces.

Note
Not a must to extend from CommandsBase, but you should if using the UltraESB MXBeans.

The full qualified class name of the CommandsBase is "org.adroitlogic.ultraesb.terminal.commands.CommandsBase", we will see the usage of this to call the JMX MXBeans to retrieve data from the UltraESB instance inside the command implementation.

Should throw TerminalException

To use the error handling and proper error reporting capabilities of the UTerm framework, any method exposed as a command should throw a TerminalException. The full qualified class name of the TerminalException is "org.adroitlogic.ultraesb.terminal.TerminalException"

It is recommended that you catch all possible exceptions within the method implementation and only throw a TerminalException with a sensible message, as that will displayed to the user on an error condition.

Use of MultiColumnResult

If the results of a particular command should be formatted into a multi column tabular data format, you should use a MultiColumnResult object to return the dataset. This will help the command implementation to completely concentrate on the commands functionality, while the result set formatting being transparently handled by the UTerm framework.

The full qualified class name of the MultiColumnResult is "org.adroitlogic.ultraesb.terminal.util.MultiColumnResult".

So the resulting class would be as follows;

package org.adroitlogic.ultraesb.terminal.commands;

import org.adroitlogic.ultraesb.jmx.JMXConstants;
import org.adroitlogic.ultraesb.jmx.core.EndpointManagementMXBean;
import org.adroitlogic.ultraesb.jmx.core.SequenceManagementMXBean;
import org.adroitlogic.ultraesb.jmx.view.EndpointView;
import org.adroitlogic.ultraesb.jmx.view.SequenceView;
import org.adroitlogic.ultraesb.terminal.TerminalException;

import java.util.ArrayList;
import java.util.List;

public class SearchCommand extends CommandsBase {

  public List<String> searchEndpoints(String contains, boolean caseSensitive) throws TerminalException {
    if (contains == null) {
      throw new TerminalException("Search string cannot be null");
    }

    List<String> searchResults = new ArrayList<String>();
    for (EndpointView endpoint : getMXBeanProxy(JMXConstants.MXBEAN_NAME_ENDPOINTS,
          EndpointManagementMXBean.class).getEndpoints()) {
      if (contains(endpoint.getId(), contains, caseSensitive)) {
        searchResults.add(endpoint.getId());
      }
    }
    return searchResults;
  }

  public List<String> searchSequences(String contains, boolean caseSensitive) throws TerminalException {
    if (contains == null) {
      throw new TerminalException("Search string cannot be null");
    }

    List<String> searchResults = new ArrayList<String>();
    for (SequenceView endpoint : getMXBeanProxy(JMXConstants.MXBEAN_NAME_ENDPOINTS,
          SequenceManagementMXBean.class).getSequences()) {
      if (contains(endpoint.getId(), contains, caseSensitive)) {
        searchResults.add(endpoint.getId());
      }
    }
    return searchResults;
  }

  private boolean contains(String id, String contains, boolean caseSensitive) {
    if (!caseSensitive) {
      id = id.toUpperCase();
      contains = contains.toUpperCase();
    }
    return id.indexOf(contains) != -1;
  }

}

If you carefully look at this class you will be able to see that we use the "getMXBeanProxy" method defined in the CommandsBase to very easily get hold of a MXBean reference and talk to the UltraESB instance via JMX to retrieve data all transparently.

Now we have written the class with using all the optimizations of the UTerm framework, yet it is not a command. We need to annotate the methods which are exposed as commands using the following annotations for it to be complete.

UTerm Annotations

There are two major types of annotations that helps to specify the meta information require in converting a method into a command on UTerm.

TerminalCommand annotation

This annotation is a markable annotation with certain metadata describing the command into the UTerm framework. The retention policy for this annotation is runtime and is targeting method element type. It has 4 properties to describe the command.

Property Name Usage Type Required

name

the long form name of the command

String

YES

alias

the short form name of the command

String

YES

description

the description of the command to be used in printing the usage with help

String

YES

helpFooter

the footer of the usage help, if any

String

NO

As you can see these properties completely describes the command, and this annotation helps the command writer concentrate on the functionality without bothering about how to expose it as a command.

Decouples the command properties from the logic
TerminalCommand annotation decouples the command properties from the execution logic so that implementing a command is just a matter of writing a Java method which does some unit of work.

Full qualified class name of the annotation class is "org.adroitlogic.ultraesb.terminal.annotations.TerminalCommand".

CommandOption annotation

This annotation also is a markable annotation with certain metadata describing the command options of a particular command into the UTerm framework. The retention policy for this annotation is runtime and is targeting method parameter element type. It has 4 properties to describe the command options, and used to make additional/optional method parameters into options in executing the command.

Property Name Usage Type Required

shortForm

the short form (single letter) name of the command option, at usage prefixed with '-'

String

YES

longForm

the long form name of the command option, at usage prefixed with '–'

String

YES

argument

whether the option requires an argument

Boolean

NO

description

the description of the command option to be used in printing the usage with help

String

YES

As you can see these properties completely describes the command option, and this annotation helps the command writer concentrate on the functionality without bothering about how to map method parameters into command options.

Command options are most of the time boolean switches
While it is possible to have options providing arguments to the command execution, most of the time the command options are boolean parameters specifying a switch in the execution

Full qualified class name of the annotation class is "org.adroitlogic.ultraesb.terminal.annotations.CommandOption".

With these annotations we could convert over class to expose 2 commands out of the 2 methods by annotating the methods and method parameters as follows;

package org.adroitlogic.ultraesb.terminal.commands;

import org.adroitlogic.ultraesb.jmx.JMXConstants;
import org.adroitlogic.ultraesb.jmx.core.EndpointManagementMXBean;
import org.adroitlogic.ultraesb.jmx.core.SequenceManagementMXBean;
import org.adroitlogic.ultraesb.jmx.view.EndpointView;
import org.adroitlogic.ultraesb.jmx.view.SequenceView;
import org.adroitlogic.ultraesb.terminal.TerminalException;
import org.adroitlogic.ultraesb.terminal.annotations.CommandOption;
import org.adroitlogic.ultraesb.terminal.annotations.TerminalCommand;

import java.util.ArrayList;
import java.util.List;

public class SearchCommand extends CommandsBase {

  @TerminalCommand(
      name = "search-endpoints",
      alias = "sep",
      description = "search the endpoints with id containing the given string")
  public List<String> searchEndpoints(String contains,
    @CommandOption(
        shortForm = "s",
        longForm = "case-sensitive",
        description = "search the term case sensitively") boolean caseSensitive) throws TerminalException {
    if (contains == null) {
      throw new TerminalException("Search string cannot be null");
    }

    List<String> searchResults = new ArrayList<String>();
    for (EndpointView endpoint : getMXBeanProxy(JMXConstants.MXBEAN_NAME_ENDPOINTS,
          EndpointManagementMXBean.class).getEndpoints()) {
      if (contains(endpoint.getId(), contains, caseSensitive)) {
        searchResults.add(endpoint.getId());
      }
    }
    return searchResults;
  }

  @TerminalCommand(
      name = "search-sequences",
      alias = "ssq",
      description = "search the sequences with id containing the given string")
  public List<String> searchSequences(String contains,
    @CommandOption(
        shortForm = "s",
        longForm = "case-sensitive",
        description = "search the term case sensitively") boolean caseSensitive) throws TerminalException {
    if (contains == null) {
      throw new TerminalException("Search string cannot be null");
    }

    List<String> searchResults = new ArrayList<String>();
    for (SequenceView endpoint : getMXBeanProxy(JMXConstants.MXBEAN_NAME_ENDPOINTS,
          SequenceManagementMXBean.class).getSequences()) {
      if (contains(endpoint.getId(), contains, caseSensitive)) {
        searchResults.add(endpoint.getId());
      }
    }
    return searchResults;
  }

  private boolean contains(String id, String contains, boolean caseSensitive) {
    if (!caseSensitive) {
      id = id.toUpperCase();
      contains = contains.toUpperCase();
    }
    return id.indexOf(contains) != -1;
  }

}

The annotated class represents a command and the registration of this command into UTerm framework will be discussed next.

Long and short form command names should be unique
For the command to be operational within UTerm the given short form and the long form of the command names need to be unique, before selecting the command name (specially the short form) you better have a look at the available commands under the Command Reference.
Integrating the command into UTerm

Hard part is already done and we have the command source now. The above source should be compiled and packed into a jar file, and copy it to the lib/custom directory (which is the place where you put all the custom libraries) of the UltraESB installation.

After making it available in the class path it is just a matter of configuring the class name as an extension to UTerm via the uterm.properties file with the property key "ultra.terminal.command.ext.x" where x is an incrementing number starting from 1 for each and every command class.

So integrating our command into the UTerm can be done with adding the following property into the uterm.properties file.

ultra.terminal.command.ext.1=org.adroitlogic.ultraesb.terminal.commands.SearchCommand

Now if you start UTerm and type in help you will be able to see our new command appearing on the list of available commands and you could see the usage of the command with the -h option.

uterm> sep -h
usage: sep
'sep' equivalent to 'search-endpoints'
search the endpoints with id containing the given string
 -h,--help             prints this command help
 -s,--case-sensitive   search the term case sensitively

uterm>

Then if you try to invoke this command over default UltraESB instance for searching "out" endpoints, it will be as follows;

uterm> sep out
echo-proxy-outDestination
uterm>
Help option is automatically added
The usage of this command given the ’-h` option too, which we have not declared, but the UTerm framework adds the'-h’ option to all the commands by default.

That is it about UTerm and its value.

1.3. IntelliJ IDEA Plugin

IntelliJ IDEA plugin for the UltraESB has integrated the following features into IntelliJ IDEA IDE. But first, please refer the installation guide.

1.3.1. Creating a UltraESB Multi-Module Project

IMPORTANT
You cannot add a multi-module project as a new module to an existing project. You can only create new multi-module projects.  
  1. In order to create a new multi-module project, launch 'New Project' wizard by File → New Project… and select 'Multi Module Project'. Then give a project name, location and press next.

    projectx 1
  2. After that fill the maven specific settings by giving a group ID and a version.

    projectX 2
  3. Then IDEA will create a maven multi-module project with a sample pom.xml file and after that go to 'Maven Projects' tab and click refresh button so that IDEA could download all dependencies and configure the project.

    projectX 3
  4. Now your project is ready to add Deployment Units.

1.3.2. Creating Deployment Units

  1. In-order to create a new UltraESB Deployment Unit module, launch ’New Module’ wizard by File → New Module… and select 'Deployment Unit'. Then give a module name and press next.

    unita 1
  2. After that fill the maven specific settings by giving a group ID and a version. Then select whether you want to create a sample or an empty deployment unit, and give a base package name. If you’re creating a sample deployment unit, then you can specify the main java class name and the test class name too. After that flick finish button.

    new
  3. Next IDEA will automatically configure all the dependencies and you can start developing the deployment unit.

    unita 3

1.3.3. File templates and Live templates

File Templates

You can add a new sequence class to your deployment unit using a predefined file template as below. Just right click on the package, where you want to add a new sequence and from the pop-up menu select 'UltraESB Sequence'. After creating a new sequence class, a corresponding <u:sequence> tag will be automatically added to the ultra-unit.xml file

unita 4
Live Templates

This plugin contains few live templates, and by pressing Ctrl+J within an ultra-unit.xml file, would show you a list of all the available live templates.

Live Template Generated Code Segment

ujava

<u:java><![CDATA[

]]></u:java>

useq

<u:sequence id="">

</u:sequence>

uep

<u:endpoint id="" type="">
<u:address type=""></u:address>
</u:endpoint>

uproxy

<u:proxy id="">
<u:transport id=""/>
<u:target inSequence="">

</u:target>
</u:proxy>

1.3.4. IntelliJ IDEA Plugin Installation

  • In-order to install AdroitLogic UltraESB Integration plugin, open the settings window (Files → Settings) and then navigate to the 'Plugins' section. 

  • Within the plugins section, click on the `Browse repositories…' button and you’ll be presented with a window which contains all the plugins in the IDEA repository. 

  • Select the AdroitLogic UltraESB Integration plugin and click on the ’Download and Install button.

install

1.3.5. Language injection and code generation

Language Injection

Now you can directly write Java code within <u:java> tags in ultra-unit.xml file without any manual configuration as below.

inject
Code Generation
  1. In-order to add a proxy, an endpoint or a sequence to the ultra-unit.xml file, you can use code generation facility. Right click within the ultra-unit.xml file and select what type of tag you want to generate.

    generation
  2. Based on the type you select, a respective dialog box will appear. Fill the relevant fields, click OK and the code will be generated in ultra-unit.xml

    unita 8 new proxy
    create new sequence

1.4. SOA Toolbox

The SOA ToolBox is a basic service and ESB test toolkit bundled with the UltraESB. It allows one to start a sample server instance hosting a set of pre-built RESTful web services, JAX-WS SOAP services, and raw HTTP echo servlets, Text and HTML servlets, and then issue sample requests to these services through the HTTP/S or JMS client modules. The HTTP/S client supports REST, POX, Text and binary payloads (such as Hessian) and supports the POST, GET, PUT, DELETE, HEAD, OPTIONS and TRACE methods in addition to many other features. The ToolBox ships with a built-in TCP dump module, able to report wire traffic as text or Hex formatted binary and additionally allows the message to be saved to a file for replay with a load test etc. Other modules of the ToolBox includes a JMS Client, raw socket level client usually used to test the ability of a service or an ESB to face invalid, malformed or malicious requests, and a high performance HTTP/S load test module.

1.4.1. Introduction

The AdroitLogic UltraESB is designed to help test and troubleshoot service and ESB test scenarios with ease. The ToolBox comprises of the following modules, and can be started with the "toolbox.sh" [Linux] or "toolbox.bat" [Windows] scripts.

1.4.2. The Jetty Server

starting jetty

The sample Jetty server comes with a RESTful Web Service sample at URL [http://localhost:9000/rest-services/customers]. The HTTP/S client preset "3" shows a sample request expected by this service. This service can be used to test the POST, GET, PUT, DELETE, HEAD, OPTIONS and TRACE methods. The Jetty server also contains an implementation of the SimpleStockQuoteService (copied with modifications from the Apache Synapse project). This service expects a slightly different message (HTTP/S client prefix "1") than the format expected by Synapse 1.2.x. (HTTP/S client prefix "2"). The EchoService is a high performance service which will echo back the request received. Thus it can be used to echo back various message sizes - say 1K, 5K, 10K etc for load and performance testing. Specifying an Echo service delay, causes the responses to be delayed by the specified number of milliseconds. This is useful to analyze how an ESB not using a Non-Blocking IO approach can easily block, when handling a large number of concurrent connections - which must be kept open until the delayed responses are received. The sample service also contains a servlet that will output a plain text response and an HTML response, to analyze how the UltraESB can handle these types of responses.

1.4.3. The HTTP/S Client

The HTTP/S client module provides a full RFC 2616 compliant HTTP/S client based on the Apache HttpComponents/HttpClient project. It can perform HTTP/S POST, GET, PUT, DELETE, HEAD, OPTIONS & TRACE and support 2-way SSL, or ignore SSL validation, and support basic or digest authentication. The preset payloads allows one to easily interact with the sample services hosted over the Jetty server, and experiment with the UltraESB samples. Payload could be typed into the text area or picked up from a file. However the correct content type should be selected as appropriate. It is even possible to use the HTTP/S client to test binary payloads - such as raw Hessian messages - which could easily be captured from the TCP dump module. The HTTP/S client supports both HTTP 1.0 and 1.1 versions, and can control the use of chunking, expectation control (i.e. waiting for a 100 continue reply before sending the body), keepalive and response compression control (i.e. accepting Gzipped responses). The socket timeout allows the client to specify the maxium delay for a response to arrive before the client times out. When sending SOAP requests, the SOAPAction maybe specified as well. Once a request is sent out, the response received is displayed on the text area below.

starting http client

1.4.4. TCP Dump

The TCP Dump module allows one to easily monitor, and optionally capture the messages sent at the wire level for debugging, or capturing (e.g. for a subsequent load test) purposes. The messages can be captured as Text, or binary Hex. The Listen port accepts messages on the local machine where the ToolBox is executed, and forwards the message to the Forward Host over the Forward Port specified. To save the request being sent, specify a file with the full path in the Save request to file option

starting tcp dump

1.4.5. JavaBench Load Test client

The JavaBench load test client consists of all the features of the standard HTTP/S client, but can be used to load test services or an ESB. Please see the description of the standard HTTP/S client for the core capabilities of the JavaBench. In addition, the concurrency specifies the number of virtual users or number of requests made in parallel during a load test run. The Iterations specifiies how many times the selected operation is performed by one virtual user. Using the Verbosity, one can see the headers, or even the payload body over the wire - but use of this will adversely affect the performance capabilities.

starting java bench

A typical load test run reports the following information, which is very similar to the report format used by the Apache Bench load testing tool.

Server Software:        Jetty(6.1.21)

Server Hostname:        localhost
Server Port:            9000

Document Path:          http://localhost:9000/service/EchoService
Document Length:        294 bytes

Concurrency Level:      20
Time taken for tests:       0.098607 seconds
Complete requests:      200
Failed requests:        0
Write errors:           0
Total transferred:      117600 bytes
Requests per second:    2,028.25 [#/sec] (mean)
Time per request:       9.861 [ms] (mean)
Time per request:       0.493 [ms] (mean, across all concurrent requests)
Transfer rate:          588.19 [Kbytes/sec] received
                        588.19 kb/s sent
                        1,186.53 kb/s total

1.4.6. The Raw Socket Client

The raw socket allows the user to send invalid, malformed, corrupted or malicious payloads to the selected host over the selected port. This is useful to test the negative test scenarios which are otherwise difficult to identify, reproduce and fix. Some service hosting engines and ESB’s may not be able to even accept malformed requests, even for logging purposes. Note that this is an advanced option and expects the user to be familiar with the HTTP RFC 2616 for operation. The most common mistake a novice user usually does is specifying a wrong content length - which should be the size of the payload in bytes. The payload must be separated from the header by a blank line.

starting raw socket client

1.4.7. A Simple end-to-end walkthrough

To start the AdroitLogic ToolBox, use the "toolbox.sh" or the "toolbox.bat" scripts found in the bin directory of your installation. Once started, the menu option will allow you to start one or more instances of the above modules. Thus it is possible to start Jetty server instances on ports 9000, 9001, 9002 etc for a load balancing test, or use two instances of the TCP Dump module to capture the traffic between the client and the ESB, and the ESB and the backend for example.
Simple Echo service request

First lets start the sample Jetty Server on the default port 9000 as shown above. Then open an instance of the HTTP/S client, and select the payload from Preset "1". Leaving all other options to the defaults, pressing the "Send" button will now display the response sent by the service at "http://localhost:9000/service/EchoService" for the request that we sent.
Using the ToolBox for RESTful experiments

If you now select Preset "3" from the HTTP/S client and use select the URL as "http://localhost:9000/rest-services/customers", you are able to create an instance of a Client in the RESTful web services example hosted by the Jetty server. You will receive a reply similar to the following:

HTTP/1.1 201 Created
Location: http://localhost:9000/rest-services/customers/1
Connection: close
Server: Jetty(6.1.21)

Now, copy the result of the "Location" header from your response (in this case "http://localhost:9000/rest-services/customers/1 ") and paste it into the URL field. Ensure that you do not copy or paste any unwanted characters or space. Now select GET method, and issue request. You should now see the response as follows:

HTTP/1.1 200 OK
Content-Type: application/xml
Connection: close
Server: Jetty(6.1.21)
<customer id="1">
   <first-name>Asankha</first-name>
   <last-name>Perera</last-name>
   <street>12 A 1 Pirivena Road</street>
   <city>Mount Lavinia</city>
   <state>LK</state>
   <zip>10370</zip>
   <country>Sri Lanka</country>
</customer>

Reslect payload from Preset "3", modify any of the values and select the PUT method on the above URL. You will now receive a response as follows, indicating that the resource has been updated.

HTTP/1.1 204 No Content
Connection: close
Server: Jetty(6.1.21)

Now issue a GET on the same URL, and you will see the updated information. If you issue a DELETE on the above URL, the resource will be deleted. You may experiment with the other options available with the HTTP/S client and other HTTP methods such as HEAD, OPTIONS, TRACE etc.

Note: The RESTful web service hosted on the Jetty server does not like new lines in the request. We will soon investigate the cause of this and update the sample to avoid the issue. In the meantime, you can use a payload without new lines (as shown by Preset "3") for your experiments.
Starting the UltraESB

Now, lets start the UltraESB using the configuration file "samples/conf/ultra-sample-101.xml". This will start a REST proxy service at URL "http://localhost:8280/service/rest-proxy". You could attempt the same REST operations discussed above against this URL and see how the UltraESB will proxy REST calls - without any interference to the flow. Additionally you will notice that the UltraESB performs"Location" header translation so that its users will never need to know about the read REST service or its URL.

For example, issue a Preset "3" request to the URL "http://localhost:8280/service/rest-proxy/customers" and you will get a response as follows, with the Location header appropriately re-written.

HTTP/1.0 201 Created
Location: http://localhost:8280/service/rest-proxy/customers/2
Date: Wed, 06 Jan 2010 05:21:01 GMT
Server: UltraESB/1.0-beta-1
Content-Length: 0
Connection: close

Thus, you can now GET, PUT, DELETE etc on the Proxy service URL exposed by the UltraESB - "http://localhost:8280/service/rest-proxy/customers/2 " to deal with the REST resource.

Back to Home Page