Side of Software
Dated Collections Library 2.0

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

java.lang.Object
  extended by sos.dated.util.AbstractDatedObject<D>
      extended by sos.dated.util.AbstractDatedCollection<E,D>
          extended by 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

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.