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.
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.Hubor, more simply:
java -jar jsamp.jar hubAs 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 "
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:
-verboseincreases the verbosity by one level and
+verbosedecreases it by one level. These flags may be supplied more than once. May be abbreviated to
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.
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>[,...]] [-extraprofiles std|web|<hubprofile-class>[,...]] [-std:secret <secret>] [-std:httplock] [-web:log none|http|xml|rpc] [-web:auth swing|true|false] [-web:[no]cors] [-web:[no]flash] [-web:[no]silverlight] [-web:[no]urlcontrol]
-profilesflag determines which profiles will be running initially, and the
-extraprofilesflag specifies additional profiles which may be available to start manually, for instance from the Profiles menu of the hub window. In each case a comma-separated list of profile identifiers is used. If no
-profilesflag is specified, then the default set of profiles is used; at present this is the Standard Profile for
profilesand the Web Profile for
extraprofilesThe flag may be given more than once, in which case all the named profiles will run. The following options are available:
-std:flags below relate only to this profile.
-web:flags below relate only to this profile.
jsamp.hub.profiles.extrasystem properties, but overrides them, and must be used to take advantage of the corresponding profile-specific flags.
The following flags are used only if the Standard Profile
-profiles std) is in operation:
The following flags are used only if the Web Profile
-profiles web) is in operation:
crossdomain.xmlfiles. By default this is currently turned on.
clientaccesspolicy.xmlfiles. By default this is currently turned off.
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 huband to run it with both Standard and Web Profiles, do this:
java -jar jsamp.jar hub -profiles std,web
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] [-auto <secs>] [-nomsg] [-nogui] [-mtype <pattern>]
-verboseis used, each message sent and received will be logged to standard error through the logging system.
-nomsgflag is given, these will not be shown.
samp.warning. If omitted, only the administrative MTypes (required for the monitor to keep track of clients) are subscribed to.
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
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>]
*", i.e. subscription to all MTypes, will be assumed.
samp.namemetadata item which the sending aplication should give for its application name following registration.
-clientmeta <metaname> <metavalue>
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>]
-param <name> <value>
<value>will be interpreted as a JSON structure if possible (note double-quoted strings are the only permitted scalars), otherwise the value will be interpreted as a plain string.
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>
metavalues may be in JSON form or plain strings.
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] [-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] [-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.
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, 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
-noexporturlsthis is not done. The default is to export URLs if the bridge is apparently running between hubs on different hosts.
-standardindicates that one of the hubs to bridge is the Standard Profile hub. This is default behaviour;
-nostandardmeans do not include the standard profile hub.
-keys <xmlrpc-url> <secret>
samp.secretvalues from the standard profile lockfile. This flag may be given more than once to specify multiple non-standard hubs.
.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.
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.