<?xml version="1.0"?>

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

<body>

<section name="System Properties">

<subsection name="Introduction">

<p>System properties are a way of communicating values from the 
runtime environment to Java; they are effectively Java's answer
to environment variables.
JSAMP defines some system properties which you can set to alter
the way that it behaves.
</p>

<p>If you are starting java from the command line, you can specify
these using java's <code>-D</code> flag with the syntax
<code>-Dname=value</code>.  Note that any such flags must occur
before a <code>-jar</code> flag on the command line.
For example, to request that JSAMP opens its default HTTP server
to listen on port 2112, you could invoke a JSAMP-using application
like this:
</p>
<pre>
   java -Djsamp.server.port=2112 -jar foo.jar
</pre>
<p>They will work the same way for JSAMP's command line tools,
and for third-party applications which use the JSAMP library for
SAMP communications.
</p>

<p>System properties can also be set programmatically from within Java
code.  Note that in this case you may need to set these property values
near the start of the application; in most cases they are only read once.
</p>

</subsection>

<subsection name="JSAMP's System Properties">

<p>The following system properties may be used to affect JSAMP's
behaviour.  Listed alongside the property name is a link to the
static public class member which may be used to refer to this
property name in code: the javadocs so linked may provide more
detail on use.
</p>
<dl>
<dt><strong>
    <a name="jsamp.hub.profiles"/>
    <code>jsamp.hub.profiles</code>
    (<a target="samp-javadoc"
        href="apidocs/org/astrogrid/samp/hub/Hub.html#HUBPROFILES_PROP"
                                            >Hub.HUBPROFILES_PROP</a>):
    </strong></dt>
<dt><strong>
    <a name="jsamp.hub.profiles.extra"/>
    <code>jsamp.hub.profiles.extra</code>
    (<a target="samp-javadoc"
        href="apidocs/org/astrogrid/samp/hub/Hub.html#EXTRAHUBPROFILES_PROP"
                                            >Hub.EXTRAHUBPROFILES_PROP</a>):
    </strong></dt>
<dd>These define the default profiles which a hub will run.
    If a hub is started from within JSAMP without specifying which profiles
    it will use, the profiles are defined by the value of these properties.
    <code>profiles</code> determines the profiles which will start when the
    hub starts, and <code>profiles.extra</code> determines additional
    profiles which may be started later under user control.
    The values are comma-separated lists, and each item may be one of:
    <ul>
    <li><code>std</code>: Standard Profile</li>
    <li><code>web</code>: Web Profile</li>
    <li><i>hubprofile-classname</i>: the name of a class which implements
        <a target="samp-javadoc"
           href="apidocs/org/astrogrid/samp/hub/HubProfile.html"
                                               >HubProfile</a>
        and has a suitable no-arg constructor.</li>
    </ul>
    If this property is not specified, a default list will be used.
    This is currently the Standard and Web Profiles on start, with no extras
    (equivalent to
    <code>jsamp.hub.profiles=std,web</code>,
    <code>jsamp.hub.profiles.extra=""</code>).
    This property only affects how a hub is run; it has no effect on
    SAMP clients.
    </dd>

<dt><strong>
    <a name="jsamp.localhost"/>
    <code>jsamp.localhost</code>
    (<a target="samp-javadoc"
        href="apidocs/org/astrogrid/samp/SampUtils.html#LOCALHOST_PROP"
                                        >SampUtils.LOCALHOST_PROP</a>):
    </strong></dt>
<dd>Sets the hostname by which the local host is to be identified in
    URLs, for instance server endpoints.
    If unset, the default is currently the loopback address 127.0.0.1.
    However, if this property is set (presumably to the local host's 
    fully- or partly-qualified domain name) its value will be used instead.
    There are two special values:
    <ul>
    <li><code>[hostname]</code>:
        uses the host's fully qualified domain name
        </li>
    <li><code>[hostnumber]</code>:
        uses the host's IP number
        </li>
    </ul>
    </dd>

<dt><strong>
    <a name="jsamp.notray"/>
    <code>jsamp.notray</code>
    (<a target="samp-javadoc"
        href="apidocs/org/astrogrid/samp/gui/SysTray.html#NOTRAY_PROP"
                                            >SysTray.NOTRAY_PROP</a>):
    </strong></dt>
<dd>Prevents the hub appearing in the System Tray if set "<code>true</code>".
    Normally when the hub runs it sits in the system tray on platforms
    that support a system tray, and otherwise it appears in a window
    on the desktop.  But if this property is set, the system tray is
    never used.
    </dd>

<dt><strong>
    <a name="jsamp.server.port"/>
    <code>jsamp.server.port</code>
    (<a target="samp-javadoc"
        href="apidocs/org/astrogrid/samp/httpd/UtilServer.html#PORT_PROP"
                                              >UtilServer.PORT_PROP</a>):
    </strong></dt>
<dd>Gives a preferred port number on which to open the default server.
    In most cases the default server is the only HTTP server used by
    an application using JSAMP, though they can have more than one.
    If this property is undefined or set to zero, or if the specified
    port number is already occupied, an unused port is chosen by the
    system.
    </dd>

<dt><strong>
    <a name="jsamp.web.extrahosts"/>
    <code>jsamp.web.extrahosts</code>
    (<a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/web/CorsHttpServer.html#EXTRAHOSTS_PROP"
                                           >CorsHttpServer.EXTRAHOSTS_PROP</a>):
    </strong></dt>
<dd>Gives a comma-separated list of names (host names or IP numbers)
    of hosts that are permitted to use the Web Profile alongside the
    localhost.  Normally web profile access is only allowed to the local host
    for security reasons, but trusted "near-local" hosts may be added here
    if required.  One possibility is to add the address of a mobile device
    to be used for external application control.
    </dd>

<dt><strong>
    <a name="jsamp.xmlrpc.impl"/>
    <code>jsamp.xmlrpc.impl</code>
    (<a target="samp-javadoc"
        href="apidocs/org/astrogrid/samp/xmlrpc/XmlRpcKit.html#IMPL_PROP"
                                               >XmlRpcKit.IMPL_PROP</a>):
    </strong></dt>
<dd>Indicates which pluggable XML-RPC implementation should be used.
    If defined, this may be one of the following strings:
    <ul>
    <li><code>internal</code>:
        normal internal implementation</li>
    <li><code>xml-log</code>:
        internal implementation which logs all incoming and outgoing
        XML-RPC messages by writing their full XML form to standard output</li>
    <li><code>rpc-log</code>:
        internal implementation which logs all incoming and outgoing
        XML-RPC messages by writing an abbreviated form of their content
        to standard output</li>
    <li><code>apache</code>:
        implementation using Apache's XML-RPC library version 1.2;
        this requires the
        <a href="http://www.astrogrid.org/maven/xmlrpc/jars/xmlrpc-1.2-b1.jar"
           >Apache xmlrpc-1.2b</a>
        classes to be on the classpath</li>
    </ul>
    The members of this list are given as the contents of the
    <a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/xmlrpc/XmlRpcKit.html#KNOWN_IMPLS"
                                              >XmlRpcKit.KNOWN_IMPLS</a>
    array.
    Alternatively the full classname of a class which implements
    <a target="samp-javadoc"
       href="apidocs/org/astrogrid/samp/xmlrpc/XmlRpcKit.html"
                    >org.astrogrid.samp.xmlrpc.XmlRpcKit</a>
    and which has a no-arg constructor may be given.
    The default is currently <code>internal</code> if this property
    is not specified.
    The implementations ought to behave the same as far as communications go,
    though there may be performance differences (the logging ones will be
    slower for sure).  The logging implementations can be useful
    for debugging.
    </dd>
</dl>

<p>Note that the system properties <code>jsamp.lockfile</code> and
<code>jsamp.profile</code>, which existed in JSAMP 1.0, have been 
withdrawn in subsequent versions.
Use the <code>SAMP_HUB</code> environment variable, in accordance
with the standard profile extension, instead.
</p>

</subsection>

</section>

</body>

</document>
