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
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
In all cases, supplying the "
-h" or "
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:
-verboseincreases the verbosity by one level and
+verbosedecreases it by one level. These flags may be supplied more than once. May be abbreviated to
apacheis chosen, the Apache XML-RPC library must be on the classpath. For
internalno 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.
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:
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]
-noguiflag is supplied, this window is not shown.
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.
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]
-verboseis used, each message sent and received will be logged to standard error through the logging system.
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
Snooper usage is:
Usage: org.astrogrid.samp.test.Snooper [-help] [-/+verbose] [-xmlrpc apache|internal] [-mtypes <pattern>]
*", i.e. subscription to all MTypes, will be assumed.
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>]
-param <name> <value>
<value>is simply interpreted as a string value, so it is impossible to send SAMP
map-valued parameters. This may be rectified in a future release.
notify, no responses will be received. The sender only declares itself callable if
asyncmode is used. The default is
samp.namemetadata item which the sending aplication should give for its application name following registration.
-sendermeta <metaname> <metavalue>
runs a series of tests on an existing SAMP hub.
Most aspects of hub operation are tested, along with some moderate
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]
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]
random, which means that a mixture of modes (approximately a third each of synchronous call/response, asynchronous call/response and notification) will be used.