net.jini.activation

Class ActivatableInvocationHandler

java.lang.Object

net.jini.activation.ActivatableInvocationHandler

All Implemented Interfaces:

Serializable, InvocationHandler, 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

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Implementation Specifics:

This implementation recognizes the following system property:

• org.apache.river.activation.enableActivateGrant - This property is interpreted as a boolean value (see Boolean.getBoolean). If true, this implementation invokes Security.grant as defined in the specification.

This implementation's invoke method throws IllegalArgumentException if a remote invocation is to be made and the proxy argument is an instance of an interface whose binary name is javax.management.MBeanServerConnection or any of the names produced by the following procedure:

For each resource named org/apache/river/proxy/resources/InvocationHandler.moreProhibitedProxyInterfaces that is visible to the system class loader, the contents of the resource are parsed as UTF-8 text to produce a list of interface names. The resource must contain a list of binary names of interfaces, one per line. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#'; on each line, all characters starting with the first comment character are ignored.

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

Constructors

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

Method Summary

Modifier and Type	Method and Description
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. If the underlying proxy implements RemoteMethodControl and its constraints are not null, the underlying proxy of this instance is a copy of that proxy with null 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 remote invocation is made as follows:

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:
  • If permitted by some implementation-specific mechanism, 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 ConnectException, then a new ConnectException is thrown with the original ConnectException as the cause. 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. This method throws IllegalArgumentException if proxy is an instance of InvocationHandler or, if a remote invocation is to be made, any of the superinterfaces of proxy's class have a method with the same name and parameter types as method but that does not declare RemoteException or a superclass of RemoteException in its throws clause (even if such a method is not a member of any of the direct superinterfaces of proxy's class because of overriding).

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.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class Object

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object