java.rmi.server.UnicastRemoteObject

All Implemented Interfaces:: Serializable, Remote

Direct Known Subclasses:: ActivationGroup

public class UnicastRemoteObject
extends RemoteServer

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.

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 by RMISocketFactory listen on all network interfaces. See the RMISocketFactory class and the section RMI Socket Factories in the Java RMI Specification.
Since:: 1.1
See Also:: Serialized Form

Field Summary

Fields declared in class java.rmi.server.RemoteObject
ref

Constructor Summary

Constructors
Modifier	Constructor	Description
`protected`	`UnicastRemoteObject()`	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 Type	Method	Description
`Object`	`clone()`	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

Methods declared in class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods declared in class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details
- UnicastRemoteObject
  
  protected UnicastRemoteObject() throws RemoteException
  
  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
  
  protected UnicastRemoteObject(int port) throws RemoteException
  
  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 (if port 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 of RMISocketFactory is used instead.
  
  Parameters:
  
  port - the port number on which the remote object receives calls (if port is zero, an anonymous port is chosen)
  
  csf - the client-side socket factory for making calls to the remote object
  
  ssf - the server-side socket factory for receiving remote calls
  
  Throws:
  
  RemoteException - if failed to export object
  
  Since:
  
  1.2
Method Details
- clone
  
  public Object clone() throws CloneNotSupportedException
  
  Returns a clone of the remote object that is distinct from the original.
  
  Overrides:
  
  clone in class Object
  
  Returns:
  
  the new remote object
  
  Throws:
  
  CloneNotSupportedException - if clone failed due to a RemoteException.
  
  Since:
  
  1.1
  
  See Also:
  
  Cloneable
- exportObject
  
  @Deprecated public static RemoteStub exportObject(Remote obj) throws RemoteException
  
  Deprecated.
  This method is deprecated because it supports only static stubs. Use exportObject(Remote, port) or exportObject(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
  
  public static Remote exportObject(Remote obj, int port) throws RemoteException
  
  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 exported
  
  port - 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 of RMISocketFactory is used instead.
  
  Parameters:
  
  obj - the remote object to be exported
  
  port - the port to export the object on
  
  csf - the client-side socket factory for making calls to the remote object
  
  ssf - 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 exported
  
  port - the port to export the object on
  
  filter - an ObjectInputFilter applied when deserializing invocation arguments; may be null
  
  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 of RMISocketFactory is used instead.
  
  Parameters:
  
  obj - the remote object to be exported
  
  port - the port to export the object on
  
  csf - the client-side socket factory for making calls to the remote object
  
  ssf - the server-side socket factory for receiving remote calls
  
  filter - an ObjectInputFilter applied when deserializing invocation arguments; may be null
  
  Returns:
  
  remote object stub
  
  Throws:
  
  RemoteException - if export fails
  
  Since:
  
  9
- unexportObject
  
  public static boolean unexportObject(Remote obj, boolean force) throws NoSuchObjectException
  
  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 unexported
  
  force - 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

Class UnicastRemoteObject

Field Summary

Fields declared in class java.rmi.server.RemoteObject

Constructor Summary

Method Summary

Methods declared in class java.rmi.server.RemoteServer

Methods declared in class java.rmi.server.RemoteObject

Methods declared in class java.lang.Object

Constructor Details

Method Details