Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.bridge
Class SequenceValueRange

java.lang.Object
  extended by dk.rode.thesis.bridge.SequenceValueRange
All Implemented Interfaces:
SequenceValueGenerator<Integer>, Copyable<SequenceValueGenerator<Integer>>, Stringable<SequenceValueGenerator<Integer>>

@Participant(value="ConcreteImplementor")
public class SequenceValueRange
extends Object
implements SequenceValueGenerator<Integer>

A sequence value range generates unique Integer values within a given range determined at construction time.

A sequence value range is ordered, sorted, and do not contain duplicates.

Author:
Gunni Rode / rode.dk

Field Summary
private  int maximum
          The maximum value in this range.
private  int minimum
          The minimum value in this range.
private  int value
          The current generated value corresponding to a number of value - minimum.
 
Constructor Summary
  SequenceValueRange(int minimum)
          Constructor, which creates this sequence value range to generate Integer values in the range [minimum, ..[, i.e. no fixed size.
  SequenceValueRange(int minimum, int maximum)
          Constructor, which creates this sequence value range to generate Integer values in the range [minimum, maximum].
private SequenceValueRange(int minimum, int maximum, int value)
          Constructor, which creates this sequence value range to generate Integer values in the range [minimum, maximum].
 
Method Summary
private  int checkNumber(int number, boolean fail)
          Ensures the the number of a given value generated by this value range is legal.
 SequenceValueRange copy()
          Performs a deep copy of this generator.
 boolean duplicates()
          Returns true if this generator will generate duplicate (equivalent) values, false if not.
 boolean equals(Object object)
          Returns true if object is a SequenceValueRange instance that uses the same value range as this range, false if not.
 Integer first()
          Resets this generator to re-generate its first value, where after values can (again) be generated by SequenceValueGenerator.get().
 Integer get()
          Returns a value generated by this generator.
 Integer get(int number)
          Returns the number'th value generated by this generator, which may or may not have been generated yet.
 StringablePolicy<? super SequenceValueGenerator<Integer>> getStringablePolicy(StringablePolicy<? super SequenceValueGenerator<Integer>> policy)
          Always return a non-null policy: policy is not null: policy is returned.
 Class<Integer> getValueType()
          Returns the actual type of the values generated by this generator.
 int hashCode()
          Returns the hash code of this value range.
 int number()
          Returns the number of the the last value generated by either SequenceValueGenerator.first(), SequenceValueGenerator.get(), or SequenceValueGenerator.get(int).
 int numberOf(Integer 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 SequenceValueGenerator.first().
 boolean sorted()
          Returns true if the values generated by this generator are sorted, for example based on numerical value in case of numbers.
 String toString()
          Returns the string representation of this value range.
 CharSequence toString(StringablePolicy<? super SequenceValueGenerator<Integer>> policy)
          Returns a char sequence representation of this stringable object using the format determined by policy or the default policy in case policy is null.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

maximum

private final int maximum
The maximum value in this range.

Will be Const.INFINITE if the range has no maximum.


minimum

private final int minimum
The minimum value in this range.


value

private int value
The current generated value corresponding to a number of value - minimum.

Range is: minimum <= number [<= maximum, if maximum != INFINITE]

Constructor Detail

SequenceValueRange

public SequenceValueRange(int minimum)
Constructor, which creates this sequence value range to generate Integer values in the range [minimum, ..[, i.e. no fixed size.

Parameters:
minimum - The minimum value to generate.

SequenceValueRange

public SequenceValueRange(int minimum,
                          int maximum)
Constructor, which creates this sequence value range to generate Integer values in the range [minimum, maximum].

Parameters:
minimum - The minimum value to generate.
maximum - The maximum value to generate; must be >= minimum.
Throws:
IllegalArgumentException - If minimum > maximum.

SequenceValueRange

private SequenceValueRange(int minimum,
                           int maximum,
                           int value)
Constructor, which creates this sequence value range to generate Integer values in the range [minimum, maximum].

Parameters:
minimum - The minimum value to generate.
maximum - The maximum value to generate; must be >= minimum if not Const.INFINITE.
value - The current value, offset by minimum.
Throws:
IllegalArgumentException - If minimum > maximum, or if value is illegal.
Method Detail

checkNumber

private final int checkNumber(int number,
                              boolean fail)
Ensures the the number of a given value generated by this value range is legal. If not, andfail is true, an illegal argument exception is thrown.

A valid range is minimum <= number [<= maximum, if maximum != INFINITE]

Parameters:
number - The number to check.
fail - If true, an exception is thrown if number is illegal, otherwise Const.EOF is returned. If legal, a number is always returned.
Returns:
The corresponding value to number, or EOF.
Throws:
IllegalArgumentException - If fail is true and if number is illegal.

copy

public SequenceValueRange 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 SequenceValueGenerator<Integer>
Specified by:
copy in interface Copyable<SequenceValueGenerator<Integer>>
Returns:
A copy of this generator; 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).

Specified by:
duplicates in interface SequenceValueGenerator<Integer>
Returns:
True if this generator will generate duplicate values, false if not.

equals

public boolean equals(Object object)
Returns true if object is a SequenceValueRange instance that uses the same value range as this range, false if not.

Overrides:
equals in class Object
Parameters:
object - The object to test; can be null.
Returns:
True if equal, false if not.

first

public Integer 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.

Specified by:
first in interface SequenceValueGenerator<Integer>
Returns:
A first value generated by this generator; never null.

get

public Integer 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.

Specified by:
get in interface SequenceValueGenerator<Integer>
Returns:
A value generated by this generator; never null.
See Also:
SequenceValueGenerator.get(int)

get

public Integer 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.

Specified by:
get in interface SequenceValueGenerator<Integer>
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)

getStringablePolicy

public StringablePolicy<? super SequenceValueGenerator<Integer>> getStringablePolicy(StringablePolicy<? super SequenceValueGenerator<Integer>> policy)
Description copied from interface: Stringable
Always return a non-null policy:

  1. policy is not null: policy is returned.

  2. policy is null: a default, non-null policy is returned.

Specified by:
getStringablePolicy in interface Stringable<SequenceValueGenerator<Integer>>
Parameters:
policy - The supplied policy; can be null.
Returns:
The policy to use; never null.
See Also:
Stringable.toString(StringablePolicy)

getValueType

public Class<Integer> getValueType()
Description copied from interface: SequenceValueGenerator
Returns the actual type of the values generated by this generator.

Specified by:
getValueType in interface SequenceValueGenerator<Integer>
Returns:
The value type; never null.

hashCode

public int hashCode()
Returns the hash code of this value range.

Overrides:
hashCode in class Object
Returns:
The hash code.

number

public int number()
Description copied from interface: SequenceValueGenerator
Returns the number of the the last value generated by either SequenceValueGenerator.first(), SequenceValueGenerator.get(), or SequenceValueGenerator.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 < SequenceValueGenerator.size(), if size != INFINITE.

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

Specified by:
number in interface SequenceValueGenerator<Integer>
Returns:
The number of the last value generated.

numberOf

public int numberOf(Integer 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.

Specified by:
numberOf in interface SequenceValueGenerator<Integer>
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.

Specified by:
ordered in interface SequenceValueGenerator<Integer>
Returns:
True if ordered, false if not.

size

public int size()
Description copied from interface: SequenceValueGenerator
Returns the number of values that can be generated by this generator in total, excluding re-generation of values after a call to SequenceValueGenerator.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.

Specified by:
size in interface SequenceValueGenerator<Integer>
Returns:
The number of values, or Const.INFINITE if this generator has no (practical) bounds on the number of values it can generate.

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.

Specified by:
sorted in interface SequenceValueGenerator<Integer>
Returns:
True if sorted, false if not.

toString

public String toString()
Returns the string representation of this value range.

Overrides:
toString in class Object
Returns:
The string representation; never null.

toString

public CharSequence toString(StringablePolicy<? super SequenceValueGenerator<Integer>> policy)
Description copied from interface: Stringable
Returns a char sequence representation of this stringable object using the format determined by policy or the default policy in case policy is null.

In Foo, a typical implementation of this method could be:

    public CharSequence toString(StringablePolicy<? super Foo> policy) {
      return this.getStringablePolicy(policy).toString(this);
    }
 
There are two approaches to formatting this stringable object into a char sequence representation:

  1. Let policy decide the entire format, as in the Foo example above; or

  2. Use policy to format part of the overall representation, for example letting this method append certain text regardless of the policy used.

Bullet 1) is not always applicable because a given policy implementation may not have access to all required information in its StringablePolicy.toString(Object) method, for example in case multiple stringable objects should be formatted into an overall representation.

In case an implementation uses the approach from bullet 2), care must be take to respect the policy hints so the overall format remains meaningful.

Specified by:
toString in interface Stringable<SequenceValueGenerator<Integer>>
Parameters:
policy - The policy to dictate the formatting; can be null, in which case the result of toString method is returned.
Returns:
The char sequence representation; never null.
See Also:
StringablePolicy.Type

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.