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

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

<body>
<section name="External Dependencies">

<p>JSAMP is a pure Java library.  
It should run on any Java Runtime Environment of version J2SE1.4 or above.
It does not <em>require</em> any external libraries, though see below.
</p>

<p>In order to perform the necessary XML-RPC communications for use with
the SAMP Standard Profile, a pluggable layer is used.  
This means that you can choose which XML-RPC library is used.
Currently, there are the following possibilities:
</p>
<dl>
<dt>Internal</dt>
<dd>A standalone library implementation is provided within JSAMP,
    so if you wish to use this, no external dependencies are required.
    </dd>
<dt>Apache XML-RPC 1.2</dt>
<dd>To use the Apache XML-RPC library, the Apache classes must be on the
    class path.  They can be found in the jar file
    <a href="http://www.astrogrid.org/maven/xmlrpc/jars/xmlrpc-1.2-b1.jar"
                                                       >xmlrpc-1.2-b1.jar</a>.
    </dd>
<dt>Roll your own</dt>
<dd>By implementing the class
    <a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/xmlrpc/XmlRpcKit.html"
                    >org.astrogrid.samp.xmlrpc.XmlRpcKit</a>
    you can provide your own implementation, perhaps based on a third party
    XML-RPC library.
    </dd>
</dl>
<p>In some cases you can choose which of these is used by supplying
particular implementations of the classes in the <code>xmlrpc</code>
package.  Mostly though, an implementation will be chosen without any 
explicit choice in the application code.  In this case, you can control
which implementation is used by setting the value of the 
<a href="sysprops.html#jsamp_xmlrpc_impl">jsamp.xmlrpc.impl</a>
system property.
</p>

<p>The internal implementation was introduced as an experimental measure,
but it seems to be quite reliable and of comparable speed to the Apache one.
The internal implementation is therefore recommended for most purposes.
</p>

</section>

<section name="Internal Dependencies">

<p>If you are embedding JSAMP into your own application code but want to
keep the size of the additional class files to a minimum, you can avoid
incorporating all of the classes in the built jar file.
The subordinate packages are arranged in a modular way.
They are organised as follows:
</p>
<dl>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/package-summary.html"
                    >org.astrogrid.samp</a></dt>
<dd>Basic classes required throughout the library.  You need these
    whatever you're doing.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/client/package-summary.html"
                    >org.astrogrid.samp.client</a></dt>
<dd>Classes intended for use by application authors writing SAMP clients.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/hub/package-summary.html"
                    >org.astrogrid.samp.hub</a></dt>
<dd>Classes providing the hub implementation.
    If you are only writing a client which will not contain an embedded hub,
    you do not need these classes.</dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/gui/package-summary.html"
                    >org.astrogrid.samp.gui</a></dt>
<dd>Utility classes providing GUI components for visual display of SAMP
    activity.  These classes are not required for basic client or hub
    operations.</dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/test/package-summary.html"
                    >org.astrogrid.samp.test</a></dt>
<dd>Classes providing the hub test suite and some diagnostic tools intended
    for debugging SAMP systems.  These are not intended for use in third party
    applications.  This does not however contain unit tests for JSAMP
    itself, which are not present in the distributed jar file.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/bridge/package-summary.html"
                    >org.astrogrid.samp.bridge</a></dt>
<dd>Classes for the Bridge application, which can connect two or more hubs
    together.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/httpd/package-summary.html"
                    >org.astrogrid.samp.httpd</a></dt>
<dd>Simple HTTP server implementation.  This is required by the internal
    XML-RPC implementation.  It may also provide useful utility functionality
    for client applications who wish to serve resources over HTTP.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/xmlrpc/package-summary.html"
                    >org.astrogrid.samp.xmlrpc</a></dt>
<dd>Classes which deal with XML-RPC based communications and the
    implementation of the Standard Profile.
    Everything in the packages above is independent of the Profile used,
    so if for some reason you are using a non-standard profile, you may
    not need the <code>xmlrpc*</code> packages.
    The classes here define a pluggable interface to XML-RPC implementations;
    one or other of the provided implementations, or a custom-written one,
    will be required as well to make use of these classes.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/xmlrpc/apache/package-summary.html"
                    >org.astrogrid.samp.xmlrpc.apache</a></dt>
<dd>Implementation of the pluggable XML-RPC layer based on the Apache XML-RPC
    library.  To use these classes you will need the Apache XML-RPC library
    on the classpath as well.  If you are using the internal XML-RPC 
    implementation, these classes are not required.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/xmlrpc/internal/package-summary.html"
                    >org.astrogrid.samp.xmlrpc.internal</a></dt>
<dd>Implementation of the pluggable XML-RPC layer which requires no 
    external libraries.  If you are using the Apache library
    or a home-grown XML-RPC implementation, these classes are not required.
    </dd>
<dt><a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/web/package-summary.html"
                    >org.astrogrid.samp.web</a></dt>
<dd>Implementation of the Web Profile hub and clients.  The Web Profile
    is XML-RPC based, and requires some of the classes in the
    <code>org.astrogrid.samp.xmlrpc*</code> packages as well.
    </dd>
</dl>

</section>
</body>

</document>
