System Properties


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.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 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.
jsamp.lockfile (SampUtils.LOCKFILE_PROP):
Permits overriding the location at which the Standard Profile SAMP lockfile is written/read. By default the lockfile is ".samp" in the user's home directory, as defined by the SAMP Standard Profile, but if this property is set, it gives a different location to use. Note that any clients and hubs using a given non-standard value of this parameter will only be able to communicate with other clients/hubs using the same non-standard value.
jsamp.profile (DefaultClientProfile.PROFILE_PROP):
Determines the default profile used by SAMP clients. Currently, if the value is not defined or is "standard" the SAMP Standard Profile will be used, and any other value will be interpreted as the name of a class which implements the ClientProfile interface.