com.sun.jini.norm
Class SetProxy

java.lang.Object
  extended by com.sun.jini.norm.AbstractProxy
      extended by com.sun.jini.norm.SetProxy
All Implemented Interfaces:
Serializable, ReferentUuid, LeaseRenewalSet
Direct Known Subclasses:
SetProxy.ConstrainableSetProxy

 class SetProxy
extends AbstractProxy
implements LeaseRenewalSet

Client side proxy for Norm's lease renewal sets. Uses an object of type NormServer to communicate back to server.

Author:
Sun Microsystems, Inc.

Nested Class Summary
(package private) static class SetProxy.ConstrainableSetProxy
          Defines a subclass of SetProxy that implements RemoteMethodControl.
 
Field Summary
(package private)  Lease ourLease
          Lease for this set.
private static long serialVersionUID
           
 
Fields inherited from class com.sun.jini.norm.AbstractProxy
server, uuid
 
Fields inherited from interface net.jini.lease.LeaseRenewalSet
EXPIRATION_WARNING_EVENT_ID, RENEWAL_FAILURE_EVENT_ID
 
Constructor Summary
private SetProxy(NormServer server, Uuid id, Lease lease)
          Simple constructor.
 
Method Summary
 void clearExpirationWarningListener()
          Remove the listener currently registered for expiration warning events.
 void clearRenewalFailureListener()
          Remove the listener currently registered for renewal failure events.
(package private) static SetProxy create(NormServer server, Uuid id, Lease lease)
          Creates a lease set proxy, returning an instance that implements RemoteMethodControl if the server does.
 Lease[] getLeases()
          Returns all the leases currently in the set.
 Lease getRenewalSetLease()
          Returns the lease that controls the lifetime of this set.
private  void readObject(ObjectInputStream in)
          Require lease to be non-null.
private  void readObjectNoData()
          Require fields to be non-null.
 Lease remove(Lease leaseToRemove)
          Removes the specified lease from set.
 void renewFor(Lease leaseToRenew, long membershipDuration)
          Include a client lease in the set for a specified duration.
 void renewFor(Lease leaseToRenew, long membershipDuration, long renewDuration)
          Include a client lease in the set for a specified duration and with a specified renewal duration.
(package private)  NormServer server2()
          Returns a second server proxy for use by methods that represent a second client-side method for a single server-side method.
 EventRegistration setExpirationWarningListener(RemoteEventListener listener, long minWarning, MarshalledObject handback)
          Register for the expiration warning event associated with this set.
 EventRegistration setRenewalFailureListener(RemoteEventListener listener, MarshalledObject handback)
          Register for the renewal failure event associated with this set.
 
Methods inherited from class com.sun.jini.norm.AbstractProxy
equals, getReferentUuid, hashCode
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

ourLease

final Lease ourLease
Lease for this set.

Constructor Detail

SetProxy

private SetProxy(NormServer server,
                 Uuid id,
                 Lease lease)
Simple constructor.

Method Detail

create

static SetProxy create(NormServer server,
                       Uuid id,
                       Lease lease)
Creates a lease set proxy, returning an instance that implements RemoteMethodControl if the server does.

Parameters:
server - the server proxy
id - the ID of the lease set
lease - the lease set's lease

readObjectNoData

private void readObjectNoData()
                       throws InvalidObjectException
Require fields to be non-null.

Throws:
InvalidObjectException

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException
Require lease to be non-null.

Throws:
IOException
ClassNotFoundException

renewFor

public void renewFor(Lease leaseToRenew,
                     long membershipDuration)
              throws RemoteException
Description copied from interface: LeaseRenewalSet
Include a client lease in the set for a specified duration.

Calling this method is equivalent to making the following call on this set:

     renewFor(leaseToRenew, desiredDuration, Lease.FOREVER)
 

Specified by:
renewFor in interface LeaseRenewalSet
Parameters:
leaseToRenew - the lease to be added to the renewal set
membershipDuration - the maximum length of time in milliseconds the leaseToRenew should remain in the set, or Lease.FOREVER which implies there is no pre-specified time when the lease should be removed from the set
Throws:
RemoteException - if a communication-related exception occurs

renewFor

public void renewFor(Lease leaseToRenew,
                     long membershipDuration,
                     long renewDuration)
              throws RemoteException
Description copied from interface: LeaseRenewalSet
Include a client lease in the set for a specified duration and with a specified renewal duration.

The leaseToRenew argument specifies the lease to be added to the set. An IllegalArgumentException must be thrown if the lease was granted by the renewal service itself. If leaseToRenew is null, a NullPointerException must be thrown.

The desiredDuration argument is the number of milliseconds the client would like the lease to remain in the set. It is used to calculate the lease's initial desired expiration by adding desiredDuration to the current time (as viewed by the service). If this causes an overflow, a desired expiration of Long.MAX_VALUE will be used. Unlike a lease duration, the desired duration is unilaterally specified by the client, not negotiated between the client and the service. Note, a negative value for desiredDuration (including Lease.ANY) will result in a desired expiration that is in the past, causing leaseToRenew to be dropped from the set; this action will neither result in an exception or an event.

If the actual expiration time of leaseToRenew is less than the current time (as viewed by the renewal service) and the current time is less than the desired expiration time for leaseToRenew, the method will return normally. However, leaseToRenew will be dropped from the set and a renewal failure event will be generated.

The renewDuration is the initial renewal duration to associate with leaseToRenew (in milliseconds). If desiredDuration is exactly Long.MAX_VALUE, the renewDuration may be any positive number or Lease.ANY; otherwise it must be a positive number. If these requirements are not met, the renewal service must throw an IllegalArgumentException.

Calling this method with a lease that is equivalent to a client lease already in the set will associate the existing client lease in the set with the new desired duration and renew duration. The client lease is not replaced because it is more likely that the renewal service, rather than the client, has an up-to-date lease expiration. The service is more likely to have an up-to-date expiration because the client should not be renewing a lease that it has passed to a lease renewal service unless the lease is removed first. These semantics also allow renewFor to be used in an idempotent fashion.

Specified by:
renewFor in interface LeaseRenewalSet
Parameters:
leaseToRenew - the lease to be added to the renewal set
membershipDuration - the maximum length of time in milliseconds the leaseToRenew should remain in the set, or Lease.FOREVER which implies there is no pre-specified time when the lease should be removed from the set
renewDuration - the lease duration to request when renewing the lease, unless renewDuration is greater than the remainder of the desiredDuration
Throws:
RemoteException - if a communication-related exception occurs

remove

public Lease remove(Lease leaseToRemove)
             throws RemoteException
Description copied from interface: LeaseRenewalSet
Removes the specified lease from set. If the lease is currently in the set it will be returned, otherwise null will be returned. leaseToRemove will not be canceled by this call.

Specified by:
remove in interface LeaseRenewalSet
Parameters:
leaseToRemove - lease to be removed from the set
Returns:
the removed lease if it was in the set or null if it was not
Throws:
RemoteException - if a communication-related exception occurs

getLeases

public Lease[] getLeases()
                  throws LeaseUnmarshalException,
                         RemoteException
Description copied from interface: LeaseRenewalSet
Returns all the leases currently in the set.

Specified by:
getLeases in interface LeaseRenewalSet
Returns:
the leases in the set. Return a zero length array if there are not leases currently in the set.
Throws:
LeaseUnmarshalException - if one or more of the leases can not be unmarshalled. The throwing of a LeaseUnmarshalException represents a, possibly transient, failure in the ability to unmarshal one or more client leases in the set, it does not necessarily imply anything about the state of the renewal service or the set themselves.
RemoteException - if a communication-related exception occurs

setExpirationWarningListener

public EventRegistration setExpirationWarningListener(RemoteEventListener listener,
                                                      long minWarning,
                                                      MarshalledObject handback)
                                               throws RemoteException
Description copied from interface: LeaseRenewalSet
Register for the expiration warning event associated with this set.

This method allows the client to register for notification of the approaching expiration of the set's lease. The listener argument specifies what listener should be notified when the lease is about to expire. The minWarning argument specifies a minimum number of milliseconds before lease expiration that the first event delivery attempt should be made by the service. The service may also make subsequent delivery attempts if the first and any subsequent attempts have been indeterminate. The minWarning argument must be zero or a positive number; if it is not, an IllegalArgumentException must be thrown. If the current expiration of the set's lease is less than minWarning milliseconds away, the event will occur immediately (though it will take time to propagate to the listener).

The handback argument to this method specifies an object that will be part of the expiration warning event notification. This mechanism is detailed in the Jini Distributed Event Specification.

This method returns the event registration for this event. The Lease object associated with the registration will be equivalent (in the sense of equals) to the Lease on the renewal set. Because the event registration shares a lease with the set, clients that want to just remove their expiration warning registration without destroying the set should use the clearExpirationWarningListener method instead of cancelling the registration's lease. The registration's event ID will be LeaseRenewalSet.EXPIRATION_WARNING_EVENT_ID. The source of the registration will be the set. The method must throw a NullPointerException if the listener argument is null. If an event handler has already been specified for this event the current registration is replaced with the new one. Because both registrations are for the same kind of event, the events sent to the new registration must be in the same sequence as the events sent to the old registration.

Specified by:
setExpirationWarningListener in interface LeaseRenewalSet
Parameters:
listener - the listener to be notified when this event occurs
minWarning - how long before the lease on the set expires should the event be sent
handback - an object to be handed back to the listener when the warning event occurs
Returns:
an EventRegistration describing the event registration
Throws:
RemoteException - if a communication-related exception occurs

clearExpirationWarningListener

public void clearExpirationWarningListener()
                                    throws RemoteException
Description copied from interface: LeaseRenewalSet
Remove the listener currently registered for expiration warning events. It is safe to call this method even if no listener is currently registered.

Specified by:
clearExpirationWarningListener in interface LeaseRenewalSet
Throws:
RemoteException - if a communication-related exception occurs

setRenewalFailureListener

public EventRegistration setRenewalFailureListener(RemoteEventListener listener,
                                                   MarshalledObject handback)
                                            throws RemoteException
Description copied from interface: LeaseRenewalSet
Register for the renewal failure event associated with this set.

This method allows the client to register for the event associated with the failure to renew a client lease in the set. These events are generated when a client lease expires while it is still in the set, or when the service attempts to renew a client lease and gets a definite exception. The listener argument specifies the listener to be notified if a client lease could not be renewed.

The handback argument specifies an object that will be part of the renewal failure event notification. This mechanism is detailed in the Jini Distributed Event Specification.

This method returns the event registration for this event. The Lease object associated with the registration will be equivalent (in the sense of equals) to the Lease on the renewal set. Because the event registration shares a lease with the set, clients that want to just remove their expiration warning registration without destroying the set should use the clearRenewalFailureListener method, instead of cancelling the registration's lease. The registration's event ID will be LeaseRenewalSet.RENEWAL_FAILURE_EVENT_ID. The source of the registration will be the set. The method must throw NullPointerException if the listener argument is null. If an event handler has already been specified for this event the current registration is replaced with the new one. The returned event registration must have the same event ID as the replaced registration. Because both registrations are for the same kind of event, the events sent to the new registration must be in the same sequence as the events sent to the old registration.

Specified by:
setRenewalFailureListener in interface LeaseRenewalSet
Parameters:
listener - the listener to be notified when this event occurs
handback - an object to be handed back to the listener when the warning event occurs
Returns:
an EventRegistration describing the event registration
Throws:
RemoteException - if a communication-related exception occurs

clearRenewalFailureListener

public void clearRenewalFailureListener()
                                 throws RemoteException
Description copied from interface: LeaseRenewalSet
Remove the listener currently registered for renewal failure events. It is safe to call this method even if no listener is currently registered.

Specified by:
clearRenewalFailureListener in interface LeaseRenewalSet
Throws:
RemoteException - if a communication-related exception occurs

server2

NormServer server2()
Returns a second server proxy for use by methods that represent a second client-side method for a single server-side method. The distinction only matters for the constrainable subclass, where the different server proxies need different client constraints.


getRenewalSetLease

public Lease getRenewalSetLease()
Description copied from interface: LeaseRenewalSet
Returns the lease that controls the lifetime of this set. Can be used to extend or end the sets lifetime. Note that this method does not make a remote call.

Specified by:
getRenewalSetLease in interface LeaseRenewalSet
Returns:
the lease that controls the lifetime of this set


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