net.jini.jeri

Class BasicInvocationHandler

java.lang.Object

net.jini.jeri.BasicInvocationHandler

All Implemented Interfaces:

Serializable, InvocationHandler, TrustEquivalence

public class BasicInvocationHandler
extends Object
implements InvocationHandler, TrustEquivalence, Serializable

A basic implementation of the InvocationHandler interface. This invocation handler implements Java(TM) Remote Method Invocation (Java RMI) call semantics when handling a remote invocation to a remote object.

BasicInvocationHandler instances contain an ObjectEndpoint, optional client constraints, and optional server constraints. The client and server constraints control the handling of remote methods, and they are represented as MethodConstraints objects that map remote methods to corresponding per-method constraints.

Invocation requests sent via the invoke method use the protocol defined in that method. This invocation handler also assumes that the return value conforms to the protocol outlined in the BasicInvocationDispatcher.dispatch method.

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

BasicInvocationDispatcher, Serialized Form

Constructor Summary

Constructors

Constructor and Description
BasicInvocationHandler(BasicInvocationHandler other, MethodConstraints clientConstraints) Creates a new BasicInvocationHandler with the specified client constraints and with the same ObjectEndpoint and server constraints as the given other BasicInvocationHandler.
BasicInvocationHandler(ObjectEndpoint oe, MethodConstraints serverConstraints) Creates a new BasicInvocationHandler with the specified ObjectEndpoint and server 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.
protected ObjectInputStream	createMarshalInputStream(Object proxy, Method method, OutboundRequest request, boolean integrity, Collection context) Returns a new ObjectInputStream instance to use to read objects from the response input stream obtained by invoking the getResponseInputStream method on the given request.
protected ObjectOutputStream	createMarshalOutputStream(Object proxy, Method method, OutboundRequest request, Collection context) Returns a new ObjectOutputStream instance to use to write objects to the request output stream obtained by invoking the getRequestOutputStream method on the given request.
boolean	equals(Object obj) Compares the specified object with this BasicInvocationHandler for equality.
MethodConstraints	getClientConstraints() Returns this BasicInvocationHandler's client constraints.
ObjectEndpoint	getObjectEndpoint() Returns this BasicInvocationHandler's ObjectEndpoint.
MethodConstraints	getServerConstraints() Returns this BasicInvocationHandler's server constraints.
int	hashCode() Returns the hash code value for this invocation handler.
Object	invoke(Object proxy, Method method, Object[] args) Processes a method invocation made on the encapsulating proxy instance, proxy, and returns the result.
protected void	marshalArguments(Object proxy, Method method, Object[] args, ObjectOutputStream out, Collection context) Marshals the arguments for the specified remote method to the outgoing request stream, out.
protected void	marshalMethod(Object proxy, Method method, ObjectOutputStream out, Collection context) Marshals a representation of the given method to the outgoing request stream, out.
protected InvocationHandler	setClientConstraints(MethodConstraints constraints) Returns a copy of this invocation handler with the specified constraints as its new client constraints.
String	toString() Returns a string representation of this BasicInvocationHandler.
protected Object	unmarshalReturn(Object proxy, Method method, ObjectInputStream in, Collection context) Unmarshals the return value for the specified remote method from the incoming response stream, in.
protected Throwable	unmarshalThrow(Object proxy, Method method, ObjectInputStream in, Collection context) Unmarshals the throwable for the specified remote method from the incoming response stream, in, and returns the result.

Methods inherited from class java.lang.Object

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

Constructor Detail

BasicInvocationHandler

public BasicInvocationHandler(ObjectEndpoint oe,
                              MethodConstraints serverConstraints)

Creates a new BasicInvocationHandler with the specified ObjectEndpoint and server constraints.

The client constraints of the created BasicInvocationHandler will be null.

Parameters:

oe - the ObjectEndpoint for this invocation handler

serverConstraints - the server constraints, or null

Throws:

NullPointerException - if oe is null

BasicInvocationHandler

public BasicInvocationHandler(BasicInvocationHandler other,
                              MethodConstraints clientConstraints)

Creates a new BasicInvocationHandler with the specified client constraints and with the same ObjectEndpoint and server constraints as the given other BasicInvocationHandler.

This constructor is intended for use by the BasicInvocationHandler implementation of the setClientConstraints(net.jini.core.constraint.MethodConstraints) method. To create a copy of a given BasicInvocationHandler with new client constraints, use the RemoteMethodControl.setConstraints method on the containing proxy.

Parameters:

other - the BasicInvocationHandler to obtain the ObjectEndpoint and server constraints from

clientConstraints - the client constraints, or null

Throws:

NullPointerException - if other is null

Method Detail

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.

BasicInvocationHandler implements this method as follows:

If method is one of the following methods, it is processed as described below:

• Object.hashCode: Returns the hash code value for the proxy.
• Object.equals: Returns true if the argument (args[0]) is an instance of a dynamic proxy class that implements the same ordered set of interfaces as proxy and this invocation handler is equal to the invocation handler of that argument, and returns false otherwise.
• Object.toString: Returns a string representation of the proxy.
• RemoteMethodControl.setConstraints: Returns a new proxy instance of the same class as proxy containing a new invocation handler with the specified new client constraints. The new invocation handler is created by invoking the setClientConstraints method of this object with the specified client constraints (args[0]). An exception is thrown if proxy is not an instance of a dynamic proxy class containing this invocation handler.
• RemoteMethodControl.getConstraints: Returns this BasicInvocationHandler's client constraints.
• TrustEquivalence.checkTrustEquivalence: Returns true if the argument (args[0]) is an instance of a dynamic proxy class that implements the same ordered set of interfaces as proxy and invoking the checkTrustEquivalence method of this object with the invocation handler of that argument returns true, and returns false otherwise.

Otherwise, a remote call is made as follows:

The object endpoint's newCall method is invoked to obtain an OutboundRequestIterator, passing constraints obtained by combining the client and server constraints for the specified remote method and making them absolute. If the returned iterator's hasNext method returns false, then this method throws a ConnectIOException. Otherwise, the iterator is used to make one or more attempts to communicate the remote call. Each attempt proceeds as follows:

The iterator's next method is invoked to obtain an OutboundRequest for the current attempt. If next returns normally, the request's getUnfulfilledConstraints method is invoked, and if the returned requirements or preferences include Integrity.YES, object integrity is enforced for the current remote call attempt. If the returned requirements include any constraint other than an Integrity constraint, an UnsupportedConstraintException is generated and, as described below, wrapped and handled like any other Exception thrown from a remote call attempt. Otherwise, the marshalling of the remote call proceeds with the following steps in order:

• A byte of value 0x00 is written to the request output stream of the OutboundRequest to indicate the version of the marshalling protocol being used.
• A byte is written to specify object integrity enforcement: 0x01 if object integrity is being enforced for this remote call attempt, and 0x00 otherwise.
• A client context collection is created containing an IntegrityEnforcement element that reflects whether or not object integrity is being enforced for this remote call attempt.
• The createMarshalOutputStream method is invoked, passing proxy, method, the OutboundRequest, and the client context, to create the marshal output stream for marshalling the remote call.
• The marshalMethod method of this invocation handler is invoked with proxy, method, the marshal output stream, and the client context.
• The marshalArguments method of this invocation handler is invoked with proxy, method, args, the marshal output stream, and the client context.
• The marshal output stream is closed.

Then the object endpoint's executeCall method is invoked with the OutboundRequest. If executeCall returns a RemoteException, then this method throws that exception (and thus the remote call attempt iteration terminates). If executeCall returns null, then the unmarshalling of the call response proceeds as follows:

A byte is read from the response input stream of the OutboundRequest:

• If the byte is 0x00, indicating a marshalling protocol version mismatch, a ProtocolException is generated and, as described below, wrapped and handled like any other Exception thrown from a remote call attempt.
• If the byte is 0x01, indicating a normal return, the createMarshalInputStream method is invoked, passing proxy, method, the OutboundRequest, a boolean indicating whether or not object integrity is being enforced, and the client context, to create the marshal input stream for unmarshalling the response, and the unmarshalReturn method of this invocation handler is invoked with proxy, method, the marshal input stream, and the client context. This method returns the value returned by unmarshalReturn (and thus the remote call attempt iteration terminates).
• If the byte is 0x02, indicating an exceptional return, a marshal input stream is created by calling the createMarshalInputStream method as described for the previous case, and the unmarshalThrow method of this invocation handler is invoked with proxy, method, the marshal input stream, and the client context. This method throws the exception returned by unmarshalThrow (and thus the remote call attempt iteration terminates).
• If the byte is any other value, a ProtocolException is generated and, as described below, wrapped and handled like any other Exception thrown from a remote call attempt.

If an IOException is thrown during the attempt to communicate the remote call, then it is wrapped in a RemoteException as follows:

• If marshalMethod was not invoked for this attempt, or if an invocation of getDeliveryStatus on the OutboundRequest returns false, or if a marshalling protocol version mismatch was detected, then
  • if the IOException is a java.net.UnknownHostException, it is wrapped in a java.rmi.UnknownHostException;
  • if it is a java.net.ConnectException, it is wrapped in a java.rmi.ConnectException;
  • if it is any other IOException, it is wrapped in a ConnectIOException.
• Otherwise, if executeCall was not invoked for this attempt, the IOException is wrapped in a MarshalException, and if executeCall was invoked, it is wrapped in an UnmarshalException.

If a ClassNotFoundException is thrown during the unmarshalling, then it is wrapped in an UnmarshalException.

In all cases, either the request output stream and the response input stream will be closed or the OutboundRequest will be aborted before this attempt completes.

If an attempt to communicate the remote call throws an Exception (other than an exception returned by executeCall or unmarshalThrow, which terminates the remote call attempt iteration), then if marshalMethod was not invoked for the attempt or if an invocation of getDeliveryStatus on the OutboundRequest returns false, then if the iterator's hasNext method returns true, then another attempt is made. Otherwise, this method throws the Exception thrown by the last attempt (possibly wrapped as described above).

Note that invoking a remote method on a remote object via this invoke method preserves "at-most-once" call semantics. At-most-once call semantics guarantees that the remote call will either a) not execute, b) partially execute, or c) execute exactly once at the remote site. With Java RMI's at-most-once call semantics, arguments may be marshalled more than once for a given remote call.

A subclass can override this method to handle the methods of any additional non-remote interfaces implemented by the proxy or to otherwise control invocation handling behavior.

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 call 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

setClientConstraints

protected InvocationHandler setClientConstraints(MethodConstraints constraints)

Returns a copy of this invocation handler with the specified constraints as its new client constraints.

BasicInvocationHandler implements this method as follows:

This method looks for a public constructor declared by the class of this object with two parameters, the first parameter type being the class of this object and the second parameter type being MethodConstraints. If found, the constructor is invoked with this instance and the specified constraints, and the resulting object is returned. If the constructor could not be found or was not accessible, or if the constructor invocation throws an exception, an UndeclaredThrowableException is thrown.

A subclass can override this method to control how the invocation handler is copied.

Parameters:

constraints - the new client constraints, or null

Returns:

a copy of this invocation handler with the specified constraints as its client constraints

createMarshalOutputStream

protected ObjectOutputStream createMarshalOutputStream(Object proxy,
                                                       Method method,
                                                       OutboundRequest request,
                                                       Collection context)
                                                throws IOException

Returns a new ObjectOutputStream instance to use to write objects to the request output stream obtained by invoking the getRequestOutputStream method on the given request.

BasicInvocationHandler implements this method to return a new MarshalOutputStream instance constructed with the output stream obtained from request as specified above and an unmodifiable view of the supplied context collection.

A subclass can override this method to control how the marshal input stream is created or implemented.

Parameters:

proxy - the proxy instance

method - the remote method invoked

request - the outbound request

context - the client context

Returns:

a new ObjectOutputStream instance for marshalling a call request

Throws:

IOException - if an I/O exception occurs

NullPointerException - if any argument is null

createMarshalInputStream

protected ObjectInputStream createMarshalInputStream(Object proxy,
                                                     Method method,
                                                     OutboundRequest request,
                                                     boolean integrity,
                                                     Collection context)
                                              throws IOException

Returns a new ObjectInputStream instance to use to read objects from the response input stream obtained by invoking the getResponseInputStream method on the given request.

BasicInvocationHandler implements this method to return a new MarshalInputStream instance constructed with the input stream obtained from request as specified above for the input stream in, the class loader of proxy's class for defaultLoader and verifierLoader, this method's integrity argument for verifyCodebaseIntegrity, and an unmodifiable view of context for the context collection. The useCodebaseAnnotations method is invoked on the created stream before it is returned.

An exception is thrown if proxy is not an instance of a dynamic proxy class containing this invocation handler.

A subclass can override this method to control how the marshal input stream is created or implemented.

Parameters:

proxy - the proxy instance

method - the remote method invoked

request - the outbound request

integrity - whether or not to verify codebase integrity

context - the client context

Returns:

a new ObjectInputStream instance for unmarshalling a call response

Throws:

IOException - if an I/O exception occurs

NullPointerException - if any argument is null

marshalMethod

protected void marshalMethod(Object proxy,
                             Method method,
                             ObjectOutputStream out,
                             Collection context)
                      throws IOException

Marshals a representation of the given method to the outgoing request stream, out. For each remote call, the invoke method calls this method to marshal a representation of the method.

BasicInvocationHandler implements this method to write the JRMP method hash (defined in section 8.3 of the Java RMI specification) for the given method to the output stream using the writeLong method.

A subclass can override this method to control how the remote method is marshalled.

Parameters:

proxy - the proxy instance that the method was invoked on

method - the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

out - outgoing request stream for the remote call

context - the client context

Throws:

IOException - if an I/O exception occurs

NullPointerException - if any argument is null

marshalArguments

protected void marshalArguments(Object proxy,
                                Method method,
                                Object[] args,
                                ObjectOutputStream out,
                                Collection context)
                         throws IOException

Marshals the arguments for the specified remote method to the outgoing request stream, out. For each remote call, the invoke method calls this method to marshal arguments.

BasicInvocationHandler implements this method marshal each argument as follows:

If the corresponding declared parameter type is primitive, then the the primitive value is written to the stream (for example, if the type is int.class, then the primitive int value is written to the stream using the writeInt method). Otherwise, the argument is written to the stream using the writeObject method.

A subclass can override this method to marshal the arguments in an alternative context, perform pre- or post-processing on the arguments, marshal additional implicit data, or otherwise control how the arguments are marshalled.

Parameters:

proxy - the proxy instance that the method was invoked on

method - the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

args - an array of objects containing the values of the arguments passed in the method invocation on the proxy instance. If an argument's corresponding declared parameter type is primitive, then its value is represented with an instance of the corresponding primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.

out - outgoing request stream for the remote call

context - the client context

Throws:

IOException - if an I/O exception occurs

NullPointerException - if any argument is null

unmarshalReturn

protected Object unmarshalReturn(Object proxy,
                                 Method method,
                                 ObjectInputStream in,
                                 Collection context)
                          throws IOException,
                                 ClassNotFoundException

Unmarshals the return value for the specified remote method from the incoming response stream, in. In the case that a value is returned from the invocation on the remote object, this method is called to unmarshal that return value.

BasicInvocationHandler implements this method as follows:

If the return type of the method is void, then no return value is read from the stream and null is returned. If the return type is a primitive type, then the primitive value is read from the stream (for example, if the type is int.class, then the primitive int value is read from the stream using the readInt method). Otherwise, the return value is read from the stream using the readObject method.

A subclass can override this method to unmarshal the return value in an alternative context, perform post-processing on the return value, unmarshal additional implicit data, or otherwise control how the return value is unmarshalled.

Parameters:

proxy - the proxy instance that the method was invoked on

method - the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

in - the incoming result stream for the remote call

context - the client context

Returns:

the unmarshalled return value of the method invocation on the proxy instance. If the declared return value of the interface method is a primitive type, then the value returned by invoke will be an instance of the corresponding primitive wrapper class; otherwise, it will be a type assignable to the declared return type.

Throws:

IOException - if an I/O exception occurs

ClassNotFoundException - if a class could not be found during unmarshalling

NullPointerException - if any argument is null

unmarshalThrow

protected Throwable unmarshalThrow(Object proxy,
                                   Method method,
                                   ObjectInputStream in,
                                   Collection context)
                            throws IOException,
                                   ClassNotFoundException

Unmarshals the throwable for the specified remote method from the incoming response stream, in, and returns the result. In the case that an exception was thrown as a result of the invocation on the remote object, this method is called to unmarshal that throwable.

BasicInvocationHandler implements this method to return the throwable unmarshalled from the stream using the readObject method. If the unmarshalled throwable is a checked exception that is not assignable to any exception in the throws clause of the method implemented by the proxy's class, then: if there is no public member method of proxy's class with the same name and parameter types as method an IllegalArgumentException is thrown, otherwise that exception is wrapped in an UnexpectedException and the wrapped exception is returned.

A subclass can override this method to unmarshal the return value in an alternative context, perform post-processing on the return value, unmarshal additional implicit data, or otherwise control how the return value is unmarshalled.

Parameters:

proxy - the proxy instance that the method was invoked on

method - the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

context - the client context

in - the incoming result stream for the remote call

Returns:

the unmarshalled exception to throw from the method invocation on the proxy instance. The exception's type must be assignable either to any of the exception types declared in the throws clause of the interface method or to the unchecked exception types java.lang.RuntimeException or java.lang.Error.

Throws:

IOException - if an I/O exception occurs

ClassNotFoundException - if a class could not be found during unmarshalling

NullPointerException - if any argument is null

getObjectEndpoint

public final ObjectEndpoint getObjectEndpoint()

Returns this BasicInvocationHandler's ObjectEndpoint.

Returns:

the ObjectEndpoint

getClientConstraints

public final MethodConstraints getClientConstraints()

Returns this BasicInvocationHandler's client constraints.

Returns:

the client constraints

getServerConstraints

public final MethodConstraints getServerConstraints()

Returns this BasicInvocationHandler's server constraints.

Returns:

the server constraints

hashCode

public int hashCode()

Returns the hash code value for this invocation handler.

Overrides:

hashCode in class Object

Returns:

the hash code value for this invocation handler

equals

public boolean equals(Object obj)

Compares the specified object with this BasicInvocationHandler for equality.

BasicInvocationHandler implements this method to return true if and only if

• the specified object has the same class as this object,
• the ObjectEndpoint in the specified object has the same class and is equal to the object endpoint in this object, and
• the client constraints and server constraints in the specified object are equal to the ones in this object.

A subclass should override this method if adds instance state that affects equality.

Overrides:

equals in class Object

Parameters:

obj - the object to compare with

Returns:

true if obj is equivalent to this object; false otherwise

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.

BasicInvocationHandler implements this method to return true if and only if

• the specified object has the same class as this object,
• this object's ObjectEndpoint is an instance of TrustEquivalence and invoking its checkTrustEquivalence method with the specified object's ObjectEndpoint returns true, and
• the client constraints and server constraints in the specified object are equal to the ones in this object.

A subclass should override this method to perform any additional checks that are necessary.

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

toString

public String toString()

Returns a string representation of this BasicInvocationHandler.

Overrides:

toString in class Object

Returns:

a string representation of this BasicInvocationHandler