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 argument ids. The lease
contains a client's unique virtual machine identifier (VMID) and a requested
lease period. For each remote object exported in the local virtual machine, 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 unique VMID. This is because a VMID is
a universally unique identifier only if it contains a true host address, an
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 can 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 virtual machine need only make one initial dirty call for each remote
reference referenced in the virtual machine (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, and
the sequence number for the client vmid therefore 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.
ObjID is used to identify remote objects uniquely in a virtual
machine 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.
An ObjID consists of an object number (a long) and a unique identifier for the
address space (a UID).
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 (such as those
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; to enforce this, the object number of the ObjID is set to the
"well-known" number supplied in the constructor and all UID fields are set to
zero.
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 hashcode
The 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. A UID consists of a number that is unique on the
host (an int), a time (a long), and a count (a short).
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 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 the output stream.
The method read constructs a UID whose contents is read from the specified
input stream.
VMID provides a universally unique identifier among all Java virtual
machines. A VMID contains a UID and a host address. A VMID can be used to
identify client virtual machines.
package java.rmi.dgc;
public final class VMID implements java.io.Serializable {
public VMID();
public static boolean isUnique();
public int hashCode();
public boolean equals(Object obj);
public String toString();
}
VMID default constructor creates a globally unique identifier among all
Java virtual machines under the following conditions:
java.rmi.server.UID are satisfied, and
UID object.
VMID contains the host address of the machine on which it was created. Due
to security restrictions, obtaining the true host address is not always possible
(for example, the loopback host may be used under security-restricted
conditions). The method isUnique can be called to determine if VMIDs
generated in this virtual machine are, in fact, unique among all virtual
machines. The method isUnique returns true if a valid host name can be
determined (other than loopback host); otherwise it returns false.
The hashCode, equals and toString methods are defined for VMIDs. Two
VMIDs are considered equal if they have the same contents.