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 "bridge.proxy.source" 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 (the samp.hub.xmlrpc.url and samp.secret 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 "-nostandard" flag; 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
without the -nostandard flag it would have been a four-way bridge between the hubs of foo, bar, baz, and the user running the command.
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 SAMP_HUB 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.
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 (samp.icon.url metadata) 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 accordingly.