org.apache.river.outrigger

Class QueryWatcher

java.lang.Object

org.apache.river.outrigger.TransitionWatcher

org.apache.river.outrigger.QueryWatcher

All Implemented Interfaces:

Comparable<TransitionWatcher>

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

Fields

Modifier and Type	Field and Description
private long	expiration When this query ends

Fields inherited from class org.apache.river.outrigger.TransitionWatcher

startOrdinal

Constructor Summary

Constructors

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

Method Summary

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