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. So for instance to run the hub, which is in class org.astrogrid.samp.hub.Hub, you can execute either:

   java -classpath jsamp.jar org.astrogrid.samp.hub.Hub
or, more simply:
   java -jar jsamp.jar hub
As a special case for convenience, simply running "java -jar jsamp.jar", or clicking on the jar file in some OSes/graphical environments, will start the hub, along with a short usage message to standard error.

In all cases, supplying the "-h" or "-help" flag on the command line will print a usage message.

The JSamp usage message (java -jar jsamp.jar -help) says:

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

   Commands (command-classes) are:
      hub             (org.astrogrid.samp.hub.Hub)
      hubmonitor      (org.astrogrid.samp.gui.HubMonitor)
      snooper         (org.astrogrid.samp.test.Snooper)
      messagesender   (org.astrogrid.samp.test.MessageSender)
      hubtester       (org.astrogrid.samp.test.HubTester)
      calcstorm       (org.astrogrid.samp.test.CalcStorm)
      bridge          (org.astrogrid.samp.bridge.Bridge)

   Environment Variable:
      SAMP_HUB           = std-lockurl:<url>|web-appname:<name>
                                            |jsamp-class:<clientprofile-class>

   System Properties:
      jsamp.hub.profiles = std|web|<hubprofile-class>[,...]
      jsamp.localhost    = [hostname]|[hostnumber]|<value>
      jsamp.server.port  = <port-number>
      jsamp.xmlrpc.impl  = internal|xml-log|rpc-log|apache|<xmlrpckit-class>

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.

The various system properties listed affect communications for these applications in the same way as for JSAMP applications in general; see the section on System Properties for more detail.

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 the screenshot below - though see the GUI Features section for more detail.

HubMonitor screenshot

Hub

The org.astrogrid.samp.hub.Hub class runs a SAMP hub. A graphical window showing currently registered clients and their attributes (metadata and subscribed MTypes) may optionally be displayed. By default the hub operates using the SAMP Standard Profile, but there are options to use different profiles, including user-defined ones, as well or instead. Some of the flags relate to particular profiles.

Hub usage is:

Usage:
      org.astrogrid.samp.hub.Hub
            [-help] [-/+verbose]
            [-mode no-gui|client-gui|msg-gui|facade]
            [-profiles std|web|<hubprofile-class>[,...]]
            [-std:secret <secret>] [-std:httplock]
            [-web:log none|http|xml|rpc] [-web:auth swing|true|false]
            [-web:allowremote]

-mode no-gui|client-gui|msg-gui|facade
Determines what hub implementation is used; currently this affects whether and how the hub status is displayed graphically. The following options are available:
no-gui
There is no graphical display.
client-gui
A window is displayed showing which clients are registered and their metadata and subscriptions.
msg-gui
A window is displayed showing clients with metadata and subscriptions; it also gives a graphical representation of what messages are being sent and received between clients. In the case of heavy messaging traffic, the extra processing required for this display can slow down hub operations a bit.
facade
This option piggy-backs the hub on an existing hub. The hub passes any registration requests to an underlying hub. The underlying hub is located using the usual arrangements for client hub discovery (influenced by the SAMP_HUB environment variable). This can be used to provide additional access to an existing hub using a profile which the existing hub does not implement. There is no graphical representation in this case.
In the case of the GUI options, they attempt to insert an icon into the "System Tray" area of the desktop, if one exists, and if a java version >=1.6 is being used. A menu available from this icon can be used to display or hide the window. If the system tray is not accessible (java version <1.6 or not supported on desktop), then the window will be displayed directly, and closing the window will shut down the hub.
-profiles std|web|<hubprofile-class>[,...]
Identifies what profiles to run with the hub. If no -profiles flag is specified, then the default set of profiles is used, which at present means just the Standard Profile. The flag may be given more than once, in which case all the named profiles will run. The following options are available:
std
Standard Profile. The -std: flags below relate only to this profile.
web
Web Profile. The -web: flags below relate only to this profile.
<hubprofile-class>
If the name of a class which implements the HubProfile interface and which has a no-arg constructor is given, that profile is run.
This flag has a similar usage to the jsamp.hub.profiles system property, but overrides it, and must be used to use the corresponding profile-specific flags.

The following flags are used only if the Standard Profile (-profiles std) is in operation:

-std:secret <secret>
Optional flag to supply the samp.secret string which will be written to the Standard Profile lockfile and which clients must present on registration. If not supplied, a random string will be chosen.
-std:httplock
If this flag is supplied, the Standard Profile lockfile is not written to a file, but is made available via HTTP instead. The hub will print the location, in a form suitable for use with the SAMP_HUB environment variable, when it starts up.

The following flags are used only if the Web Profile (-profiles web) is in operation:

-web:log none|http|xml|rpc
Provides different levels of logging of the Web Profile communications. This logging is to standard error, and not performed through the Java logging system. The following options are available:
none
No logging.
http
All HTTP communications, including HTTP headers and in most cases HTTP request/response bodies, to the web server hosting the XML-RPC server, are logged. This can be very useful for debugging communication issues, since both HTTP headers and non-XML-RPC HTTP requests are essential parts of the various sandbox-busting technologies required by the Web Profile.
xml
The XML text of all XML-RPC communications is logged.
rpc
An interpreted summary of the content of the remote procedure calls is logged.
-web:auth swing|true|false
Configures how the Web Profile hub determines whether clients are permitted to connect. The options are:
swing
A popup dialogue is shown to the user for every registration request. Registration is only granted if the user explicitly authorizes it. This option is the default and should usually be used.
true
All requests to register are granted without reference to the user. This can be convenient during testing, but should be used with care, since it can facilitate access for potentially hostile browser-based clients.
false
All requests to register are refused without reference to the user. This rather silly option means that no clients can register via the Web Profile.
-web:allowremote
If used, this option means that clients from hosts other than the local host may be permitted to register. Normally such requests are automatically refused. Enable this option with care, it has serious security implications.

For convenience, the hub can also be started simply by invoking the jar file with no arguments (for instance clicking on it).

To run a hub with default settings (standard profile only) do this:

    java -jar jsamp.jar hub
and to run it with both Standard and Web Profiles, do this:
    java -jar jsamp.jar hub -profiles std,web

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]
            [-auto <secs>] [-nomsg] [-nogui]
            [-mtype <pattern>]

-/+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.
-nomsg
Normally the window displays an indication of pending messages sent and received by the monitor itself. If the -nomsg flag is given, these will not be shown.
-mtype <pattern>
Gives an MType or wildcarded MType pattern to subscribe to. This flag may be repeated to subscribe to several different MType patterns. Like the Snooper command, it does not actually understand MTypes subscribed to in this way, so it sends a response with samp.status=samp.warning. If omitted, only the administrative MTypes (required for the monitor to keep track of clients) are subscribed to.

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.

Note that the HubMonitor command can also be used in this way; Snooper is useful if you would rather have information presented on standard output than in a GUI.

Snooper usage is:

Usage:
      org.astrogrid.samp.test.Snooper
          [-help] [-/+verbose]
          [-clientname <appname>] [-clientmeta <metaname> <metavalue>]
          [-mtype <pattern>]

-mtype <pattern>
Gives an MType or wildcarded MType pattern 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.
-clientname <appname>
Specifies the samp.name metadata item which the sending aplication should give for its application name following registration.
-clientmeta <metaname> <metavalue>
Specifies additional items of metadata for the sending application to give following registration.

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]
            -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]
            [-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]
            [-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.

Bridge

The org.astrogrid.samp.bridge.Bridge class provides a connection between two or more different hubs. If run between two hubs, A and B, every client on A also appears as a 'proxy' client on B, and vice versa. A bridge client also runs on both hubs A and B to keep track of which clients are currently registered, so that it can generate new proxies as required. The effect of this is that clients registered with one hub can send and receive messages to and from clients registered on a different hub, just as if they were local. This can be used to facilitate collaborative working, though you may be able to think of other uses.

To run it, you must specify which hubs to bridge between. In most cases you'll want one to be the default (standard profile) hub, so this is assumed by default. You therefore only need to specify how to connect to the non-default hub(s). You can do this by using one or more of the command-line options described below.

Bridge usage is:

Usage:
      org.astrogrid.samp.bridge.Bridge
          [-help] [-/+verbose] [-[no]exporturls]
          [-nostandard] [-sampdir <lockfile-dir>] [-sampfile <lockfile>] [-sampurl <lockurl>]
          [-keys <xmlrpc-url> <secret>] [-profile <clientprofile-class>]

-exporturls/-noexporturls
With -exporturls, an attempt is made to translate URLs in message bodies and responses from localhost-specific forms to remotely accessible ones, for instance renaming loopback addresses like "127.0.0.1" as the fully qualified domain name. With -noexporturls this is not done. The default is to export URLs if the bridge is apparently running between hubs on different hosts.
-standard/-nostandard
-standard indicates that one of the hubs to bridge is the Standard Profile hub. This is default behaviour; -nostandard means do not include the standard profile hub.
-sampfile <lockfile>
Names a file in standard-profile format which describes the location of a hub. This flag may be given more than once to specify multiple non-standard hubs.
-keys <xmlrpc-url> <secret>
Gives the XML-RPC endpoint and "samp-secret" string required for communicating with a running hub. These correspond to the samp.hub.xmlrpc.url and samp.secret values from the standard profile lockfile. This flag may be given more than once to specify multiple non-standard hubs.
-sampdir <lockfile-dir>
Names a directory containing a file ".samp" in standard-profile format which describes the location of a hub. This flag may be given more than once to specify multiple non-standard hubs.
-profile <clientprofile-class>
Gives the fully-qualified classname of a java class which implements the ClientProfile interface and which has a no-arg constructor. A newly-constructed instance of this class will be used to contact a hub. This flag may be given more than once to specify multiple non-standard hubs.

The bridge is a bit experimental, and there are a few subtleties concerning its use. Some more discussion can be found on the bridge page.