Topics:
dirty
and clean
. A dirty
call is made when a remote reference is unmarshaled in a client (the client is indicated by its VMID
). A corresponding clean call is made when no more references to the remote reference exist in the client. A failed dirty call must schedule a strong clean call so that the call's sequence number can be retained in order to detect future calls received out of order by the distributed garbage collector.A reference to a remote object is leased for a period of time by the client holding the reference. The lease period starts when the dirty call is received. It is the client's responsibility to renew the leases, by making additional
dirty
calls, on the remote references it holds before such leases expire. If the client does not renew the lease before it expires, the distributed garbage collector assumes that the remote object is no longer referenced by that client.
package java.rmi.dgc; import java.rmi.server.ObjID; public interface DGC extends java.rmi.Remote { Lease dirty(ObjID[] ids, long sequenceNum, Lease lease) throws java.rmi.RemoteException; void clean(ObjID[] ids, long seqNum, VMID vmid, boolean strong) throws java.rmi.RemoteException; }
dirty
requests leases for the remote object references associated with the object identifiers contained in the array ids. The lease contains a client's unique VM identifier (VMID) and a requested lease period. For each remote object exported in the local VM, the garbage collector maintains a reference list-a list of clients that hold references to it. If the lease is granted, the garbage collector adds the client's VMID to the reference list for each remote object indicated in ids. The sequenceNum parameter is a sequence number that is used to detect and discard late calls to the garbage collector. The sequence number should always increase for each subsequent call to the garbage collector.Some clients are unable to generate a VMID, since a VMID is a universally unique identifier that contains a host address which some clients are unable to obtain due to security restrictions. In this case, a client can use a VMID of
null
, and the distributed garbage collector will assign a VMID for the client.The
dirty
call returns a Lease
object that contains the VMID used and the lease period granted for the remote references (a server may decide to grant a smaller lease period than the client requests). A client must use the VMID the garbage collector uses in order to make corresponding clean
calls when the client drops remote object references.A client VM need only make one initial
dirty
call for each remote reference referenced in the VM (even if it has multiple references to the same remote object). The client must also make a dirty
call to renew leases on remote references before such leases expire. When the client no longer has any references to a specific remote object, it must schedule a clean
call for the object ID associated with the reference.The
clean
call removes the vmid from the reference list of each remote object indicated in ids. The sequence number is used to detect late clean calls. If the argument strong is true, then the clean call is a result of a failed dirty
call, thus the sequence number for the client vmid needs to be remembered.
Lease
object is used to request and grant leases to remote object references.
package java.rmi.dgc; public final class Lease implements java.io.Serializable { public Lease(VMID id, long duration); public VMID getVMID(); public long getValue(); }
Lease
constructor creates a lease with a specific VMID and lease duration. The VMID may be null
.The
getVMID
method returns the client VMID associated with the lease.The
getValue
method returns the lease duration (either requested or granted).
ObjID
is used to identify remote objects uniquely in a VM over time. Each identifier contains an object number and an address space identifier that is unique with respect to a specific host. An object identifier is assigned to a remote object when it is exported.
package java.rmi.server; public final class ObjID implements java.io.Serializable { public ObjID (); public ObjID (int num); public void write(ObjectOutput out) throws java.io.IOException; public static ObjID read(ObjectInput in) throws java.io.IOException; public int hashCode() public boolean equals(Object obj) public String toString() }
ObjID
constructor generates a unique object identifier. The second constructor generates well-known object identifiers (e.g. used by the registry and the distributed garbage collector) and takes as an argument a well-known object number. A well-known object ID generated via this second constructor will not clash with any object IDs generated via the default constructor.The method
write
marshals the object id's representation to an output stream. The method
read
constructs an object id whose contents is read from the specified input stream.The method
hashCode
returns the object number as the hashcodeThe
equals
method returns true if obj is an ObjID
with the same contents.The
toString
method returns a string containing the object id representation. The address space identifier is included in the string representation only if the object id is from a non-local address space.
UID
is an abstraction for creating identifiers that are unique with respect to the host on which it is generated. A UID
is contained in an ObjID
as an address space identifier.
package java.rmi.server; public final class UID implements java.io.Serializable { public UID(); public UID(short num); public int hashCode(); public boolean equals(Object obj); public String toString(); public void write(DataOutput out) throws java.io.IOException; public static UID read(DataInput in) throws java.io.IOException; }
UID
is unique under the following conditions: a) the machine takes more than one second to reboot, and b) the machine's clock is never set backward. In order to construct a UID
that is globally unique, simply pair a UID
with an InetAddress
.The second form of the constructor creates a well-known
UID
. There are 216 -1 such possible well-known ids. An id generated via this constructor will not clash with any id generated via the default UID
constructor which will generates a genuinely unique identifier with respect to this host.The methods
hashCode
, equals
, and toString
are defined for UIDs. Two UIDs are considered equal if they have the same contents.The method
write
writes the uid to output stream.The method
read
constructs a UID whose contents is read from the specified input stream.
VMID
provides a universally unique identifier for a client VM. A VMID
contains a UID
and a host address.
package java.rmi.dgc; public final class VMID implements java.io.Serializable { public VMID() throws VMIDNotSupportedException; public boolean equals(Object obj); public String toString(); }
VMIDNotSupportedException
.The
hashCode
, equals
and toString
methods are defined for VMID
s. Two VMIDs are considered equal if they have the same contents.