Activatable (Java 2 Platform SE v1.4.1_"07")

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.rmi.activation
Class Activatable

    java.lang.Object
      |
      +--java.rmi.server.RemoteObject
            |
            +--java.rmi.server.RemoteServer
                  |
                  +--java.rmi.activation.Activatable

All Implemented Interfaces:
  Remote, Serializable

public abstract class Activatable
extends RemoteServer

The `Activatable` class provides support for remote objects that require persistent access over time and that can be activated by the system.

Since:
  1.2
See Also:
  Serialized Form

Field Summary

Fields inherited from class java.rmi.server.RemoteObject
`ref`

Constructor Summary
`protected` | `Activatable(ActivationID id, int port)` Constructor used to activate/export the object on a specified port.
`protected` | `Activatable(ActivationID id, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf)` Constructor used to activate/export the object on a specified port.
`protected` | `Activatable(String location, MarshalledObject data, boolean restart, int port)` Constructor used to register and export the object on a specified port (an anonymous port is chosen if port=0) .
`protected` | `Activatable(String location, MarshalledObject data, boolean restart, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf)` Constructor used to register and export the object on a specified port (an anonymous port is chosen if port=0) .

Method Summary
`static Remote` | `exportObject(Remote obj, ActivationID id, int port)` Export the activatable remote object to the RMI runtime to make the object available to receive incoming calls.
`static Remote` | `exportObject(Remote obj, ActivationID id, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf)` Export the activatable remote object to the RMI runtime to make the object available to receive incoming calls.
`static ActivationID` | `exportObject(Remote obj, String location, MarshalledObject data, boolean restart, int port)` This `exportObject` method may be invoked explicitly by an "activatable" object, that does not extend the `Activatable` class, in order to both a) register the object's activation descriptor, constructed from the supplied `location`, and `data`, with the activation system (so the object can be activated), and b) export the remote object, `obj`, on a specific port (if port=0, then an anonymous port is chosen).
`static ActivationID` | `exportObject(Remote obj, String location, MarshalledObject data, boolean restart, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf)` This `exportObject` method may be invoked explicitly by an "activatable" object, that does not extend the `Activatable` class, in order to both a) register the object's activation descriptor, constructed from the supplied `location`, and `data`, with the activation system (so the object can be activated), and b) export the remote object, `obj`, on a specific port (if port=0, then an anonymous port is chosen).
`protected ActivationID` | `getID()` Returns the object's activation identifier.
`static boolean` | `inactive(ActivationID id)` Informs the system that the object with the corresponding activation `id` is currently inactive.
`static Remote` | `register(ActivationDesc desc)` Register an object descriptor for an activatable remote object so that is can be activated on demand.
`static boolean` | `unexportObject(Remote obj, boolean force)` Remove the remote object, obj, from the RMI runtime.
`static void` | `unregister(ActivationID id)` Revokes previous registration for the activation descriptor associated with `id`.

Methods inherited from class java.rmi.server.RemoteServer
`getClientHost, getLog, setLog`

Methods inherited from class java.rmi.server.RemoteObject
`equals, getRef, hashCode, toString, toStub`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

### Activatable

    protected Activatable(String location,
                          MarshalledObject data,
                          boolean restart,
                          int port)
                   throws ActivationException,
                          RemoteException

  Constructor used to register and export the object on a specified port (an anonymous port is chosen if port=0) . A concrete subclass of this class must call this constructor to register and export the object during initial construction. As a side-effect of activatable object construction, the remote object is both "registered" with the activation system and "exported" (on an anonymous port if port=0) to the RMI runtime so that it is available to accept incoming calls from clients.

Parameters:
  `location` - the location for classes for this object
  `data` - the object's initialization data
  `port` - the port on which the object is exported (an anonymous port is used if port=0)
  `restart` - if true, the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false, the object is only activated on demand. Specifying `restart` to be `true` does not force an initial immediate activation of a newly registered object; initial activation is lazy.
Throws:
  `ActivationException` - if object registration fails.
  `RemoteException` - if either of the following fails: a) registering the object with the activation system or b) exporting the object to the RMI runtime.
Since:
  1.2

### Activatable

    protected Activatable(String location,
                          MarshalledObject data,
                          boolean restart,
                          int port,
                          RMIClientSocketFactory csf,
                          RMIServerSocketFactory ssf)
                   throws ActivationException,
                          RemoteException

  Constructor used to register and export the object on a specified port (an anonymous port is chosen if port=0) .

  A concrete subclass of this class must call this constructor to register and export the object during initial construction. As a side-effect of activatable object construction, the remote object is both "registered" with the activation system and "exported" (on an anonymous port if port=0) to the RMI runtime so that it is available to accept incoming calls from clients.

Parameters:
  `location` - the location for classes for this object
  `data` - the object's initialization data
  `restart` - if true, the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false, the object is only activated on demand. Specifying `restart` to be `true` does not force an initial immediate activation of a newly registered object; initial activation is lazy.
  `port` - the port on which the object is exported (an anonymous port is used if port=0)
  `csf` - the client-side socket factory for making calls to the remote object
  `ssf` - the server-side socket factory for receiving remote calls
Throws:
  `ActivationException` - if object registration fails.
  `RemoteException` - if either of the following fails: a) registering the object with the activation system or b) exporting the object to the RMI runtime.
Since:
  1.2

### Activatable

    protected Activatable(ActivationID id,
                          int port)
                   throws RemoteException

  Constructor used to activate/export the object on a specified port. An "activatable" remote object must have a constructor that takes two arguments:
  - the object's activation identifier (`ActivationID`), and
  - the object's initialization data (a `MarshalledObject`).

  A concrete subclass of this class must call this constructor when it is activated via the two parameter constructor described above. As a side-effect of construction, the remote object is "exported" to the RMI runtime (on the specified `port`) and is available to accept incoming calls from clients.

Parameters:
  `id` - activation identifier for the object
  `port` - the port number on which the object is exported
Throws:
  `RemoteException` - if exporting the object to the RMI runtime fails
Since:
  1.2

### Activatable

    protected Activatable(ActivationID id,
                          int port,
                          RMIClientSocketFactory csf,
                          RMIServerSocketFactory ssf)
                   throws RemoteException

  Constructor used to activate/export the object on a specified port. An "activatable" remote object must have a constructor that takes two arguments:
  - the object's activation identifier (`ActivationID`), and
  - the object's initialization data (a `MarshalledObject`).

  A concrete subclass of this class must call this constructor when it is activated via the two parameter constructor described above. As a side-effect of construction, the remote object is "exported" to the RMI runtime (on the specified `port`) and is available to accept incoming calls from clients.

Parameters:
  `id` - activation identifier for the object
  `port` - the port number on which the object is exported
  `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 exporting the object to the RMI runtime fails
Since:
  1.2

Method Detail

### getID

    protected ActivationID getID()

  Returns the object's activation identifier. The method is protected so that only subclasses can obtain an object's identifier.

  Returns:
    the object's activation identifier
  Since:
    1.2

### register

    public static Remote register(ActivationDesc desc)
                           throws UnknownGroupException,
                                  ActivationException,
                                  RemoteException

  Register an object descriptor for an activatable remote object so that is can be activated on demand.

  Parameters:
    `desc` - the object's descriptor
  Returns:
    the stub for the activatable remote object
  Throws:
    `UnknownGroupException` - if group id in `desc` is not registered with the activation system
    `ActivationException` - if activation system is not running
    `RemoteException` - if remote call fails
  Since:
    1.2

### inactive

    public static boolean inactive(ActivationID id)
                            throws UnknownObjectException,
                                   ActivationException,
                                   RemoteException

  Informs the system that the object with the corresponding activation `id` is currently inactive. If the object is currently active, the object is "unexported" from the RMI runtime (only if there are no pending or in-progress calls) so the that it can no longer receive incoming calls. This call informs this VM's ActivationGroup that the object is inactive, that, in turn, informs its ActivationMonitor. If this call completes successfully, a subsequent activate request to the activator will cause the object to reactivate. The operation may still succeed if the object is considered active but has already unexported itself.

  Parameters:
    `id` - the object's activation identifier
  Returns:
    true if the operation succeeds (the operation will succeed if the object in currently known to be active and is either already unexported or is currently exported and has no pending/executing calls); false is returned if the object has pending/executing calls in which case it cannot be deactivated
  Throws:
    `UnknownObjectException` - if object is not known (it may already be inactive)
    `ActivationException` - if group is not active
    `RemoteException` - if call informing monitor fails
  Since:
    1.2

### unregister

    public static void unregister(ActivationID id)
                           throws UnknownObjectException,
                                  ActivationException,
                                  RemoteException

  Revokes previous registration for the activation descriptor associated with `id`. An object can no longer be activated via that `id`.

  Parameters:
    `id` - the object's activation identifier
  Throws:
    `UnknownObjectException` - if object (`id`) is unknown
    `ActivationException` - if activation system is not running
    `RemoteException` - if remote call to activation system fails
  Since:
    1.2

### exportObject

    public static ActivationID exportObject(Remote obj,
                                            String location,
                                            MarshalledObject data,
                                            boolean restart,
                                            int port)
                                     throws ActivationException,
                                            RemoteException

  This `exportObject` method may be invoked explicitly by an "activatable" object, that does not extend the `Activatable` class, in order to both a) register the object's activation descriptor, constructed from the supplied `location`, and `data`, with the activation system (so the object can be activated), and b) export the remote object, `obj`, on a specific port (if port=0, then an anonymous port is chosen). Once the object is exported, it can receive incoming RMI calls.

  This method does not need to be called if `obj` extends `Activatable`, since the first constructor calls this method.

  Parameters:
    `obj` - the object being exported
    `location` - the object's code location
    `data` - the object's bootstrapping data
    `restart` - if true, the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false, the object is only activated on demand. Specifying `restart` to be `true` does not force an initial immediate activation of a newly registered object; initial activation is lazy.
    `port` - the port on which the object is exported (an anonymous port is used if port=0)
  Returns:
    the activation identifier obtained from registering the descriptor, `desc`, with the activation system the wrong group
  Throws:
    `ActivationException` - if activation group is not active
    `RemoteException` - if object registration or export fails
  Since:
    1.2

### exportObject

    public static ActivationID exportObject(Remote obj,
                                            String location,
                                            MarshalledObject data,
                                            boolean restart,
                                            int port,
                                            RMIClientSocketFactory csf,
                                            RMIServerSocketFactory ssf)
                                     throws ActivationException,
                                            RemoteException

  This `exportObject` method may be invoked explicitly by an "activatable" object, that does not extend the `Activatable` class, in order to both a) register the object's activation descriptor, constructed from the supplied `location`, and `data`, with the activation system (so the object can be activated), and b) export the remote object, `obj`, on a specific port (if port=0, then an anonymous port is chosen). Once the object is exported, it can receive incoming RMI calls.

  This method does not need to be called if `obj` extends `Activatable`, since the first constructor calls this method.

  Parameters:
    `obj` - the object being exported
    `location` - the object's code location
    `data` - the object's bootstrapping data
    `restart` - if true, the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false, the object is only activated on demand. Specifying `restart` to be `true` does not force an initial immediate activation of a newly registered object; initial activation is lazy.
    `port` - the port on which the object is exported (an anonymous port is used if port=0)
    `csf` - the client-side socket factory for making calls to the remote object
    `ssf` - the server-side socket factory for receiving remote calls
  Returns:
    the activation identifier obtained from registering the descriptor, `desc`, with the activation system the wrong group
  Throws:
    `ActivationException` - if activation group is not active
    `RemoteException` - if object registration or export fails
  Since:
    1.2

### exportObject

    public static Remote exportObject(Remote obj,
                                      ActivationID id,
                                      int port)
                               throws RemoteException

  Export the activatable remote object to the RMI runtime to make the object available to receive incoming calls. The object is exported on an anonymous port, if `port` is zero.

  During activation, this `exportObject` method should be invoked explicitly by an "activatable" object, that does not extend the `Activatable` class. There is no need for objects that do extend the `Activatable` class to invoke this method directly; this method is called by the second constructor above (which a subclass should invoke from its special activation constructor).

  Parameters:
    `obj` - the remote object implementation
    `id` - the object's activation identifier
    `port` - the port on which the object is exported (an anonymous port is used if port=0)
  Returns:
    the stub for the activatable remote object
  Throws:
    `RemoteException` - if object export fails
  Since:
    1.2

### exportObject

    public static Remote exportObject(Remote obj,
                                      ActivationID id,
                                      int port,
                                      RMIClientSocketFactory csf,
                                      RMIServerSocketFactory ssf)
                               throws RemoteException

  Export the activatable remote object to the RMI runtime to make the object available to receive incoming calls. The object is exported on an anonymous port, if `port` is zero.

  During activation, this `exportObject` method should be invoked explicitly by an "activatable" object, that does not extend the `Activatable` class. There is no need for objects that do extend the `Activatable` class to invoke this method directly; this method is called by the second constructor above (which a subclass should invoke from its special activation constructor).

  Parameters:
    `obj` - the remote object implementation
    `id` - the object's activation identifier
    `port` - the port on which the object is exported (an anonymous port is used if port=0)
    `csf` - the client-side socket factory for making calls to the remote object
    `ssf` - the server-side socket factory for receiving remote calls
  Returns:
    the stub for the activatable remote object
  Throws:
    `RemoteException` - if object export fails
  Since:
    1.2

### unexportObject

    public static boolean unexportObject(Remote obj,
                                         boolean force)
                                  throws NoSuchObjectException

  Remove 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

JavaTM 2 Platform
Std. Ed. v1.4.1_"07"

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.