sos.dated.util
Class AbstractDatedList<E,D>

java.lang.Object
  sos.dated.util.AbstractDatedObject<D>
      sos.dated.util.AbstractDatedCollection<E,D>
          sos.dated.util.AbstractDatedList<E,D>

Type Parameters:

E - the type of elements maintained by this dated list

D - the type of dates used by this dated list

All Implemented Interfaces:

DatedCollection<E,D>, DatedList<E,D>, DatedObject<D>

Direct Known Subclasses:

AbstractSequentialDatedList, ArrayListByDate, ArrayListByElement

public abstract class AbstractDatedList<E,D>
extends AbstractDatedCollection<E,D>
implements DatedList<E,D>

A partial implementation of a dated list. The purpose of this class is to make it easier to create a concrete DatedList and to share implementation common across concrete classes. It provides an implementation of iterator. To create an unmodifiable dated list, the programmer can subclass this class and implement the dateIterator, get, and size methods. To create a modifiable version, the programmer must also override the set, add, and remove methods.

Since:

1.0

See Also:

AbstractDatedCollection, DatedList, ArrayListByDate, ArrayListByElement

Constructor Summary

protected

AbstractDatedList() No-argument constructor available only to subclasses.

Method Summary

Dates<D>	add(E value, D from, D to) Adds the specified element to this dated collection for the specified date range (optional operation).
void	add(int index, E value, D from, D to) Inserts an element into this dated list for a specified date range (optional operation).
Dates<D>	addAll(int index, DatedCollection<? extends E,D> datedCollection) Inserts an entire dated collection into this dated list at the specified index (optional operation).
protected void	checkForComodification(int expectedModCount, D at) Throws a ConcurrentModificationException if the expected modification count does not equal the actual modification count for the specified date.
void	clear(D from, D to) Removes all elements from this dated collection for the specified dates (optional operation).
protected java.lang.Object	clone() Creates and returns a shallow copy of this object.
boolean	equals(D at, DatedObject<D> obj, D objAt) Indicates if this dated object at at is equal to obj at objAt.
abstract E	get(int index, D at) Retrieves the element at the specified position on the specified date.
int	hashCode(D at) Returns a hash code value of this dated object at the specified date.
int	indexOf(java.lang.Object value, D at) Returns the position of the first occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date.
Iterator<E,D>	iterator(D at) Returns an iterator over the elements of this dated collection at the specified date.
int	lastIndexOf(java.lang.Object value, D at) Returns the position of the last occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date.
ListIterator<E,D>	listIterator(D at) Returns a list iterator over the elements of this dated list at the specified date.
ListIterator<E,D>	listIterator(int index, D at) Returns a list iterator over the elements of this dated list at the specified date, starting at the specified index.
protected int	modCount(D at) Returns the modification count at the specified date.
DatedValue<E,D>	remove(int index, D from, D to) Removes from this dated list the element at the specified position for the specified date range (optional operation).
protected void	removeRange(int fromIndex, int toIndex, D from, D to) Removes all elements between fromIndex, inclusive, and toIndex, exclusive, for the specified date range.
DatedValue<E,D>	set(int index, E value, D from, D to) Replaces the element at the specified position with the specified element for the specified date range.
abstract int	size(D at) Returns the number of elements in this dated collection at the specified date.
DatedList<E,D>	subList(int fromIndex, int toIndex) Returns a view of this dated list restricted to the range fromIndex, inclusive, to toIndex, exclusive.
protected void	upModCount(D from, D to) Increments the modification count for the specified date range.

Methods inherited from class sos.dated.util.AbstractDatedCollection

addAll, contains, containsAll, containsThroughout, dateIterator, excludesThroughout, hasSizeThroughout, isEmpty, isEmptyThroughout, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class sos.dated.util.AbstractDatedObject

dateIterator, equals, hashCode, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface sos.dated.util.DatedCollection

addAll, contains, containsAll, containsThroughout, excludesThroughout, hasSizeThroughout, isEmpty, isEmptyThroughout, remove, removeAll, retainAll, toArray, toArray

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, dateIterator, equals, hashCode, toString

Constructor Detail

AbstractDatedList

protected AbstractDatedList()

No-argument constructor available only to subclasses.

Method Detail

add

public Dates<D> add(E value,
                    D from,
                    D to)

Adds the specified element to this dated collection for the specified date range (optional operation).

The returned value indicates when this dated collection changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this dated collection.

This implementation throws an UnsupportedOperationException.

This implementation invokes add(int,Object,D,D) for each static window within the specified range, passing it the size of this list at the start of the window as given by size.

Specified by:

add in interface DatedCollection<E,D>

Overrides:

add in class AbstractDatedCollection<E,D>

Parameters:

value - element to add

from - starting date (inclusive) at which the element should be added

to - ending date (exclusive) at which the element should be added

Returns:

a series of date ranges indicating when the addition changed this dated collection

Throws:

java.lang.ClassCastException - if the underlying type of value prevents it from being added to this dated collection

java.lang.IllegalArgumentException - if from does not precede to or if some property of value prevents it from being added to this dated collection

java.lang.NullPointerException - if from or to is null or if value is null and this dated collection cannot hold null elements

java.lang.UnsupportedOperationException - always

add

public void add(int index,
                E value,
                D from,
                D to)

Inserts an element into this dated list for a specified date range (optional operation). This implementation throws an UnsupportedOperationException.

Specified by:

add in interface DatedList<E,D>

Parameters:

index - position to insert the element

value - element to insert

from - starting date (inclusive) at which the element should be inserted

to - ending date (exclusive) at which the element should be inserted

Throws:

java.lang.UnsupportedOperationException - always

addAll

public Dates<D> addAll(int index,
                       DatedCollection<? extends E,D> datedCollection)

Inserts an entire dated collection into this dated list at the specified index (optional operation).

Specified by:

addAll in interface DatedList<E,D>

Parameters:

index - index at which to insert the dated collection

datedCollection - collection to insert into this dated list

Returns:

a series of date ranges for which this list changed

Throws:

java.lang.ClassCastException - if the type of an element of datedCollection prevents it from being added to this dated list

java.lang.IllegalArgumentException - if some property of an element of datedCollection prevents it from being added to this dated list

java.lang.IndexOutOfBoundsException - if index < 0 || index > size( d ) where d is a date when elements exist in datedCollection

java.lang.NullPointerException - if datedCollection is null or if an element of datedCollection is null and this dated list cannot hold null elements

java.lang.UnsupportedOperationException - if this implementation does not support add

checkForComodification

protected void checkForComodification(int expectedModCount,
                                      D at)

Throws a ConcurrentModificationException if the expected modification count does not equal the actual modification count for the specified date.

Parameters:

expectedModCount - the caller's expected modification count

at - the date in question

Throws:

java.util.ConcurrentModificationException - if the expected modification count does not equal the actual modification count for the specified date

clear

public void clear(D from,
                  D to)

Removes all elements from this dated collection for the specified dates (optional operation).

This implementation repeatedly invokes remove on the iterator, while iterating through the elements at each date within the specified range. This implementation invokes removeRange for each static window within the specified date range, passing in the size of the list at the start of the window, as gotten from a call to size.

Specified by:

clear in interface DatedCollection<E,D>

Overrides:

clear in class AbstractDatedCollection<E,D>

Parameters:

from - starting date (inclusive) at which this dated collection should be cleared

to - ending date (exclusive) at which this dated collection should be cleared

Throws:

java.lang.IllegalArgumentException - if from does not precede to

java.lang.NullPointerException - if if from or to is null

java.lang.UnsupportedOperationException - if the list iterator throws this exception on removal

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Creates and returns a shallow copy of this object. Subclasses that wish to be cloneable should override this method but first call their parent's clone method.

Overrides:

clone in class java.lang.Object

Returns:

a copy of this dated list

Throws:

java.lang.CloneNotSupportedException - if this object's class does not support the Cloneable interface.

equals

public boolean equals(D at,
                      DatedObject<D> obj,
                      D objAt)

Description copied from class: AbstractDatedObject

Indicates if this dated object at at is equal to obj at objAt. This implementation uses object identity to determine equality. In other words, it returns true if

   this == obj && date.equals( objDate )

Subclasses should override this method to impose a weaker equality condition.

Specified by:

equals in interface DatedList<E,D>

Specified by:

equals in interface DatedObject<D>

Overrides:

equals in class AbstractDatedObject<D>

Parameters:

at - date at which this object should be tested

obj - the other dated object to be compared to

objAt - the date of the other dated object

Returns:

true if this dated object at at equals another dated object at objAt

Throws:

java.lang.NullPointerException - if any argument is null

get

public abstract E get(int index,
                      D at)

Description copied from interface: DatedList

Retrieves the element at the specified position on the specified date.

Specified by:

get in interface DatedList<E,D>

Parameters:

index - position to retrieve an element

at - date at which this dated list is to be queried

Returns:

the element at the specified position on the specified date

hashCode

public int hashCode(D at)

Returns a hash code value of this dated object at the specified date. For two dated objects o1 and o2 and two dates d1 and d2, if o1.equals( d1, o2, d2 ) returns true, then o1.hashCode( d1 ) must equal o2.hashCode( d2 ). This implementation returns the identity hash code value of this dated object.

This implementation iterates through the elements of this dated list at the specified date, computing the hash code value as required.

Specified by:

hashCode in interface DatedList<E,D>

Specified by:

hashCode in interface DatedObject<D>

Overrides:

hashCode in class AbstractDatedObject<D>

Parameters:

at - date to which the hash code value should correspond

Returns:

the hash code value of this dated object at the specified date

Throws:

java.lang.NullPointerException - if at is null

indexOf

public int indexOf(java.lang.Object value,
                   D at)

Returns the position of the first occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date. After getting a list iterator at the specified date, this implementation traverses the list, stopping at the first occurrence of the specified value.

Specified by:

indexOf in interface DatedList<E,D>

Parameters:

value - element whose presence is to be tested

at - date to search for the element

Returns:

the position of the first occurrence of the specified element in this dated list at the specified date, or -1 if not present.

Throws:

java.lang.NullPointerException - if at is null

iterator

public Iterator<E,D> iterator(D at)

Returns an iterator over the elements of this dated collection at the specified date. The returned iterator will always throw an UnsupportedOperationException in its remove method because a date range is required to remove an element from this dated collection.

This implementation returns listIterator( at ).

Specified by:

iterator in interface DatedCollection<E,D>

Specified by:

iterator in class AbstractDatedCollection<E,D>

Parameters:

at - date at which to iterate through the elements

Returns:

an iterator over the elements of this dated collection at the specified date.

Throws:

java.lang.NullPointerException - if at is null

lastIndexOf

public int lastIndexOf(java.lang.Object value,
                       D at)

Returns the position of the last occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date. After getting a list iterator at the specified date and positioned after the last element, this implementation traverses the list in reverse, stopping at the first occurrence of the specified value.

Specified by:

lastIndexOf in interface DatedList<E,D>

Parameters:

value - element whose presence is to be tested

at - date to search for the element

Returns:

the position of the last occurrence of the specified element in this dated list at the specified date, or -1 if not present.

Throws:

java.lang.NullPointerException - if at is null

listIterator

public ListIterator<E,D> listIterator(D at)

Returns a list iterator over the elements of this dated list at the specified date. This implementation returns listIterator( 0, at ).

Specified by:

listIterator in interface DatedList<E,D>

Parameters:

at - date at which to iterate over the elements of this dated list

Returns:

a list iterator at the specified date

Throws:

java.lang.NullPointerException - if at is null

listIterator

public ListIterator<E,D> listIterator(int index,
                                      D at)

Returns a list iterator over the elements of this dated list at the specified date, starting at the specified index. This implementation creates a fully functional list iterator, positioned at the element given by index and date. The list iterator's update operations call this dated list's add(int,Object,Date,Date), remove(int,Date,Date), and set(int,Object,Date,Date).

Specified by:

listIterator in interface DatedList<E,D>

Parameters:

index - position at which to start the iteration

at - date at which to iterate over the elements of this dated list

Returns:

a list iterator at the specified date with the specified index as its starting position

Throws:

java.lang.IndexOutOfBoundsException - if index < 0 || index >= size( at )

java.lang.NullPointerException - if at is null

modCount

protected int modCount(D at)

Returns the modification count at the specified date. The return value should be used to detect concurrent modifications and other programming errors. The value is only meaningful if assertions are turned on. If assertions are enabled for this class, the returned value is the number of times upModCount has been called with a date range that includes at. If assertions are not enabled, the returned value is always zero.

Parameters:

at - date to request the modification count

Returns:

the modification count at the specified date

remove

public DatedValue<E,D> remove(int index,
                              D from,
                              D to)

Removes from this dated list the element at the specified position for the specified date range (optional operation). This implementation throws an UnsupportedOperationException.

Specified by:

remove in interface DatedList<E,D>

Parameters:

index - position at which to start the iteration

from - starting date (inclusive) at which the element should be removed

to - ending date (exclusive) at which the element should be removed

Returns:

the elements previously at the specified index from this list for the specified date range.

Throws:

java.lang.UnsupportedOperationException - always

removeRange

protected void removeRange(int fromIndex,
                           int toIndex,
                           D from,
                           D to)

Removes all elements between fromIndex, inclusive, and toIndex, exclusive, for the specified date range. The dated list is constant in the date range. This implementaion gets a list iterator at from, starting at fromIndex. It then iterates through the elements up to toIndex, invoking remove(from,to). Subclasses may override this method to make it more efficient for the particular implementation.

Parameters:

fromIndex - start index of elements to remove

toIndex - end index of elements to remove

from - start date (inclusive) for which the elements should be removed

to - end date (exclusive) for which the elements should be removed

set

public DatedValue<E,D> set(int index,
                           E value,
                           D from,
                           D to)

Replaces the element at the specified position with the specified element for the specified date range. This implementation throws an UnsupportedOperationException.

Specified by:

set in interface DatedList<E,D>

Parameters:

index - position of the element to replace

value - element to place in this list

from - starting date (inclusive) at which the position should be set

to - ending date (exclusive) at which the position should be set

Throws:

java.lang.UnsupportedOperationException - always

size

public abstract int size(D at)

Description copied from class: AbstractDatedCollection

Returns the number of elements in this dated collection at the specified date.

This implementation iterates through the elements at the specified date, counting the elements as it goes.

A subclass that can determine the size of its collection more efficiently should override this method.

Specified by:

size in interface DatedCollection<E,D>

Overrides:

size in class AbstractDatedCollection<E,D>

Parameters:

at - date at which this dated collection is to be queried

Returns:

the number of elements on the specified date

See Also:

DatedCollection.hasSizeThroughout(int, D, D)

subList

public DatedList<E,D> subList(int fromIndex,
                              int toIndex)

Returns a view of this dated list restricted to the range fromIndex, inclusive, to toIndex, exclusive. Changes made to the returned sub-list are reflected in the master list, and vice versa.

For the date ranges where the interval [fromIndex,toIndex) is not present in this dated list, some sub-list operations will throw an IllegalArgumentException. For example, consider the following code, where d0, d1, etc. are consecutive dates:

  DatedList list = new ArrayListByDate();
  list.add( "A", d0, d2 );
  list.add( "B", d1, d2 );
  DatedList subList = list.subList( 1, 2 );

  subList.add( "C", d1, d2 ); // successful
  subList.add( "C", d0, d2 ); // fails because list does not have
                              // 2 elements at d0

  int size = subList.size( d0 );  // returns 0
  size = subList.size( d1 );      // returns 1

  subList.get( 0, d0 );           // fails
 

Therefore, it is only safe to use the sub-list during date ranges where the interval [fromIndex,toIndex) exists in this list.

This implementation returns a fully operational sublist. The sublist implements RandomAccess if this dated list implements RandomAccess.

Specified by:

subList in interface DatedList<E,D>

Parameters:

fromIndex - starting position of the returned view (inclusive)

toIndex - ending position of the returned view (exclusive)

Returns:

a fully modifiable view of this dated list restricted to the specified range

upModCount

protected void upModCount(D from,
                          D to)

Increments the modification count for the specified date range. The modification count keeps track of the number of times this dated list has been structurally modified, allowing iterators to check for concurrent modifications.

Parameters:

from - starting date (inclusive) for which to increment the count

to - ending date (exclusive) for which to increment the count