uka.karmi.rmi
Class ExportPoint

java.lang.Object
  uka.karmi.rmi.ExportPoint

public final class ExportPoint

extends java.lang.Object

An Exportpoint is an abstraction to implement support for port numbers. A remote object is exported on an ExportPoint instead on a TCP/IP port in RMI.

Each ExportPoint has a utid structure that contains its address. Every ExportPoint has its private object table.

Deletion of ExportPoints is not supported, yet.

Author:

Christian Nester, Bernhard Haumacher

Nested Class Summary

private static class	ExportPoint.ObjectQueue
private static class	ExportPoint.WeakObjectRef

Field Summary

static int	EXPORTID_DEFAULT If not specified otherwise, a remote object is exported at the default export point.
private UTID	firstTechnology
int	id Identifier of this export point object.
(package private) IDPool	idPool Manages the object identifiers that are assigned from this export point.
private UTID	lastTechnology
static int	OBJECTID_ANONYMOUS Regular remote objects are exported under the anonymous object ID.
static int	OBJECTID_REGISTRY The well-known object ID, the registry is exported on.
static int	OBJECTID_WELLKNOWN ObjectIds from 1 to OBJECTID_WELLKNOWN are reserved for objects that are exported under a well-known object ID.
(package private) java.util.Random	objectId2Generator
private EnlargingArray	pinTable The array pinTable contains references to pinned objects.
(package private) static ExportPoint.ObjectQueue	queue
(package private) static java.util.WeakHashMap	refHash Remote objects that are not subclasses of RemoteObject use this hashtable to find their server reference
(package private) EnlargingArray	refTable Table of remote server references
(package private) IDPool	slotPool

Constructor Summary

(package private)

ExportPoint(int nr) Creates a new ExportPoint with a specific number.

Method Summary

void	dump()
void	exportObject(RemoteServerRef ref, int objectId) Makes object accessible to remote address spaces.
RemoteServerRef	getRemoteServerRef(int objectId, int objectId2) Returns the server reference for the object that is identified with the object identifiers (objectId, objectId2), if it was exported at this export point.
static RemoteServerRef	getRemoteServerRef(java.lang.Object obj) Returns the server reference to the exported remote object.
UTID	getUTID() Get the UTID structure for this export point.
int	hashCode()
void	pinObject(RemoteServerRef ref)
static void	registerForReplacement(Remote obj, RemoteServerRef ref) Remote objects that do not extend RemoteObject must be registered at the export point to be replaced by their stub during marshaling in a remote method invocation.
(package private) void	registerTechnology(UTID utid)
static java.lang.Object	replaceObject(java.lang.Object obj)
static java.lang.Object	replaceRemote(java.lang.Object obj) Replaces a registered remote server implementation object with it's stub.
java.lang.String	toString()
java.lang.String	toStringMembers()
static Remote	toStub(Remote obj) Convert the passed remote server implementation object to a stub object.
boolean	unexportObject(RemoteServerRef ref, boolean force) Unexporting an exported remote object makes it unaccessible from a remote address space.
static void	unregisterForReplacement(Remote obj)

Methods inherited from class java.lang.Object

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

Field Detail

OBJECTID_REGISTRY

public static final int OBJECTID_REGISTRY

The well-known object ID, the registry is exported on.

See Also:

Constant Field Values

OBJECTID_WELLKNOWN

public static final int OBJECTID_WELLKNOWN

ObjectIds from 1 to OBJECTID_WELLKNOWN are reserved for objects that are exported under a well-known object ID. The registry is such an object. Objects exported under a well-known object ID are necessary to get an initial reference to a remote server machine. A remote reference to an object with a well-known ID can be created without a network connection to the server machine the object is allocated on. In contrast to objects with a well-known object ID, references to regular objects are only passed around in remote method invocations.

See Also:

OBJECTID_REGISTRY, UnicastRemoteObject.buildStub(String, String, int), Constant Field Values

OBJECTID_ANONYMOUS

public static final int OBJECTID_ANONYMOUS

Regular remote objects are exported under the anonymous object ID. They get assigned an arbitrary object ID during export.

See Also:

OBJECTID_WELLKNOWN, Constant Field Values

EXPORTID_DEFAULT

public static final int EXPORTID_DEFAULT

If not specified otherwise, a remote object is exported at the default export point. If an application uses custom export points, they have to be configured in the KaRMI configuration file.

See Also:

Constant Field Values

refHash

static java.util.WeakHashMap refHash

Remote objects that are not subclasses of RemoteObject use this hashtable to find their server reference

refTable

EnlargingArray refTable

Table of remote server references

idPool

IDPool idPool

Manages the object identifiers that are assigned from this export point. On unexport the identifier of the object is recycled for reuse for the next export.

objectId2Generator

java.util.Random objectId2Generator

queue

static ExportPoint.ObjectQueue queue

pinTable

private EnlargingArray pinTable

The array pinTable contains references to pinned objects. A pinned object is not deleted by garbage collector, even if no other reference exists to that object.

Objects are deleted automatically from the pin table on unexport. Normally only the registry is a pinned object.

slotPool

IDPool slotPool

id

public int id

Identifier of this export point object. This ID corresponds to the port number in Sun's RMI.

firstTechnology

private UTID firstTechnology

lastTechnology

private UTID lastTechnology

Constructor Detail

ExportPoint

ExportPoint(int nr)

Creates a new ExportPoint with a specific number.

Method Detail

registerTechnology

void registerTechnology(UTID utid)

exportObject

public void exportObject(RemoteServerRef ref,
                         int objectId)
                  throws RemoteException

Makes object accessible to remote address spaces.

if (objectId == 0) the object is exported anonymously with a free random object identifier. Otherwise objectId is expected to be a reserved well-known object identifier in the range 1..WELLKNOWN.

For well-known objects a stub can be constructed in a remote address space without transmitting a remote reference from where the remote server implementation resides. This mechanism is used to bootstrap the communication between two address spaces with only knowing the IP-address of the remote node. For remote objects exported with well-known object identifiers no further checks are performed on access. For details see server.RemoteServerRef.

Parameters:

ref - server reference of the object to export.

objectId - Valid values are 0 to export the object anonymously and 1..WELLKNOWN to export the object with the specified well-known identifier.

Throws:

RemoteException

pinObject

public void pinObject(RemoteServerRef ref)
               throws RemoteException

Throws:

RemoteException

unexportObject

public boolean unexportObject(RemoteServerRef ref,
                              boolean force)
                       throws NoSuchObjectException

Unexporting an exported remote object makes it unaccessible from a remote address space. The object normally can only be unexported, if there is currently no method executing on that object. With force the object can be forced to be unexported, even if a method is currently executing. The server reference is responsible to delete the exported remote object from the replacemet table.

Parameters:

ref - server side reference object of the remote object which should be unexported.

force - true, is the callCounter check should be skipped.

Throws:

NoSuchObjectException

See Also:

registerForReplacement(Remote, RemoteServerRef)

getUTID

public UTID getUTID()

Get the UTID structure for this export point.

The UTID structure for an export point contains the UTID of each supported technology. Note: The returned value is a direct reference to the internal structure, it should obly be accessed for reading.

Returns:

the UTID structure of this export point

hashCode

public int hashCode()

toStub

public static Remote toStub(Remote obj)
                     throws NoSuchObjectException

Convert the passed remote server implementation object to a stub object.

This method is used in generated KaRMI stub classes for converting parameters and return values of remote type in a local shortcut invocation.

Parameters:

obj - remote object

Returns:

stub for the remote object

Throws:

NoSuchObjectException

getRemoteServerRef

public RemoteServerRef getRemoteServerRef(int objectId,
                                          int objectId2)
                                   throws NoSuchObjectException

Returns the server reference for the object that is identified with the object identifiers (objectId, objectId2), if it was exported at this export point.

Parameters:

objectId - first object identifier

objectId2 - second object identifier

Returns:

server reference to the exported object or null, if the server was not found or the second indentifier did not match.

Throws:

NoSuchObjectException

getRemoteServerRef

public static RemoteServerRef getRemoteServerRef(java.lang.Object obj)
                                          throws NoSuchObjectException

Returns the server reference to the exported remote object.

Parameters:

obj - remote server implementation object

Returns:

the corresponding server reference or null, the object was not exported.

Throws:

NoSuchObjectException

registerForReplacement

public static void registerForReplacement(Remote obj,
                                          RemoteServerRef ref)

Remote objects that do not extend RemoteObject must be registered at the export point to be replaced by their stub during marshaling in a remote method invocation. This method is called by the exporting method of the server reference.

Parameters:

obj - remote server implementation object

ref - server side reference object which belongs to the remote object

unregisterForReplacement

public static void unregisterForReplacement(Remote obj)

Parameters:

obj - remote server implementation object

See Also:

registerForReplacement(Remote obj, RemoteServerRef ref)

replaceRemote

public static java.lang.Object replaceRemote(java.lang.Object obj)
                                      throws RemoteException

Replaces a registered remote server implementation object with it's stub. This replacement policy for remote objects is technology independent and is implemented here for all marshal streams of KaRMI transport technologies.

This method is called from the replaceObject() method of each marshal stream.

Parameters:

obj - the object in question

Returns:

the replacement for the original object or the original object itself.

Throws:

RemoteException

See Also:

MarshalOutputStream.replaceObject(Object)

replaceObject

public static java.lang.Object replaceObject(java.lang.Object obj)
                                      throws RemoteException

Throws:

RemoteException

toStringMembers

public java.lang.String toStringMembers()

toString

public java.lang.String toString()

dump

public void dump()