ca.odell.glazedlists.event
Class ListEventAssembler

java.lang.Object
  ca.odell.glazedlists.event.ListEventAssembler

public final class ListEventAssembler
extends Object

Models a continuous stream of changes on a list. Changes of the same type that occur on a continuous set of rows are grouped into blocks automatically for performance benefits.

Atomic sets of changes may involve many lines of changes and many blocks of changes. They are committed to the queue in one action. No other threads should be creating a change on the same list change queue when an atomic change is being created.

Author:

Jesse Wilson

Constructor Summary

ListEventAssembler(EventList sourceList, ListEventPublisher publisher)
Creates a new ListEventAssembler that tracks changes for the specified list.

Method Summary

void	addChange(int type, int index) Convenience method for appending a single change of the specified type.
void	addChange(int type, int startIndex, int endIndex) Adds a block of changes to the set of list changes.
void	addDelete(int index) Convenience method for appending a single delete.
void	addDelete(int startIndex, int endIndex) Convenience method for appending a range of deletes.
void	addInsert(int index) Convenience method for appending a single insert.
void	addInsert(int startIndex, int endIndex) Convenience method for appending a range of inserts.
void	addListEventListener(ListEventListener listChangeListener) Registers the specified listener to be notified whenever new changes are appended to this list change sequence.
void	addUpdate(int index) Convenience method for appending a single update.
void	addUpdate(int startIndex, int endIndex) Convenience method for appending a range of updates.
void	beginEvent() Starts a new atomic change to this list change queue.
void	beginEvent(boolean allowNestedEvents) Starts a new atomic change to this list change queue.
void	commitEvent() Commits the current atomic change to this list change queue.
void	forwardEvent(ListEvent listChanges) Forwards the event.
boolean	isEventEmpty() Returns true if the current atomic change to this list change queue is empty; false otherwise.
void	removeListEventListener(ListEventListener listChangeListener) Removes the specified listener from receiving notification when new changes are appended to this list change sequence.
void	reorder(int[] reorderMap) Sets the current event as a reordering.

Methods inherited from class java.lang.Object

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

Constructor Detail

ListEventAssembler

public ListEventAssembler(EventList sourceList,
                          ListEventPublisher publisher)

Creates a new ListEventAssembler that tracks changes for the specified list.

Method Detail

beginEvent

public void beginEvent()

Starts a new atomic change to this list change queue.

This simple change event does not support change events nested within. To allow other methods to nest change events within a change event, use beginEvent(true).

beginEvent

public void beginEvent(boolean allowNestedEvents)

Starts a new atomic change to this list change queue. This signature allows you to specify allowing nested changes. This simply means that you can call other methods that contain a beginEvent(), commitEvent() block and their changes will be recorded but not fired. This allows the creation of list modification methods to call simpler list modification methods while still firing a single ListEvent to listeners.

Parameters:

allowNestedEvents - false to throw an exception if another call to beginEvent() is made before the next call to commitEvent(). Nested events allow multiple method's events to be composed into a single event.

See Also:

Bug 52

addChange

public void addChange(int type,
                      int startIndex,
                      int endIndex)

Adds a block of changes to the set of list changes. The change block allows a range of changes to be grouped together for efficiency.

One or more calls to this method must be prefixed by a call to beginEvent() and followed by a call to commitEvent().

addChange

public void addChange(int type,
                      int index)

Convenience method for appending a single change of the specified type.

addInsert

public void addInsert(int index)

Convenience method for appending a single insert.

addDelete

public void addDelete(int index)

Convenience method for appending a single delete.

addUpdate

public void addUpdate(int index)

Convenience method for appending a single update.

addInsert

public void addInsert(int startIndex,
                      int endIndex)

Convenience method for appending a range of inserts.

addDelete

public void addDelete(int startIndex,
                      int endIndex)

Convenience method for appending a range of deletes.

addUpdate

public void addUpdate(int startIndex,
                      int endIndex)

Convenience method for appending a range of updates.

reorder

public void reorder(int[] reorderMap)

Sets the current event as a reordering. Reordering events cannot be combined with other events.

forwardEvent

public void forwardEvent(ListEvent listChanges)

Forwards the event. This is a convenience method that does the following:
1. beginEvent()
2. For all changes in sourceEvent, apply those changes to this
3. commitEvent()

Note that this method should be preferred to manually forwarding events because it is heavily optimized.

Note that currently this implementation does a best effort to preserve reorderings. This means that a reordering is lost if it is combined with any other ListEvent.

commitEvent

public void commitEvent()

Commits the current atomic change to this list change queue. This will notify all listeners about the change.

If the current event is nested within a greater event, this will simply change the nesting level so that further changes are applied directly to the parent change.

isEventEmpty

public boolean isEventEmpty()

Returns true if the current atomic change to this list change queue is empty; false otherwise.

Returns:

true if the current atomic change to this list change queue is empty; false otherwise

addListEventListener

public void addListEventListener(ListEventListener listChangeListener)

Registers the specified listener to be notified whenever new changes are appended to this list change sequence. For each listener, a ListEvent is created, which provides a read-only view to the list changes in the list. The same ListChangeView object is used for all notifications to the specified listener, so if a listener does not process a set of changes, those changes will persist in the next notification.

removeListEventListener

public void removeListEventListener(ListEventListener listChangeListener)

Removes the specified listener from receiving notification when new changes are appended to this list change sequence. This uses the == identity comparison to find the listener instead of equals(). This is because multiple Lists may be listening and therefore equals() may be ambiguous.