com.sun.jini.outrigger
Class QueryWatcher

java.lang.Object
  extended by com.sun.jini.outrigger.TransitionWatcher
      extended by com.sun.jini.outrigger.QueryWatcher
All Implemented Interfaces:
Comparable
Direct Known Subclasses:
SingletonQueryWatcher, TakeMultipleWatcher

abstract class QueryWatcher
extends TransitionWatcher

Subclass of TransitionWatcher for blocking queries. QueryWatchers are waiting for a set of conditions (time, transitions, etc.) that will resolve the query. Threads can block on resolution by calling the waitOnResolution method. Once waitOnResolution than can use subclass specific methods to obtain the result.

Resolution may involve capturing one or more entries (that is locking or removing an entry from the space). It is important that a QueryWatcher never capture an entry after the watcher enters the resolved state, since that could allow a caller to believe that the call failed, when it fact it locked or removed an entry and/or in entries being removed/locked that are never returned to the client. Put another way, the decision to capture an entry has to be done atomically with the check that ensures that the related query is still unresolved.


Field Summary
private  long expiration
          When this query ends
 
Fields inherited from class com.sun.jini.outrigger.TransitionWatcher
startOrdinal
 
Constructor Summary
QueryWatcher(long expiration, long timestamp, long startOrdinal)
          Create a new QueryWatcher.
 
Method Summary
(package private) abstract  boolean catchUp(EntryTransition transition, long now)
          Process a transition which was posted before the watcher was placed in TransitionWatchers object.
 long getExpiration()
          Get the expiration time of this object.
(package private) abstract  boolean isResolved()
          Returns true if this query has been resolved.
(package private)  void removeIfExpired(long now)
          This method does nothing.
(package private) abstract  void waitOnResolution()
          Block until the query this object represents is resolved.
 
Methods inherited from class com.sun.jini.outrigger.TransitionWatcher
addTemplateHandle, compareTo, isInterested, process
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

expiration

private final long expiration
When this query ends

Constructor Detail

QueryWatcher

QueryWatcher(long expiration,
             long timestamp,
             long startOrdinal)
Create a new QueryWatcher.

Parameters:
expiration - the initial expiration time for this QueryWatcher in milliseconds since the beginning of the epoch.
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

getExpiration

public long getExpiration()
Description copied from class: TransitionWatcher
Get the expiration time of this object. This method may be called before addTemplateHandle is called. Assumes locking is handled by the caller.

Specified by:
getExpiration in class TransitionWatcher
Returns:
The time (in milliseconds since the beginning of the epoch) when this watcher is no longer relevant.

catchUp

abstract boolean catchUp(EntryTransition transition,
                         long now)
Process a transition which was posted before the watcher was placed in TransitionWatchers object. Assumes that the entry in the transition matches matches the template in the TemplateHandle associated with this watcher. Does not assume isInterested has been called.

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).
Returns:
true if the query has been resolved, and false otherwise. Note, even if this call returns true, waitOnResolution must still be called.
Throws:
NullPointerException - if transition is null.

removeIfExpired

void removeIfExpired(long now)
This method does nothing. Since each QueryWatcher has a thread that blocks until the expiration time is reached it simpler to do the removal there instead of in the reaping thread.

Specified by:
removeIfExpired in class TransitionWatcher
Parameters:
now - An estimate of the current time that must be less than or equal to the current time.

waitOnResolution

abstract void waitOnResolution()
                        throws InterruptedException
Block until the query this object represents is resolved. If the query is already resolved, return immediately. This method must be called even if it is know that the query has been resolved. This method should be called exactly once.

Throws:
InterruptedException

isResolved

abstract boolean isResolved()
Returns true if this query has been resolved. If the calling thread is owns the lock on this object the answer is definitive. If the lock is not held only a true answer can be considered definitive.

Returns:
true if the query has been resolved, false otherwise.


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