JSAMP Toolkit - Command-line Tools

Command-line Tools

JSAMP provides a number of command-line applications for standalone use in various contexts. These come with their own main() methods so can be invoked directly. A convenience class org.astrogrid.samp.JSamp is also provided (with its own main() method) which might save you a bit of typing when running these; if the dependencies are in the same directory as the jsamp jar file itself, then the JSamp class can be invoked as "java -jar jsamp-version.jar". In all cases, supplying the "-h" or "-help" flag on the command line will print a usage message.

The JSamp usage message says:

Usage:
      org.astrogrid.samp.JSamp [-help] [-version] <command> [-help] <cmd-args>
      <command-class> [-help] <cmd-args>

   Commands (command-classes) are:
      hubmonitor      (org.astrogrid.samp.gui.HubMonitor)
      hubtester       (org.astrogrid.samp.test.HubTester)
      calcstorm       (org.astrogrid.samp.test.CalcStorm)
      messagesender   (org.astrogrid.samp.test.MessageSender)
      snooper         (org.astrogrid.samp.test.Snooper)
      hubrunner       (org.astrogrid.samp.xmlrpc.HubRunner)

The individual command-line applications are described below. They have their own specific command-line flags to control use, but most share the following common flags:

-help: Outputs the usage message. May be abbreviated to -h.
-/+verbose: Increases/decreases verbosity. This controls what level of logging is performed by the application. By default, WARNING (and higher) messages are output, while INFO (and lower) messages are suppressed. -verbose increases the verbosity by one level and +verbose decreases it by one level. These flags may be supplied more than once. May be abbreviated to -v or +v.
-xmlrpc apache|internal: Configures which pluggable XML-RPC implementation will be used for XML-RPC communications. If apache is chosen, the Apache XML-RPC library must be on the classpath. For internal no external libraries are required. If this flag is not used, an implementation will be chosen depending on what is available. The implementations ought to behave the same, but the internal one is currently a bit slower and may not be as well tested.
-gui/-nogui: Shows/hides a window which shows which clients are currently registered with the hub and their metadata and subscriptions.

The GUI window, which is used by several of these tools to display the clients currently registered with the hub along with their metadata and subscriptions, looks something like this:

HubRunner

The org.astrogrid.samp.xmlrpc.HubRunner class runs a SAMP hub using the SAMP Standard Profile. A graphical window showing currently registered clients and their attributes (metadata and subscribed MTypes) may optionally be displayed.

HubRunner usage is:

Usage:
      org.astrogrid.samp.xmlrpc.HubRunner
            [-help] [-/+verbose] [-xmlrpc apache|internal] [-nogui]

-nogui: Normally, a window is shown which shows currently registered clients. This window remains visible for as long as the hub is running. If the window is closed, the hub will terminate. If the -nogui flag is supplied, this window is not shown.

HubMonitor

The org.astrogrid.samp.gui.HubMonitor class runs a SAMP client which connects to any available hub and displays a window showing currently registered clients along with their attributes (metadata and subscribed MTypes). If no hub is available at startup, or the hub shuts down while the monitor is running, the monitor will poll for a hub at regular intervals and reconnect if a new one starts up.

A button at the bottom of the window allows you to disconnect from a running hub or to reconnect. While disconnected, no automatic connection attempts are made.

The HubMonitor class itself is a very simple application which uses the facilities provided by the other classes in the toolkit. See the source code for details.

HubMonitor usage is:

Usage:
      org.astrogrid.samp.gui.HubMonitor
            [-help] [+/-verbose] [-xmlrpc apache|internal]
            [-auto <secs>] [-nogui]

-/+verbose: See above for the description of verbosity setting. If -verbose is used, each message sent and received will be logged to standard error through the logging system.
-auto <secs>: Sets the number of seconds between reconnection attempts when the monitor is inactive but unregistered. If <=0, autoconnection is not attempted.
-nogui: The monitor registers as a client, but no window is displayed.

Snooper

The org.astrogrid.samp.test.Snooper class runs a SAMP client which subscribes to some or all MTypes and logs each message it receives to the terminal. This can be useful for debugging, especially for testing whether your application is sending messages which look right. Since it does not actually understand the messages which have been sent, it sends a Response with samp.status=samp.warning.

Snooper usage is:

Usage:
      org.astrogrid.samp.test.Snooper
          [-help] [-/+verbose] [-xmlrpc apache|internal]
          [-mtypes <pattern>]

-mtypes <pattern>: Gives an MType or wildcarded MType to subscribe to. This flag may be repeated to subscribe to several different MType patterns. If omitted, a value of "*", i.e. subscription to all MTypes, will be assumed.

MessageSender

The org.astrogrid.samp.test.MessageSender class can send a simple SAMP message from the command line and display any responses received in response.

MessageSender usage is:

Usage:
      org.astrogrid.samp.test.MessageSender
            [-help] [-/+verbose] [-xmlrpc apache|internal]
            -mtype <mtype> [-param <name> <value> ...]
            [-target <receiverId> ...] [-mode sync|async|notify]
            [-sendername <appname>] [-sendermeta <metaname> <metavalue>]

-mtype <mtype>: Gives the MType for the message to send.
-param <name> <value>: Gives a named parameter for the message. This flag may be repeated to pass more than one parameter. Currently <value> is simply interpreted as a string value, so it is impossible to send SAMP list- or map-valued parameters. This may be rectified in a future release.
-target <receiverId>: Specifies the SAMP public ID for a client to which this message will be sent. This flag may be repeated to send the same messsage to more than one recipient. If omitted, the message is broadcast to all clients which are subscribed to the MType.
-mode sync|async|notify: Specifies the delivery pattern to be used to send the message. In the case of notify, no responses will be received. The sender only declares itself callable if async mode is used. The default is sync.
-sendername <appname>: Specifies the samp.name metadata item which the sending aplication should give for its application name following registration.
-sendermeta <metaname> <metavalue>: Specifies additional items of metadata for the sending application to give following registration.

HubTester

The org.astrogrid.samp.test.HubTester class runs a series of tests on an existing SAMP hub. Most aspects of hub operation are tested, along with some moderate load testing. In case of a test failure, an exception will be thrown, and under normal circumstances the stackdump will be shown on standard error. These exceptions may not be particularly informative; hub authors debugging hubs will have to examine the HubTester source code to see what was was being attempted when the failure occurred.

Normally, if a hub passes all the tests there will be no output to standard output or standard error. Under some circumstances however a WARNING log message will be output. This corresponds to behaviour that a hub implementation SHOULD, but not MUST, display according to the SAMP standard.

It's OK for other clients to be registered while the test runs, but such clients should not either register or unregister while the test is under way - this will confuse the test and probably result in spurious test failures.

HubTester usage is:

Usage:
      org.astrogrid.samp.test.HubTester
            [-help] [-/+verbose] [-xmlrpc apache|internal] [-gui]

-gui: If supplied, a HubMonitor window will be shown for the duration of the test.

CalcStorm

The org.astrogrid.samp.test.CalcStorm class runs a number of clients simultaneously, which all connect to the hub and then send each other messages. A private set of MTypes which provide simple integer arithmetic are used. Checks are made that all the expected responses are obtained and have the correct content. On termination, a short message indicating the number of messages sent and how long they took is output. This application can therefore be used as a load test and/or benchmark for a given hub implementation.

CalcStorm usage is:

Usage:
      org.astrogrid.samp.test.CalcStorm
            [-help] [-/+verbose] [-xmlrpc apache|internal] [-gui]
            [-nclient <n>] [-nquery <n>] [-mode sync|async|notify|random]

-nclient <n>: Gives the number of clients which will run at once.
-nquery <n>: Gives the number of queries which each client will send to other clients during the run.
-mode sync|async|notify|random: Specifies the delivery pattern by which messages are sent. The default is random, which means that a mixture of modes (approximately a third each of synchronous call/response, asynchronous call/response and notification) will be used.
-gui: If supplied, a HubMonitor window will be shown for the duration of the test.