sun.rmi Properties

WARNING: The properties described here are not supported, can change at any time, and only exist in certain implementations of Java^TM Remote Method Invocation (Java RMI) from Sun Microsystems. These properties are not part of the Java RMI public API. To see a list of the properties that are part of the 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.execPolicy (1.3 and later)

The value of this property controls the policy that rmid uses to determine whether or not the information in an ActivationGroupDesc may be used to launch a virtual machine for an activation group. The possible values for the property are default, none, or the fully qualified name of a class that implements a method named checkExecCommand that is called to verify ActivationGroupDesc information. For details, see the tools documentation for rmid [Solaris and Linux] [Windows].

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.groupThrottle (5.0 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. In previous releases, this property was named sun.rmi.rmid.maxstartgroup which is no longer supported.

sun.rmi.activation.groupTimeout (5.0 and later)

The value of this property represents the time (in milliseconds) that rmid will wait after destroying an activation group's process before creating a new incarnation of the activation group. The default value is 60000 milliseconds (60 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.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 VMs 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 Java 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 Java RMI runtime checks for expired DGC leases. The default value is half the value of the java.rmi.dgc.leaseValue property.

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 Java RMI runtime will allow between garbage collections of the local heap. The default value is 3600000 milliseconds (one hour).

sun.rmi.loader.logLevel (1.2 and later)

This property controls the logging of each class name and codebase, whenever the Java 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.

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 Java 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 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 Java 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 TCP connections the Java RMI runtime uses. 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 (two hours).

sun.rmi.transport.tcp.maxConnectionThreads (6 and later)

The value of this property controls the maximum size of the pool of threads used to handle incoming connections, and thus it places an upper bound on the number of incoming remote method invocations that can execute concurrently. Setting this property to a lower value may improve the throughput of a Java RMI server application under heavy load, but setting it too low may (depending on the nature of the application's remote invocation patterns) lead to deadlock or starvation. The default value is the maximum, Integer.MAX_VALUE, which effectively means no limit.

sun.rmi.transport.tcp.threadKeepAliveTime (6 and later)

The value of this property controls the amount of time that a thread in the pool of threads used to handle incoming connections will remain idle before terminating. The default value is 60000 milliseconds (one minute).

Properties that are useful to set on VMs 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 Java RMI runtime will wait before retrying a failed DGC "clean" call. The default value is 180000 milliseconds (three 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 Java RMI runtime will allow between garbage collections of the local heap. The default value is 3600000 milliseconds (one hour).

sun.rmi.loader.logLevel (1.2 and later)

This property controls the logging of each class name and codebase, whenever the Java 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.

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 socket connections may reside in an "unused" state, before the Java 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 Java 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 the default global RMISocketFactory 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 global RMISocketFactory. 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 Java 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 Java 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 Java 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 a Java 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.responseTimeout (1.4 and later)

The value of this property represents the length of time (in milliseconds) that the client-side Java RMI runtime will use as a socket read timeout on an established JRMP connection when reading response data for a remote method invocation. Therefore, this property can be used to impose a timeout on waiting for the results of remote invocations; if this timeout expires, the associated invocation will fail with a java.rmi.RemoteException. Setting this property should be done with due consideration, however, because it effectively places an upper bound on the allowed duration of any successful outgoing remote invocation. The maximum value is Integer.MAX_VALUE, and a value of zero indicates an infinite timeout. The default value is zero (no timeout).

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.

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

Java Software