API Overview

The client toolkit API is fully described by the javadocs. This section provides some pointers for deciding where to start looking in order to use the toolkit for a particular purpose.

Implementing SAMP Client Functionality

If you have an application which you would like to provide SAMP functionality, you should in most cases use the HubConnector class. 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. HubConnector provides some hooks for graphical capabilities, for instance a ListModel which keeps track of other clients and their attributes as the hub notifies of changes in them. Some ready-to-use GUI components suitable for use with these hooks 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. Currently, a single implementation of this, StandardClientProfile, is provided, corresponding to the SAMP Standard Profile. However, 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 Profile hub are in org.astrogrid.samp.xmlrpc. If you want to run a Standard Profile hub, either with or without a graphical display, in most cases you can do it simply by using static methods of the HubRunner 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.

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);