rmi

Class Stub

java.lang.Object

rmi.Stub

public abstract class Stub
extends java.lang.Object

RMI stub factory.

RMI stubs hide network communication with the remote server and provide a simple object-like interface to their users. This class provides methods for creating stub objects dynamically, when given pre-defined interfaces.

The network address of the remote server is set when a stub is created, and may not be modified afterwards. Two stubs are equal if they implement the same interface and carry the same remote server address - and would therefore connect to the same skeleton. Stubs are serializable.

Field Summary

Fields

Modifier and Type	Field and Description
private static java.net.InetSocketAddress	add

Constructor Summary

Constructors

Constructor and Description
Stub()

Method Summary

Modifier and Type	Method and Description
(package private) static void	checkInterface(java.lang.Class<?> c) This function checks whether the passed interface is adheres to the specification.
static <T> T	create(java.lang.Class<T> c, java.net.InetSocketAddress address) Creates a stub, given the address of a remote server.
static <T> T	create(java.lang.Class<T> c, Skeleton<T> skeleton) Creates a stub, given a skeleton with an assigned address.
static <T> T	create(java.lang.Class<T> c, Skeleton<T> skeleton, java.lang.String hostname) Creates a stub, given a skeleton with an assigned address and a hostname which overrides the skeleton's hostname.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

add

private static java.net.InetSocketAddress add

Constructor Detail

Stub

public Stub()

Method Detail

create

public static <T> T create(java.lang.Class<T> c,
                           Skeleton<T> skeleton)
                    throws java.net.UnknownHostException

Creates a stub, given a skeleton with an assigned address.

The stub is assigned the address of the skeleton. The skeleton must either have been created with a fixed address, or else it must have already been started.

This method should be used when the stub is created together with the skeleton. The stub may then be transmitted over the network to enable communication with the skeleton.

Parameters:

c - A Class object representing the interface implemented by the remote object.

skeleton - The skeleton whose network address is to be used.

Returns:

The stub created.

Throws:

java.lang.IllegalStateException - If the skeleton has not been assigned an address by the user and has not yet been started.

java.net.UnknownHostException - When the skeleton address is a wildcard and a port is assigned, but no address can be found for the local host.

java.lang.NullPointerException - If any argument is null.

java.lang.Error - If c does not represent a remote interface - an interface in which each method is marked as throwing RMIException, or if an object implementing this interface cannot be dynamically created.

create

public static <T> T create(java.lang.Class<T> c,
                           Skeleton<T> skeleton,
                           java.lang.String hostname)

Creates a stub, given a skeleton with an assigned address and a hostname which overrides the skeleton's hostname.

The stub is assigned the port of the skeleton and the given hostname. The skeleton must either have been started with a fixed port, or else it must have been started to receive a system-assigned port, for this method to succeed.

This method should be used when the stub is created together with the skeleton, but firewalls or private networks prevent the system from automatically assigning a valid externally-routable address to the skeleton. In this case, the creator of the stub has the option of obtaining an externally-routable address by other means, and specifying this hostname to this method.

Parameters:

c - A Class object representing the interface implemented by the remote object.

skeleton - The skeleton whose port is to be used.

hostname - The hostname with which the stub will be created.

Returns:

The stub created.

Throws:

java.lang.IllegalStateException - If the skeleton has not been assigned a port.

java.lang.NullPointerException - If any argument is null.

java.lang.Error - If c does not represent a remote interface - an interface in which each method is marked as throwing RMIException, or if an object implementing this interface cannot be dynamically created.

create

public static <T> T create(java.lang.Class<T> c,
                           java.net.InetSocketAddress address)

Creates a stub, given the address of a remote server.

This method should be used primarily when bootstrapping RMI. In this case, the server is already running on a remote host but there is not necessarily a direct way to obtain an associated stub.

Parameters:

c - A Class object representing the interface implemented by the remote object.

address - The network address of the remote skeleton.

Returns:

The stub created.

Throws:

java.lang.NullPointerException - If any argument is null.

java.lang.Error - If c does not represent a remote interface - an interface in which each method is marked as throwing RMIException, or if an object implementing this interface cannot be dynamically created.

checkInterface

static void checkInterface(java.lang.Class<?> c)
                    throws java.lang.Error

This function checks whether the passed interface is adheres to the specification. In short, it extracts all methods and checks if it throws RMIException.

Parameters:

c - An object representing the class of the interface for which the skeleton server is to handle method call requests.

Throws:

java.lang.Error - If c does not represent a remote interface - an interface whose methods are all marked as throwing RMIException.