dk.rode.thesis.bridge
Interface SequenceValueGenerator<E>

Type Parameters:

E - The type of values generated by this generator.

All Superinterfaces:

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

All Known Implementing Classes:

SequenceValueArrayList, SequenceValueCollection, SequenceValueHashSet, SequenceValueLinkedHashSet, SequenceValueRange, SequenceValueSet, SequenceValueTreeSet

@Participant(value="Implementor")
public interface SequenceValueGenerator<E>
extends Copyable<SequenceValueGenerator<E>>, Stringable<SequenceValueGenerator<E>>

A sequence value generator can be used as the implementation for a sequence abstraction as it generates non-null sequence values that can be delivered by the sequence in question.

Any generator has the following properties:

• At least one value and at most size values will be generated, possibly including duplicates, and values are never null;

• The generator itself is copyable, and will perform a deep copy if necessary, i.e. including generated values stored internally;

• Can generate ordered and/or sorted values, and may or may not generate duplicate values;

• Keeps track of the number of generated values between calls to first();

• Will generate a value on each call to get() or get(int) adhering to the properties listed in the above bullet, and will automatically restart when values are depleted; and

• Can be reset to generate values from the start again by calling first().

Note, that the size, ordered, and duplicate properties makes it very easy to alter the behaviour of a given sequence abstraction!

Author:

Gunni Rode / rode.dk

Method Summary

SequenceValueGenerator<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 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.
Class<E>	getValueType() Returns the actual type of the values generated by this generator.
int	number() Returns the number of the the last value generated by either first(), get(), or get(int).
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.
int	size() Returns the number of values that can be generated by this generator in total, excluding re-generation of values after a call to first().
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 interface dk.rode.thesis.strategy.Stringable

getStringablePolicy, toString

Method Detail

copy

SequenceValueGenerator<E> copy()

Performs a deep copy of this generator.

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

Specified by:

copy in interface Copyable<SequenceValueGenerator<E>>

Returns:

A copy of this generator; never null.

duplicates

boolean duplicates()

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

E first()

Resets this generator to re-generate its first value, where after values can (again) be generated by 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

E get()

Returns a value generated by this generator.

The number of the generated value is one higher than the last value returned by either first(), get(), or 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 first() have been invoked. Otherwise the order is undefined.

Returns:

A value generated by this generator; never null.

See Also:

get(int)

get

E get(int number)

Returns the number'th value generated by this generator, which may or may not have been generated yet. The next call to 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 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.

Throws:

IllegalArgumentException - If number is zero or negative or larger than the maximum number of values that can be generated by this generator, if a maximum is enforced.

See Also:

get(), numberOf(Object, int)

getValueType

Class<E> getValueType()

Returns the actual type of the values generated by this generator.

Returns:

The value type; never null.

number

int number()

Returns the number of the the last value generated by either first(), get(), or get(int).

The number of generated values is reset when first() is invoked, i.e. to a number of one.

Notice, that first and get(int) alter the number count of values generated, which will be reflected in the next invocation of get()!

Range: 1 (0) < number < size(), if size != INFINITE.

A number of zero will only occur when no values have been generated yet.

Returns:

The number of the last value generated.

numberOf

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.

Unlike first(), get(), and 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 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.

Throws:

NullPointerException - If value is null.

IllegalArgumentException - If fromNumber is zero or negative.

See Also:

get(int)

ordered

boolean ordered()

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.

size

int size()

Returns the number of values that can be generated by this generator in total, excluding re-generation of values after a call to first().

Whether or not the count include duplicates is sub-class specific. If duplicates is false, the size is always equal to the number of unique values generated by this generator.

Returns:

The number of values, or Const.INFINITE if this generator has no (practical) bounds on the number of values it can generate.

sorted

boolean sorted()

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.