com.sun.jini.outrigger
Class TransitionWatcher

java.lang.Object
  extended by 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
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
TransitionWatcher(long timestamp, long startOrdinal)
          Create a new TransitionWatcher.
 
Method Summary
(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.


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