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 invoke(Remote,Method,Object[],long) 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 (JVMS) 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 64-bit hash value is the little-endian composition of an eight byte sequence where the first four bytes are the first 32-bit value of the message digest in big-endian byte order and the last four bytes are the second 32-bit value of the message digest in big-endian byte order. For example, if the first two 32-bit values of the message digest are 0xB0B1B2B3 and 0xB4B5B6B7, then the hash value would be 0xB7B6B5B4B3B2B1B0.

---

Note - The methods newCall(RemoteObject,Operation[],int,long), invoke(RemoteCall), and done(RemoteCall) 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. The interface hash is a 64-bit value used to enforce compatibility between a stub and skeleton using the v1.1 stub protocol. The interface hash is computed from the first two 32-bit values of the message digest of a particular byte stream using SHA-1. This byte stream contains data as if it was written using the writeInt and writeUTF methods of the interface java.io.DataOutput, consisting of the following items:

(int) stub version number, always 1

for each remote method, in order of operation number:

• (UTF-8) remote method name
• (UTF-8) remote method descriptor (see section 4.3.3 of JVMS)
• for each declared exception, in lexicographic order of binary name:
  • (UTF-8) the name of the exception class

The interface hash value is composed from the message digest in the same manner as described above for the method hash used in the invoke method.

The method invoke(RemoteCall) 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.