org.apache.river.norm

Class SetProxy

java.lang.Object

org.apache.river.norm.AbstractProxy

org.apache.river.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

Nested Classes

Modifier and Type	Class and Description
(package private) static class	SetProxy.ConstrainableSetProxy Defines a subclass of SetProxy that implements RemoteMethodControl.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Lease	ourLease Lease for this set.
private static long	serialVersionUID

Fields inherited from class org.apache.river.norm.AbstractProxy

server, uuid

Fields inherited from interface net.jini.lease.LeaseRenewalSet

EXPIRATION_WARNING_EVENT_ID, RENEWAL_FAILURE_EVENT_ID

Constructor Summary

Constructors

Modifier	Constructor and Description
private	SetProxy(NormServer server, Uuid id, Lease lease) Simple constructor.

Method Summary

Modifier and Type	Method and Description
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 org.apache.river.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