com.levigo.util.base.glazedlists
Class TransactionList<E>

java.lang.Object
  com.levigo.util.base.glazedlists.AbstractEventList<E>
      com.levigo.util.base.glazedlists.TransformedList<E,E>
          com.levigo.util.base.glazedlists.TransactionList<E>

All Implemented Interfaces:

ListEventListener<E>, EventList<E>, Iterable<E>, Collection<E>, EventListener, List<E>

public class TransactionList<E>
extends TransformedList<E,E>

A list transformation that presents traditional transaction semantics. Typical usage resembles one of two methods:

   EventList source = ...
   TransactionList txList = new TransactionList(source);

   // begin a transaction in which all ListEvents are collected by txList
   // into a single "super ListEvent", which is fired on commit
   txList.beginEvent(true);

   // fill in the details of the transaction
   // (these operations actually physically change ONLY txList and its source)
   txList.add("A new element");
   txList.set(0, "A changed element");
   txList.remove(6);

   // commit the transaction, which will broadcast a single ListEvent from
   // txList describing the aggregate of all changes made during the transaction
   // (this returns the entire list pipeline to a consistent state)
   txList.commitEvent();
 

In this usage, all ListEventListeners "downstream" of TransactionList remain clueless about changes made during a transaction. As a result, the "list pipeline" is allowed to temporarily fall into an inconsistent state because only a portion of the pipeline (TransactionList and lower) has seen changes made during the transaction. Users must ensure that they do not read or write through any "downstream" EventList that depends on the TransactionList during a transaction. Typically this is done using the built-in locks.

If the transaction was rolled back instead of committed, the txList would not produce a ListEvent, since none of its listeners would be aware of any changes made during the transaction. The second popular usage resembles this:

   EventList source = ...
   TransactionList txList = new TransactionList(source);

   // begin a transaction in which we change the ListEvent
   txList.beginEvent(); // this is the same as txList.beginEvent(false);

   // fill in the details of the transaction
   // (these operations actually physically change the ENTIRE PIPELINE)
   txList.add("A new element");
   txList.set(0, "A changed element");
   txList.remove(6);

   // commit the transaction, which will NOT broadcast a ListEvent from
   // txList because all of its listeners are already aware of the changes
   // made during the transaction
   txList.commitEvent();
 

In this case, the "list pipeline" always remains consistent and reads/writes may occur through any part EventList in the pipeline without error.

If the transaction is rolled back instead of committed, the txList produces a ListEvent describing the rollback, since its listeners are fully aware of the changes made during the transaction and must also be given a chance to undo their changes.

Transactions may be nested arbitrarily deep using code that resembles:

   txList.beginEvent();
     txList.add("A");

     txList.beginEvent();
       txList.set(0, "B");
     txList.commitEvent();

     txList.beginEvent();
       txList.add("C");
     txList.commitEvent();
   txList.commitEvent();
 

Author:

James Lemieux

Field Summary

Fields inherited from class com.levigo.util.base.glazedlists.TransformedList

source

Fields inherited from class com.levigo.util.base.glazedlists.AbstractEventList

publisher, readWriteLock, updates

Constructor Summary

TransactionList(EventList<E> source)
Constructs a TransactionList that provides traditional transaction semantics over the given source.

Method Summary

void	beginEvent() Demarks the beginning of a transaction which accumulates all ListEvents received during the transaction and fires a single aggregate ListEvent on commitEvent().
void	beginEvent(boolean buffered) Demarks the beginning of a transaction.
void	commitEvent() Demarks the successful completion of a transaction.
void	dispose() Releases the resources consumed by this TransformedList so that it may eventually be garbage collected.
protected boolean	isWritable() Gets whether the source EventList is writable via this API.
void	listChanged(ListEvent<E> listChanges) Simply forwards all of the listChanges since TransactionList doesn't transform the source data in any way.
void	rollbackEvent() Demarks the unsuccessful completion of a transaction.

Methods inherited from class com.levigo.util.base.glazedlists.TransformedList

add, addAll, clear, get, getSourceIndex, remove, removeAll, retainAll, set, size

Methods inherited from class com.levigo.util.base.glazedlists.AbstractEventList

add, addAll, addListEventListener, contains, containsAll, equals, getPublisher, getReadWriteLock, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeListEventListener, subList, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TransactionList

public TransactionList(EventList<E> source)

Constructs a TransactionList that provides traditional transaction semantics over the given source.

Parameters:

source - the EventList over which to provide a transactional view

Method Detail

beginEvent

public void beginEvent()

Demarks the beginning of a transaction which accumulates all ListEvents received during the transaction and fires a single aggregate ListEvent on commitEvent().

beginEvent

public void beginEvent(boolean buffered)

Demarks the beginning of a transaction. If buffered is true then all ListEvents received during the transaction are accumulated and fired as a single aggregate ListEvent on commitEvent(). If buffered is false then all ListEvents received during the transaction are forwarded immediately and commitEvent() produces no ListEvent of its own.

Parameters:

buffered - true indicates ListEvents should be buffered and sent on commitEvent(); false indicates they should be sent on immediately

commitEvent

public void commitEvent()

Demarks the successful completion of a transaction. If changes were buffered during the transaction by calling beginEvent(true) then a single ListEvent will be fired from this TransactionList describing the changes accumulated during the transaction.

rollbackEvent

public void rollbackEvent()

Demarks the unsuccessful completion of a transaction. If changes were NOT buffered during the transaction by calling beginEvent(false) then a single ListEvent will be fired from this TransactionList describing the rollback of the changes accumulated during the transaction.

isWritable

protected boolean isWritable()

Gets whether the source EventList is writable via this API.

Extending classes must override this method in order to make themselves writable.

Specified by:

isWritable in class TransformedList<E,E>

dispose

public void dispose()

Releases the resources consumed by this TransformedList so that it may eventually be garbage collected.

A TransformedList will be garbage collected without a call to TransformedList.dispose(), but not before its source EventList is garbage collected. By calling TransformedList.dispose(), you allow the TransformedList to be garbage collected before its source EventList. This is necessary for situations where a TransformedList is short-lived but its source EventList is long-lived.

Warning: It is an error to call any method on a TransformedList after it has been disposed.

Specified by:

dispose in interface EventList<E>

Overrides:

dispose in class TransformedList<E,E>

listChanged

public void listChanged(ListEvent<E> listChanges)

Simply forwards all of the listChanges since TransactionList doesn't transform the source data in any way.

Specified by:

listChanged in interface ListEventListener<E>

Specified by:

listChanged in class TransformedList<E,E>