Overview
CLI may be activated out of a Java program for programmatic administration. This administration API offers a simple but powerful instrument to the administration of SwiftMQ router networks. The administration takes place by performing any CLI command via an executeCommand method of CLI. All property values and entities of routers of the network may be inquired by the API. Furthermore it is possible to wait for the availability of certain routers or to receive notification events.
Preparation
The following import needs to exist to use the CLI Admin API:
import com.swiftmq.admin.cli.*;
|
If router events should be received, the following further import statement is needed:
import com.swiftmq.admin.cli.event.*;
|
CLI requires a QueueConnection in stopped mode (default on creation). The user of this QueueConnection needs to have full administration rights of the routers to be administered. This is the case when placing send/receive grants to the queue swiftmqmgmt of the respective routers.
Creation of a QueueConnection:
QueueConnection connection = null; try { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY,"com.swiftmq.jndi.InitialContextFactoryImpl"); env.put(Context.PROVIDER_URL,"smqp://localhost:4001/timeout=10000"); InitialContext ctx = new InitialContext(env); QueueConnectionFactory connectionFactory = (QueueConnectionFactory)ctx.lookup("QueueConnectionFactory"); connection = connectionFactory.createQueueConnection(); ctx.close(); } catch (Exception e) { System.out.println(e); System.exit(-1); }
|
After that CLI may be created:
CLI cli = null; try { cli = new CLI(connection); } catch (Exception e) { System.out.println(e); System.exit(-1); }
|
At construction, CLI produces several sessions and starts the connection.
Waiting for Routers
After creating CLI it receives asynchronous availability notifications by the network routers. A router may not be administered until he is available. One can wait for the availability to administer a specific router. This is done by calling the method waitForRouter. This method exists in two versions, one without and one with timeout. The one without timeout waits until the router is available. The one with timeout waits until the availability or until timeout. If the router is already available at call of the method, it returns straight away.
example without timeout:
cli.waitForRouter("router1");
|
example with timeout:
cli.waitForRouter("router1", 20000); // max 20 secs
|
Router Listener
Beside the synchronous waitForRouter methods a RouterListener may also be registered. In this case, CLI informs these listeners asynchronous by router availabilities.
Example:
cli.addRouterListener(new RouterListener() { public void onRouterEvent(String routerName, boolean available) { System.out.println("Router '"+routerName+"' is "+(available?"AVAILABLE":"UNAVAILABLE")); } });
|
Executing CLI Commands
The execution of CLI commands takes place by the method executeCommand, which has the corresponding CLI command as parameter. Here it is to be taken into account that the command mustn't deliver a result, otherwise a CLIException is thrown. Thus, commands like "lc", "ar", "show template" are unauthorized.
Example to create a new queue:
cli.waitForRouter("router1"); try { cli.executeCommand("sr router1"); cli.executeCommand("cc /sys$queuemanager/queues"); cli.executeCommand("new mynewqueue cache.size 1000"); cli.executeCommand("save"); } catch (CLIException e) { processError(e); }
|
Getting available Routers
CLI may be requested at any time, which routers are currently available. This is done by the method getAvailableRouters. The method returns a string array with router names.
Example:
String[] availableRouters = cli.getAvailableRouters();
|
Getting the actual Router
The router, mentioned at the last "sr" command is the current one. It may be requested by getActRouter. If no "sr" command has been set, null is passed back.
Example:
System.out.println("Act Router: "+cli.getActRouter());
|
Getting the actual Context
The context, given at the last "cc" command, is the current one. It may be requested by getActContext. If no "cc" command has been set, null is passed back. After a "sr" command, "/" is the current context.
Example:
System.out.println("Act Context: "+cli.getActContext());
|
Getting Property Values
After setting oneself in a context by "cc", any property in this context may be read out. This is done by the method getContextProperty. The name of the property is given as parameter. The current value is given back as String type. If the property is unknown within the current context, a CLIException is thrown. If the property value is null, null will be passed back.
Example:
cli.executeCommand("sr router1"); cli.executeCommand("cc /sys$queuemanager/queues/mynewqueue"); int cacheSize = Integer.parseInt(cli.getContextProperty("cache.size"));
|
Getting Context Entities
After setting the actual context with 'cc', it is possible to get the actual entity names defined whithin this context.
Example:
cli.executeCommand("sr router1"); // getting all defined queues cli.executeCommand("cc /sys$queuemanager/queues"); String[] allQueueNames = cli.getContextEntities(); // getting all defined users cli.executeCommand("cc /sys$authentication/users"); String[] allUserNames = cli.getContextEntities();
|
Closing CLI
With completion of the use of CLI Admin API, it should be closed by close(). Hereby, all resources used by CLI are released. The QueueConnection given with the construction is not closed and remains in the started mode.
Example:
Detecting a Connection Lost
In order to recognize if the QueueConnection committed to CLI got lost, a JMS ExceptionListener needs to be registered at the QueueConnection and it needs to be responded accordingly.
Code Example
The SwiftMQ distribution contains an example "AdminClient.java" within the directory "samples/cli". This is an easy administration client, which reads CLI commands by System.in and executes them.