uka.karmi.rmi
Class SingleRemoteClientRef

java.lang.Object
  uka.karmi.rmi.RemoteClientRef
      uka.karmi.rmi.SingleRemoteClientRef

All Implemented Interfaces:

Anonymous, java.io.Externalizable, Immutable, java.io.Serializable

Direct Known Subclasses:

UnicastRemoteClientRef

public class SingleRemoteClientRef

extends RemoteClientRef

implements Immutable, java.io.Externalizable

Base class for remote client references that only reference a single object on the server side. This is the base class for the DGC. Objects of SingleRemoteClientRef encapsulate the address of one remote object.

The main part of the whole garbage collection process is implemented inside the readExternal and writeExternal methods.

If a stub and its SingleRemoteClientRef is local to the server implementation object, then the local garbage collector is responsible for the local reference from the SingleRemoteClientRef to the server implementation object. Therefore it is important that a SingleRemoteClientRef has a standard Java reference to the controlled server implementation object. This reference is transient. If the SingleRemoteClientRef object is transported in a remote method invocation to a remote address space then the distributed garbage collector becomes responsible for the now remote reference.

Objects of this class are sent over the network by KaRMI.

Author:

Christian Nester, Bernhard Haumacher

See Also:

Serialized Form

Field Summary

java.lang.Object	dgcInfo Information for the DGC.
private ObjectId	dgcObjectId An identifier of the DGC object this remote reference belongs to.
private RemoteServerRef	dgcRef References a local DGC object.
(package private) ObjectId	objectId Address of the server implementation.
private RemoteServerRef	proxyRef References a local proxy for the remote server.
RemoteServerRef	serverRef Points to the corresponding server reference object of the server implementation, if this reference is local to the server implementation.
UTID	useUtid References the technology that is used to access the remote object.

Constructor Summary

SingleRemoteClientRef()
Constructor required for implementing the Externalizable interface in subclasses.

SingleRemoteClientRef(ObjectId objectId, UTID useUtid)
Create a new artificial client reference to a remote server object.

SingleRemoteClientRef(RemoteServerRef serverRef)
Create a new client reference for an exported local server object.

Method Summary

private ObjectId	createProxy(Technology technology) Make sure that there is a local proxy for the referenced object.
boolean	equals(java.lang.Object obj)
void	finalize() Finalizes a remote reference object.
ClientConnection	getContext(int methodId) Get the context for a method invocation on the server addressed by this remote reference object.
int	hashCode()
boolean	isLocal() Decides whether this SingleRemoteClientRef points to a local server implementation.
void	readExternal(java.io.ObjectInput objectInput)
java.lang.String	toString()
java.lang.String	toStringMembers()
void	writeExternal(java.io.ObjectOutput objectOutput) Write this client reference to a marshal stream.

Methods inherited from class uka.karmi.rmi.RemoteClientRef

getMarshalInput, getMarshalOutput

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serverRef

public transient RemoteServerRef serverRef

Points to the corresponding server reference object of the server implementation, if this reference is local to the server implementation. This direct reference is used for optimized access and prevents the server implementation from being garbage collected. If the reference is not local, objectId is used for access.

objectId

ObjectId objectId

Address of the server implementation. This structure is used for access, if the server implementation is located on a remote VM.

useUtid

public transient UTID useUtid

References the technology that is used to access the remote object. A null value indicates that the remote object is local.

proxyRef

private transient RemoteServerRef proxyRef

References a local proxy for the remote server. A proxy is created on demand, if this reference is passed to a remote VM that can not directly access the referenced object.

dgcRef

private transient RemoteServerRef dgcRef

References a local DGC object.

dgcObjectId

private ObjectId dgcObjectId

An identifier of the DGC object this remote reference belongs to. Each remote reference belongs to exactly one DGC. A null value indicates that this is reference is artificial or the referenced object is local. An artificial referenced is created via UnicastRemoteObject.buildStub(String, String, int) and is not part of a DGC. A local server implementation has alway a local DGC reference.

dgcInfo

public transient java.lang.Object dgcInfo

Information for the DGC. This information is created by the garbage collector during the marshaling of this reference to another VM and stored to dgcInfo during unmarshaling on the other side.

Constructor Detail

SingleRemoteClientRef

public SingleRemoteClientRef(RemoteServerRef serverRef)

Create a new client reference for an exported local server object.

SingleRemoteClientRef

public SingleRemoteClientRef(ObjectId objectId,
                             UTID useUtid)

Create a new artificial client reference to a remote server object. This reference is not part of the DGC.

SingleRemoteClientRef

public SingleRemoteClientRef()

Constructor required for implementing the Externalizable interface in subclasses.

See Also:

UnicastRemoteClientRef

Method Detail

isLocal

public boolean isLocal()

Decides whether this SingleRemoteClientRef points to a local server implementation.

hashCode

public int hashCode()

equals

public boolean equals(java.lang.Object obj)

getContext

public ClientConnection getContext(int methodId)
                            throws RemoteException

Get the context for a method invocation on the server addressed by this remote reference object. This method is called by a stub object to initiate a remote method invocation. The context returned by this method is used to control the remote method call. It is used to marshal the method parameters and unmarshal the method result value.

Specified by:

getContext in class RemoteClientRef

Throws:

RemoteException

writeExternal

public void writeExternal(java.io.ObjectOutput objectOutput)
                   throws java.io.IOException

Write this client reference to a marshal stream. A client reference is marshaled as a tuple (object identifier, DGC object identifier) with optionally additional DGC information.

When marshaling a client reference, the following cases have to be distinguished.

The DCG object is remote

Communication proxy required

DGC proxy required

No proxy required

The DCG object is local

There is no DCG object

Communication proxy required

No proxy required

Specified by:

writeExternal in interface java.io.Externalizable

Throws:

java.io.IOException

readExternal

public void readExternal(java.io.ObjectInput objectInput)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

Specified by:

readExternal in interface java.io.Externalizable

Throws:

java.io.IOException

java.lang.ClassNotFoundException

createProxy

private final ObjectId createProxy(Technology technology)
                            throws RemoteException

Make sure that there is a local proxy for the referenced object. Return a new object identifier for the proxy.

Throws:

RemoteException

finalize

public void finalize()
              throws java.lang.Throwable

Finalizes a remote reference object. If this reference points to a server in another virtual machine, the responsible DGC object that is identified by dgcObjectId is informed via the DGC.remoteFinalize(ObjectId, Object) method.

Throws:

java.lang.Throwable

toStringMembers

public java.lang.String toStringMembers()

toString

public java.lang.String toString()