Side of Software
Dated Collections Library 2.0

sos.dated.util
Class DatedCollections

java.lang.Object
  extended by sos.dated.util.DatedCollections

public class DatedCollections
extends java.lang.Object

Views and algorithms that act on dated collections. This class is the equivalent to java.util.Collections that works on dated collections.

Specifically, it provides synchronized equivalents of the collections with the methods

It also provides read-only equivalents of the collections with the methods It also provides "checked" equivalents of the collections with the methods

Since:
1.0
See Also:
DatedCollection, DatedSet, DatedList, DatedMap, Adapters

Nested Class Summary
static interface DatedCollections.Action<D>
          Action to perform on a dated object at a period when it does not change.
 
Field Summary
static DatedList EMPTY_DATED_LIST
          An empty and immutable dated list.
static DatedMap EMPTY_DATED_MAP
          An empty and immutable dated map.
static DatedSet EMPTY_DATED_SET
          An empty and immutable dated set.
static Dates EMPTY_DATES
          An empty and immutable series of dates.
static DatedValue NULL_DATED_VALUE
          An immutable dated value with only null values.
 
Method Summary
static
<E,D> Dates<D>
addAll(DatedCollection<? super E,D> datedCollection, D from, D to, E... elements)
          Adds the specified elements to a dated collection for a given date range.
static
<D> void
applyAtDates(DatedObject<D> datedObject, D from, D to, DatedCollections.Action<D> action)
          Performs the specified destructive action on the specified dated object within the specified date range.
static
<E,D> int
binarySearch(DatedList<? extends java.lang.Comparable<? super E>,D> datedList, E key, D at)
          Searches for the specified key in the specified ordered list at the specified date, returning the index of the key or the index of where the key would be inserted times negative one minus one.
static
<E,D> int
binarySearch(DatedList<? extends E,D> datedList, E key, java.util.Comparator<? super E> comparator, D at)
          Searches for the specified key in the specified ordered list at the specified date, using the specified comparator, and returning the index of the key or the index of where the key would be inserted times negative one minus one.
static
<E,D> DatedCollection<E,D>
checkedDatedCollection(DatedCollection<E,D> datedCollection, java.lang.Class<E> type)
          Wraps a dated collection with one that requires elements to be of a given type.
static
<E,D> DatedList<E,D>
checkedDatedList(DatedList<E,D> datedList, java.lang.Class<E> type)
          Wraps a dated list with one that requires elements to be of a given type.
static
<K,V,D> DatedMap<K,V,D>
checkedDatedMap(DatedMap<K,V,D> datedMap, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
          Wraps a dated map with one that requires keys and values to be of a given type.
static
<E,D> DatedSet<E,D>
checkedDatedSet(DatedSet<E,D> datedSet, java.lang.Class<E> type)
          Wraps a dated set with one that requires elements to be of a given type.
static
<K,V,D> DatedSortedMap<K,V,D>
checkedDatedSortedMap(DatedSortedMap<K,V,D> datedSortedMap, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
          Wraps a dated sorted map with one that requires keys and values to be of a given type.
static
<E,D> DatedSortedSet<E,D>
checkedDatedSortedSet(DatedSortedSet<E,D> datedSortedSet, java.lang.Class<E> type)
          Wraps a dated sorted set with one that requires elements to be of a given type.
static
<E,D> DatedValue<E,D>
checkedDatedValue(DatedValue<E,D> datedValue, java.lang.Class<E> type)
          Wraps a dated value with one that requires values to be of a given type.
static
<E,D> void
copy(DatedList<? super E,D> datedList, java.util.List<? extends E> src, D from, D to)
          Copies the elements of src into datedList for the specified date range.
static
<D> boolean
disjoint(DatedCollection<?,D> datedCollection1, DatedCollection<?,D> datedCollection2, D at)
          Returns true if the two specified dated collections have no elements in common at the given date.
static
<E,D> DatedList<E,D>
emptyDatedList()
          Returns the empty dated list in a type-safe fashion.
static
<K,V,D> DatedMap<K,V,D>
emptyDatedMap()
          Returns the empty dated map in a type-safe fashion.
static
<E,D> DatedSet<E,D>
emptyDatedSet()
          Returns the empty dated set in a type-safe fashion.
static
<D> Dates<D>
emptyDates()
          Returns the empty dates in a type-safe fashion.
static
<E,D> void
fill(DatedList<? super E,D> datedList, E obj, D from, D to)
          Replaces all elements of the specified dated list with the specified object for the specified date range.
static
<D> int
frequency(DatedCollection<?,D> datedCollection, java.lang.Object object, D at)
          Returns the number of occurrences of an object in the specified dated collection at a given date.
static
<D> int
indexOfSubList(DatedList<?,D> datedList, java.util.List<?> target, D at)
          Returns the index of the first occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.
static
<D> int
lastIndexOfSubList(DatedList<?,D> datedList, java.util.List<?> target, D at)
          Returns the index of the last occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.
static
<E,D> E
max(DatedCollection<E,D> datedCollection, java.util.Comparator<? super E> comparator, D at)
          Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator.
static
<E,D> E
max(DatedCollection<E,D> datedCollection, D at)
          Returns the maximum value (according to the natural ordering) in the specified dated collection at the specified date.
static
<E,D> E
min(DatedCollection<E,D> datedCollection, java.util.Comparator<? super E> comparator, D at)
          Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator.
static
<E,D> E
min(DatedCollection<E,D> datedCollection, D at)
          Returns the minimum value (according to the natural ordering) in the specified dated collection at the specified date.
static
<E,D> DatedList<E,D>
nCopies(int n, E o, D from, D to)
          Returns an unmodifiable dated list containing exactly n copies of the specified object during the specified date range.
static
<E,D> DatedValue<E,D>
nullDatedValue()
          Returns the null dated value in a type-safe fashion.
static
<D> void
queryAtDates(DatedObject<D> datedObject, D from, D to, DatedCollections.Action<D> action)
          Performs the specified non-destructive action on the specified dated object within the specified date range.
static
<E,D> Dates<D>
replaceAll(DatedList<E,D> datedList, E oldVal, E newVal, D from, D to)
          Replaces all occurrences of oldVal with newVal in the specified list throughout the specified date range.
static
<E,D> void
reverse(DatedList<E,D> datedList, D from, D to)
          Reverses the elements of the specified dated list in the specified date range.
static
<E,D> void
rotate(DatedList<E,D> datedList, int distance, D from, D to)
          Shifts the elements of the specified dated list in the specified date range the specified distance.
static
<E,D> void
shuffle(DatedList<E,D> datedList, D from, D to)
          Randomly rearranges the elements of the specified dated list in the specified date range The routine uses an internal random number generator.
static
<E,D> void
shuffle(DatedList<E,D> datedList, java.util.Random rnd, D from, D to)
          Randomly rearranges the elements of the specified dated list in the specified date range, using the specified random number generator.
static
<E,D> DatedList<E,D>
singletonDatedList(E o, D from, D to)
          Returns an unmodifiable dated list containing only the specified object during the specified date range.
static
<K,V,D> DatedMap<K,V,D>
singletonDatedMap(K key, V value, D from, D to)
          Returns an unmodifiable dated map containing only the mapping of key to value during the specified date range.
static
<E,D> DatedSet<E,D>
singletonDatedSet(E o, D from, D to)
          Returns an unmodifiable dated set containing only the specified object during the specified date range.
static
<E,D> void
sort(DatedList<E,D> datedList, java.util.Comparator<? super E> comparator, D from, D to)
          Sorts the elements of the specified dated list in the specified date range in ascending order, using the specified comparator.
static
<E,D> void
sort(DatedList<E,D> datedList, D from, D to)
          Sorts the elements of the specified dated list in the specified date range in ascending order.
static
<D> void
swap(DatedList<?,D> datedList, int i, int j, D from, D to)
          Exchanges the elements at indices i and j in the specified list at the specified date.
static
<E,D> DatedCollection<E,D>
synchronizedDatedCollection(DatedCollection<E,D> datedCollection)
          Returns a synchronized, or thread-safe, view of a dated collection.
static
<E,D> DatedList<E,D>
synchronizedDatedList(DatedList<E,D> datedList)
          Returns a synchronized, or thread-safe, view of a dated list.
static
<K,V,D> DatedMap<K,V,D>
synchronizedDatedMap(DatedMap<K,V,D> datedMap)
          Returns a synchronized, or thread-safe, view of a dated map.
static
<D> DatedObject<D>
synchronizedDatedObject(DatedObject<D> datedObject)
          Returns a synchronized, or thread-safe, view of a dated object.
static
<E,D> DatedSet<E,D>
synchronizedDatedSet(DatedSet<E,D> datedSet)
          Returns a synchronized, or thread-safe, view of a dated set.
static
<K,V,D> DatedSortedMap<K,V,D>
synchronizedDatedSortedMap(DatedSortedMap<K,V,D> datedSortedMap)
          Returns a synchronized, or thread-safe, view of a dated sorted map.
static
<E,D> DatedSortedSet<E,D>
synchronizedDatedSortedSet(DatedSortedSet<E,D> datedSortedSet)
          Returns a synchronized, or thread-safe, view of a dated sorted set.
static
<E,D> DatedValue<E,D>
synchronizedDatedValue(DatedValue<E,D> datedValue)
          Returns a synchronized, or thread-safe, view of a dated value.
static
<D> Dates<D>
synchronizedDates(Dates<D> dates)
          Returns a synchronized, or thread-safe, view of a series of date ranges.
static
<E,D> DatedCollection<E,D>
unmodifiableDatedCollection(DatedCollection<? extends E,D> datedCollection)
          Returns an unmodifiable view of a dated collection.
static
<E,D> DatedList<E,D>
unmodifiableDatedList(DatedList<? extends E,D> datedList)
          Returns an unmodifiable view of a dated list.
static
<K,V,D> DatedMap<K,V,D>
unmodifiableDatedMap(DatedMap<? extends K,? extends V,D> datedMap)
          Returns an unmodifiable view of a dated map.
static
<E,D> DatedSet<E,D>
unmodifiableDatedSet(DatedSet<? extends E,D> datedSet)
          Returns an unmodifiable view of a dated set.
static
<K,V,D> DatedSortedMap<K,V,D>
unmodifiableDatedSortedMap(DatedSortedMap<K,? extends V,D> datedSortedMap)
          Returns an unmodifiable view of a dated sorted map.
static
<E,D> DatedSortedSet<E,D>
unmodifiableDatedSortedSet(DatedSortedSet<E,D> datedSortedSet)
          Returns an unmodifiable view of a dated sorted set.
static
<E,D> DatedValue<E,D>
unmodifiableDatedValue(DatedValue<? extends E,D> datedValue)
          Returns an unmodifiable view of a dated value.
static
<D> Dates<D>
unmodifiableDates(Dates<D> dates)
          Returns an unmodifiable view of a series of dates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_DATES

public static final Dates EMPTY_DATES
An empty and immutable series of dates. This Dates object is serializable and resolves to this same object when deserialized.


EMPTY_DATED_LIST

public static final DatedList EMPTY_DATED_LIST
An empty and immutable dated list. This dated list is serializable and resolves to this same object when deserialized.


EMPTY_DATED_SET

public static final DatedSet EMPTY_DATED_SET
An empty and immutable dated set. This dated set is serializable and resolves to this same object when deserialized.


EMPTY_DATED_MAP

public static final DatedMap EMPTY_DATED_MAP
An empty and immutable dated map. This dated map is serializable and resolves to this same object when deserialized.


NULL_DATED_VALUE

public static final DatedValue NULL_DATED_VALUE
An immutable dated value with only null values. This dated value is serializable and resolves to this same object when deserialized.

Method Detail

applyAtDates

public static <D> void applyAtDates(DatedObject<D> datedObject,
                                    D from,
                                    D to,
                                    DatedCollections.Action<D> action)
Performs the specified destructive action on the specified dated object within the specified date range. The method first determines all dates of changes between from and to in datedObject. Then it invokes the action's perform method for the discovered ranges. A change to the dated object during perform does not alter the iteration over dates in any way.

Parameters:
datedObject - target of action
from - start date of range (inclusive) to perform action
to - end date of range (exclusive) to perform action
action - destructive action to perform on datedObject between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if any argument is null
See Also:
queryAtDates(sos.dated.util.DatedObject, D, D, sos.dated.util.DatedCollections.Action)

queryAtDates

public static <D> void queryAtDates(DatedObject<D> datedObject,
                                    D from,
                                    D to,
                                    DatedCollections.Action<D> action)
Performs the specified non-destructive action on the specified dated object within the specified date range. The action must not modify the dated object in such a way that an iteration over the dates of changes fails.

Parameters:
datedObject - target of action
from - start date of range (inclusive) to perform action
to - end date of range (exclusive) to perform action
action - non-destructive action to perform on datedObject between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if any argument is null
See Also:
applyAtDates(sos.dated.util.DatedObject, D, D, sos.dated.util.DatedCollections.Action)

emptyDates

public static final <D> Dates<D> emptyDates()
Returns the empty dates in a type-safe fashion.

Returns:
the empty dates
Since:
2.0
See Also:
EMPTY_DATES

emptyDatedList

public static final <E,D> DatedList<E,D> emptyDatedList()
Returns the empty dated list in a type-safe fashion.

Returns:
the empty dated list
Since:
2.0
See Also:
EMPTY_DATED_LIST

emptyDatedMap

public static final <K,V,D> DatedMap<K,V,D> emptyDatedMap()
Returns the empty dated map in a type-safe fashion.

Returns:
the empty dated map
Since:
2.0
See Also:
EMPTY_DATED_MAP

emptyDatedSet

public static final <E,D> DatedSet<E,D> emptyDatedSet()
Returns the empty dated set in a type-safe fashion.

Returns:
the empty dated set
Since:
2.0
See Also:
EMPTY_DATED_SET

nullDatedValue

public static final <E,D> DatedValue<E,D> nullDatedValue()
Returns the null dated value in a type-safe fashion.

Returns:
the null dated value
Since:
2.0
See Also:
NULL_DATED_VALUE

unmodifiableDates

public static <D> Dates<D> unmodifiableDates(Dates<D> dates)
Returns an unmodifiable view of a series of dates. Any attempt to modify the returned dates results in a run-time exception.

In this implementation, the returned Dates object "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned Dates object is serializable only if the parameter is serializable.

Parameters:
dates - dates to treat as read-only
Returns:
an unmodifiable view of dates
Throws:
java.lang.NullPointerException - if dates is null

unmodifiableDatedValue

public static <E,D> DatedValue<E,D> unmodifiableDatedValue(DatedValue<? extends E,D> datedValue)
Returns an unmodifiable view of a dated value. Any attempt to modify the returned value results in a run-time exception.

In this implementation, the returned value "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated value is serializable only if the parameter is serializable.

Parameters:
datedValue - dated value to treat as read-only
Returns:
an unmodifiable view of datedValue
Throws:
java.lang.NullPointerException - if the specified dated value is null

unmodifiableDatedCollection

public static <E,D> DatedCollection<E,D> unmodifiableDatedCollection(DatedCollection<? extends E,D> datedCollection)
Returns an unmodifiable view of a dated collection. Any attempt to modify the returned collection results in a run-time exception.

In this implementation, the returned collection "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated collection is serializable only if the parameter is serializable.

Parameters:
datedCollection - dated collection to treat as read-only
Returns:
an unmodifiable view of datedCollection
Throws:
java.lang.NullPointerException - if the specified dated collection is null

unmodifiableDatedSet

public static <E,D> DatedSet<E,D> unmodifiableDatedSet(DatedSet<? extends E,D> datedSet)
Returns an unmodifiable view of a dated set. Any attempt to modify the returned set results in a run-time exception.

In this implementation, the returned set "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated set is serializable only if the parameter is serializable.

Parameters:
datedSet - dated set to treat as read-only
Returns:
an unmodifiable view of datedSet
Throws:
java.lang.NullPointerException - if the specified dated set is null

unmodifiableDatedList

public static <E,D> DatedList<E,D> unmodifiableDatedList(DatedList<? extends E,D> datedList)
Returns an unmodifiable view of a dated list. Any attempt to modify the returned list results in a run-time exception.

In this implementation, the returned list "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated list is serializable only if the parameter is serializable. Also, the returned dated list implements RandomAccess if the parameter implements RandomAccess.

Parameters:
datedList - dated list to treat as read-only
Returns:
an unmodifiable view of datedList
Throws:
java.lang.NullPointerException - if the specified dated list is null

unmodifiableDatedMap

public static <K,V,D> DatedMap<K,V,D> unmodifiableDatedMap(DatedMap<? extends K,? extends V,D> datedMap)
Returns an unmodifiable view of a dated map. Any attempt to modify the returned map results in a run-time exception.

In this implementation, the returned map "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated map is serializable only if the parameter is serializable.

Parameters:
datedMap - dated map to treat as read-only
Returns:
an unmodifiable view of datedMap
Throws:
java.lang.NullPointerException - if the specified dated map is null

unmodifiableDatedSortedMap

public static <K,V,D> DatedSortedMap<K,V,D> unmodifiableDatedSortedMap(DatedSortedMap<K,? extends V,D> datedSortedMap)
Returns an unmodifiable view of a dated sorted map. Any attempt to modify the returned sorted map results in a run-time exception.

In this implementation, the returned sorted map "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated sorted map is serializable only if the parameter is serializable.

Parameters:
datedSortedMap - dated sorted map to treat as read-only
Returns:
an unmodifiable view of datedSortedMap
Throws:
java.lang.NullPointerException - if the specified dated sorted map is null

unmodifiableDatedSortedSet

public static <E,D> DatedSortedSet<E,D> unmodifiableDatedSortedSet(DatedSortedSet<E,D> datedSortedSet)
Returns an unmodifiable view of a dated sorted set. Any attempt to modify the returned sorted set results in a run-time exception.

In this implementation, the returned sorted set "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated sorted set is serializable only if the parameter is serializable.

Parameters:
datedSortedSet - dated sorted set to treat as read-only
Returns:
an unmodifiable view of datedSortedSet
Throws:
java.lang.NullPointerException - if the specified dated sorted set is null

synchronizedDates

public static <D> Dates<D> synchronizedDates(Dates<D> dates)
Returns a synchronized, or thread-safe, view of a series of date ranges. The returned Dates object synchronizes on itself at each method invocation and then passes the operation on to the parameter. Note that this implementation is coarse grained in that it does not allow concurrent access to disjoint date ranges of the object.

The client must manually synchronize on the returned Dates object in order to iterate over the ranges safely, as follows:

   Dates dates = ...
   Dateds syncDates = DatedCollections.synchronizedDates( dates );
   synchronized( syncDates ) {
     DateIterator dateIter = syncDates.dateIterator();
     while( dateIter.hasNext() ) {
       ...
     }
   }
 
The returned dated object is serializable only if the parameter is serializable.

Parameters:
dates - series of date ranges to be thread-safe
Returns:
a view of dates that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated object is null

synchronizedDatedObject

public static <D> DatedObject<D> synchronizedDatedObject(DatedObject<D> datedObject)
Returns a synchronized, or thread-safe, view of a dated object. The returned dated object synchronizes on itself at each method invocation and then passes the operation on to the parameter. Note that this implementation is coarse grained in that it does not allow concurrent access to disjoint date ranges of the object.

The client must manually synchronize on the returned dated object in order to iterate over the dates safely, as follows:

   DateObject obj = ...
   DatedObject syncObj = DatedCollections.synchronizedDatedObject( obj );
   synchronized( syncObj ) {
     DateIterator dateIter = syncObj.dateIterator();
     while( dateIter.hasNext() ) {
       ...
     }
   }
 
To satisfy the contracts of equals(Date,DatedObject,Date) and hashCode(int) in subtypes that strengthen these contracts, the returned dated object does not forward these calls to the parameter.

The returned dated object is serializable only if the parameter is serializable.

Parameters:
datedObject - dated object to be thread-safe
Returns:
a view of datedObject that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated ibject is null

synchronizedDatedValue

public static <E,D> DatedValue<E,D> synchronizedDatedValue(DatedValue<E,D> datedValue)
Returns a synchronized, or thread-safe, view of a dated value. The returned dated value synchronizes on itself at each method invocation and then passes the operation on to the parameter.

The returned dated value is serializable only if the parameter is serializable.

Parameters:
datedValue - dated value to be thread-safe
Returns:
a view of datedValue that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated value is null
See Also:
synchronizedDatedObject(DatedObject)

synchronizedDatedCollection

public static <E,D> DatedCollection<E,D> synchronizedDatedCollection(DatedCollection<E,D> datedCollection)
Returns a synchronized, or thread-safe, view of a dated collection. The returned dated collection synchronizes on itself at each method invocation and then passes the operation on to the parameter. The client must manually synchronize on the returned dated collection in order to iterate over the elements safely, as follows:
   Date someDate = ...
   DatedCollection coll = ...
   DatedCollection syncColl = DatedCollections.synchronizedDatedCollection( coll );
   synchronized( syncColl ) {
     Iterator iter = syncColl.iterator( someDate );
     while( iter.hasNext() ) {
       Object element = iter.next();
       ...
     }
   }
 
The returned dated collection is serializable only if the parameter is serializable.

Parameters:
datedCollection - dated collection to be thread-safe
Returns:
a view of datedCollection that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated collection is null
See Also:
synchronizedDatedObject(DatedObject)

synchronizedDatedSet

public static <E,D> DatedSet<E,D> synchronizedDatedSet(DatedSet<E,D> datedSet)
Returns a synchronized, or thread-safe, view of a dated set. The returned dated set synchronizes on itself at each method invocation and then passes the operation on to the parameter.

The returned dated set is serializable only if the parameter is serializable.

Parameters:
datedSet - dated set to be thread-safe
Returns:
a view of datedSet that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated set is null
See Also:
synchronizedDatedCollection(DatedCollection)

synchronizedDatedList

public static <E,D> DatedList<E,D> synchronizedDatedList(DatedList<E,D> datedList)
Returns a synchronized, or thread-safe, view of a dated list. The returned dated list synchronizes on itself at each method invocation and then passes the operation on to the parameter.

The returned dated set is serializable only if the parameter is serializable. Also, the returned dated list implements RandomAccess if the parameter implements RandomAccess.

Parameters:
datedList - dated list to be thread-safe
Returns:
a view of datedList that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated list is null
See Also:
synchronizedDatedCollection(DatedCollection)

synchronizedDatedMap

public static <K,V,D> DatedMap<K,V,D> synchronizedDatedMap(DatedMap<K,V,D> datedMap)
Returns a synchronized, or thread-safe, view of a dated map. The returned dated map synchronizes on itself at each method invocation and then passes the operation on to the parameter. The client must manually synchronize on the returned dated map in order to iterate over the mappings safely, as follows:
   Date someDate = ...
   DatedMap map = ...
   DatedMap syncMap = DatedCollections.synchronizedDatedMap( map );
   DatedSet entrySet = syncMap.entrySet();
   synchronized( syncMap ) {
     Iterator iter = entrySet.iterator( someDate );
     while( iter.hasNext() ) {
       DatedMap.Entry entry = (DatedMap.Entry)iter.next();
       ...
     }
   }
 
The returned dated map is serializable only if the parameter is serializable.

Parameters:
datedMap - dated map to be thread-safe
Returns:
a view of datedMap that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated map is null
See Also:
synchronizedDatedObject(DatedObject)

synchronizedDatedSortedMap

public static <K,V,D> DatedSortedMap<K,V,D> synchronizedDatedSortedMap(DatedSortedMap<K,V,D> datedSortedMap)
Returns a synchronized, or thread-safe, view of a dated sorted map. The returned dated sorted map synchronizes on itself at each method invocation and then passes the operation on to the parameter. The map portions returned by headMap, subMap, and tailMap synchronize on the parent dated sorted map. Thus, before iterating over the mappings of these map portions, the client must manually synchronize on the full dated sorted map, as follows:
   Date someDate = ...
   DatedMap map = ...
   DatedMap syncMap = DatedCollections.synchronizedDatedMap( map );
   DatedMap headMap = syncMap.headMap( someKey );
   DatedSet entrySet = headMap.entrySet();
   synchronized( syncMap ) {
     Iterator iter = entrySet.iterator( someDate );
     while( iter.hasNext() ) {
       DatedMap.Entry entry = (DatedMap.Entry)iter.next();
       ...
     }
   }
 
The returned dated sorted map is serializable only if the parameter is serializable.

Parameters:
datedSortedMap - dated sorted map to be thread-safe
Returns:
a view of datedSortedMap that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated sorted map is null
See Also:
synchronizedDatedMap(DatedMap)

synchronizedDatedSortedSet

public static <E,D> DatedSortedSet<E,D> synchronizedDatedSortedSet(DatedSortedSet<E,D> datedSortedSet)
Returns a synchronized, or thread-safe, view of a dated sorted set. The returned dated sorted set synchronizes on itself at each method invocation and then passes the operation on to the parameter. The map portions returned by headSet, subSet, and tailSet synchronize on the parent dated sorted set. Thus, before iterating over the mappings of these set portions, the client must manually synchronize on the full dated sorted set, as follows:
   Date someDate = ...
   DatedSet set = ...
   DatedSet syncSet = DatedCollections.synchronizedDatedSet( set );
   DatedMap tailSet = syncSet.tailSet( someElement );
   synchronized( syncSet ) {
     Iterator iter = tailSet.iterator( someDate );
     while( iter.hasNext() ) {
       Object element = iter.next();
       ...
     }
   }
 
The returned dated sorted set is serializable only if the parameter is serializable.

Parameters:
datedSortedSet - dated sorted set to be thread-safe
Returns:
a view of datedSortedSet that multiple threads may safely access
Throws:
java.lang.NullPointerException - if the specified dated sorted set is null
See Also:
synchronizedDatedCollection(DatedCollection)

checkedDatedValue

public static <E,D> DatedValue<E,D> checkedDatedValue(DatedValue<E,D> datedValue,
                                                      java.lang.Class<E> type)
Wraps a dated value with one that requires values to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedValue - dated value to wrap
type - the type of values that the dated value is allowed to hold
Returns:
a dated value that throws ClassCastException when there is an attempt to set the dated value with an object that is not assignable to the class represented by type
Since:
2.0

checkedDatedCollection

public static <E,D> DatedCollection<E,D> checkedDatedCollection(DatedCollection<E,D> datedCollection,
                                                                java.lang.Class<E> type)
Wraps a dated collection with one that requires elements to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedCollection - dated collection to wrap
type - the type of elements that the dated collection is allowed to hold
Returns:
a dated collection that throws ClassCastException when there is an attempt to add an object that is not assignable to the class represented by type
Since:
2.0

checkedDatedSet

public static <E,D> DatedSet<E,D> checkedDatedSet(DatedSet<E,D> datedSet,
                                                  java.lang.Class<E> type)
Wraps a dated set with one that requires elements to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedSet - dated set to wrap
type - the type of elements that the dated set is allowed to hold
Returns:
a dated set that throws ClassCastException when there is an attempt to add an object that is not assignable to the class represented by type
Since:
2.0

checkedDatedList

public static <E,D> DatedList<E,D> checkedDatedList(DatedList<E,D> datedList,
                                                    java.lang.Class<E> type)
Wraps a dated list with one that requires elements to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedList - dated list to wrap
type - the type of elements that the dated list is allowed to hold
Returns:
a dated list that throws ClassCastException when there is an attempt to add an object that is not assignable to the class represented by type
Since:
2.0

checkedDatedMap

public static <K,V,D> DatedMap<K,V,D> checkedDatedMap(DatedMap<K,V,D> datedMap,
                                                      java.lang.Class<K> keyType,
                                                      java.lang.Class<V> valueType)
Wraps a dated map with one that requires keys and values to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedMap - dated map to wrap
keyType - the type of keys that the dated map is allowed to hold
valueType - the type of values that the dated map is allowed to hold
Returns:
a dated map that throws ClassCastException when there is an attempt to add a key that is not assignable to keyType or a value that is not assignable to valueType
Since:
2.0

checkedDatedSortedMap

public static <K,V,D> DatedSortedMap<K,V,D> checkedDatedSortedMap(DatedSortedMap<K,V,D> datedSortedMap,
                                                                  java.lang.Class<K> keyType,
                                                                  java.lang.Class<V> valueType)
Wraps a dated sorted map with one that requires keys and values to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedSortedMap - dated sorted map to wrap
keyType - the type of keys that the dated map is allowed to hold
valueType - the type of values that the dated map is allowed to hold
Returns:
a dated sorted map that throws ClassCastException when there is an attempt to add a key that is not assignable to keyType or a value that is not assignable to valueType
Since:
2.0

checkedDatedSortedSet

public static <E,D> DatedSortedSet<E,D> checkedDatedSortedSet(DatedSortedSet<E,D> datedSortedSet,
                                                              java.lang.Class<E> type)
Wraps a dated sorted set with one that requires elements to be of a given type.

The returned object is serializable only if the parameter is serializable.

Parameters:
datedSortedSet - dated sorted set to wrap
type - the type of elements that the dated sorted set is allowed to hold
Returns:
a dated sorted set that throws ClassCastException when there is an attempt to add an object that is not assignable to the class represented by type
Since:
2.0

sort

public static <E,D> void sort(DatedList<E,D> datedList,
                              D from,
                              D to)
Sorts the elements of the specified dated list in the specified date range in ascending order. The sorting algorithm uses the elements' natural ordering.

Parameters:
datedList - dated list to be sorted
from - start date of range (inclusive) to sort the list
to - end date of range (exclusive) to sort the list
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if any argument is null

sort

public static <E,D> void sort(DatedList<E,D> datedList,
                              java.util.Comparator<? super E> comparator,
                              D from,
                              D to)
Sorts the elements of the specified dated list in the specified date range in ascending order, using the specified comparator. A null comparator causes the sorting algorithm to use the elements' natural ordering.

Parameters:
datedList - dated list to be sorted
comparator - comparator used to determine ascending order (may be null)
from - start date of range (inclusive) to sort the list
to - end date of range (exclusive) to sort the list
Throws:
java.lang.NullPointerException - if datedList, from, or to is null
java.lang.IllegalArgumentException - if from does not precede to

shuffle

public static <E,D> void shuffle(DatedList<E,D> datedList,
                                 D from,
                                 D to)
Randomly rearranges the elements of the specified dated list in the specified date range The routine uses an internal random number generator.

Parameters:
datedList - dated list to be shuffled
from - start date of range (inclusive) to shuffle the list
to - end date of range (exclusive) to shuffle the list
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if any argument is null

shuffle

public static <E,D> void shuffle(DatedList<E,D> datedList,
                                 java.util.Random rnd,
                                 D from,
                                 D to)
Randomly rearranges the elements of the specified dated list in the specified date range, using the specified random number generator.

Parameters:
datedList - dated list to be sorted
rnd - random number generator used to determine the permutation
from - start date of range (inclusive) to sort the list
to - end date of range (exclusive) to sort the list
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if datedList, from, or to is null

rotate

public static <E,D> void rotate(DatedList<E,D> datedList,
                                int distance,
                                D from,
                                D to)
Shifts the elements of the specified dated list in the specified date range the specified distance. A positive distance shifts the elements up in index, while a negative distance shifts the elements down in index. If (the absolute value of) distance is greater than the size of the list at any date within the range, then elements "circle back" to the beginning of the list. A distance of zero has no effect on the list.

Parameters:
datedList - dated list to be rotated
distance - number of indices to shift the elements of the list
from - start date of range (inclusive) to rotate the list
to - end date of range (exclusive) to rotate the list
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if datedList, from, or to is null

reverse

public static <E,D> void reverse(DatedList<E,D> datedList,
                                 D from,
                                 D to)
Reverses the elements of the specified dated list in the specified date range.

Parameters:
datedList - dated list to be reversed
from - start date of range (inclusive) to reverse the list
to - end date of range (exclusive) to reverse the list
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if any argument is null

addAll

public static <E,D> Dates<D> addAll(DatedCollection<? super E,D> datedCollection,
                                    D from,
                                    D to,
                                    E... elements)
Adds the specified elements to a dated collection for a given date range.

Parameters:
datedCollection - dated collection for which to add the elements
from - start date (inclusive) for which to add the elements
to - end date (exclusive) for which to add the elements
elements - the objects to add
Returns:
the dates for which the dated collection changed as a result of adding the elements
Throws:
java.lang.ClassCastException - if the type of an element prevents it from being added to the dated collection
java.lang.IllegalArgumentException - if some property of an element prevents it from being added to the dated collection
java.lang.NullPointerException - if datedCollection is null or if an element is null and the dated collection cannot hold null elements
java.lang.UnsupportedOperationException - if the dated collection does not support addAll
Since:
2.0

disjoint

public static <D> boolean disjoint(DatedCollection<?,D> datedCollection1,
                                   DatedCollection<?,D> datedCollection2,
                                   D at)
Returns true if the two specified dated collections have no elements in common at the given date.

Parameters:
datedCollection1 - first collection
datedCollection2 - second collection
at - date at which to check if the dated collections are disjoint
Returns:
true if the two dated collections are disjoing at the specified date
Throws:
java.lang.NullPointerException - if any argument is null
Since:
2.0

frequency

public static <D> int frequency(DatedCollection<?,D> datedCollection,
                                java.lang.Object object,
                                D at)
Returns the number of occurrences of an object in the specified dated collection at a given date.

Parameters:
datedCollection - dated collection to be searched
object - element to count
at - date at which to retrieve the frequency
Returns:
the frequency of object in datedCollection at date at
Throws:
java.lang.NullPointerException - if datedCollection or at is null
Since:
2.0

max

public static <E,D> E max(DatedCollection<E,D> datedCollection,
                          D at)
Returns the maximum value (according to the natural ordering) in the specified dated collection at the specified date.

Parameters:
datedCollection - dated collection to be searched
at - date to search the collection
Returns:
the maximum element in datedCollection at date, according to their natural ordering
Throws:
java.util.NoSuchElementException - if the dated collection is empty at the specified date
java.lang.NullPointerException - if any argument is null
See Also:
max(DatedCollection,Comparator,Object), min(DatedCollection,Object)

max

public static <E,D> E max(DatedCollection<E,D> datedCollection,
                          java.util.Comparator<? super E> comparator,
                          D at)
Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator. A null comparator indicates that the method should use the elements' natural ordering.

Parameters:
datedCollection - dated collection to be searched
comparator - comparator used to order the elements (may be null)
at - date to search the collection
Returns:
the maximum element in datedCollection at date, according to the comparator
Throws:
java.util.NoSuchElementException - if the dated collection is empty at the specified date
java.lang.NullPointerException - if datedCollection or date is null
See Also:
max(DatedCollection,Object), min(DatedCollection,Comparator,Object)

min

public static <E,D> E min(DatedCollection<E,D> datedCollection,
                          D at)
Returns the minimum value (according to the natural ordering) in the specified dated collection at the specified date.

Parameters:
datedCollection - dated collection to be searched
at - date to search the collection
Returns:
the minimum element in datedCollection at date, according to their natural ordering
Throws:
java.util.NoSuchElementException - if the dated collection is empty at the specified date
java.lang.NullPointerException - if any argument is null
See Also:
min(DatedCollection,Comparator,Object), max(DatedCollection,Object)

min

public static <E,D> E min(DatedCollection<E,D> datedCollection,
                          java.util.Comparator<? super E> comparator,
                          D at)
Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator. A null comparator indicates that the method should use the elements' natural ordering.

Parameters:
datedCollection - dated collection to be searched
comparator - comparator used to order the elements (may be null)
at - date to search the collection
Returns:
the maximum element in datedCollection at date, according to the comparator
Throws:
java.util.NoSuchElementException - if the dated collection is empty at the specified date
java.lang.NullPointerException - if datedCollection or date is null
See Also:
min(DatedCollection,Object), max(DatedCollection,Comparator,Object)

binarySearch

public static <E,D> int binarySearch(DatedList<? extends java.lang.Comparable<? super E>,D> datedList,
                                     E key,
                                     D at)
Searches for the specified key in the specified ordered list at the specified date, returning the index of the key or the index of where the key would be inserted times negative one minus one.

Parameters:
datedList - dated list to be searched
key - element to look for in the list
at - date to search the list
Returns:
either i, where i is the index of the key in datedList at date, or -i-1, where i is the index of the key if it were in the list
Throws:
java.lang.NullPointerException - if datedList or date is null

binarySearch

public static <E,D> int binarySearch(DatedList<? extends E,D> datedList,
                                     E key,
                                     java.util.Comparator<? super E> comparator,
                                     D at)
Searches for the specified key in the specified ordered list at the specified date, using the specified comparator, and returning the index of the key or the index of where the key would be inserted times negative one minus one. A null comparator causes the method to use the elements' natural ordering.

Parameters:
datedList - dated list to be searched
key - element to look for in the list
comparator - comparator used to order the elements of the list (may be null)
at - date to search the list
Returns:
either i, where i is the index of the key in datedList at date, or -i-1, where i is the index of the key if it were in the list
Throws:
java.lang.NullPointerException - if datedList or date is null

swap

public static <D> void swap(DatedList<?,D> datedList,
                            int i,
                            int j,
                            D from,
                            D to)
Exchanges the elements at indices i and j in the specified list at the specified date.

Parameters:
datedList - dated list holding the elements to be swapped
i - index of an element to be swapped
j - index of the other element to be swapped
from - start date of range (inclusive) to perform the swap
to - end date of range (exclusive) to perform the swap
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.IndexOutOfBoundsException - if i > size(d) or j > size(d) for any d between from and to
java.lang.NullPointerException - if datedList, from, or to is null

replaceAll

public static <E,D> Dates<D> replaceAll(DatedList<E,D> datedList,
                                        E oldVal,
                                        E newVal,
                                        D from,
                                        D to)
Replaces all occurrences of oldVal with newVal in the specified list throughout the specified date range.

Parameters:
datedList - dated list holding the elements to replace
oldVal - element to replace
newVal - element to substitute for oldVal
from - start date of range (inclusive) to perform the substitution
to - end date of range (exclusive) to perform the substitution
Returns:
list of date ranges indicating when a substitution occurred
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if datedList, from, or to is null
java.lang.UnsupportedOperationException - if the dated list does not support the setting of elements

fill

public static <E,D> void fill(DatedList<? super E,D> datedList,
                              E obj,
                              D from,
                              D to)
Replaces all elements of the specified dated list with the specified object for the specified date range.

Parameters:
datedList - dated list to fill
obj - element to put in list
from - start date of range (inclusive) to fill the list
to - end date of range (exclusive) to fill the list
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if datedList, from, or to is null
java.lang.UnsupportedOperationException - if the dated list does not support the setting of elements

indexOfSubList

public static <D> int indexOfSubList(DatedList<?,D> datedList,
                                     java.util.List<?> target,
                                     D at)
Returns the index of the first occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.

Parameters:
datedList - dated list to search
target - list elements to search for
at - date to check for occurrence in the dated list
Returns:
the index of the first occurrence of target in datedList at date, or -1 if target never occurs
Throws:
java.lang.NullPointerException - if any argument is null

lastIndexOfSubList

public static <D> int lastIndexOfSubList(DatedList<?,D> datedList,
                                         java.util.List<?> target,
                                         D at)
Returns the index of the last occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.

Parameters:
datedList - dated list to search
target - list elements to search for
at - date to check for occurrence in the dated list
Returns:
the index of the last occurrence of target in datedList at date, or -1 if target never occurs
Throws:
java.lang.NullPointerException - if any argument is null

copy

public static <E,D> void copy(DatedList<? super E,D> datedList,
                              java.util.List<? extends E> src,
                              D from,
                              D to)
Copies the elements of src into datedList for the specified date range.

Parameters:
datedList - dated list to copy into
src - list of elements to copy
from - start date of range (inclusive) to copy into
to - end date of range (exclusive) to copy into
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.IndexOutOfBoundsException - if the destination dated list does not have enough cells to hold the elements of src at some time within the range
java.lang.NullPointerException - if any argument is null
java.lang.UnsupportedOperationException - if the destination dated list does not support the setting of elements

singletonDatedSet

public static <E,D> DatedSet<E,D> singletonDatedSet(E o,
                                                    D from,
                                                    D to)
Returns an unmodifiable dated set containing only the specified object during the specified date range.

Parameters:
o - object to include in the returned set
from - start date of range (inclusive) for the returned dated set to contain the object
to - end date of range (exclusive) for the returned dated set to contain the object
Returns:
an unmodifiable dated set containing only o between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

singletonDatedList

public static <E,D> DatedList<E,D> singletonDatedList(E o,
                                                      D from,
                                                      D to)
Returns an unmodifiable dated list containing only the specified object during the specified date range.

Parameters:
o - object to include in the returned list
from - start date of range (inclusive) for the returned dated list to contain the object
to - end date of range (exclusive) for the returned dated list to contain the object
Returns:
an unmodifiable dated list containing only o between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

singletonDatedMap

public static <K,V,D> DatedMap<K,V,D> singletonDatedMap(K key,
                                                        V value,
                                                        D from,
                                                        D to)
Returns an unmodifiable dated map containing only the mapping of key to value during the specified date range.

Parameters:
key - key to include in the returned map
value - value to be associated with key in the returned map
from - start date of range (inclusive) for the returned dated map to contain the object
to - end date of range (exclusive) for the returned dated map to contain the object
Returns:
an unmodifiable dated map containing only o between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

nCopies

public static <E,D> DatedList<E,D> nCopies(int n,
                                           E o,
                                           D from,
                                           D to)
Returns an unmodifiable dated list containing exactly n copies of the specified object during the specified date range.

Parameters:
n - number of copies of o to include in the returned list
o - object to include in the returned list
from - start date of range (inclusive) for the returned dated list to contain n copies of the object
to - end date of range (exclusive) for the returned dated list to contain n copies of the object
Returns:
an unmodifiable dated list containing exactly n copies of o between from and to
Throws:
java.lang.IllegalArgumentException - if from does not precede to or if n < 0
java.lang.NullPointerException - if from or to is null

Side of Software
Dated Collections Library 2.0

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