com.sun.jini.outrigger

Class TransitionWatcher

java.lang.Object

com.sun.jini.outrigger.TransitionWatcher

All Implemented Interfaces:

Comparable

Direct Known Subclasses:

AvailabilityRegistrationWatcher, EventRegistrationWatcher, QueryWatcher

abstract class TransitionWatcher
extends Object
implements Comparable

Base class for objects that represent interest in particular entry visibility transitions. Each TransitionWatcher has a time stamp and when compared TransitionWatchers with a lower time stamp are considered less than those with a larger time stamp. If two TransitionWatcher have the same time stamp their tie breaker values are used.

Unless otherwise noted, the addTemplateHandle method must be called at least once before any other method. Some implementations of this call only support calling addTemplateHandle once on any particular instance.

Unless otherwise noted, all the package protected methods are thread safe.

Field Summary

Fields

Modifier and Type	Field and Description
private static long	nextTiebreaker Next tiebreaker to use
private static Object	nextTiebreakerLock Lock for nextTiebreaker
(package private) long	startOrdinal The transitions with higher ordinals occurred after the operation associated with this watcher was started.
private long	tiebreaker The tie breaker for this object
private long	timestamp The time stamp for this object

Constructor Summary

Constructors

Constructor and Description
TransitionWatcher(long timestamp, long startOrdinal) Create a new TransitionWatcher.

Method Summary

Methods

Modifier and Type	Method and Description
(package private) abstract boolean	addTemplateHandle(TemplateHandle h) Associate a TemplateHandle with this object.
int	compareTo(Object o) Compares this object with another.
abstract long	getExpiration() Get the expiration time of this object.
(package private) abstract boolean	isInterested(EntryTransition transition, long ordinal) Return true if this watcher cares about a given visibility transition.
(package private) abstract void	process(EntryTransition transition, long now) Process the given transition.
(package private) abstract void	removeIfExpired(long now) Remove this watcher from the system if it has expired.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

timestamp

private final long timestamp

The time stamp for this object

tiebreaker

private final long tiebreaker

The tie breaker for this object

startOrdinal

final long startOrdinal

The transitions with higher ordinals occurred after the operation associated with this watcher was started. Package protected but should only be accessed by subclasses.

nextTiebreaker

private static long nextTiebreaker

Next tiebreaker to use

nextTiebreakerLock

private static Object nextTiebreakerLock

Lock for nextTiebreaker

Constructor Detail

TransitionWatcher

TransitionWatcher(long timestamp,
                 long startOrdinal)

Create a new TransitionWatcher.

Parameters:

timestamp - the value that is used to sort TransitionWatchers.

startOrdinal - the highest ordinal associated with operations that are considered to have occurred before the operation associated with this watcher.

Method Detail

addTemplateHandle

abstract boolean addTemplateHandle(TemplateHandle h)

Associate a TemplateHandle with this object. An implementation may support calling this method only once on a given instance.

Parameters:

h - The TemplateHandle associated with this watcher.

Returns:

true if the handle was succfully added, and false if the watcher has already been removed.

Throws:

NullPointerException - if h is null

compareTo

public int compareTo(Object o)

Compares this object with another. If the other object is not a TransitionWatcher a ClassCastException will be thrown. The object with the lower time stamp will be considered less than the other. If they both have the same time stamp the object will the lower tie breaker will be less than the other. If both have the same tie breaker and time stamp they will be considered equal.

This method may be called before addTemplateHandle is called.

Specified by:

compareTo in interface Comparable

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

ClassCastException - if o is not a TransitionWatcher.

getExpiration

public abstract long getExpiration()

Get the expiration time of this object. This method may be called before addTemplateHandle is called. Assumes locking is handled by the caller.

Returns:

The time (in milliseconds since the beginning of the epoch) when this watcher is no longer relevant.

removeIfExpired

abstract void removeIfExpired(long now)

Remove this watcher from the system if it has expired. Responsible for calling the remove method of the associated TemplateHandle. This method can be called more than once, though second and subsequent calls may have no effect.

Parameters:

now - An estimate of the current time that must be less than or equal to the current time.

isInterested

abstract boolean isInterested(EntryTransition transition,
                   long ordinal)

Return true if this watcher cares about a given visibility transition. Assumes the transitioning entry matches the template in the TemplateHandle associated with this watcher. This method should return a value even if the expiration time has been reached or remove has been called. This call should not obtain any locks.

Parameters:

transition - A EntryTransition that describes the transition and what entry is transitioning. This method will assume that transition.getHandle returns a non-null value.

ordinal - The ordinal associated with transition.

Returns:

true if this watcher is interested in the indicated transition and false otherwise.

Throws:

NullPointerException - if transition is null.

process

abstract void process(EntryTransition transition,
           long now)

Process the given transition. Assumes the passed entry matches the template in the TemplateHandle associated with this watcher and that isInterested returned true. This call may make changes to the passed EntryHandle that will prevent it from being used by other watchers. If remove has been called or the expiration time of this watcher has passed, this call should have no effect. This call may cause the watcher to be removed.

Parameters:

transition - A EntryTransition that describes the transition and what entry is transitioning. This method will assume that transition.getHandle returns a non-null value.

now - An estimate of the current time (not the time when the event occured).

Throws:

NullPointerException - if transition is null.