dk.rode.thesis.bridge
Class SequenceValueArrayList<E extends Serializable>

java.lang.Object
  dk.rode.thesis.bridge.SequenceValueCollection<E,ArrayList<E>>
      dk.rode.thesis.bridge.SequenceValueArrayList<E>

Type Parameters:

E - The type of serializable values stored in this value list.

All Implemented Interfaces:

SequenceValueGenerator<E>, Copyable<SequenceValueGenerator<E>>, Stringable<SequenceValueGenerator<E>>

@Participant(value="ConcreteImplementor")
public class SequenceValueArrayList<E extends Serializable>
extends SequenceValueCollection<E,ArrayList<E>>

A sequence value array list stores sequence values in a java.util.ArrayList instance.

A sequence value array list is ordered, can be sorted, and may or may not contain duplicates.

Implementation notes:
The get(int) method is fast as the ArrayList class offers random access via indexes. The numberOf(Serializable, int) method uses a binary search on the sub-list of length m identified by the supplied index if the list is sorted. Hence, the running time is O(log(m)), where m <= n and n is the number of values in the entire value list. If all the elements are identical or not sorted, the worst-case running time is proportional to the number of elements in the value list, i.e. O(n).

Author:

Gunni Rode / rode.dk

Field Summary

private Comparator<? super E>	comparator The comparator used to sort this value list, if any.
private boolean	duplicates True if this list contains duplicates, false if it does not.
private boolean	sorted True if this list is sorted, false if not.

Fields inherited from class dk.rode.thesis.bridge.SequenceValueCollection

number, type, values

Constructor Summary

	SequenceValueArrayList(Class<E> type, ArrayList<E> values) Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.
	SequenceValueArrayList(Class<E> type, ArrayList<E> values, boolean sorted, Boolean duplicates) Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.
	SequenceValueArrayList(Class<E> type, ArrayList<E> values, Comparator<? super E> comparator, Boolean duplicates) Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.
private	SequenceValueArrayList(Class<E> type, ArrayList<E> values, int number, boolean sorted, Comparator<? super E> comparator, Boolean duplicates) Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.

Method Summary

SequenceValueArrayList<E>	copy() Performs a deep copy of this generator.
boolean	duplicates() Returns true if this generator will generate duplicate (equivalent) values, false if not.
E	first() Resets this generator to re-generate its first value, where after values can (again) be generated by SequenceValueGenerator.get().
E	get() Returns a value generated by this generator.
E	get(int number) Returns the number'th value generated by this generator, which may or may not have been generated yet.
int	numberOf(E value, int fromNumber) Returns the number of the generated value supplied as value using an offset of fromNumber, or Const.EOF if no such value will ever been generated by this generator.
boolean	ordered() Returns true if the values generated by this generator are ordered, i.e. always delivered in some known order.
boolean	sorted() Returns true if the values generated by this generator are sorted, for example based on numerical value in case of numbers.

Methods inherited from class dk.rode.thesis.bridge.SequenceValueCollection

checkNumber, equals, getStringablePolicy, getValueType, hashCode, number, size, toCollection, toString, toString

Methods inherited from class java.lang.Object

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

Field Detail

comparator

private final Comparator<? super E extends Serializable> comparator

The comparator used to sort this value list, if any.

If null and sorted is true, the comparable natural ordering is assumed.

Can be null.

duplicates

private final boolean duplicates

True if this list contains duplicates, false if it does not.

This can either be specified or calculated at construction time.

sorted

private final boolean sorted

True if this list is sorted, false if not.

Constructor Detail

SequenceValueArrayList

public SequenceValueArrayList(Class<E> type,
                              ArrayList<E> values)

Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.

This value list is assumed to be unsorted, but whether or not values contains duplicates is calculated. The worst case calculation running time is O(values.size).

Modifying values externally will affect this value set and should not be performed. The result of doing so is undefined - but never good.

values must not contain null entries. If it does, the sequence abstraction using this value list will generate an internal error when that entry is returned by this value list!

Parameters:

type - The type of values stored in this list (and values); cannot be null.

values - The actual ArrayList instance storing the sequence values; cannot be null, empty, or contain null values.

Throws:

NullPointerException - If either argument is null.

IllegalArgumentException - If values is empty, or contain a null value discovered during duplicate calculation.

SequenceValueArrayList

public SequenceValueArrayList(Class<E> type,
                              ArrayList<E> values,
                              boolean sorted,
                              Boolean duplicates)

Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.

Modifying values externally will affect this value set and should not be performed. The result of doing so is undefined - but never good.

values must not contain null entries. If it does, the sequence abstraction using this value list will generate an internal error when that entry is returned by this value list!

Parameters:

type - The type of values stored in this list (and values); cannot be null.

values - The actual ArrayList instance storing the sequence values; cannot be null, empty, or contain null values.

sorted - True if values is sorted, false if not. If true, comparable natural ordering is assumed.

duplicates - If true, values is known to contain duplicates; if false, values is known not to contain duplicates; or if null, whether or not values contains duplicates is calculated. Potentially expensive, worst running time O(values.size).

Throws:

NullPointerException - If either type or values are null.

IllegalArgumentException - If values is empty, or contain a null value discovered during duplicate calculation.

SequenceValueArrayList

public SequenceValueArrayList(Class<E> type,
                              ArrayList<E> values,
                              Comparator<? super E> comparator,
                              Boolean duplicates)

Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.

Modifying values externally will affect this value set and should not be performed. The result of doing so is undefined - but never good.

values is assumed already sorted by the Comparator supplied as comparator; if null, the comparable natural ordering is assumed.

values must not contain null entries. If it does, the sequence abstraction using this value list will generate an internal error when that entry is returned by this value list!

Parameters:

type - The type of values stored in this list (and values); cannot be null.

values - The actual ArrayList instance storing the sequence values; cannot be null, empty, or contain null values.

comparator - The comparator used, if any; can be null, in which case comparator natural ordering is assumed.

duplicates - If true, values is known to contain duplicates; if false, values is known not to contain duplicates; or if null, whether or not values contains duplicates is calculated. Potentially expensive, worst running time O(values.size).

Throws:

NullPointerException - If either type or values are null.

IllegalArgumentException - If values is empty, or contain a null value discovered during duplicate calculation.

SequenceValueArrayList

private SequenceValueArrayList(Class<E> type,
                               ArrayList<E> values,
                               int number,
                               boolean sorted,
                               Comparator<? super E> comparator,
                               Boolean duplicates)

Constructor, which creates this sequence value array list to use the java.util.ArrayList instance supplied as values.

The next value to return by get() is the value that is the number'th value in this value list, and this constructor ensures that this value list is initialised accordingly!

Modifying values externally will affect this value set and should not be performed. The result of doing so is undefined - but never good.

values must not contain null entries. If it does, the sequence abstraction using this value list will generate an internal error when that entry is returned by this value list!

Parameters:

type - The type of values stored in this list (and values); cannot be null.

values - The actual ArrayList instance storing the sequence values; cannot be null, empty, or contain null values.

number - The number pointing the the number'th value to be returned by the next call to get().

sorted - True if values is sorted, false if not.

comparator - The comparator used, if any; can be null, in which case comparator natural ordering is assumed.

duplicates - If true, values is known to contain duplicates; if false, values is known not to contain duplicates; or if null, whether or not values contains duplicates is calculated. Potentially expensive, worst running time O(values.size).

Throws:

NullPointerException - If either type or values are null.

IllegalArgumentException - If values is empty, or contain a null value discovered during duplicate calculation, or if number is illegal.

Method Detail

copy

public SequenceValueArrayList<E> copy()

Description copied from class: SequenceValueCollection

Performs a deep copy of this generator.

The size, ordered, sorted, and duplicate properties are adhered to by the returned clone.

The work in copying this collection is proportional with the number of values contained, and is thus more expensive the larger this collection is!

Specified by:

copy in interface SequenceValueGenerator<E extends Serializable>

Specified by:

copy in interface Copyable<SequenceValueGenerator<E extends Serializable>>

Specified by:

copy in class SequenceValueCollection<E extends Serializable,ArrayList<E extends Serializable>>

Returns:

A copy of this value collection; never null.

duplicates

public boolean duplicates()

Description copied from interface: SequenceValueGenerator

Returns true if this generator will generate duplicate (equivalent) values, false if not.

The test for duplicates is performed using equals(Object).

Returns:

True if this generator will generate duplicate values, false if not.

first

public E first()

Description copied from interface: SequenceValueGenerator

Resets this generator to re-generate its first value, where after values can (again) be generated by SequenceValueGenerator.get().

The number of generated values is reset when this method is invoked.

If this generator does not generate ordered, nor sorted values, it is undefined which value is generated as the first value.

Returns:

A first value generated by this generator; never null.

get

public E get()

Description copied from interface: SequenceValueGenerator

Returns a value generated by this generator.

The number of the generated value is one higher than the last value returned by either SequenceValueGenerator.first(), SequenceValueGenerator.get(), or SequenceValueGenerator.get(int).

The number of generated values is reset when first() is invoked.

If this generator generates ordered or sorted values, the generation of values is consistent even after SequenceValueGenerator.first() have been invoked. Otherwise the order is undefined.

Returns:

A value generated by this generator; never null.

See Also:

SequenceValueGenerator.get(int)

get

public E get(int number)

Description copied from interface: SequenceValueGenerator

Returns the number'th value generated by this generator, which may or may not have been generated yet. The next call to SequenceValueGenerator.get() from generate and return the number + 1'th value.

The number of generated values is reset when first() is invoked.

If this generator generates ordered or sorted values, the generation of values is consistent even after SequenceValueGenerator.first() have been invoked. Otherwise the order is undefined, and this method may generate different values for the same number each time invoked.

Parameters:

number - The number in question; cannot be zero or negative. Is one-, not zero-based!

Returns:

The number'th value generated by this generator; never null.

See Also:

SequenceValueGenerator.get(), SequenceValueGenerator.numberOf(Object, int)

numberOf

public int numberOf(E value,
                    int fromNumber)

Description copied from interface: SequenceValueGenerator

Returns the number of the generated value supplied as value using an offset of fromNumber, or Const.EOF if no such value will ever been generated by this generator.

Unlike SequenceValueGenerator.first(), SequenceValueGenerator.get(), and SequenceValueGenerator.get(int), this method will not alter the number of values generated by this generator.

Parameters:

value - The value to test; cannot be null.

fromNumber - The number to start from; only relevant if the values generated contain duplicates. Is one-, not zero-based! If larger than SequenceValueGenerator.size(), this method will always return EOF.

Returns:

The number of the generated value supplied as value, or EOF if no such value can be generated by this value generator.

See Also:

SequenceValueGenerator.get(int)

ordered

public boolean ordered()

Description copied from interface: SequenceValueGenerator

Returns true if the values generated by this generator are ordered, i.e. always delivered in some known order.

Returns:

True if ordered, false if not.

sorted

public boolean sorted()

Description copied from interface: SequenceValueGenerator

Returns true if the values generated by this generator are sorted, for example based on numerical value in case of numbers.

Returns:

True if sorted, false if not.