Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.activation
Class ActivatableInvocationHandler

    java.lang.Object
      net.jini.activation.ActivatableInvocationHandler

All Implemented Interfaces:
  InvocationHandler, Serializable, TrustEquivalence

public final class ActivatableInvocationHandler
extends Object
implements InvocationHandler, TrustEquivalence, Serializable

An invocation handler for activatable remote objects. If the client constraints of this activatable invocation handler are not `null`, then the invocation handler's underlying proxy (if any) must implement `RemoteMethodControl` or a remote invocation will fail with an `UnsupportedConstraintException`.

Since:
  2.0
See Also:
  Serialized Form
Implementation Specifics:

  This implementation uses the `Logger` named `net.jini.activation.ActivatableInvocationHandler` to log information at the following levels:

  Level | Description
  --- | ---
  `FAILED` | exception thrown from final attempt to communicate a remote call
  `FAILED` | exception thrown activating the object
  `HANDLED` | exception caught in attempt to communicate a remote call

Constructor Summary
`ActivatableInvocationHandler(ActivationID id, Remote underlyingProxy)` Creates an instance with the specified activation identifier, a possibly-`null` underlying proxy, and `null` client constraints.

Method Summary
`boolean` | `checkTrustEquivalence(Object obj)` Returns `true` if the specified object (which is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and `false` otherwise.
`boolean` | `equals(Object obj)` Compares the specified object with this `ActivatableInvocationHandler` for equality.
`ActivationID` | `getActivationID()` Returns the activation identifier supplied during construction of this invocation handler.
`Object` | `getCurrentProxy()` Returns the current value for the underlying proxy.
`protected ProxyTrustIterator` | `getProxyTrustIterator()` Returns a proxy trust iterator for an activatable object that is suitable for use by `ProxyTrustVerifier`.
`int` | `hashCode()` Returns a hash code value for this object.
`Object` | `invoke(Object proxy, Method method, Object[] args)` Processes a method invocation made on the encapsulating proxy instance, `proxy`, and returns the result.
`String` | `toString()` Returns a string representation of this object.

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

Constructor Detail

### ActivatableInvocationHandler

    public ActivatableInvocationHandler(ActivationID id,
                                        Remote underlyingProxy)

  Creates an instance with the specified activation identifier, a possibly-`null` underlying proxy, and `null` client constraints.

Parameters:
  `id` - the activation identifier
  `underlyingProxy` - an underlying proxy, or `null`
Throws:
  `NullPointerException` - if `id` is `null`

Method Detail

### getActivationID

    public ActivationID getActivationID()

  Returns the activation identifier supplied during construction of this invocation handler.

  Returns:
    the activation identifier

### getCurrentProxy

    public Object getCurrentProxy()

  Returns the current value for the underlying proxy.

  Returns:
    the underlying proxy

### invoke

    public Object invoke(Object proxy,
                         Method method,
                         Object[] args)
                  throws Throwable

  Processes a method invocation made on the encapsulating proxy instance, `proxy`, and returns the result. This method is invoked when a method is invoked on a proxy instance that this handler is associated with.

  If the specified method is one of the following `java.lang.Object` methods, it will be processed as follows:

  - `equals`: returns `true` if the argument is an instance of a dynamically generated `Proxy` class that implements the same ordered set of interfaces as the specified proxy, and this invocation handler is equal to the invocation handler of that parameter, and returns `false` otherwise.
  - `hashCode`: returns the hash code for the proxy.
  - `toString`: returns a string representation of the specified `proxy` object.

  If the specified method is `RemoteMethodControl.setConstraints`, then if `proxy` is an instance of a dynamic proxy class containing this invocation handler, returns a new proxy containing a copy of this invocation handler with the same activation identifier, the new specified client constraints (`args[0]`), and the current underlying proxy, or if the current underlying proxy implements `RemoteMethodControl`, a copy of that proxy with the new specified client constraints. An exception is thrown if `proxy` is not an instance of a dynamic proxy class containing this invocation handler.

  If the specified method is `RemoteMethodControl.getConstraints`, returns the client constraints.

  If the specified method is `TrustEquivalence.checkTrustEquivalence`, returns `true` if the argument (`args[0]`) is an instance of a dynamic proxy class (that is, a class generated by `Proxy`) that implements the same interfaces as the specified proxy and calling the `checkTrustEquivalence` method of this invocation handler with the invocation handler of that argument returns `true`, and returns `false` otherwise.

  For all other methods:

  A single set of absolute constraints (if any) is used for the duration of the remote invocation, including any activation that may occur.

  - If the underlying proxy is non-`null`, the method is invoked as follows:
    - If the client constraints of this object are not `null` and the underlying proxy does not implement `RemoteMethodControl` then an `UnsupportedConstraintException` is thrown.
    - If `method`'s declaring class is not `public`, the underlying proxy is an instance of the `method`'s declaring class, and the underlying proxy's class is `public`, then a `public` method with the same name and parameter types is obtained from the underlying proxy's class, and if such a method exists, that method is reflectively invoked on the underlying proxy passing it the specified `args` and the result is returned; otherwise if such a method doesn't exist an `ActivateFailedException` is thrown with `NoSuchMethodException` as the cause.
    - Otherwise, the original `method` is reflectively invoked on the underlying proxy passing it the specified `args`.

    If this reflective invocation throws an exception other than `IllegalAccessException`, `IllegalArgumentException`, the `ActivateFailedException` described above, or an `InvocationTargetException` containing `ConnectException`, `ConnectIOException`, `NoSuchObjectException`, or `UnknownHostException`, then if the exception an `InvocationTargetException` the contained exception is thrown to the caller, otherwise the exception is thrown directly.

  - If the underlying proxy is `null` or if the reflective invocation does not throw an exception to the caller as described above:
    - Dynamically grants permissions to the class loader of the activation identifier's class by invoking `Security.grant` passing the class of the proxy and the class of the activation identifier. If this invocation throws an `UnsupportedOperationException`, the exception is ignored.
    - A new proxy is obtained by invoking the `activate` method on the activation identifier, passing `false` as the argument. That method must return an instance of a dynamic `Proxy` class, with an invocation handler that is an instance of this class, containing the same activation identifier. If the returned proxy does not meet this criteria, then an `ActivateFailedException` is thrown. If the `activate` call throws `RemoteException`, then `ConnectIOException` is thrown with the `RemoteException` as the cause. If the `activate` call throws `UnknownObjectException`, then `NoSuchObjectException` is thrown with the `UnknownObjectException` as the cause. Finally, if the `activate` call throws `ActivationException`, then `ActivateFailedException` is thrown with the `ActivationException` as the cause.
    - If a valid, new proxy is returned by the `activate` call, the underlying proxy of the new proxy is obtained from the new proxy's activatable invocation handler. If the obtained underlying proxy implements `RemoteMethodControl`, this invocation handler's underlying proxy is set to a copy of the obtained underlying proxy with the client constraints of this instance. Otherwise, this invocation handler's underlying proxy is set to the obtained underlying proxy.
    - The reflective invocation is then retried (as above) on the new underlying proxy. Activation and retry can occur up to three times. On subsequent attempts, `true` will be passed to the activation identifier's `activate` method, if passing `false` returned the same underlying proxy as before or if `NoSuchObjectException` was thrown by the call to the underlying proxy.
    - If the final attempt at reflective invocation throws `IllegalAccessException` or `IllegalArgumentException` an `ActivateFailedException` is thrown with the original exception as the cause. If this reflective invocation throws `InvocationTargetException`, the contained target exception is thrown.

  The implementation of remote method invocation defined by this class preserves at-most-once call semantics: the remote call either does not execute, partially executes, or executes exactly once at the remote site. Note that for remote calls to activatable objects, arguments may be marshalled more than once.

  The semantics of this method are unspecified if the arguments could not have been produced by an instance of some valid dynamic proxy class containing this invocation handler.

  Specified by:
    `invoke` in interface `InvocationHandler`
  Throws:
    `Throwable`
  See Also:
    `UndeclaredThrowableException`

### getProxyTrustIterator

    protected ProxyTrustIterator getProxyTrustIterator()

  Returns a proxy trust iterator for an activatable object that is suitable for use by `ProxyTrustVerifier`.

  The iterator produces the current underlying proxy on each iteration. The iterator produces up to three elements, but after the first element, iteration terminates unless the exception set by a call to `setException` on the previous iteration is an instance of `ConnectException`, `ConnectIOException`, `NoSuchObjectException`, or `UnknownHostException`.

  On each iteration, if the current underlying proxy is `null` or the same as the underlying proxy produced by the previous iteration:

  A new proxy is obtained by invoking the `activate` method on the activation identifier, passing `false` as the argument. That method must return an instance of a dynamic `Proxy` class, with an invocation handler that is an instance of this class, containing the same activation identifier. If this activation throws one of the following exceptions, the exception is thrown by the `next` method of the iterator and the iteration terminates:

  > If the proxy returned by the `activate` call does not meet the criteria listed above, then an `ActivateFailedException` is thrown. If the `activate` call throws `RemoteException`, then `ConnectIOException` is thrown with the `RemoteException` as the cause. If the `activate` call throws `UnknownHostException`, then `NoSuchObjectException` is thrown with the `UnknownHostException` as the cause. Finally, if the `activate` call throws `ActivationException`, then `ActivateFailedException` is thrown with the `ActivationException` as the cause.

  If a valid, new proxy is returned by the `activate` call, the underlying proxy of the new proxy is obtained from the new proxy's activatable invocation handler. If the obtained underlying proxy implements `RemoteMethodControl`, this invocation handler's underlying proxy is set to a copy of the obtained underlying proxy with the client constraints of this instance. Otherwise, this invocation handler's underlying proxy is set to the obtained underlying proxy.

  On the first call to the activation identifier's `activate` method, `false` is passed as an argument; on subsequent calls `true` will be passed, if passing `false` returned the same underlying proxy as before (when compared using the `equals` method) or if the exception passed to `setException` is an instance of `NoSuchObjectException`. If an activation attempt results in an exception, that exception is thrown by the `next` method of the iterator and iteration terminates.

  Returns:
    a proxy trust iterator suitable for use by `ProxyTrustVerifier`

### checkTrustEquivalence

    public boolean checkTrustEquivalence(Object obj)

  Returns `true` if the specified object (which is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and `false` otherwise.

  `ActivatableInvocationHandler` implements this method as follows:

  This method returns `true` if and only if the following conditions are met:

  - The specified object has the same class as this object.
  - This object's activation identifier implements `TrustEquivalence`.
  - Invoking the `checkTrustEquivalence` method on this object's activation identifier passing the specified object's activation identifier returns `true`.
  - The client constraints in the specified object are equal to the ones in this object.

  The underlying proxy of the specified object is set to `null` if this method returns `true` and any of the following conditions are met:

  - This object's underlying proxy is `null`.
  - This object's underlying proxy is not an instance of `TrustEquivalence`.
  - Invoking the `checkTrustEquivalence` method on this object's underlying proxy, passing the underlying proxy of the specified object, returns `false`.

  Specified by:
    `checkTrustEquivalence` in interface `TrustEquivalence`
  Parameters:
    `obj` - object to check that is not yet known to be trusted
  Returns:
    `true` if the specified object (that is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and returns `false` otherwise

### equals

    public boolean equals(Object obj)

  Compares the specified object with this `ActivatableInvocationHandler` for equality.

  This method returns `true` if and only if the specified object has the same class as this object, and the activation identifier and client constraints in the specified object are equal to the ones in this object.

### hashCode

    public int hashCode()

  Returns a hash code value for this object.

### toString

    public String toString()

  Returns a string representation of this object.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved