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
tofalse
to avoid restoring of windows from a previous session. - Set
swiftmq.explorer.state.save
tofalse
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.