com.sun.jini.jeri.internal.runtime
Class AbstractDgcClient

java.lang.Object
  extended by com.sun.jini.jeri.internal.runtime.AbstractDgcClient
Direct Known Subclasses:
DgcClient

abstract class AbstractDgcClient
extends Object

AbstractDgcClient implements the client-side behavior of RMI's distributed garbage collection system abstractly with respect to the types used to represent transport endpoints, object IDs, and live remote references. The actual types used for endpoints, object IDs, and live references depends on the concrete subclass. The entry point into the machinery of AbstractDgcClient is the "registerRefs" method: when a live reference enters the scope of this AbstractDgcClient (the current virtual machine, for example), it should be registered with that method in order for it to participate in distributed garbage collection. When the first live reference to a particular remote object is registered, a "dirty" call is made to the server-side distributed garbage collector at the remote object's endpoint, which, if successful, returns a lease guaranteeing that the server-side DGC will not collect the remote object for a certain period of time. While live references to remote objects at a particular endpoint exist, this AbstractDgcClient will continue to make more "dirty" calls to renew its lease on the referenced remote objects. This AbstractDgcClient tracks the local reachability of registered live references (using phantom references). When all of the live reference instances for a particular remote object become garbage collected locally, a "clean" call is made to the server-side distributed garbage collector, indicating that the server no longer needs to keep the remote object alive for this client. Internally, AbstractDgcClient holds and manipulates transport endpoints, object IDs, and live references with references of type java.lang.Object; it is assumed that their actual classes define "equals" and "hashCode" in a meaningful way. Concrete subclasses must provide additional behavior for the actual endpoint, object ID, and live reference types by implementing the abstract protected methods of this class (see below). In particular, the "getDgcProxy" method should return an object that implements the actual protocol for DGC "dirty" and "clean" calls for the endpoint type being used, the "freeEndpoint" method may make use of the indication that a particular endpoint no longer has references, and the "getRefEndpoint" and "getRefObjectID" methods should return the endpoint and object ID contained in a particular live reference object. A concrete subclass should also provide a type-safe equivalent of "registerRefs" that delegates to this class's "registerRefs" method.

Author:
Sun Microsystems, Inc.

Nested Class Summary
private static class AbstractDgcClient.CleanRequest
          CleanRequest holds the data for the arguments of a clean call that needs to be made.
protected static interface AbstractDgcClient.DgcProxy
          A DgcProxy is a proxy for invoking DGC operations on a server-side DGC implementation at a particular endpoint.
private  class AbstractDgcClient.EndpointEntry
          EndpointEntry encapsulates the client-side DGC information specific to a particular endpoint.
 
Field Summary
private static int cleanConnectRetries
          retry count for clean calls that fail with ConnectException
private static long cleanInterval
          maximum interval between retries of failed clean calls
private static int dirtyFailureRetries
          minimum retry count for dirty calls that fail
private static Object[] emptyObjectArray
          constant empty Object array for lease renewal optimization
private  Map endpointTable
          endpoint table: maps generic endpoint to EndpointEntry (lock guards endpointTable)
private static long leaseValue
          lease duration to request (usually ignored by server)
private static long minimumDuration
          minimum lease duration that we bother to honor
private static long nextSequenceNum
          next sequence number for DGC calls (access synchronized on class)
 
Constructor Summary
protected AbstractDgcClient()
           
 
Method Summary
private static long computeRenewTime(long grantTime, long duration)
          Given the length of a lease and the time that it was granted, computes the absolute time at which it should be renewed, giving room for reasonable computational and communication delays.
protected abstract  void freeEndpoint(Object endpoint)
          Indicates that resources for the given endpoint may be freed.
protected abstract  AbstractDgcClient.DgcProxy getDgcProxy(Object endpoint)
          Returns a proxy for making DGC calls to the given endpoint.
private  AbstractDgcClient.EndpointEntry getEndpointEntry(Object endpoint)
          Looks up the EndpointEntry for the given endpoint.
private static long getNextSequenceNum()
          Gets the next sequence number to be used for a dirty or clean operation from this AbstractDgcClient.
protected abstract  Object getRefEndpoint(Object ref)
          Returns the endpoint in the given live reference.
protected abstract  Object getRefObjectID(Object ref)
          Returns the object ID in the given live reference.
protected  void registerRefs(Object endpoint, Collection refs)
          Registers the live reference instances in the supplied collection to participate in distributed garbage collection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

leaseValue

private static final long leaseValue
lease duration to request (usually ignored by server)


cleanInterval

private static final long cleanInterval
maximum interval between retries of failed clean calls


minimumDuration

private static final long minimumDuration
minimum lease duration that we bother to honor


dirtyFailureRetries

private static final int dirtyFailureRetries
minimum retry count for dirty calls that fail

See Also:
Constant Field Values

cleanConnectRetries

private static final int cleanConnectRetries
retry count for clean calls that fail with ConnectException

See Also:
Constant Field Values

emptyObjectArray

private static final Object[] emptyObjectArray
constant empty Object array for lease renewal optimization


nextSequenceNum

private static long nextSequenceNum
next sequence number for DGC calls (access synchronized on class)


endpointTable

private final Map endpointTable
endpoint table: maps generic endpoint to EndpointEntry (lock guards endpointTable)

Constructor Detail

AbstractDgcClient

protected AbstractDgcClient()
Method Detail

getDgcProxy

protected abstract AbstractDgcClient.DgcProxy getDgcProxy(Object endpoint)
Returns a proxy for making DGC calls to the given endpoint.


freeEndpoint

protected abstract void freeEndpoint(Object endpoint)
Indicates that resources for the given endpoint may be freed.


getRefEndpoint

protected abstract Object getRefEndpoint(Object ref)
Returns the endpoint in the given live reference.


getRefObjectID

protected abstract Object getRefObjectID(Object ref)
Returns the object ID in the given live reference.


registerRefs

protected final void registerRefs(Object endpoint,
                                  Collection refs)
Registers the live reference instances in the supplied collection to participate in distributed garbage collection. All of the live references in the list must be for remote objects at the given endpoint.


getNextSequenceNum

private static long getNextSequenceNum()
Gets the next sequence number to be used for a dirty or clean operation from this AbstractDgcClient. This method should only be called while synchronized on the EndpointEntry whose data structures the operation affects.


computeRenewTime

private static long computeRenewTime(long grantTime,
                                     long duration)
Given the length of a lease and the time that it was granted, computes the absolute time at which it should be renewed, giving room for reasonable computational and communication delays.


getEndpointEntry

private AbstractDgcClient.EndpointEntry getEndpointEntry(Object endpoint)
Looks up the EndpointEntry for the given endpoint. An entry is created if one does not already exist.



Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.