[TOC] [Prev] [Next]

# Stub/Skeleton Interfaces

This section contains the interfaces and classes used by the stubs and skeletons generated by the `rmic` stub compiler.

### Topics:

- The RemoteStub Class
- The RemoteCall Interface
- The RemoteRef Interface
- The ServerRef Interface
- The Skeleton Interface
- The Operation Class

# The RemoteStub Class

The `java.rmi.server.RemoteStub` class is the common superclass to all client stubs. Stub objects are surrogates that support exactly the same set of remote interfaces defined by the actual implementation of a remote object.

    package java.rmi.server;

    public abstract class RemoteStub extends java.rmi.RemoteObject {}

# The RemoteCall Interface

The interface `RemoteCall` is an abstraction used by the stubs and skeletons of remote objects to carry out a call to a remote object.

    package java.rmi.server;
    import java.io.*;

    public interface RemoteCall {

    	ObjectOutput getOutputStream() throws IOException;

    	void releaseOutputStream() throws IOException;

    	ObjectInput getInputStream() throws IOException;

    	void releaseInputStream() throws IOException;

    	ObjectOutput getResultStream(boolean success)
    		throws IOException, StreamCorruptedException;

    	void executeCall() throws Exception;

    	void done() throws IOException;
    }

The method `getOutputStream` returns the output stream into which either the stub marshals arguments or the skeleton marshals results.

The method `releaseOutputStream` releases the output stream; in some transports this will release the stream.

The method `getInputStream` returns the InputStream from which the stub unmarshals results or the skeleton unmarshals parameters.

The method `releaseInputStream` releases the input stream. This will allow some transports to release the input side of a connection early.

The method `getResultStream` returns an output stream (after writing out header information relating to the success of the call). Obtaining a result stream should only succeed once per remote call. If success is true, then the result to be marshaled is a normal return; otherwise the result is an exception. `StreamCorruptedException` is thrown if the result stream has already been obtained for this remote call.

The method `executeCall` does whatever it takes to execute the call.

The method `done` allows cleanup after the remote call has completed.

# 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 {

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

# The ServerRef Interface

The interface `ServerRef` represents the server-side handle for a remote object implementation.

    package java.rmi.server;

    public interface ServerRef extends RemoteRef {

    	RemoteStub exportObject(java.rmi.Remote obj, Object data)
    		throws java.rmi.RemoteException;

    	String getClientHost() throws ServerNotActiveException;
    }

The method `exportObject` finds or creates a client stub object for the supplied `Remote` object implementation obj.The parameter data contains information necessary to export the object (such as port number).

The method `getClientHost` returns the host name of the current client. When called from a thread actively handling a remote method invocation, the host name of the client invoking the call is returned. If a remote method call is not currently being service, then `ServerNotActiveException` is called.

# The Skeleton Interface

The interface `Skeleton` is used solely by the implementation of skeletons generated by the `rmic` compiler. A skeleton for a remote object is a server-side entity that dispatches calls to the actual remote object implementation.

    package java.rmi.server;

    public interface Skeleton {

        void dispatch(Remote obj, RemoteCall call, int opnum, long hash)
    		throws Exception;

        Operation[] getOperations();
    }

The `dispatch` method unmarshals any arguments from the input stream obtained from the call object, invokes the method (indicated by the operation number opnum) on the actual remote object implementation obj, and marshals the return value or throws an exception if one occurs during the invocation.

The `getOperations` method returns an array containing the operation descriptors for the remote object's methods.

# The Operation Class

The class `Operation` holds a description of a Java method for a remote object.

    package java.rmi.server;

    public class Operation {

    	public Operation(String op);

    	public String getOperation();

    	public String toString();
    }

An `Operation` object is typically constructed with the method signature.

The method `getOperation` returns the contents of the operation descriptor (the value with which it was initialized).

The method `toString` also returns the string representation of the operation descriptor (typically the method signature).

[TOC] [Prev] [Next]

Copyright © 1996, 1997 Sun Microsystems, Inc. All rights reserved.