Used for exporting a remote object with JRMP and obtaining a stub that communicates to the remote object. Stubs are either generated at runtime using dynamic proxy objects, or they are generated statically at build time, typically using the
rmic
tool.
Deprecated: Static Stubs. Support for statically generated stubs is deprecated. This includes the API in this class that requires the use of static stubs, as well as the runtime support for loading static stubs. Generating stubs dynamically is preferred, using one of the non-deprecated ways of exporting objects as listed below. Do not run rmic
to generate static stub classes. It is unnecessary, and it is also deprecated.
There are eight ways to export remote objects:
- Subclassing
UnicastRemoteObject
and calling the UnicastRemoteObject()
constructor.
- Subclassing
UnicastRemoteObject
and calling the UnicastRemoteObject(port)
constructor.
- Subclassing
UnicastRemoteObject
and calling the UnicastRemoteObject(port, csf, ssf)
constructor.
- Calling the
exportObject(Remote)
method. Deprecated.
- Calling the
exportObject(Remote, port)
method.
- Calling the
exportObject(Remote, port, csf, ssf)
method.
- Calling the
exportObject(Remote, port, filter)
method.
- Calling the
exportObject(Remote, port, csf, ssf, filter)
method.
The fourth technique, exportObject(Remote)
, always uses statically generated stubs and is deprecated.
The other techniques all use the following approach: if the java.rmi.server.ignoreStubClasses
property is true
(case insensitive) or if a static stub cannot be found, stubs are generated dynamically using Proxy
objects. Otherwise, static stubs are used.
The default value of the java.rmi.server.ignoreStubClasses
property is false
.
Statically generated stubs are typically pregenerated from the remote object's class using the rmic
tool. A static stub is loaded and an instance of that stub class is constructed as described below.
- A "root class" is determined as follows: if the remote object's class directly implements an interface that extends
Remote
, then the remote object's class is the root class; otherwise, the root class is the most derived superclass of the remote object's class that directly implements an interface that extends Remote
.
- The name of the stub class to load is determined by concatenating the binary name of the root class with the suffix
_Stub
.
- The stub class is loaded by name using the class loader of the root class. The stub class must be public, it must extend
RemoteStub
, it must reside in a package that is exported to at least the java.rmi
module, and it must have a public constructor that has one parameter of type RemoteRef
.
- Finally, an instance of the stub class is constructed with a
RemoteRef
.
- If the appropriate stub class could not be found, or if the stub class could not be loaded, or if a problem occurs creating the stub instance, a
StubNotFoundException
is thrown.
Stubs are dynamically generated by constructing an instance of a Proxy
with the following characteristics:
- The proxy's class is defined according to the specifications for the
Proxy
class, using the class loader of the remote object's class.
- The proxy implements all the remote interfaces implemented by the remote object's class.
- Each remote interface must either be public and reside in a package that is exported to at least the
java.rmi
module, or it must reside in a package that is open to at least the java.rmi
module.
- The proxy's invocation handler is a
RemoteObjectInvocationHandler
instance constructed with a RemoteRef
.
- If the proxy could not be created, a
StubNotFoundException
will be thrown.
Exported remote objects receive method invocations from the stubs as described in the RMI specification. Each invocation's operation and parameters are unmarshaled using a custom ObjectInputStream
. If an ObjectInputFilter
is provided and is not null
when the object is exported, it is used to filter the parameters as they are unmarshaled from the stream. The filter is used for all invocations and all parameters regardless of the method being invoked or the parameter values. If no filter is provided or is null
for the exported object then the ObjectInputStream
default filter, if any, is used. The default filter is configured with ObjectInputFilter.Config.setSerialFilter
. If the filter rejects any of the parameters, the InvalidClassException
thrown by ObjectInputStream
is reported as the cause of an UnmarshalException
.