<?xml version="1.0"?>
<document>

<properties>
  <title>API Overview</title>
  <author email="m.b.taylor@bristol.ac.uk">Mark Taylor</author>
</properties>
  
<body>

<section name="API Overview">

<p>The client toolkit API is fully described by the
<a href="apidocs/index.html" target="samp-javadoc">javadocs</a>.
This section provides some pointers for deciding where to start looking
in order to use the toolkit for a particular purpose.
</p>

<subsection name="Implementing SAMP Client Functionality">

<p>If you have an application in which you would like to provide SAMP
functionality, you should in most cases use the
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/client/HubConnector.html"
                                          >HubConnector</a> 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.
</p>

<p>The <code>HubConnector</code> subclasses
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/gui/GuiHubConnector.html"
                                       >GuiHubConnector</a> and
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/gui/MessageTrackerHubConnector.html"
                                       >MessageTrackerHubConnector</a>
layer some additional graphical facilities on top of <code>HubConnector</code>
itself, for instance automatically updated <code>ListModel</code>s 
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
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/gui/package-summary.html"
                >org.astrogrid.samp.gui</a> package,
or you can roll your own.
The <code>org.astrogrid.samp.gui.HubMonitor</code> class is a simple
application which uses a <code>HubConnector</code>.  You may find its
source code useful as a template for your own applications.
</p>

<p>Short-lived applications, for instance ones which simply wish to register,
send a message and unregister again, may prefer to use the lower-level
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/client/HubConnection.html"
                                          >HubConnection</a>
interface directly.
</p>

<p>In either case, an instance of the
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/client/ClientProfile.html"
                                          >ClientProfile</a> class
is used to initiate communication with the hub.
The usual way for a client to obtain a profile for communication is
to call
<a target="samp-javadoc"
 href="apidocs/org/astrogrid/samp/client/DefaultClientProfile.html#getProfile()"
                                         >DefaultClientProfile.getProfile</a>.
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.
</p>

</subsection>

<subsection name="Running a SAMP Hub">

<p>The classes which provide the basic SAMP hub functionality 
are in the package 
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/hub/package-summary.html"
                >org.astrogrid.samp.hub</a>,
and the classes required for running a Standard and Web Profile hub are in
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/xmlrpc/package-summary.html"
                >org.astrogrid.samp.xmlrpc</a> and
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/web/package-summary.html"
                >org.astrogrid.samp.web</a> 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
(<code>runHub</code>/<code>runExternalHub</code>) of the
<a target="samp-javadoc"
   href="apidocs/org/astrogrid/samp/hub/Hub.html"
                                       >Hub</a> 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 <code>Hub</code> class methods or externally by setting the
<a href="sysprops.html#jsamp_hub_profiles">jsamp.hub.profiles</a>
system property.
</p>

</subsection>

<subsection name="Control of Logging">

<p>The JSAMP classes log activity using the J2SE 
<code>java.util.logging</code> 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 <code>java.util.logging</code> javadocs,
but the short story is: to restrict logging to WARNINGs only, do
</p>
<source>
    Logger.getLogger("org.astrogrid.samp").setLevel(Level.WARN);
</source>
<p>or to turn logging off altogether, do
</p>
<source>
    Logger.getLogger("org.astrogrid.samp").setLevel(Level.OFF);
</source>

</subsection>

</section>

</body>

</document>
