# `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` (1.5 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` (1.5 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 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 Java 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 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.

> 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 Java 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 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 (2 hours).

## 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 (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 Java 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 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.

> 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 Java 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 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.ConnectionException`s inside the client's default global `RMISocketFactory`. If this system property is not enabled, then such `ConnectionException`s will not trigger HTTP fallback, since they are neither `UnknownHostException`s nor `NoRouteToHostException`s. However, if this system property is enabled, then the `ConnectionException`s 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.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".

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