uka.karmi.rmi.server
Class RemoteServerRef

java.lang.Object
  uka.karmi.rmi.server.RemoteServerRef

Direct Known Subclasses:

ProxyServerRef, ReplicatedServerRef, UnicastRemoteServerRef

public abstract class RemoteServerRef

extends java.lang.Object

RemoteServerRef is the base class for all remote server references in KaRMI. A server reference is the transport representation for an exported server implementation object. The transport layer of KaRMI uses remote server references to address exported remote objects.

Addressing:

A remote server is addressed by two integer identifiers in the transport layer. The first identifier objectId is unique within the address space the server implementation resides.

The first identifier is therefore sufficient to address a remote server in an address space. The second identifier is only used for safety reasons:

If the server implementation is deleted while there are remote references out there and a new server is exported reusing the object identifier this new server can be accessed with the old out of date reference. This leads to unpredictable behavior, because other methods than the expected are called. This situation only occurs, if the old server is forced to be unexported while there are remote references out, or the Java virtual machine that exports the server terminates and a new one is started exporting a new server with the same object identifier.

The second identifier helps to detect a situation like the one described above. In the original implementation the second identifier was a sequence number for objects in the same transport with the same objectId. But the effort of keeping track of the sequence number of all old objects can be avoided by assigning a random number as second object identifier on export. With a good random number generator it is as probable to have the situation of a new object being accessed with an old stub as with sequence numbers. The random numbers are even better than the sequence numbers if someone wants to deny access to a remote object with a faced remote reference. In this situation there are stronger requirements on the random number generation that are not fulfilled in this implementation.

There is a call counter to implement a correct unexport method. As synchronized methods are expensive it is left to the actual reference object if the call counter is used at all.

The abstract methods are normally "up calls" from the transport layer which executes the remote method invocation.

remoteEquals() must be implemented to check equality between a RemoteServerRef and a RemoteClientRef.

Author:

Christian Nester, Bernhard Haumacher

Field Summary

int	callCounter if (callCounter == -1) then the RemoteServerRef is not exported.
ExportPoint	ep the export point this object is exported on
int	objectId The export point's internal ids of this reference.
int	objectId2

Constructor Summary

protected

RemoteServerRef()

Method Summary

static RemoteSkeleton	createSkeletonFor(Remote object)
static RemoteStub	createStubFor(Remote object)
void	decCallCounter()
abstract void	doApplicationCall(ServerConnection c) The entry-point into the method dispatch process.
static java.lang.String	getClientHost() Returns the name of the host that initiated the remote call or throws an exception if not in a remote call.
abstract RemoteStub	getStub() Returns a corresponding stub object.
void	incCallCounter()
static java.lang.Object	newInstanceRelative(java.lang.Object object, java.lang.String className)
abstract boolean	remoteEquals(RemoteStub obj) Determines if a stub object references this server object.
abstract void	synchronize(RMACallback cb)
java.lang.String	toString()
java.lang.String	toStringMembers()
abstract void	unreferenced() Called whenever the last remote reference to this server implementation is garbage collected.

Methods inherited from class java.lang.Object

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

Field Detail

objectId

public int objectId

The export point's internal ids of this reference.

The first Id is the main Id to identify the object. Now consider a DGC that deletes the server side of a remote object. Later on a new remote object is build and gets the same (now free) object id. Depending on the implementation of the DGC it is more or less easy to cheat (or unexport an object with force). This results in the situation that there are invalid references that now point to a newly allocated remote object with the same identifier. If this old reference is used, a method on the wrong object is invoked. The second identifier is a sequence number for objects in the same transport with the same objectId. This second id allows the transport to detect that an out of date reference was used.

It depends on the implementation of the technology if and how this check is performed.

There is a call counter to implement a correct unexport method. As synchronized methods are expensive it is left to the actual reference object if the call counter is used at all.

objectId2

public int objectId2

ep

public ExportPoint ep

the export point this object is exported on

callCounter

public int callCounter

if (callCounter == -1) then the RemoteServerRef is not exported.

Constructor Detail

RemoteServerRef

protected RemoteServerRef()

Method Detail

getClientHost

public static java.lang.String getClientHost()
                                      throws ServerNotActiveException

Returns the name of the host that initiated the remote call or throws an exception if not in a remote call.

Returns:

host name of the caller

Throws:

ServerNotActiveException - no remote call is executed

incCallCounter

public void incCallCounter()
                    throws RemoteException

Throws:

RemoteException

decCallCounter

public void decCallCounter()

doApplicationCall

public abstract void doApplicationCall(ServerConnection c)
                                throws java.io.IOException,
                                       java.lang.ClassNotFoundException

The entry-point into the method dispatch process. This method is called from the dispatch() method of the server connection. The actual dispatch is done in a sub-class of RemoteServerRef. This abstract method is implemented for unicast servers in the UnicastRemoteServerRef class.

Parameters:

c - the connection, the call came in

Throws:

java.io.IOException

java.lang.ClassNotFoundException

See Also:

ServerConnection.dispatch(boolean), UnicastRemoteServerRef.doApplicationCall(ServerConnection)

unreferenced

public abstract void unreferenced()

Called whenever the last remote reference to this server implementation is garbage collected.

See Also:

Unreferenced

getStub

public abstract RemoteStub getStub()

Returns a corresponding stub object. This method is called from the transport, when a stub object is needed. The returned stub doesn't need to be a newly created stub object. The implementation can also create a stub object on export and always return the same.

This stub is used during passing a remote server as argument or result in a remote method invocation.

synchronize

public abstract void synchronize(RMACallback cb)
                          throws java.lang.Throwable

Throws:

java.lang.Throwable

remoteEquals

public abstract boolean remoteEquals(RemoteStub obj)

Determines if a stub object references this server object.

newInstanceRelative

public static java.lang.Object newInstanceRelative(java.lang.Object object,
                                                   java.lang.String className)
                                            throws java.lang.InstantiationException,
                                                   java.lang.IllegalAccessException,
                                                   java.lang.ClassNotFoundException

Throws:

java.lang.InstantiationException

java.lang.IllegalAccessException

java.lang.ClassNotFoundException

createStubFor

public static RemoteStub createStubFor(Remote object)
                                throws RemoteException

Throws:

RemoteException

createSkeletonFor

public static RemoteSkeleton createSkeletonFor(Remote object)
                                        throws RemoteException

Throws:

RemoteException

toStringMembers

public java.lang.String toStringMembers()

toString

public java.lang.String toString()