sun.rmi Properties


WARNING: The properties described here are not supported, can change at any time, and only exist in certain implementations of RMI from Sun MicrosystemsTM. These properties are not part of the RMI public API. To see a list of the properties that are part of the RMI public API, please refer to the page, java.rmi Properties.

Please Note: Unless otherwise stated, any output from these properties is sent to System.err.

Each of the properties that have names ending in ".logLevel" have possible values of "SILENT", "BRIEF", and "VERBOSE". These values are case insensitive and may be abbreviated as a string containing the first n letters, where n is greater than or equal to 1. If not specified, these properties have a default value of "SILENT". A value of "BRIEF" causes the corresponding Logger to be set to the level Level.FINE, and a value of "VERBOSE" causes the corresponding Logger to be set to the level Level.FINER. Use of the logging configuration file is now preferred over the use of these sun.rmi.* system properties for logging.

Logging messages are sent to System.err. For instance, if a property is said to send output to the "transport" log, this means that logging messages are sent to a LogStream returned by java.rmi.server.LogStream.log("transport"), which sends messages to System.err, unless you've set it to something else.

Properties that can be set on rmid

sun.rmi.activation.execTimeout (1.2 and later)
The value of this property represents the time (in milliseconds) that the activation system will wait for a spawned activation group to start up. Setting this property gives you the ability to shorten or lengthen the maximum time that rmid will wait for an activation group to start up. The default value is 30000 milliseconds (30 seconds).

sun.rmi.activation.snapshotInterval (1.2 and later)
This property controls the number of updates for which the activation system will wait before it serializes a snapshot of its state to the rmid log file on disk. An "update" refers to a persistent change in the state of the activation system (for example, the registration of an Activatable object) since the last snapshot was taken. Changing the value of this property can be used to make rmid re-start more quickly (by taking snapshots of the log more often) or to make rmid more efficient (by taking snapshots of the log less often). The value of this property is a positive integer value. The default value is 200.

sun.rmi.log.debug (1.2 and later)
If this value is true, details of rmid's logging activity are sent to System.err.

sun.rmi.rmid.maxstartgroup (1.2 and later)
The value of this property represents the maximum number of activation group VMs that rmid will allow to be in the "spawning but not yet active" state simultaneously. If more VMs need to be started, they will queue up until one of the current spawn attempts either succeeds or times out. Note that this property does not limit the maximum number of active VMs; it is intended to smooth out sudden spikes of activity to avoid reaching operating system limits. While setting the value of this property to a lower number may result in a longer start-up time for rmid, and setting the value to a higher number could shorten the start-up time, setting this value too high can crash rmid, because your system may run out of resources. The default value is 3.

sun.rmi.server.activation.debugExec (1.2 and later)
If this value is true, the activation system will print out debugging information to the command line that is used for spawning activation groups. By default, the value is false, so debugging information is not printed.

Properties that are useful to set on JVMs* that export remote objects

sun.rmi.dgc.ackTimeout (1.4 and later)
The value of this property represents the length of time (in milliseconds) that the server-side RMI runtime will strongly refer to a remote object (or a reference to a remote object) that has been returned from the current virtual machine as part of the result of a remote method call, until it receives positive acknowledgment from the client that the remote reference has been fully received and processed. This timeout only applies to failure situations (in which the client fails to send the acknowledgment). Setting the value too low can increase the risk of a remote object being prematurely garbage collected when the only known reference to the remote object is the one in transit as part of the remote method call result. The maximum value is Long.MAX_VALUE. The default value is 300000 (five minutes).

sun.rmi.dgc.checkInterval (1.1 and later)
The value of this property represents (in milliseconds) how often the RMI runtime checks for expired DGC leases. The default value is 300000 milliseconds (5 minutes).

sun.rmi.dgc.logLevel (1.1 and later)
This property controls the logging of incoming and outgoing calls related to DGC lease granting, renewing, and expiration. It sends output to the "dgc" log.

sun.rmi.dgc.server.gcInterval (1.2 and later)
When it is necessary to ensure that unreachable remote objects are unexported and garbage collected in a timely fashion, the value of this property represents the maximum interval (in milliseconds) that the RMI runtime will allow between garbage collections of the local heap. The default value is 60000 milliseconds (60 seconds).

sun.rmi.loader.logLevel (1.2 and later)
This property controls the logging of each class name and codebase, whenever the RMI runtime attempts to load a class as a result of unmarshalling either an argument or return value. This property sends output to the "loader" log.

Please note in 1.3 that while the codebase that is printed is the annotated codebase, it may not necessarily be the actual codebase from which the class gets loaded; the RMI class loader defers the class loading to the current thread's context class loader, which may load the class from the CLASSPATH, rather than the annotated codebase. This issue no longer exists in 1.4.

sun.rmi.server.exceptionTrace (1.2 and later)
This property controls the output of server-side stack traces from exceptions and errors that are thrown by dispatched, incoming remote calls. If this value is true, exception stack traces will be printed. By default (false), exception and error stack traces are not printed.

sun.rmi.server.suppressStackTraces (1.4 and later)
If this value is true, the server-side RMI runtime implementation will clear the stack traces of all exceptions thrown from the current virtual machine as the result of remote calls. This property is useful for certain RMI server applications that may wish to prevent any server-side stack trace data from accompanying an exception to be marshalled out as the result of an incoming remote call (as part of the exception's default serialized form in J2SE 1.4), perhaps for reasons of performance or confidentiality.

sun.rmi.transport.logLevel (1.1 and later)
This property controls detailed logging throughout the transport layer. It sends output to the "transport" log.

sun.rmi.transport.tcp.localHostNameTimeOut (1.1.7 and later)
The value of this property represents the time (in milliseconds) that the RMI runtime will wait to obtain a fully qualified domain name for the local host. The default value is 10000 milliseconds (10 seconds).

sun.rmi.transport.tcp.logLevel (1.1 and later)
This property provides detailed logging for the TCP-specific transport sub-layer. It sends output to the "tcp" log.

sun.rmi.transport.tcp.readTimeout (1.2.2 and later)
The value of this property represents the time (in milliseconds) used as an idle timeout for incoming RMI-TCP connections. The value is passed to java.net.Socket.setSoTimeout. This property is used only for cases where a client has not dropped an unused connection as it should (see sun.rmi.transport.connectionTimeout). The default value is 2*3600*1000 milliseconds (2 hours).

Properties that are useful to set on JVMs that make remote method calls

sun.rmi.client.logCalls (1.4 and later)
If the value of this property is true, the sun.rmi.client.call logger will be set to the level Level.FINER. Remote calls are logged at the level Level.FINER, and exceptions from remote calls are logged at the level Level.FINE.

sun.rmi.dgc.cleanInterval (1.1 and later)
The value of this property represents the maximum length of time (in milliseconds) that the RMI runtime will wait before retrying a failed DGC "clean" call. The default value is 180000 milliseconds (3 minutes).

sun.rmi.dgc.client.gcInterval (1.2 and later)
When it is necessary to ensure that DGC clean calls for unreachable remote references are delivered in a timely fashion, the value of this property represents the maximum interval (in milliseconds) that the RMI runtime will allow between garbage collections of the local heap. The default value is 60000 milliseconds (60 seconds).

sun.rmi.loader.logLevel (1.2 and later)
This property controls the logging of each class name and codebase, whenever the RMI runtime attempts to load a class as a result of unmarshalling either an argument or return value. This property sends output to the "loader" log.

Please note in 1.3 that while the codebase that is printed is the annotated codebase, it may not necessarily be the actual codebase from which the class gets loaded; the RMI class loader defers the class loading to the current thread's context class loader, which may load the class from the CLASSPATH, rather than the annotated codebase. This issue no longer exists in 1.4.

sun.rmi.server.logLevel (1.1 and later)
This property controls the logging of information related to outgoing calls, including some connection-reuse information. It sends output to the "transport" log.

sun.rmi.transport.connectionTimeout (1.1.6 and later)
The value of this property represents the period (in milliseconds) for which RMI socket connections may reside in an "unused" state, before the RMI runtime will allow those connections to be freed (closed). The default value is 15000 milliseconds (15 seconds). See also sun.rmi.transport.tcp.readTimeout.

sun.rmi.transport.logLevel (1.1 and later)
This property controls detailed logging throughout the transport layer. It sends output to the "transport" log.

sun.rmi.transport.proxy.connectTimeout (1.1 and later)
The value of this property represents the maximum length of time (in milliseconds) that the RMI runtime will wait for a connection attempt (createSocket) to complete, before attempting to contact the server using HTTP. This property is only used when the http.proxyHost property is set and the value of java.rmi.server.disableHttp is false. The default value is 15000 milliseconds (15 seconds).

sun.rmi.transport.proxy.eagerHttpFallback (1.4.1 and later)
If this value is true and the java.rmi.server.disableHttp system property is not set, then RMI's default socket factory will fall back to HTTP tunneling when any java.net.SocketException is thrown from an initial (direct) connection attempt, as opposed to the default behavior of falling back to HTTP tunneling only if an initial connection attempt throws a java.net.UnknownHostException or java.net.NoRouteToHostException.

This setting can be useful when dealing with firewalls that deny (instead of ignore) connection attempts to unauthorized ports, resulting in java.net.ConnectionExceptions inside the client's default RMI socket factory. If this system property is not enabled, then such ConnectionExceptions will not trigger HTTP fallback, since they are neither UnknownHostExceptions nor NoRouteToHostExceptions. However, if this system property is enabled, then the ConnectionExceptions will cause HTTP fallback to occur, because ConnectionException is a subclass of SocketException.

sun.rmi.transport.proxy.logLevel (1.1 and later)
This property controls the logging of events (createSocket and createServerSocket) when the default RMISocketFactory class is used. This type of logging is likely to be useful for applications that use RMI over HTTP. Events in custom socket factories are not logged by this property. It sends some messages to the "proxy" log, and others to the "transport" log.

sun.rmi.transport.tcp.handshakeTimeout (1.4 and later)
The value of this property represents the length of time (in milliseconds) that the client-side RMI runtime will use as a socket read timeout when reading initial handshake data (protocol acknowledgment) when establishing a new JRMP connection. This property is used to configure how long the RMI runtime will wait before deciding that a TCP connection accepted by a remote server cannot actually be used, either because the entity listening on the remote host's port is not actually an RMI server, or because the server is somehow not functioning correctly. The maximum value is Integer.MAX_VALUE, and a value of zero indicates an infinite timeout. The default value is 60000 (one minute).

sun.rmi.transport.tcp.logLevel (1.1 and later)
This property provides detailed logging for the TCP-specific transport sub-layer. It sends output to the "tcp" log.
We are very interested in knowing whether this information is useful. Please send any comments or suggestions to: rmi-comments@java.sun.com, with a subject of "sun.rmi properties FAQ".

*As used on this web site, the terms "Java(TM) virtual machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. 
Please send comments to: rmi-comments@java.sun.com 		 Sun