com.sun.jini.outrigger

Class SingletonQueryWatcher

java.lang.Object

com.sun.jini.outrigger.TransitionWatcher

com.sun.jini.outrigger.QueryWatcher

com.sun.jini.outrigger.SingletonQueryWatcher

All Implemented Interfaces:

Comparable

Direct Known Subclasses:

ConsumingWatcher, ReadIfExistsWatcher, ReadWatcher, TakeIfExistsWatcher, TransactableReadIfExistsWatcher

abstract class SingletonQueryWatcher
extends QueryWatcher

Subclass of QueryWatcher for singleton queries. Most of the usage model is laid out in QueryWatcher except how the result of the query is obtained from the watcher. SingletonQueryWatcher defines the resolvedWithEntry and resolvedWithThrowable methods which can be used to obtain the entry or throwable the query was resolved with (and in the case of IfExistsWatchers isConflictSetEmpty).

Field Summary

Fields

Modifier and Type	Field and Description
private EntryHandle	handle If resolved and an entry was found the entry to return
private TemplateHandle	owner The TemplateHandle associated with this watcher.
private boolean	resolved Set to true when this query is resolved
private Throwable	toThrow If resolved and an exception needs to be thrown the exception to throw

Fields inherited from class com.sun.jini.outrigger.TransitionWatcher

startOrdinal

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
(package private) boolean	addTemplateHandle(TemplateHandle h) Associate a TemplateHandle with this object.
(package private) OutriggerServerImpl	getServer() Method to give sub-classes access to OutriggerServerImpl Assumes caller owns lock on this and that this watcher has not been removed.
(package private) boolean	isResolved() Returns true if this query has been resolved.
(package private) void	resolve(EntryHandle handle, Throwable throwable) Mark this query as resolved.
(package private) EntryHandle	resolvedWithEntry() If the query has been resolved by finding an matching entry, returns the EntryHandle for that entry.
(package private) Throwable	resolvedWithThrowable() If the query has been resolved with an exceptional condition, the exception that should be thrown to the client.
(package private) void	waitOnResolution() Block until the query this object represents is resolved.

Methods inherited from class com.sun.jini.outrigger.QueryWatcher

catchUp, getExpiration, removeIfExpired

Methods inherited from class com.sun.jini.outrigger.TransitionWatcher

compareTo, isInterested, process

Methods inherited from class java.lang.Object

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

Field Detail

resolved

private boolean resolved

Set to true when this query is resolved

handle

private EntryHandle handle

If resolved and an entry was found the entry to return

toThrow

private Throwable toThrow

If resolved and an exception needs to be thrown the exception to throw

owner

private TemplateHandle owner

The TemplateHandle associated with this watcher.

Constructor Detail

SingletonQueryWatcher

SingletonQueryWatcher(long expiration,
                     long timestamp,
                     long startOrdinal)

Create a new SingletonQueryWatcher.

Parameters:

expiration - the initial expiration time for this TransitionWatcher 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

addTemplateHandle

boolean addTemplateHandle(TemplateHandle h)

Associate a TemplateHandle with this object. May only be called once on any given SingletonQueryWatcher instance.

Specified by:

addTemplateHandle in class TransitionWatcher

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

waitOnResolution

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.

Specified by:

waitOnResolution in class QueryWatcher

Throws:

InterruptedException

resolvedWithEntry

EntryHandle resolvedWithEntry()

If the query has been resolved by finding an matching entry, returns the EntryHandle for that entry. If the query has been resolved but no entry is available (e.g. the expiration time has been reached or an exception needs to be thrown) returns null. Note, once resolution has been reached this method can only return non-null if resolvedWithThrowable returns null.

Returns:

The entry to be returned, or null if no entry is available.

Throws:

IllegalStateException - if the query has not yet been resolved.

resolvedWithThrowable

Throwable resolvedWithThrowable()

If the query has been resolved with an exceptional condition, the exception that should be thrown to the client. Returns null otherwise. Note, once resolution has been reached this method can only return non-null if resolvedWithEntry returns null.

Returns:

the exception (if any) that should be thrown to the client.

Throws:

IllegalStateException - if the query has not yet been resolved.

isResolved

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.

Specified by:

isResolved in class QueryWatcher

Returns:

true if the query has been resolved, false otherwise.

resolve

void resolve(EntryHandle handle,
           Throwable throwable)

Mark this query as resolved. This method assumes the calling thread own the lock on this object. This method is intended only for use by subclasses.

Parameters:

handle - If being resolved by finding an entry the entry which was found and that should be returned by resolvedWithEntry. Otherwise should be null. May only be non-null if throwable is null.

throwable - If being resolved by an exception the throwable to be thrown and that should be returned by resolvedWithThrowable otherwise should be null. May only be non-null if entry is null.

Throws:

IllegalArgumentException - if both entry and throwable are non-null.

IllegalStateException - if the query has already been resolved.

getServer

OutriggerServerImpl getServer()

Method to give sub-classes access to OutriggerServerImpl Assumes caller owns lock on this and that this watcher has not been removed.