8.3 The RemoteRef Interface

The interface RemoteRef represents the handle for a remote object. Each stub contains an instance of RemoteRef that contains the concrete representation of a reference. This remote reference is used to carry out remote calls on the remote object for which it is a reference.

package java.rmi.server;

public interface RemoteRef extends java.io.Externalizable {
	Object invoke(Remote obj, 
				   java.lang.reflect.Method method,
				   Object[] params,
				   long opnum)
		throws Exception;

	RemoteCall newCall(RemoteObject obj, Operation[] op, int opnum,
		           long hash) throws RemoteException;
	void invoke(RemoteCall call) throws Exception;
	void done(RemoteCall call) throws RemoteException;
	String getRefClass(java.io.ObjectOutput out);
	int remoteHashCode();
	boolean remoteEquals(RemoteRef obj);
	String remoteToString();
}

The first invoke method delegates method invocation to the stub's (obj) remote reference and allows the reference to take care of setting up the connection to the remote host, marshaling some representation for the method and parameters, params, then communicating the method invocation to the remote host. This method either returns the result of the method invocation on the remote object which resides on the remote host or throws a RemoteException if the call failed or an application-level exception if the remote invocation throws an exception. Note that the operation number, opnum, represents a hash of the method signature and may be used to encode the method for transmission.

The method hash to be used for the opnum parameter is a 64-bit (long) integer computed from the first two 32-bit values of the message digest of a particular byte stream using the National Institute of Standards and Technology (NIST) Secure Hash Algorithm (SHA-1). This byte stream contains a string as if it was written using the java.io.DataOutput.writeUTF method, consisting of the remote method's name followed by its method descriptor (see section 4.3.3 of The Java Virtual Machine Specification for a description of method descriptors).

For example, if a method of a remote interface has the following name and signature:

	void myRemoteMethod(int count, Object obj, boolean flag)

the string containing the remote method's name and descriptor would be the following:

	myRemoteMethod(ILjava.lang.Object;Z)V

The hash value is assembled from the first two 32-bit values of the SHA-1 message digest. If the result of the message digest, the five 32-bit words H₀ H₁ H₂ H₃ H₄, is in an array of five int values named sha, the hash value would be computed as follows:

long hash = ((sha[0] >>> 24) & 0xFF) |
            ((sha[0] >>> 16) & 0xFF) << 8 |
            ((sha[0] >>>  8) & 0xFF) << 16 |
            ((sha[0] >>>  0) & 0xFF) << 24 |
            ((sha[1] >>> 24) & 0xFF) << 32 |
            ((sha[1] >>> 16) & 0xFF) << 40 |
            ((sha[1] >>>  8) & 0xFF) << 48 |
            ((sha[1] >>>  0) & 0xFF) << 56;

---

Note - The newCall, invoke, and done methods are deprecated as of the Java 2 SDK, Standard Edition, v1.2. The stubs generated by rmic using the 1.2 stub protocol version do not use these methods any longer. The sequence of calls consisting of newCall, invoke, and done have been replaced by a new invoke method that takes a Method object as one of its parameters.

---

The method newCall creates an appropriate call object for a new remote method invocation on the remote object obj. The operation array, op, contains the available operations on the remote object. The operation number, opnum, is an index into the operation array which specifies the particular operation for this remote call. Passing the operation array and index allows the stubs generator to assign the operation indexes and interpret them. The remote reference may need the operation description to encode in the call.

The method invoke executes the remote call. invoke will raise any "user" exceptions which should pass through and not be caught by the stub. If any exception is raised during the remote invocation, invoke should take care of cleaning up the connection before raising the "user exception" or RemoteException.

The method done allows the remote reference to clean up (or reuse) the connection. done should only be called if the invoke call returns successfully (non-exceptionally) to the stub.

The method getRefClass returns the nonpackage-qualified class name of the reference type to be serialized onto the stream out.

The method remoteHashCode returns a hashcode for a remote object. Two remote object stubs that refer to the same remote object will have the same hash code (in order to support remote objects as keys in hashtables). A RemoteObject forwards a call to its hashCode method to the remoteHashCode method of the remote reference.

The method remoteEquals compares two remote objects for equality. Two remote objects are equal if they refer to the same remote object. For example, two stubs are equal if they refer to the same remote object. A RemoteObject forwards a call to its equals method to the remoteEquals method of the remote reference.

The method remoteToString returns a String that represents the reference of this remote object.