org.tentackle.util
Class TrackedArrayList<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractList<E>
          java.util.ArrayList<E>
              org.tentackle.util.TrackedArrayList<E>

Type Parameters:

E - the element type

All Implemented Interfaces:

Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess

public class TrackedArrayList<E>
extends ArrayList<E>

An extended ArrayList with the ability to tell whether it has been structurally modified.

Furthermore, a TrackedArrayList distinguish between additions and removals. Replacements are treated as a removal followed by an addition. Furthermore, all removed objects are kept in a separate list.

The main usage is in OR-mapping to check whether a list should be written back to persistant storage or not and which elements have to be deleted and which to be inserted or updated. However, the TrackedArrayList is not restricted to DbObjects. However, if it is used in OR-mapping (see DbRelations.wrbl), all objects must be DbObjects and must be tracked as well (honour isModified()).

Notice that the list of added objects is just the sum of this list and the list of removed objects.

Author:

harald

See Also:

Serialized Form

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

TrackedArrayList()
Creates a tracked ArrayList.

TrackedArrayList(boolean modified)
Creates a tracked ArrayList.

TrackedArrayList(Collection<E> collection)
Creates a list from a collection.

TrackedArrayList(int initialCapacity, boolean modified)
Creates a tracked ArrayList.

Method Summary

boolean	add(E o) Appends the specified element to the end of this list.
void	add(int index, E element) Inserts the specified element at the specified position in this list.
boolean	addAll(Collection<? extends E> c) Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.
boolean	addAll(int index, Collection<? extends E> c) Inserts all of the elements in the specified collection into this list, starting at the specified position.
protected void	addRemovedObject(E object) Adds an object to the list of removed objects.
protected void	addRemovedObjects(Collection<E> objects) Adds a list of objects to the list of removed objects.
void	clear() Removes all of the elements from this list.
TrackedArrayList<E>	clone() Clones the list.
List<E>	getRemovedObjects() Gets the removed objects in the order of their removal.
boolean	isModified() Gets the modification state, i.e.
boolean	isObjectAdded() Gets the added state.
boolean	isObjectRemoved() Gets the removal state.
E	remove(int index) Removes the element at the specified position in this list.
boolean	remove(Object obj) Removes the first occurrence of the specified element from this list, if it is present.
boolean	removeAll(Collection<?> c) Removes all objects that are contained in the given collection.
protected void	removeRange(int fromIndex, int toIndex) Removes from this list all of the elements whose index is between fromIndex, inclusive, and toIndex, exclusive.
boolean	retainAll(Collection<?> c) Removes all objects that are not contained in the given collection.
E	set(int index, E element) Replaces the element at the specified position in this list with the specified element.
void	setModified(boolean modified) Sets the modified state.

Methods inherited from class java.util.ArrayList

contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, size, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

containsAll, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.List

containsAll, equals, hashCode, iterator, listIterator, listIterator, subList

Constructor Detail

TrackedArrayList

public TrackedArrayList(int initialCapacity,
                        boolean modified)

Creates a tracked ArrayList.

Parameters:

initialCapacity - is the initial size of the list

modified - is true if list is marked modified initially

TrackedArrayList

public TrackedArrayList(boolean modified)

Creates a tracked ArrayList.

Parameters:

modified - is true if list is marked modified initially

TrackedArrayList

public TrackedArrayList()

Creates a tracked ArrayList. Notice that the list is initially marked 'modified'! Thus replacing a list with an empty one will still treated as a modification.

TrackedArrayList

public TrackedArrayList(Collection<E> collection)

Creates a list from a collection. The list is NOT marked modified.

Parameters:

collection - the collection

Method Detail

clone

public TrackedArrayList<E> clone()

Clones the list. A cloned list is always not modified and does not contain any removed objects.

Overrides:

clone in class ArrayList<E>

Returns:

a clone of this ArrayList instance

See Also:

Cloneable

setModified

public void setModified(boolean modified)

Sets the modified state.

Parameters:

modified - is true to set modified to true, false to clear all 4 flags including the list of removed Objects.

isModified

public boolean isModified()

Gets the modification state, i.e. whether objects have been added, removed or replaced or setModified(true) was invoked.

Returns:

true if modified.

isObjectRemoved

public boolean isObjectRemoved()

Gets the removal state.

Returns:

true if objects have been removed.

isObjectAdded

public boolean isObjectAdded()

Gets the added state.

Returns:

true if objects have been added.

getRemovedObjects

public List<E> getRemovedObjects()

Gets the removed objects in the order of their removal.

Returns:

the list of removed objects, null if no object has been removed so far.

addRemovedObject

protected void addRemovedObject(E object)

Adds an object to the list of removed objects. Only objects of type are added. The method is invoked whenever an object is removed from the list.

Parameters:

object - the object to be added.

addRemovedObjects

protected void addRemovedObjects(Collection<E> objects)

Adds a list of objects to the list of removed objects. Only objects of type are added. The method is invoked whenever an object is removed from the list.

Parameters:

objects - the list of objects

add

public boolean add(E o)

Appends the specified element to the end of this list.

Specified by:

add in interface Collection<E>

Specified by:

add in interface List<E>

Overrides:

add in class ArrayList<E>

Parameters:

o - element to be appended to this list

Returns:

true (as specified by Collection.add(E))

add

public void add(int index,
                E element)

Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:

add in interface List<E>

Overrides:

add in class ArrayList<E>

Parameters:

index - index at which the specified element is to be inserted

element - element to be inserted

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())

addAll

public boolean addAll(Collection<? extends E> c)

Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this list, and this list is nonempty.)

Specified by:

addAll in interface Collection<E>

Specified by:

addAll in interface List<E>

Overrides:

addAll in class ArrayList<E>

Parameters:

c - collection containing elements to be added to this list

Returns:

true if this list changed as a result of the call

Throws:

NullPointerException - if the specified collection is null

See Also:

AbstractCollection.add(Object)

addAll

public boolean addAll(int index,
                      Collection<? extends E> c)

Inserts all of the elements in the specified collection into this list, starting at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in the list in the order that they are returned by the specified collection's iterator.

Specified by:

addAll in interface List<E>

Overrides:

addAll in class ArrayList<E>

Parameters:

index - index at which to insert the first element from the specified collection

c - collection containing elements to be added to this list

Returns:

true if this list changed as a result of the call

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())

NullPointerException - if the specified collection is null

clear

public void clear()

Removes all of the elements from this list. The list will be empty after this call returns. All objects in the list will be added to the list of removed objects.

Specified by:

clear in interface Collection<E>

Specified by:

clear in interface List<E>

Overrides:

clear in class ArrayList<E>

remove

public E remove(int index)

Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their indices). The removed object will be added to the list of removed objects.

Specified by:

remove in interface List<E>

Overrides:

remove in class ArrayList<E>

Parameters:

index - the index of the element to be removed

Returns:

the element that was removed from the list

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())

remove

public boolean remove(Object obj)

Removes the first occurrence of the specified element from this list, if it is present. If the list does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))) (if such an element exists). Returns true if this list contained the specified element (or equivalently, if this list changed as a result of the call). The removed object will be added to the list of removed objects.

Specified by:

remove in interface Collection<E>

Specified by:

remove in interface List<E>

Overrides:

remove in class ArrayList<E>

Parameters:

obj - element to be removed from this list, if present

Returns:

true if this list contained the specified element

removeAll

public boolean removeAll(Collection<?> c)

Removes all objects that are contained in the given collection. All removed object will be added to the list of removed objects.

Specified by:

removeAll in interface Collection<E>

Specified by:

removeAll in interface List<E>

Overrides:

removeAll in class AbstractCollection<E>

Parameters:

c - the collection containing the objects to be removed from this list.

Returns:

true if at least one object has been removed.

See Also:

AbstractCollection.remove(Object), AbstractCollection.contains(Object)

retainAll

public boolean retainAll(Collection<?> c)

Removes all objects that are not contained in the given collection. All removed object will be added to the list of removed objects.

Specified by:

retainAll in interface Collection<E>

Specified by:

retainAll in interface List<E>

Overrides:

retainAll in class AbstractCollection<E>

Parameters:

c - the collection containing the objects not to be removed from this list.

Returns:

true if at least one object has been removed.

See Also:

AbstractCollection.remove(Object), AbstractCollection.contains(Object)

removeRange

protected void removeRange(int fromIndex,
                           int toIndex)

Removes from this list all of the elements whose index is between fromIndex, inclusive, and toIndex, exclusive. Shifts any succeeding elements to the left (reduces their index). This call shortens the list by (toIndex - fromIndex) elements. (If toIndex==fromIndex, this operation has no effect.) All removed object will be added to the list of removed objects.

Overrides:

removeRange in class ArrayList<E>

Parameters:

fromIndex - index of first element to be removed

toIndex - index after last element to be removed

Throws:

IndexOutOfBoundsException - if fromIndex or toIndex out of range (fromIndex < 0 || fromIndex >= size() || toIndex > size() || toIndex < fromIndex)

set

public E set(int index,
             E element)

Replaces the element at the specified position in this list with the specified element. The old element will be added to the list of removed objects. Thus, replacing an element will result in isAdded() and isRemoved() to return true.

Specified by:

set in interface List<E>

Overrides:

set in class ArrayList<E>

Parameters:

index - index of the element to replace

element - element to be stored at the specified position

Returns:

the element previously at the specified position

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())