1/* 2 * Copyright (c) 1996, 1999, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25package java.rmi.dgc; 26 27import java.rmi.*; 28import java.rmi.server.ObjID; 29 30/** 31 * The DGC abstraction is used for the server side of the distributed 32 * garbage collection algorithm. This interface contains the two 33 * methods: dirty and clean. A dirty call is made when a remote 34 * reference is unmarshaled in a client (the client is indicated by 35 * its VMID). A corresponding clean call is made when no more 36 * references to the remote reference exist in the client. A failed 37 * dirty call must schedule a strong clean call so that the call's 38 * sequence number can be retained in order to detect future calls 39 * received out of order by the distributed garbage collector. 40 * 41 * A reference to a remote object is leased for a period of time by 42 * the client holding the reference. The lease period starts when the 43 * dirty call is received. It is the client's responsibility to renew 44 * the leases, by making additional dirty calls, on the remote 45 * references it holds before such leases expire. If the client does 46 * not renew the lease before it expires, the distributed garbage 47 * collector assumes that the remote object is no longer referenced by 48 * that client. 49 * 50 * @author Ann Wollrath 51 */ 52public interface DGC extends Remote { 53 54 /** 55 * The dirty call requests leases for the remote object references 56 * associated with the object identifiers contained in the array 57 * 'ids'. The 'lease' contains a client's unique VM identifier (VMID) 58 * and a requested lease period. For each remote object exported 59 * in the local VM, the garbage collector maintains a reference 60 * list-a list of clients that hold references to it. If the lease 61 * is granted, the garbage collector adds the client's VMID to the 62 * reference list for each remote object indicated in 'ids'. The 63 * 'sequenceNum' parameter is a sequence number that is used to 64 * detect and discard late calls to the garbage collector. The 65 * sequence number should always increase for each subsequent call 66 * to the garbage collector. 67 * 68 * Some clients are unable to generate a VMID, since a VMID is a 69 * universally unique identifier that contains a host address 70 * which some clients are unable to obtain due to security 71 * restrictions. In this case, a client can use a VMID of null, 72 * and the distributed garbage collector will assign a VMID for 73 * the client. 74 * 75 * The dirty call returns a Lease object that contains the VMID 76 * used and the lease period granted for the remote references (a 77 * server may decide to grant a smaller lease period than the 78 * client requests). A client must use the VMID the garbage 79 * collector uses in order to make corresponding clean calls when 80 * the client drops remote object references. 81 * 82 * A client VM need only make one initial dirty call for each 83 * remote reference referenced in the VM (even if it has multiple 84 * references to the same remote object). The client must also 85 * make a dirty call to renew leases on remote references before 86 * such leases expire. When the client no longer has any 87 * references to a specific remote object, it must schedule a 88 * clean call for the object ID associated with the reference. 89 * 90 * @param ids IDs of objects to mark as referenced by calling client 91 * @param sequenceNum sequence number 92 * @param lease requested lease 93 * @return granted lease 94 * @throws RemoteException if dirty call fails 95 */ 96 Lease dirty(ObjID[] ids, long sequenceNum, Lease lease) 97 throws RemoteException; 98 99 /** 100 * The clean call removes the 'vmid' from the reference list of 101 * each remote object indicated in 'id's. The sequence number is 102 * used to detect late clean calls. If the argument 'strong' is 103 * true, then the clean call is a result of a failed dirty call, 104 * thus the sequence number for the client 'vmid' needs to be 105 * remembered. 106 * 107 * @param ids IDs of objects to mark as unreferenced by calling client 108 * @param sequenceNum sequence number 109 * @param vmid client VMID 110 * @param strong make 'strong' clean call 111 * @throws RemoteException if clean call fails 112 */ 113 void clean(ObjID[] ids, long sequenceNum, VMID vmid, boolean strong) 114 throws RemoteException; 115} 116