KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > rmi > dgc > DGC


1 /*
2  * @(#)DGC.java 1.15 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7 package java.rmi.dgc;
8
9 import java.rmi.*;
10 import java.rmi.server.ObjID JavaDoc;
11
12 /**
13  * The DGC abstraction is used for the server side of the distributed
14  * garbage collection algorithm. This interface contains the two
15  * methods: dirty and clean. A dirty call is made when a remote
16  * reference is unmarshaled in a client (the client is indicated by
17  * its VMID). A corresponding clean call is made when no more
18  * references to the remote reference exist in the client. A failed
19  * dirty call must schedule a strong clean call so that the call's
20  * sequence number can be retained in order to detect future calls
21  * received out of order by the distributed garbage collector.
22  *
23  * A reference to a remote object is leased for a period of time by
24  * the client holding the reference. The lease period starts when the
25  * dirty call is received. It is the client's responsibility to renew
26  * the leases, by making additional dirty calls, on the remote
27  * references it holds before such leases expire. If the client does
28  * not renew the lease before it expires, the distributed garbage
29  * collector assumes that the remote object is no longer referenced by
30  * that client.
31  *
32  * @author Ann Wollrath
33  */
34 public interface DGC extends Remote {
35
36     /**
37      * The dirty call requests leases for the remote object references
38      * associated with the object identifiers contained in the array
39      * 'ids'. The 'lease' contains a client's unique VM identifier (VMID)
40      * and a requested lease period. For each remote object exported
41      * in the local VM, the garbage collector maintains a reference
42      * list-a list of clients that hold references to it. If the lease
43      * is granted, the garbage collector adds the client's VMID to the
44      * reference list for each remote object indicated in 'ids'. The
45      * 'sequenceNum' parameter is a sequence number that is used to
46      * detect and discard late calls to the garbage collector. The
47      * sequence number should always increase for each subsequent call
48      * to the garbage collector.
49      *
50      * Some clients are unable to generate a VMID, since a VMID is a
51      * universally unique identifier that contains a host address
52      * which some clients are unable to obtain due to security
53      * restrictions. In this case, a client can use a VMID of null,
54      * and the distributed garbage collector will assign a VMID for
55      * the client.
56      *
57      * The dirty call returns a Lease object that contains the VMID
58      * used and the lease period granted for the remote references (a
59      * server may decide to grant a smaller lease period than the
60      * client requests). A client must use the VMID the garbage
61      * collector uses in order to make corresponding clean calls when
62      * the client drops remote object references.
63      *
64      * A client VM need only make one initial dirty call for each
65      * remote reference referenced in the VM (even if it has multiple
66      * references to the same remote object). The client must also
67      * make a dirty call to renew leases on remote references before
68      * such leases expire. When the client no longer has any
69      * references to a specific remote object, it must schedule a
70      * clean call for the object ID associated with the reference.
71      *
72      * @param ids IDs of objects to mark as referenced by calling client
73      * @param sequenceNum sequence number
74      * @param lease requested lease
75      * @return granted lease
76      * @throws RemoteException if dirty call fails
77      */
78     Lease JavaDoc dirty(ObjID JavaDoc[] ids, long sequenceNum, Lease JavaDoc lease)
79     throws RemoteException;
80
81     /**
82      * The clean call removes the 'vmid' from the reference list of
83      * each remote object indicated in 'id's. The sequence number is
84      * used to detect late clean calls. If the argument 'strong' is
85      * true, then the clean call is a result of a failed dirty call,
86      * thus the sequence number for the client 'vmid' needs to be
87      * remembered.
88      *
89      * @param ids IDs of objects to mark as unreferenced by calling client
90      * @param sequenceNum sequence number
91      * @param vmid client VMID
92      * @param strong make 'strong' clean call
93      * @throws RemoteException if clean call fails
94      */
95     void clean(ObjID JavaDoc[] ids, long sequenceNum, VMID JavaDoc vmid, boolean strong)
96     throws RemoteException;
97 }
98
Popular Tags