Implementing SAMP Client Functionality

If you have an application in which you would like to provide SAMP functionality, you should in most cases use the HubConnector class or one of its subclasses. It is suitable for long-running applications which wish to send and receive SAMP messages, and seamlessly handles registering and unregistering with hubs, including taking care of the case in which a running hub shuts down and another one starts up later during the application's lifetime.

The HubConnector subclasses GuiHubConnector and MessageTrackerHubConnector layer some additional graphical facilities on top of HubConnector itself, for instance automatically updated ListModels which keep track of registered clients and sent/received messages. Some ready-to-use GUI components suitable for use with these are provided in the org.astrogrid.samp.gui package, or you can roll your own. The org.astrogrid.samp.gui.HubMonitor class is a simple application which uses a HubConnector. You may find its source code useful as a template for your own applications.

Short-lived applications, for instance ones which simply wish to register, send a message and unregister again, may prefer to use the lower-level HubConnection interface directly.

In either case, an instance of the ClientProfile class is used to initiate communication with the hub. The usual way for a client to obtain a profile for communication is to call DefaultClientProfile.getProfile. By default this returns an object conforming to SAMP's Standard Profile, but other profiles could be implemented and used with the rest of the API.

Running a SAMP Hub

The classes which provide the basic SAMP hub functionality are in the package org.astrogrid.samp.hub, and the classes required for running a Standard and Web Profile hub are in org.astrogrid.samp.xmlrpc and org.astrogrid.samp.web respectively. If you want to run a hub, either with or without a graphical display, in most cases you can do it simply by using static methods (runHub/runExternalHub) of the Hub class. This hub can be embedded within a third party application if required. For more configurability, for instance customising the graphical display or hub discovery process, you may want to look at the other classes in this package, perhaps with reference to the source code. It is possible to configure which profiles a hub runs either programmatically using Hub class methods or externally by setting the jsamp.hub.profiles system property.

Control of Logging

The JSAMP classes log activity using the J2SE java.util.logging classes. Most messages are either at the INFO level (normal activity, e.g. details of each message sent/received) or the WARNING level (errors, things which might be cause for concern). If run under default settings, all of these messages will be written to standard error for the application. It's easy to configure this behaviour otherwise however. For details see the J2SE java.util.logging javadocs, but the short story is: to restrict logging to WARNINGs only, do

    Logger.getLogger("org.astrogrid.samp").setLevel(Level.WARN);

or to turn logging off altogether, do

    Logger.getLogger("org.astrogrid.samp").setLevel(Level.OFF);