Introduction

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.

If you are starting java from the command line, you can specify these using java's -D flag with the syntax -Dname=value. Note that any such flags must occur before a -jar 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:

   java -Djsamp.server.port=2112 -jar foo.jar

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.

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.

JSAMP's System Properties

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.

jsamp.hub.profiles (Hub.HUBPROFILES_PROP):

Defines 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 this property. The value is a comma-separated list, and each item may be one of:

• std: Standard Profile
• web: Web Profile
• hubprofile-classname: the name of a class which implements HubProfile and has a suitable no-arg constructor.

If this property is not specified, a default list will be used. This is currently just the Standard Profile (equivalent to jsamp.hub.profiles=std). This property only affects how a hub is run; it has no effect on SAMP clients.

jsamp.localhost (SampUtils.LOCALHOST_PROP):

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:

• [hostname]: uses the host's fully qualified domain name
• [hostnumber]: uses the host's IP number

jsamp.server.port (UtilServer.PORT_PROP):

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.

jsamp.xmlrpc.impl (XmlRpcKit.IMPL_PROP):

Indicates which pluggable XML-RPC implementation should be used. If defined, this may be one of the following strings:

• internal: normal internal implementation
• xml-log: internal implementation which logs all incoming and outgoing XML-RPC messages by writing their full XML form to standard output
• rpc-log: internal implementation which logs all incoming and outgoing XML-RPC messages by writing an abbreviated form of their content to standard output
• apache: implementation using Apache's XML-RPC library version 1.2; this requires the Apache xmlrpc-1.2b classes to be on the classpath

The members of this list are given as the contents of the XmlRpcKit.KNOWN_IMPLS array. Alternatively the full classname of a class which implements org.astrogrid.samp.xmlrpc.XmlRpcKit and which has a no-arg constructor may be given. The default is currently internal 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.

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