home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / DGC.java < prev    next >
Text File  |  1997-05-20  |  5KB  |  100 lines
  1. /*
  2.  * @(#)DGC.java    1.5 96/11/18
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  */
  21. package java.rmi.dgc;
  22.  
  23. import java.rmi.*;
  24. import java.rmi.server.ObjID;
  25.  
  26. /**
  27.  * The DGC abstraction is used for the server side of the distributed
  28.  * garbage collection algorithm. This interface contains the two
  29.  * methods: dirty and clean. A dirty call is made when a remote
  30.  * reference is unmarshaled in a client (the client is indicated by
  31.  * its VMID). A corresponding clean call is made when no more
  32.  * references to the remote reference exist in the client. A failed
  33.  * dirty call must schedule a strong clean call so that the call's
  34.  * sequence number can be retained in order to detect future calls
  35.  * received out of order by the distributed garbage collector.
  36.  *
  37.  * A reference to a remote object is leased for a period of time by
  38.  * the client holding the reference. The lease period starts when the
  39.  * dirty call is received. It is the client's responsibility to renew
  40.  * the leases, by making additional dirty calls, on the remote
  41.  * references it holds before such leases expire. If the client does
  42.  * not renew the lease before it expires, the distributed garbage
  43.  * collector assumes that the remote object is no longer referenced by
  44.  * that client.
  45.  *
  46.  * @author Ann Wollrath
  47.  */
  48. public interface DGC extends Remote {
  49.  
  50.     /**
  51.      * The dirty call requests leases for the remote object references
  52.      * associated with the object identifiers contained in the array
  53.      * 'ids'. The 'lease' contains a client's unique VM identifier (VMID)
  54.      * and a requested lease period. For each remote object exported
  55.      * in the local VM, the garbage collector maintains a reference
  56.      * list-a list of clients that hold references to it. If the lease
  57.      * is granted, the garbage collector adds the client's VMID to the
  58.      * reference list for each remote object indicated in 'ids'. The
  59.      * 'sequenceNum' parameter is a sequence number that is used to
  60.      * detect and discard late calls to the garbage collector. The
  61.      * sequence number should always increase for each subsequent call
  62.      * to the garbage collector.
  63.      *
  64.      * Some clients are unable to generate a VMID, since a VMID is a
  65.      * universally unique identifier that contains a host address
  66.      * which some clients are unable to obtain due to security
  67.      * restrictions. In this case, a client can use a VMID of null,
  68.      * and the distributed garbage collector will assign a VMID for
  69.      * the client.
  70.      *
  71.      * The dirty call returns a Lease object that contains the VMID
  72.      * used and the lease period granted for the remote references (a
  73.      * server may decide to grant a smaller lease period than the
  74.      * client requests). A client must use the VMID the garbage
  75.      * collector uses in order to make corresponding clean calls when
  76.      * the client drops remote object references.
  77.      *
  78.      * A client VM need only make one initial dirty call for each
  79.      * remote reference referenced in the VM (even if it has multiple
  80.      * references to the same remote object). The client must also
  81.      * make a dirty call to renew leases on remote references before
  82.      * such leases expire. When the client no longer has any
  83.      * references to a specific remote object, it must schedule a
  84.      * clean call for the object ID associated with the reference.
  85.      */
  86.     Lease dirty(ObjID[] ids, long sequenceNum, Lease lease)
  87.     throws RemoteException;
  88.  
  89.     /**
  90.      * The clean call removes the 'vmid' from the reference list of
  91.      * each remote object indicated in 'id's.  The sequence number is
  92.      * used to detect late clean calls.  If the argument 'strong' is
  93.      * true, then the clean call is a result of a failed dirty call,
  94.      * thus the sequence number for the client 'vmid' needs to be
  95.      * remembered.
  96.      */
  97.     void clean(ObjID[] ids, long sequenceNum, VMID vmid, boolean strong)
  98.     throws RemoteException;
  99. }
  100.