Next Previous Up Contents
Next: JDBC Configuration
Up: Java Options
Previous: Memory Size

10.2.3 System properties

System properties are a way of getting information into Java (they are the Java equivalent of environment variables). The following ones have special significance within TOPCAT:

On the Apple Macintosh platform only, this property controls whether menus appear at the top of the screen as usual for Mac, or at the top of individual windows as usual for Java. By default it is set to true for TOPCAT, so menus mostly appear at the top of the screen (though it's not true to say that TOPCAT obeys the Mac look and feel completely); if you prefer the more Java-like look and feel, set it to false.
If you are operating inside a firewall which prohibits direct HTTP connections, you can set this to the name of an HTTP proxy server in order to access remote servers as required for VO functionality etc. There are a number of related system properties which you may or may not need to use in this case: http.proxyPort, https.proxyHost etc. See the appropriate java documentation (e.g. by googling for "http.proxyHost") for details.
The directory in which TOPCAT will write any temporary files it needs. This defaults to the system temporary directory (e.g. /tmp on Unix), so if working with large unmapped (e.g. CSV) tables on a machine with limited space on the default disk, it may be necessary to change it.
Controls the level of parallelisation done by certain processing, currently mainly visualisation. By default it is typically set to one less than the number of processing cores on the current machine. To inhibit parallelisation (e.g. if you suspect that the parallel output is giving different results to sequential processing) you can set this to 1.
Can be set to a (colon-separated) list of JDBC driver classes using which SQL databases can be accessed (see Section 10.3).
Can be set to a (colon-separated) list of classes containing static methods which define user-provided functions for synthetic columns or subsets. (see Section 7.10).
Can be set to a (colon-separated) list of classes containing static methods which define user-provided functions for use in custom activation expressions. (see Section 7.10).
This property determines what profiles a SAMP hub will use if you run an internal or external hub from TOPCAT (either with the -hub/-exthub flag or from the GUI). The value is a comma-separated list of profile specifiers; options are "std" for Standard Profile, "web" for Web Profile or the name of a class implementing the org.astrogrid.samp.hub.HubProfile interface. The default setting runs just a Standard Profile hub, but, for instance, setting it to "std,web" would run a Web Profile as well. Note you should include std in the list, otherwise TOPCAT will not be able to talk to the hub. See the JSAMP documentation for more detail.
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. Two special values may also be set: "[hostname]" for the host's fully qualified domain name, and "[hostnumber]" for the IP number.
Gives a preferred port number on which to open TOPCAT's internal HTTP server, used for SAMP communications amongst other things. If this port is unavailable, some other port will be used instead.
Indicates which pluggable XML-RPC implementation should be used for SAMP communications. By default an internal implementation is used. If it is set to "xml-log" or "rpc-log" then all XML-RPC communications will be logged in very or fairly verbose terms respectively to standard output. The classname of an org.astrogrid.samp.xmlrpc.XmlRpcKit implementation may be given instead to use a custom implementation.
Can be set to a (colon-separated on *nix, semicolon-separated on Windows) list of files giving custom lookup tables for auxiliary axis and density map colour maps. Each file should be a text file containing a number of space-separated lines, each containing red, green, blue samples in the range 0-1. For instance the file
       1.0  1.0  0.0
       1.0  0.0  1.0
would give a colour map that fades from yellow to magenta. Any number of samples may be given; the scale is interpolated.
If set to "true", this will work around a bug in the mark()/reset() methods of some java InputStream classes. These are rather common, including in Sun's J2SE system libraries. Use this if you are seeing errors that say something like "Resetting to invalid mark". Currently defaults to "false".
If set to "true", this will prevent directories in the MySpace file browser from being read more than once. This is a workaround for MySpace performance problems at time of writing (April 2006); setting it true may lead to out of date file listings in MySpace, but it may be much faster. This behaviour may be withdrawn in future versions if MySpace performance improves. Currently defaults to "false".
Raises the maximum number of concurrent queries that may be made during a multi-cone operation. You should only increase this value with great care since you risk overloading servers and becoming unpopular with data centres. As a rule, you should only increase this value if you have obtained permission from the data centres whose services on which you will be using the increased parallelism.
Configures the list of authentication schemes that will be considered when connecting to services issuing a WWW-Authenticate challenge. A comma-separated list of scheme names or implementation classnames may be provided.
Can be set to a (colon-separated) list of classes which provide access to remote filespace implementations. Thus-named classes should implement the interface which specifies how you can log on to such a service and provides a hierarchical view of the filespace it contains.
Can be set to a (colon-separated) list of custom table load dialogue classes. Briefly, you can install your own table import dialogues at runtime by providing classes which implement the interface and naming them in this property. See STIL documentation for more detail.
Can be set to a (colon-separated) list of custom table format input handler classes (see Section 4.1.3).
Can be set to a (colon-separated) list of custom table scheme handler classes. Each class must implement the interface, and must have a no-arg constructor. The schemes thus named will be available alongside the standard ones listed in Section 4.3.
Can be set to determine the default storage policy. Setting it to "disk" has basically the same effect as supplying the "-disk" argument on the TOPCAT command line (see Section 10.1). Other possible values are "adaptive", "memory", "sideways" and "discard"; see SUN/252. The default is "adaptive", which means storing smaller tables in memory, and larger ones on disk.
Determines whether and how unmapping of memory mapped buffers is done. Possible values are "sun" (the default), "cleaner", "unsafe" or "none". In most cases you are advised to leave this alone, but in the event of unmapping-related JVM crashes (not expected!), setting it to none may help.
Can be set to a (colon-separated) list of custom table format output handler classes (see Section 4.1.3).
Can be set to a (colon-separated) list of custom Activation Actions. Each element must be the class path of a class implementing the interface, and which has a no-arg constructor.
Defines extension tools to be used by TOPCAT. The value is a colon-separated list of class names, each of which must implement the interface and have a no-arg constructor. The actions corresponding to any such classes will be added to toolbar. This is an experimental extensibility feature, which may be modified or withdrawn in a future release.
Sets the current working directory. This determines the default from which the file browsers will start.
Determines how namespacing is handled in input VOTable documents. Known values are "none" (no namespacing, xmlns declarations in VOTable document will probably confuse parser), "lax" (anything that looks like it is probably a VOTable element will be treated as a VOTable element) and "strict" (VOTable elements must be properly declared in one of the correct VOTable namespaces). May also be set to the classname of a implementation. The default is "lax".
Controls the behaviour when encountering a VOTable FIELD or PARAM element with a datatype attribute of char/unicodeChar, and no arraysize attribute. The VOTable standard says this indicates a single character, but some VOTables omit arraysize specification by accident when they intend arraysize="*". If votable.strict is set true, a missing arraysize will be interpreted as meaning a single character, and if false, it will be interpreted as a variable-length array of characters (a string). The default is true.
Selects the version of the VOTable standard which output VOTables will conform to by default. May take the values "1.0", "1.1", "1.2", "1.3" or "1.4". By default, version 1.4 VOTables are written.

To define these properties on the command line you use the -D flag, which has the form

If you're using the TOPCAT startup script, you can write something like:
    topcat -Djdbc.drivers=org.postgresql.Driver ...
or if you're using the java command directly:
    java -Djdbc.drivers=org.postgresql.Driver ...

Alternatively you may find it more convenient to write these definitions in a file named in your home directory; the above command-line flag would be equivalent to inserting the line:

in your file.

Next Previous Up Contents
Next: JDBC Configuration
Up: Java Options
Previous: Memory Size

TOPCAT - Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page:
Author email:
Mailing list: