rmic
stub compiler.
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 {}
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;
}
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.
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();
}
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.
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;
}
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.
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();
}
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.
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();
}
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).