System Properties

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):
jsamp.hub.profiles.extra (Hub.EXTRAHUBPROFILES_PROP):
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. profiles determines the profiles which will start when the hub starts, and profiles.extra determines additional profiles which may be started later under user control. The values are comma-separated lists, 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 the Standard and Web Profiles on start, with no extras (equivalent to jsamp.hub.profiles=std,web, jsamp.hub.profiles.extra=""). 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.mtypes.safe (ListMessageRestriction.SAFE_MTYPE_PROP):
Provides a comma-separated list of MTypes that web clients are permitted to send; others may be blocked for security reasons.
jsamp.notray (SysTray.NOTRAY_PROP):
Prevents the hub appearing in the System Tray if set "true". 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.
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.web.extrahosts (CorsHttpServer.EXTRAHOSTS_PROP):
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.
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.