Class UnicastRemoteObject
- All Implemented Interfaces:
Serializable
,Remote
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.
There are eight ways to export remote objects:
- Subclassing
UnicastRemoteObject
and calling theUnicastRemoteObject()
constructor. - Subclassing
UnicastRemoteObject
and calling theUnicastRemoteObject(port)
constructor. - Subclassing
UnicastRemoteObject
and calling theUnicastRemoteObject(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. 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 extendsRemote
. - 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 thejava.rmi
module, and it must have a public constructor that has one parameter of typeRemoteRef
. - 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 thejava.rmi
module. - The proxy's invocation handler is a
RemoteObjectInvocationHandler
instance constructed with aRemoteRef
. - 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
.
- Implementation Note:
- Depending upon which constructor or static method is used for exporting an
object,
RMISocketFactory
may be used for creating sockets. By default, server sockets created byRMISocketFactory
listen on all network interfaces. See theRMISocketFactory
class and the section RMI Socket Factories in the Java RMI Specification. - Since:
- 1.1
- See Also:
-
Field Summary
Fields declared in class java.rmi.server.RemoteObject
ref
-
Constructor Summary
ModifierConstructorDescriptionprotected
Creates and exports a new UnicastRemoteObject object using an anonymous port.protected
UnicastRemoteObject
(int port) Creates and exports a new UnicastRemoteObject object using the particular supplied port.protected
UnicastRemoteObject
(int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) Creates and exports a new UnicastRemoteObject object using the particular supplied port and socket factories. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Returns a clone of the remote object that is distinct from the original.static RemoteStub
exportObject
(Remote obj) Deprecated.This method is deprecated because it supports only static stubs.static Remote
exportObject
(Remote obj, int port) Exports the remote object to make it available to receive incoming calls, using the particular supplied port.static Remote
exportObject
(Remote obj, int port, ObjectInputFilter filter) Exports the remote object to make it available to receive incoming calls, using the particular supplied port and filter.static Remote
exportObject
(Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) Exports the remote object to make it available to receive incoming calls, using a transport specified by the given socket factory.static Remote
exportObject
(Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf, ObjectInputFilter filter) Exports the remote object to make it available to receive incoming calls, using a transport specified by the given socket factory and filter.static boolean
unexportObject
(Remote obj, boolean force) Removes the remote object, obj, from the RMI runtime.Methods declared in class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
-
Constructor Details
-
UnicastRemoteObject
Creates and exports a new UnicastRemoteObject object using an anonymous port.The object is exported with a server socket created using the
RMISocketFactory
class.- Throws:
RemoteException
- if failed to export object- Since:
- 1.1
-
UnicastRemoteObject
Creates and exports a new UnicastRemoteObject object using the particular supplied port.The object is exported with a server socket created using the
RMISocketFactory
class.- Parameters:
port
- the port number on which the remote object receives calls (ifport
is zero, an anonymous port is chosen)- Throws:
RemoteException
- if failed to export object- Since:
- 1.2
-
UnicastRemoteObject
protected UnicastRemoteObject(int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws RemoteException Creates and exports a new UnicastRemoteObject object using the particular supplied port and socket factories.Either socket factory may be
null
, in which case the corresponding client or server socket creation method ofRMISocketFactory
is used instead.- Parameters:
port
- the port number on which the remote object receives calls (ifport
is zero, an anonymous port is chosen)csf
- the client-side socket factory for making calls to the remote objectssf
- the server-side socket factory for receiving remote calls- Throws:
RemoteException
- if failed to export object- Since:
- 1.2
-
-
Method Details
-
clone
Returns a clone of the remote object that is distinct from the original.- Overrides:
clone
in classObject
- Returns:
- the new remote object
- Throws:
CloneNotSupportedException
- if clone failed due to a RemoteException.- Since:
- 1.1
- See Also:
-
exportObject
Deprecated.This method is deprecated because it supports only static stubs. UseexportObject(Remote, port)
orexportObject(Remote, port, csf, ssf)
instead.Exports the remote object to make it available to receive incoming calls using an anonymous port. This method will always return a statically generated stub.The object is exported with a server socket created using the
RMISocketFactory
class.- Parameters:
obj
- the remote object to be exported- Returns:
- remote object stub
- Throws:
RemoteException
- if export fails- Since:
- 1.1
-
exportObject
Exports the remote object to make it available to receive incoming calls, using the particular supplied port.The object is exported with a server socket created using the
RMISocketFactory
class.- Parameters:
obj
- the remote object to be exportedport
- the port to export the object on- Returns:
- remote object stub
- Throws:
RemoteException
- if export fails- Since:
- 1.2
-
exportObject
public static Remote exportObject(Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws RemoteException Exports the remote object to make it available to receive incoming calls, using a transport specified by the given socket factory.Either socket factory may be
null
, in which case the corresponding client or server socket creation method ofRMISocketFactory
is used instead.- Parameters:
obj
- the remote object to be exportedport
- the port to export the object oncsf
- the client-side socket factory for making calls to the remote objectssf
- the server-side socket factory for receiving remote calls- Returns:
- remote object stub
- Throws:
RemoteException
- if export fails- Since:
- 1.2
-
exportObject
public static Remote exportObject(Remote obj, int port, ObjectInputFilter filter) throws RemoteException Exports the remote object to make it available to receive incoming calls, using the particular supplied port and filter.The object is exported with a server socket created using the
RMISocketFactory
class.- Parameters:
obj
- the remote object to be exportedport
- the port to export the object onfilter
- an ObjectInputFilter applied when deserializing invocation arguments; may benull
- Returns:
- remote object stub
- Throws:
RemoteException
- if export fails- Since:
- 9
-
exportObject
public static Remote exportObject(Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf, ObjectInputFilter filter) throws RemoteException Exports the remote object to make it available to receive incoming calls, using a transport specified by the given socket factory and filter.Either socket factory may be
null
, in which case the corresponding client or server socket creation method ofRMISocketFactory
is used instead.- Parameters:
obj
- the remote object to be exportedport
- the port to export the object oncsf
- the client-side socket factory for making calls to the remote objectssf
- the server-side socket factory for receiving remote callsfilter
- an ObjectInputFilter applied when deserializing invocation arguments; may benull
- Returns:
- remote object stub
- Throws:
RemoteException
- if export fails- Since:
- 9
-
unexportObject
Removes the remote object, obj, from the RMI runtime. If successful, the object can no longer accept incoming RMI calls. If the force parameter is true, the object is forcibly unexported even if there are pending calls to the remote object or the remote object still has calls in progress. If the force parameter is false, the object is only unexported if there are no pending or in progress calls to the object.- Parameters:
obj
- the remote object to be unexportedforce
- if true, unexports the object even if there are pending or in-progress calls; if false, only unexports the object if there are no pending or in-progress calls- Returns:
- true if operation is successful, false otherwise
- Throws:
NoSuchObjectException
- if the remote object is not currently exported- Since:
- 1.2
-