com.sun.jini.outrigger
Class SingletonQueryWatcher

java.lang.Object
  extended by com.sun.jini.outrigger.TransitionWatcher
      extended by com.sun.jini.outrigger.QueryWatcher
          extended by 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
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
SingletonQueryWatcher(long expiration, long timestamp, long startOrdinal)
          Create a new SingletonQueryWatcher.
 
Method Summary
(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.



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