Proposal : Range class
			~~~~~~~~~~~~~~~~~~~~~~
			
Aastha Bhardwaj
Created: Aug 10, 2000
Revised: Oct 10, 2000
Revised: Dec 18, 2000

1. Motivation

The motivation for this class is to make implementation of Negotiable
objects easier. It is expected that many Negotiable's will want to
express their capabilities or their support for some parameter as being
a range of values. No class providing the functionality of the Range
class was found in the JDK core, which is why this class is being
proposed. 

2. The Range class

package javax.media.jai.util;

/**
 * A class to represent ranges of values. A range is defined to contain 
 * all the values between the minimum and maximum values, where 
 * the minimum/maximum value can be considered either included or excluded 
 * from the range. 
 *
 * <p> This example creates a range of <code>Integer</code>s whose minimum
 * value is 1 and the maximum value is 5. The range is inclusive at both
 * ends:
 *
 * <p><code>
 * Range intRange = new Range(Integer.class, new Integer(1), new Integer(5)); 
 * </code>
 *
 * <p> A <code>Range</code> can be unbounded at either or both of its ends.
 * An unbounded end is specified by passing null for the value of that end.
 * A <code>Range</code> unbounded at both of its ends represents a range of
 * all possible values for the <code>Class</code> of elements in that
 * <code>Range</code>. The <code>isMinIncluded()</code> method will always
 * return true for a <code>Range</code> unbounded on the minimum side and
 * correspondingly the <code>isMaxIncluded()</code> method will always
 * return true for a <code>Range</code> unbounded on the maximum side.
 *
 * <p> An empty range is defined as a <code>Range</code> whose minimum value
 * is greater than it's maximum value if the ends are included, or as a
 * <code>Range</code> whose minimum value is greater than or equal to it's
 * maximum value, if the minimum or the maximum value is excluded.
 */
public class Range implements Serializable {

    /**
     * Constructs a <code>Range</code> object given the <code>Class</code>
     * of the elements in the <code>Range</code>, the minimum value and 
     * the maximum value. The minimum and the maximum value are considered
     * inclusive.
     *
     * <p> An unbounded range can be specified by passing in a null for
     * either of the two values, in which case the <code>Range</code> is
     * unbounded on one side, or for both, in which case the
     * <code>Range</code> represents an all inclusive set.
     * 
     * @param elementClass  The <code>Class</code> of the <code>Range</code>
     *                      elements.
     * @param minValue      The lowest value included in the <code>Range</code>.
     * @param maxValue      The highest value included in the <code>Range</code>.
     *
     * @throws IllegalArgumentException if minValue and maxValue are both null,
     *					and elementClass is not one of the 
     *					subclasses of <code>Comparable</code>.
     * @throws IllegalArgumentException if minValue is not the same 
     *                                  <code>Class</code> as elementClass.
     * @throws IllegalArgumentException if maxValue is not the same 
     *                                  <code>Class</code> as elementClass.
     */
    public Range(Class elementClass, 
		 Comparable minValue, 
		 Comparable maxValue) {}

    /**
     * Constructs a <code>Range</code> object given the <code>Class</code>
     * of the elements in the <code>Range</code>, the minimum value and
     * the maximum value. Whether the minimum value and the maximum value
     * are considered inclusive is specified via the 
     * <code>isMinIncluded</code> and <code>isMaxIncluded</code> variables.
     *     
     * <p> An unbounded range can be specified by passing in a null for
     * either of the two values, in which case the <code>Range</code> is
     * unbounded at one end, or for both, in which case the
     * <code>Range</code> represents an all inclusive set. If null is passed
     * in for either variable, the <code>boolean</code> variables have
     * no effect.
     *     
     * @param elementClass  The <code>Class</code> of the <code>Range</code>
     *                      elements.
     * @param minValue      The lowest value for the <code>Range</code>.
     * @param isMinIncluded A boolean that defines whether the minimum value is
     *                      included in the <code>Range</code>.
     * @param maxValue      The highest value for the <code>Range</code>.
     * @param isMaxIncluded A boolean that defines whether the maximum value is
     *                      included in the <code>Range</code>.
     *
     * @throws IllegalArgumentException if minValue and maxValue are both null,
     *                                  and elementClass is not one of the
     *                                  subclasses of <code>Comparable</code>.
     * @throws IllegalArgumentException if minValue is not the same 
     *                                  <code>Class</code> as elementClass.
     * @throws IllegalArgumentException if maxValue is not the same 
     *                                  <code>Class</code> as elementClass.
     */
    public Range(Class elementClass, 
		 Comparable minValue, 
		 boolean isMinIncluded,
		 Comparable maxValue,
		 boolean isMaxIncluded) {}

    /**
     * Returns true if the minimum value is included within this
     * <code>Range</code>. If the range is unbounded at this end, this
     * method will return true.
     */
    public boolean isMinIncluded() {}

    /**
     * Returns true if the maximum value is included within this
     * <code>Range</code>. If the range is unbounded at this end, this
     * method will return true.
     */
    public boolean isMaxIncluded() {}

    /**
     * Returns the <code>Class</code> of the elements of this <code>Range</code>.
     */
    public Class getElementClass() {}

    /**
     * Returns the minimum value of this <code>Range</code>.
     * Returns null if the <code>Range</code> is unbounded at this end.
     */
    public Comparable getMinValue() {}

    /**
     * Returns the maximum value of this <code>Range</code>.
     * Returns null if the <code>Range</code> is unbounded at this end.
     */
    public Comparable getMaxValue() {}

    /**
     * Returns true if the specified value is within this <code>Range</code>,
     * i.e. is either equal to or greater than the minimum value of this
     * <code>Range</code> and is either lesser than or equal to the maximum
     * value of this <code>Range</code>.    
     *
     * @param value  The value to be checked for being within this 
     *               <code>Range</code>.
     * @throws IllegalArgumentException if the <code>Class</code> of the value
     * parameter is not the same as the elementClass of this <code>Range</code>.
     */
    public boolean contains(Comparable value) {}

    /**
     * Returns true if the supplied <code>Range</code> is fully contained 
     * within this <code>Range</code>. Fully contained is defined as having
     * the minimum and maximum values of the fully contained range lie 
     * within the range of values of the containing <code>Range</code>.
     *
     * @throws IllegalArgumentException if the <code>Class</code> of the
     * elements of the given <code>Range</code> is not the same as the 
     * <code>Class</code> of the elements of this <code>Range</code>.
     * @throws IllegalArgumentException if the given <code>Range</code> is null
     */
    public boolean contains(Range range) {}

    /**
     * Returns true if this <code>Range</code> intersects the 
     * given <code>Range</code>.
     *
     * @throws IllegalArgumentException if the <code>Class</code> of the
     * elements of the given <code>Range</code> is not the same as the 
     * <code>Class</code> of the elements of this <code>Range</code>.
     * @throws IllegalArgumentException if the given <code>Range</code> is null
     */
    public boolean intersects(Range range) {}

    /**
     * Returns the union of this <code>Range</code> with the given 
     * <code>Range</code>. If this <code>Range</code> and the given
     * <code>Range</code> are disjoint, the <code>Range</code> returned
     * as a result of the union will have a minimum value set to the
     * minimum of the two disjoint range's minimum values, and the maximum
     * set to the maximum of the two disjoint range's maximum values, thus
     * including the disjoint range within it.
     *
     * @throws IllegalArgumentException if the <code>Class</code> of the
     * elements of the given <code>Range</code> is not the same as the 
     * <code>Class</code> of the elements of this <code>Range</code>.
     * @throws IllegalArgumentException if the given <code>Range</code> is null
     */
    public Range union(Range range) {}

    /**
     * Returns the intersection of this <code>Range</code> with the
     * given <code>Range</code>.
     *
     * @throws IllegalArgumentException if the <code>Class</code> of the
     * elements of the given <code>Range</code> is not the same as the 
     * <code>Class</code> of the elements of this <code>Range</code>.
     * @throws IllegalArgumentException if the given <code>Range</code> is null
     */
    public Range intersect(Range range) {}

    /**
     * Returns the <code>Range</code> of values that are in this
     * <code>Range</code> but not in the given <code>Range</code>. If 
     * the subtraction results in two disjoint <code>Range</code>s, they
     * will be returned as two elements of a <code>Range</code> array, 
     * otherwise the resultant <code>Range</code> will be returned as the
     * first element of a one element array.
     *
     * When this <code>Range</code> and the given <code>Range</code> are
     * both unbounded at both the ends (i.e both the <code>Range</code>s
     * are all inclusive), this method will return null as the first
     * element of one element array, as a result of the subtraction.
     *
     * When this <code>Range</code> is completely contained in the
     * given <code>Range</code>, an empty <code>Range</code> is returned.
     *
     * @throws IllegalArgumentException if the <code>Class</code> of the
     * elements of the given <code>Range</code> is not the same as the 
     * <code>Class</code> of the elements of this <code>Range</code>.
     */
    public Range[] subtract(Range range) {}

    /**
     * Returns true if this <code>Range</code> and the given 
     * <code>Range</code> both have elements of the same <code>Class</code>,
     * their minimum and maximum values are the same, and their isMinIncluded()
     * and isMaxIncluded() methods return the same values.
     *
     * If this <code>Range</code> and the given <code>Range</code> are both
     * empty and the <code>Class</code> of their elements is the same, they
     * will be found to be equal and true will be returned.
     */
    public boolean equals(Object other) {}

    /**
     * Returns true if this <code>Range</code> is empty, i.e. if the minimum
     * value is greater than the maximum value, if both are included, or if
     * the minimum value is greater than equal to the maximum value if either
     * the minimum or maximum value is excluded.
     */
    public boolean isEmpty() {}

    /**
     * Returns a <code>String</code> representation of this <code>Range</code>.
     */
    public String toString() {}
}

3. Enumeration

The other class that is expected to be commonly used is the concept of a 
enumeration of values. This can be adequately represented using the 
java.util.Enumeration interface.