com.levigo.util.base.glazedlists.matchers
Class ThreadedMatcherEditor<E>

java.lang.Object
  com.levigo.util.base.glazedlists.matchers.AbstractMatcherEditor<E>
      com.levigo.util.base.glazedlists.matchers.ThreadedMatcherEditor<E>

All Implemented Interfaces:

MatcherEditor<E>

public class ThreadedMatcherEditor<E>
extends AbstractMatcherEditor<E>

A MatcherEditor which decorates a source MatcherEditor with functionality. Specifically, this MatcherEditor is meant to act as a buffer for MatcherEvents to smooth out disparities between the rate at which MatcherEvents are produced by the source MatcherEditor and the rate at which they are consumed by registered MatcherEditorListeners.

Internally, a ThreadedMatcherEditor enqueues MatcherEvents as they they are received from the source MatcherEditor. The MatcherEvents on the queue are fired by another Thread as rapidly as the MatcherEditorListeners can consume them. Two methods exist on this class which enable subclasses to customize aspects of processing queued MatcherEvents:

1. executeMatcherEventQueueRunnable(Runnable) is consulted when a Thread must be selected to execute the given Runnable which will drain the queue of MatcherEvents. Subclasses may override to customize which Thread is used.
2. coalesceMatcherEvents(List) is used to compress many enqueued MatcherEvents into a single representative MatcherEvent. This implies a contract between all registered MatcherEditorListeners and this ThreadedMatcherEditor that guarantees that processing the coalesced MatcherEvent is equivalent to processing all MatcherEvents sequentially.

Typical usage patterns of ThreadedMatcherEditor resemble:

   MatcherEditor threadedMatcherEditor = new ThreadedMatcherEditor(new AnyMatcherEditor());
   FilterList filterList = new FilterList(new BasicEventList(), threadedMatcherEditor);
 

Author:

James Lemieux

Nested Class Summary

Nested classes/interfaces inherited from interface com.levigo.util.base.glazedlists.matchers.MatcherEditor

MatcherEditor.Event<E>, MatcherEditor.Listener<E>

Field Summary

Fields inherited from class com.levigo.util.base.glazedlists.matchers.AbstractMatcherEditor

currentMatcher

Constructor Summary

ThreadedMatcherEditor(MatcherEditor<E> source)
Creates a ThreadedMatcherEditor which wraps the given source.

Method Summary

protected MatcherEditor.Event<E>	coalesceMatcherEvents(List<MatcherEditor.Event<E>> matcherEvents) This method implements the strategy for coalescing many queued MatcherEvents into a single representative MatcherEvent.
protected void	executeMatcherEventQueueRunnable(Runnable runnable) This method executes the given runnable on a Thread.
Matcher<E>	getMatcher() Returns the current Matcher specified by the source MatcherEditor.

Methods inherited from class com.levigo.util.base.glazedlists.matchers.AbstractMatcherEditor

addMatcherEditorListener, fireChanged, fireChangedMatcher, fireConstrained, fireMatchAll, fireMatchNone, fireRelaxed, isCurrentlyMatchingAll, isCurrentlyMatchingNone, removeMatcherEditorListener

Methods inherited from class java.lang.Object

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

Constructor Detail

ThreadedMatcherEditor

public ThreadedMatcherEditor(MatcherEditor<E> source)

Creates a ThreadedMatcherEditor which wraps the given source. MatcherEvents fired from the source will be enqueued within this MatcherEditor until they are processed on an alternate Thread.

Parameters:

source - the MatcherEditor to wrap with buffering functionality

Throws:

NullPointerException - if source is null

Method Detail

getMatcher

public Matcher<E> getMatcher()

Returns the current Matcher specified by the source MatcherEditor.

Specified by:

getMatcher in interface MatcherEditor<E>

Overrides:

getMatcher in class AbstractMatcherEditor<E>

Returns:

the current Matcher specified by the source MatcherEditor

coalesceMatcherEvents

protected MatcherEditor.Event<E> coalesceMatcherEvents(List<MatcherEditor.Event<E>> matcherEvents)

This method implements the strategy for coalescing many queued MatcherEvents into a single representative MatcherEvent. Listeners which process the MatcherEvent returned from this method should match the state that would exist if each of the matcherEvents were fired sequentially. In general, any group of matcherEvents can be succesfully coalesced as a single MatcherEvent with a type of changed, however, this method's default implementation uses a few heuristics to do more intelligent coalescing in order to gain speed improvements:

1. if matcherEvents ends in a MatcherEvent which is a MatcherEditor.Event.MATCH_ALL or MatcherEditor.Event.MATCH_NONE type, the last MatcherEvent is returned, regardless of previous MatcherEvents

2. if matcherEvents only contains a series of monotonically constraining MatcherEvents, the final MatcherEvent is returned

3. if matcherEvents only contains a series of monotonically relaxing MatcherEvents, the final MatcherEvent is returned

4. if matcherEvents contains both constraining and relaxing MatcherEvents, the final MatcherEvent is returned with its type as MatcherEditor.Event.CHANGED

Note that 1, 2, and 3 above merely represent safe optimizations of the type of MatcherEvent that can be returned. It could also have been returned as a MatcherEvent with a type of MatcherEditor.Event.CHANGED and be assumed to work correctly, though potentially less efficiently, since it is a more generic type of change.

Subclasses with the ability to fire precise MatcherEvents with fine grain types (i.e. relaxed or constrained) when coalescing matcherEvents in situations not recounted above may do so by overiding this method.

Parameters:

matcherEvents - an array of MatcherEvents recorded in the order they were received from the source MatcherEditor

Returns:

a single MatcherEvent which, when fired, will result in the same state as if all matcherEvents had been fired sequentially

executeMatcherEventQueueRunnable

protected void executeMatcherEventQueueRunnable(Runnable runnable)

This method executes the given runnable on a Thread. The particular Thread chosen to execute the Runnable is left as an implementation detail. By default, a new Thread named MatcherQueueThread is constructed to execute the runnable each time this method is called. Subclasses may override this method to use any Thread selection strategy they wish.

Parameters:

runnable - a Runnable to execute on an alternate Thread