SwiftMQ Explorer

SwiftMQ Explorer is a graphical administration tool for SwiftMQ router networks. If offers the same functions as CLI, but is much more comfortable to operate.

In addition to CLI, changes are reported asynchronous to the SwiftMQ Explorer in the status of the respective router by so-called management messages. Therefore a current image of the router network status is always displayed.

Like CLI, SwiftMQ Explorer is based on the Router Configuration Files of the respective router.

SwiftMQ Explorer comes in its own distribution.

Starting SwiftMQ Explorer (JMS Version)

Unpack the distribution, go to the scripts directory and start Explorer as follows:

      ./explorer [<smqp-url> <cf> FN|CR <prot>|LATEST [<user> <password>]]

      Where <smqp-url>  SMQP-URL, e.g. smqp://localhost:4001/timeout=10000
            <cf>        JMS Connection Factory, e.g. ConnectionFactory
            FN          Manage full router network
            CR          Manage connected router only
            <prot>      SMQP protocol version, e.g. 610
            LATEST      Use latest SMQP protocol version
            <user>      JMS user
            <password>  JMS user's password

If you use Java 9 or higher, add java9 as the first parameter:

      ./explorer java9 [<smqp-url> <cf> FN|CR <prot>|LATEST [<user> <password>]]

      Where <smqp-url>  SMQP-URL, e.g. smqp://localhost:4001/timeout=10000
            <cf>        JMS Connection Factory, e.g. ConnectionFactory
            FN          Manage full router network
            CR          Manage connected router only
            <prot>      SMQP protocol version, e.g. 610
            LATEST      Use latest SMQP protocol version
            <user>      JMS user
            <password>  JMS user's password

SwiftMQ Explorer connects as a normal JMS client and thus requires JNDI-URL (SMQP-URL) and connection factory name. This can be specified on command line (since release 8.0.0) or, if not, the connect can be executed from a menu.

After starting, the SwiftMQ Explorer displays a main frame and a so-called navigator frame. The main frame is for connecting/disconnecting to/from a router network, for window arrangement and help functions. The navigator frame displays all routers of a connected router network with their management trees. All configuration task are to be performed via the navigator frame through popup menus, available on the various tree nodes on right-button mouse clicks.

Connecting a Router Network (JMS Version)

To administer a router network, any given router of the network can be connected. After the connection setup, all routers of this network are available and are shown as a node in the navigator frame.

For the connection setup choose the entry Connect... in the menu Connection in the main frame. Now the following window is displayed:

SwiftMQ Explorer connects to a router via JMS and so, like any other JMS application, executes a JNDI-Lookup on a QueueConnectionFactory. For this, the JNDI-Provider-URL and the name of the QueueConnectionFactory needs to be given.

The indicated input fields are to be filled in as follows:

JNDI-Provider-URL:

The SMQP-URL of the respective JMS listeners by which the connection should be made. The assignment of the input field points at the JMS listener of the example configuration at router1.

The format of an SMQP-URL is the following:

     smqp://[<user>[:<password>]@](<host>:<port>)|"intravm"[/[type=<type>]
      [;timeout=<long>][;keepalive=<long>]

Where

     smqp       ::=  Specifies the SwiftMQ Protocol
     <user>     ::=  Username. Default is 'anonymous'
     <password> ::=  User's password. Default is null.
     <host>     ::=  DNS hostname of the router or the keyword "intravm" to connect intra-VM
     <port>     ::=  JMS listener port
     type       ::=  Class name of the socket factory used by this JMS listener.
                     In this release, com.swifmq.net.PlainSocketFactory and
                     com.swiftmq.net.JSSESocketFactory are available. Default is
                     com.swifmq.net.PlainSocketFactory. See JMSSwiftlet configuration for details.
     timeout    ::=  Specifies a timeout in milliseconds for lookups. If no JNDI object is
                     received within this time, the lookup throws a NamingException. Default is no timeout;
                     lookups are waiting until they receive the requested JNDI objects.
     keepalive  ::=  Specifies a keepalive interval in milliseconds. If this value is greater 0, a
                     timer is created on the client side to send keepalive messages to detect broken
                     JNDI connections. Default is 0 (no keepalive). This option is new since SwiftMQ 5.0.0.

Name Queue Connection Factory:

Here you can specify the name of the QueueConnectionFactory on which a JNDI-Lookup should result. The field default is plainsocket@router which is pre-configurated in the example configuration.

Username:

The user name on which the QueueConnection is established by the demanded QueueConnectionFactory. This user needs to have a send grant on the queue swiftmqmgmt on all routers belonging to the router network. The grants are to be determined for the router by which the connection takes place. In the example configuration the user admin is pre-configurated with these grants for the queues swiftmqmgmt@router1 and swiftmqmgmt@router2.

Password:

The password of the user. If the pre-configurated user admin is used, the password is secret.

Manage:

Either choose Whole Router Network (default) if you want to manage the connected router and all routers connected to this router, or choose Connected Router only which limits the management to the connected router only. This option is useful in router network with many routers that would bring the SwiftMQ Explorer down because they produce too many management events. This option was introduced in release 7.3.2.

Use Protocol Version:

Uses a particular SMQP protocol version to connect to a SwiftMQ Universal Router. This is useful to connect with a newer versioned SwiftMQ Explorer to an older versioned SwiftMQ Universal Router to use the latest features of SwiftMQ Explorer without upgrading the SwiftMQ Universal Router. This option was introduced in release 7.3.2.

Starting SwiftMQ Explorer (AMQP Version) (since 9.5.0)

Unpack the distribution, go to the scripts directory and start Explorer as follows:

      ./exploreramqp [<amqp-url> FN|CR [<user> <password>]]

      Where <amqp-url>  AMQP-URL, e.g. amqp://localhost:5672
            FN          Manage full router network
            CR          Manage connected router only
            <user>      user
            <password>  password

If you use Java 9 or higher, add java9 as the first parameter:

    ./exploreramqp java9 [<amqp-url> FN|CR [<user> <password>]]

The AMQP-URL has the following format:

    amqp[s]://<host>:<port>[/?<param>[&<param>...]]

    Where

    amqp      ::= AMQP protocol over plain sockets.
    amqps     ::= AMQP protocol over SSL sockets.
    <host>    ::= Hostname.
    <port>    ::= Port. 5672 is for plain, 5661 for SSL.
    <param>   ::= Parameter in form <name>=<value>.

         Possible parameters are:

            maxframesize   Sets the AMQP max frame size. Value is in bytes. Default unlimited.
            idletimeout    Closes the connection after no data has been sent for this amount of time.
                           Value is in milliseconds. Default no timeout.
            mechanism      SASL authentication mechanism like CRAM-MD5.

SwiftMQ Explorer connects via AMQP 1.0. The parameters can be specified on command line or, if not, the connect can be executed from a menu.

Management Tree

All network routers in the navigator frame are shown as a node after a successful connection setup:

After opening the node, the management tree of the router is shown. On the upper level it contains the router environment and the swiftlets of the router. Every swiftlet contains at least the swiftlet meta data as well as possibly further swiftletspecific entities, entity lists, and properties.

Showing Entity Tables

Every entity list may be displayed alternatively as a table. This is done by the popup-menu command Show Entity Table of the entity list:

Thereupon the entity list is shown as an entity table:

The toolbar of the entity table makes it possible to insert or delete entities. Furthermore, properties (cells) may be edited directly by double clicking if the properties are not read-only.

Usage Lists/Activity Charts

Active resources of Swiftlets are shown under the entity list Usage of the Swiftlet.

An entity table of a usage list got an activity chart as supplement which may be switched on or off by a button.

Viewing Messages

The SwiftMQ Explorer contains a powerful message viewer which can be invoked on 2 different ways.

The first way is to select the queue node of the Usage folder of the Queue Manager Swiftlet and press the right mouse button.

The second way is to open the Entity Table of the Usage folder of the Queue Manager Swiftlet, select the queue and press the View Messages button on the toolbar.

Thereafter the message viewer frame is shown:

The message viewer works like a database query tool. You first specify your select condition, execute it and see the result. The select condition is entered into the Selection Attributes panel. The first field may contain an optional SQL92 message selector. The fields From and To specify the range of the result set one like to select. Both values are indexes, starting with 0 (first row) and are inclusive. The To field may contain a \* which means to select till the end of the result set. If a message selector is specified, the result set is first reduced to those message matching the selector, and the from/to indexes then specify the part of the result set to display. Note that the maximum number of messages returned is 200 to avoid overloading the router through transfering huge result sets. However, one is able to look at every message by reducing the range by specifying the from/to indexes.

The field Body Truncate contains the number of characters the message body is truncated to. This is also to avoid overloading the router with large message results. The default is 2048 characters. One may specify any value here.

After all selection attributes have been entered, the Execute Select button may be pushed and the table Selection Result will contain all messages of the result set.

Messages marked with a locking icon in the Lock column are locked against consumption by consumers. This means they either have been delivered to a consumer's cache but have not yet been consumed or they have been locked by a XA transaction, respectively. Using Execute multiple times may change the locking state because it is only a snapshot at the time of the query.

One or more messages may be selected. If a single message is selected, the content is displayed in the tabbed panel below.

The chart at the end of the frame displays the message flow and the current number of messages in the queue. It can be switched on/off with the Message Flow Chart button on the toolbar. The update interval depends on the attribute Collect Interval of the Queue Manager Swiftlet and may be changed accordingly.

Deleting Messages

All selected messages are deleted by pressing the "Delete selected Messages" button. The whole queue content can be deleted by pressing the Drain Queue button.

Moving Messages

If messages are selected and the Move all or selected Messages button is pressed, the target queue name is requested and all selected messages are moved to the target queue. If no messages are selected, ALL messages will be moved to the target queue.

Export Messages (since 9.3.0)

To export messages from a queue either invoke the command from the queue node of the Usage folder of the Queue Manager Swiftlet by pressing the right mouse button:

Or from the Entity Table of the Usage folder of the Queue Manager Swiftlet, by selecting the queue and pressing the Export Messages button on the toolbar:

A dialog frame appears where you can specify the properties for the export:

The export takes place to the specified directory which is on the host where the SwiftMQ Universal Router or, in case of SwiftMQ HA Router, the ACTIVE/STANDALONE HA instance is running. The directory can be a relative or absolute path name. ./ refers to the router's working directory (scripts/ by default).

Each message is stored in a single file which filename is in format swiftmq_<queuename>_<seqno>_<extension>. The <extension> is message if the format is binary (default).

If the XML option is specified, the <extension> is xml and the format is the XStream XML serialization format. If the delete option is specified, the messages are deleted from the queue after the export. The optional selector can be specified to reduce the number of messages by use of a JMS message selector.

Import Messages (since 9.3.0)

To import messages into a queue either invoke the command from the queue node of the Usage folder of the Queue Manager Swiftlet by pressing the right mouse button:

Or from the Entity Table of the Usage folder of the Queue Manager Swiftlet, by selecting the queue and pressing the Import Messages button on the toolbar:

A dialog frame appears where you can specify the properties for the import:

Import takes place from the specified directory which is on the host where the SwiftMQ Universal Router or, in case of SwiftMQ HA Router, the ACTIVE/STANDALONE HA instance is running. The directory can be a relative or absolute path name. ./ refers to the router's working directory (scripts/ by default).

If the new id option is specified, new message ids are assigned during import. Otherwise the old message ids are used. In the latter case keep in mind that messages may be discarded by duplicate message detection (which works on message ids) during import. If the delete option is specified, the files are deleted after import. The filter option can be used to filter the files by using a regular expression on the file names.

Import respects filename extensions xml and messages. It is expected that files with xml extensions contain XStream XML serialization format while those with message extension contain SwiftMQ binary format. Messages are imported as is without changing their content.

Listing Files (since 9.4.0)

The SwiftMQ Explorer contains a powerful utility to list the content of a file cache. It can be invoked on 2 different ways.

The first way is to select the file cache node of the Usage folder of the File Cache Swiftlet and press the right mouse button.

The second way is to open the Entity Table of the Usage folder of the File Cache Swiftlet, select the file cache and press the "List Cache Files" button on the toolbar.

Thereafter the frame to list files is shown:

The frame works similar to the message viewer except there is no body truncate.

Creating new Entities

It is possible to generate new entities concerning nodes representing an entity list if this entity list offers this command. To do so, select the concerning node of the entity list and call the popup-menu by clicking the right mouse button.

The following example demonstrates the generation of a new JMS listener:

First, the node Listeners of the JMS Swiftlet is selected and the popup-menu is activated:

On execution of Create a new Entity an interactive window is displayed as well as the inquiry of the new entity data. Fields, highlited in orange, are to be filled in. Fields, highlited in white are optional:

After the execution, the new entity is shown in the entity list:

Deleting Entities

To delete an entity, please choose it and click the right mouse button. If a popup-menu is offered with the command Delete Entity, the entity may be deleted, otherwise not.

Changing Properties

Properties are indicated in the navigator frame with

or

(read-only). It may be changed by double clicking on the Property if it is not read-only. Now, a window will be displayed by which the value may be changed. Boolean properties are a special case and may be switched on or off directly in the navigator frame by double clicking.

It is also possible to change properties in an entity table. In this case make a double click to the cell and edit there directly.

Displaying the Router Environment

The navigator frame includes a folder directly below the router node which contains informations concerning the runtime environment of the router:

Displaying the Router's Memory

Within the folder Router Environment is an entity list "Router Memory List" which contains a single entry with the free and total memory of this particular router:

The values are collected in the interval, specified in the attribute Memory Collect Interval.

This entity list can also be displayed as an entity table frame:

By toggling the chart button it is possible to show the history of memory consumption.

By selecting the router entry, a garbage collection can be performed:

Changing the Routername

Within the folder Router Environment of each router is a property routername which contains the logical name of the router. This name must be set if multiple routers are running on one host. If this property isn't set, the routername is equal to the DNS name of the host where the router is running on.

Be aware, that changing the routername is - even in a connected router network - a very heavyweight change, because all references to this router (authentication grants, static routes etc) must also be changed. For this reason it is the very best, to give each router per default a logical routername on initial configuration. In this case, there are really minimal changes if, for example, a router is transferred on another physical host or another router is started on the same host.

Halting a Router

The router stops by executing the popup-menu of the respective router node in the navigator frame:

The router waits 10 seconds after executing the command, then it shuts down. The node in the navigator frame disappears.

Rebooting a Router

A router is rebooted by the popup-menu of the respective router node in the navigator frame:

The router waits 10 seconds after executing the command, then it shuts down all swiftlets. The router process will not be closed. After the Swiftlets shutdown, they restart automatically. The node in the navigator frame disappears during the reboot temporarily, then it appears again.

If changes are made concerning the configuration which require a reboot, these changes are active now if the configuration was saved before.

Saving a Router's Configuration

All changes made concerning a router configuration are valid immediately. But they are not persistent, except they are saved explicitly. In this case, the router produces a backup of the existing XML configuration files and saves the current configuration in a new file.

To save a router's configuration, execute the appropriate command from the popup-menu of the respective router node in the navigator frame:

Disconnecting a Router Network

To close the connection to a router network, choose Disconnect... in the menu Connection (or Exit, then the SwiftMQ Explorer will also be closed).

It is to be considered that changes are not saved automatically. All implemented changes are saved directly in the routers and are written in the respective XML configuration file at execution of the respective save command. So it is quite possible to connect again and then save the changes.

Restore of Open Windows

Per default, the SwiftMQ Explorer restores the state (location, size, chart on/off etc) of the last open windows per router. This is a very useful feature to have always a set of open frames per dedicated router. During the exit, the state of the open windows is saved in a file called explorerstate.xml in the user's home directory.

The following system properties are checked from the SwiftMQ Explorer:

Property	Default	Description
swiftmq.explorer.state.load	true	Specifies whether the states should be loaded during the start.
swiftmq.explorer.state.save	true	Specifies whether the states should be saved during the exit.

These combinations are useful:

• Set swiftmq.explorer.state.load to false to avoid restoring of windows from a previous session.
• Set swiftmq.explorer.state.save to false to ensure always to restore the same window set, saved in some previous session.
• Don't set anything (both properties have true as default) ensures to have always the state from the previous session restored.