JSAMP provides a special client called the Bridge. Its purpose is to link up two or more hubs, so that clients registered with one of the linked hubs can communicate with clients registered with any of the other hubs as if they were registered on the same one. Usage instructions are given in the commands reference.
The bridge works by registering a proxy client on all the remote hubs
for each client on a local hub.
These proxy clients can be communicated with just like non-proxy ones,
but the client metadata is adjusted so that a user can see that they
are proxies; the icons are mangled, the names have "(proxy)" appended,
and a metadata entry with the key "
is added to indicate which hub the client is proxied from.
You can see some slides from October 2008 explaining how it works here: Bridge presentation.
In order to set it up, you need to specify which hubs will be connected.
There are various ways you can do this, as explained in the usage
documentation. In most cases, you will want to bridge the local
'standard' hub with a remote one.
If you can see a
.samp file (for instance from another user's home
directory) you can specify it by name like this:
jsamp bridge -sampfile /home/foo/.samp
or by directory like this (the name "
.samp" is assumed):
jsamp bridge -sampdir /home/foo
or by URL like this:
jsamp bridge -sampurl file://localhost/home/foo/.samp
If you can't see the SAMP lockfile (for instance if it is on a remote machine), you can specify the XML-RPC endpoint and samp.secret string directly. You might exchange this information with a collaborator by email or instant messaging if you want to set up a collaboration. In this case, one (not both) parties would execute a command like:
jsamp bridge -keys http://foo.star.com:46557/xmlrpc 3c3135435de76ef5
The keys here are obtained by looking in the remote user's .samp lockfile
entries respectively). Note that if the URL uses a loopback hostname
like "localhost" or "127.0.0.1" you may need to replace it with the
fully qualified domain name.
By default the local standard-profile hub is used in addition to any
others specified on the command line, but you can inhibit this
with the "
for instance the following sets up a three-way bridge between the standard
profile hubs running in the home directories of users foo, bar and baz:
jsamp bridge -nostandard -sampdir /home/foo -sampdir /home/bar -sampdir /home/baz
-nostandard flag it would have been a four-way
bridge between the hubs of foo, bar, baz, and the user running the
By use of the
-profile flag, non-standard profiles
can be used as well. The bridge can thus enable two communities
of SAMP clients using different profiles to communicate together,
with no other changes to the client source code or configurations.
The bridge can be run programmatically using the org.astrogrid.samp.bridge.Bridge class as well - see the javadocs.
If you want to experiment with the bridge without having multiple
accounts or multiple hosts you can do so by using the
environment variable to set up different
hubs and communities of clients for connection with bridges.
// Start up a hub and a client using the standard profile. java -jar jsamp.jar hub java -jar jsamp.jar hubmonitor // Start a hub and client using a non-standard lockfile location. setenv SAMP_HUB std-lockurl:file://localhost/tmp/samp1 java -jar jsamp.jar hub & java -jar topcat.jar & unsetenv SAMP_HUB // Bridge them together. java -jar jsamp.jar bridge -sampfile /tmp/samp1
The syntax here is C-shell-like - something similar can be done in other environments.
In principle, once set up the bridge should work with no further intervention. However, in the case of a bridge between different machines, there may be some communications issues related to URLs. Although URLs are formally intended for locating a resource regardless of where you are, in practice there may be problems accessing a URL from a machine other than the one it was constructed on. These problems fall into two categories.
table.load.votablemessages pass the location of the table to load as a URL. Although in general a URL is intended to specify the absolute location of a resource, in some cases a URL can only be resolved on the machine on which it was generated. This is true in two main cases: firstly if it is a "
file://..."-type URL, which is specific to the current host's filesystem, and secondly if it names the host in some way other than with its fully-qualified domain name, for instance using a loopback name such as
127.0.0.1. Exchanging such URLs between bridged hubs on different hosts will not work. The bridge can mitigate these problems to some extent, by attempting to export problematic URLs. In this mode, strings in message bodies and responses which appear to be URLs are examined, and if they appear to be host-specific for a remote host, they are rephrased to make them remotely readable. This involves replacing loopback hostnames with fully-qualified ones, and where possible exporting
file-protocol URLs with HTTP ones. File URL exporting can only work from the host that the bridge is running on though, not in the other direction. For this reason it may be a good idea to have the bridge running on the machine providing most of the data rather than the one receiving most of the data, if there's a choice. This URL exporting is done by default if there appear to be multiple hosts involved in the bridge, but may be controlled by supplying the
-[no]exporturlsflag on the bridge command line. This kind of message manipulation necessarily involves a bit of guesswork, so it is possible that it may cause problems.
The bridge is somewhat experimental; what (if anything) it's useful for and whether it needs adjustment or new features are still under consideration. Please contact the author or discuss it on the apps-samp list if you've got any comments or queries.
Here is an illustration of how it looks when two hubs have been connected together using a bridge.
Prior to the bridge we have two separate hubs, as shown in the images below. The left hand one shows a JSAMP hub (displayed using the JSAMP graphical hub view) with TOPCAT registered. The right hand one shows the state of a SAMPy hub (displayed using the JSAMP hubmonitor), running on a different machine, with registered clients HubMonitor and SPLAT.
Following a suitable bridge command, they look like this:
As well as the original, directly registered clients,
each hub now has the bridge client itself, and a proxy copy
of each (non-hub) client registered on the other hub.
The proxy ones are easy to identify because their names
samp.name metadata) have "(proxy)" appended,
and their icons (
have been adjusted (currently the bottom right corner is cut
off, though some other visual idiom may be used in future releases).
In other respects these proxy clients appear to other clients on their
remote hubs just the same as any other client, and can be treated