com.sun.jini.outrigger

Class TakeMultipleWatcher

java.lang.Object

com.sun.jini.outrigger.TransitionWatcher

com.sun.jini.outrigger.QueryWatcher

com.sun.jini.outrigger.TakeMultipleWatcher

All Implemented Interfaces:

Transactable, Comparable, TransactionConstants

 class TakeMultipleWatcher
extends QueryWatcher
implements Transactable

Subclass of QueryWatcher for blocking take multiple 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 entries or throwable the query was resolved with.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	blocking true if we have processed the transition that occurred during the initial search and are now blocking waiting for a match to appear
private Set	handles The entries (as handles) this watcher has captured
private int	limit The maxium number of entries that should be captured
private Set	owners The TemplateHandles associated with this watcher.
private WeakHashMap	provisionallyRemovedEntrySet Set of entries (represented by EntryHolders) that we would have liked to return, but have been provisionally removed.
private boolean	resolved Set to true when this query is resolved
private OutriggerServerImpl	server The OutriggerServerImpl we are part of.
private Throwable	toThrow If resolved and an exception needs to be thrown the exception to throw
private Txn	txn If non-null the transaction this query is being performed under.

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

startOrdinal

Fields inherited from interface net.jini.core.transaction.server.TransactionConstants

ABORTED, ACTIVE, COMMITTED, NOTCHANGED, PREPARED, VOTING

Constructor Summary

Constructors

Constructor and Description
TakeMultipleWatcher(int limit, long expiration, long timestamp, long startOrdinal, WeakHashMap provisionallyRemovedEntrySet, Txn txn) Create a new TakeMultipleWatcher.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort(TransactableMgr mgr, OutriggerServerImpl space) If a transaction ends in the middle of a query we want to throw an exception to the client making the query (not the Txn calling us here.)
(package private) boolean	addTemplateHandle(TemplateHandle h) Associate a TemplateHandle with this object.
private void	captured(EntryHandle handle) Mark this query as resolved.
(package private) boolean	catchUp(EntryTransition transition, long now) Process a transition which was posted before the watcher was placed in TransitionWatchers object.
void	commit(TransactableMgr mgr, OutriggerServerImpl space) This should never happen since we always return NOTCHANGED from prepare.
(package private) boolean	isInterested(EntryTransition transition, long ordinal) Return true if this watcher cares about a given visibility transition.
(package private) boolean	isResolved() Returns true if this query has been resolved.
int	prepare(TransactableMgr mgr, OutriggerServerImpl space) If a transaction ends in the middle of a query we want to throw an exception to the client making the query (not to the Txn calling us here.)
(package private) void	process(EntryTransition transition, long now) Process the given transition.
(package private) EntryHandle[]	resolvedWithEntries() 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

getExpiration, removeIfExpired

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

compareTo

Methods inherited from class java.lang.Object

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

Field Detail

handles

private final Set handles

The entries (as handles) this watcher has captured

limit

private final int limit

The maxium number of entries that should be captured

provisionallyRemovedEntrySet

private final WeakHashMap provisionallyRemovedEntrySet

Set of entries (represented by EntryHolders) that we would have liked to return, but have been provisionally removed.

txn

private final Txn txn

If non-null the transaction this query is being performed under. If null this query is not associated with a transaction.

resolved

private boolean resolved

Set to true when this query is resolved

toThrow

private Throwable toThrow

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

owners

private Set owners

The TemplateHandles associated with this watcher.

server

private OutriggerServerImpl server

The OutriggerServerImpl we are part of.

blocking

private boolean blocking

true if we have processed the transition that occurred during the initial search and are now blocking waiting for a match to appear

Constructor Detail

TakeMultipleWatcher

TakeMultipleWatcher(int limit,
                   long expiration,
                   long timestamp,
                   long startOrdinal,
                   WeakHashMap provisionallyRemovedEntrySet,
                   Txn txn)

Create a new TakeMultipleWatcher.

Parameters:

limit - the maximum number of entries that should be captured by this watcher

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

provisionallyRemovedEntrySet - If the watcher encounters an entry that can not be read/taken because it has been provisionally removed then its handle will be placed in this WeakHashMap as a key (with null as the value). May be null in which case provisionally removed entries will not be recorded. Ensures that object is only accessed by one thread at a time

txn - If the query is being performed under a transaction the Txn object associated with that transaction.

Method Detail

addTemplateHandle

boolean addTemplateHandle(TemplateHandle h)

Associate a TemplateHandle with this object. May be called more than once.

Specified by:

addTemplateHandle in class TransitionWatcher

Parameters:

h - The TemplateHandle to associate 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

catchUp

boolean catchUp(EntryTransition transition,
              long now)

Description copied from class: QueryWatcher

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.

Specified by:

catchUp in class QueryWatcher

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.

isInterested

boolean isInterested(EntryTransition transition,
                   long ordinal)

Description copied from class: TransitionWatcher

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.

Specified by:

isInterested in class TransitionWatcher

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.

process

void process(EntryTransition transition,
           long now)

Description copied from class: TransitionWatcher

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.

Specified by:

process in class TransitionWatcher

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).

waitOnResolution

void waitOnResolution()
                throws InterruptedException

Description copied from class: QueryWatcher

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

resolvedWithEntries

EntryHandle[] resolvedWithEntries()

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()

Description copied from class: QueryWatcher

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.

captured

private void captured(EntryHandle handle)

Mark this query as resolved. This method assumes the calling thread own the lock on this object.

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.

Throws:

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

IllegalStateException - if the query has already been resolved.

prepare

public int prepare(TransactableMgr mgr,
          OutriggerServerImpl space)

If a transaction ends in the middle of a query we want to throw an exception to the client making the query (not to the Txn calling us here.)

Specified by:

prepare in interface Transactable

commit

public void commit(TransactableMgr mgr,
          OutriggerServerImpl space)

This should never happen since we always return NOTCHANGED from prepare.

Specified by:

commit in interface Transactable

abort

public void abort(TransactableMgr mgr,
         OutriggerServerImpl space)

If a transaction ends in the middle of a query we want to throw an exception to the client making the query (not the Txn calling us here.)

Specified by:

abort in interface Transactable