toValue = minValue - 1.0f;
        try {
            testedFloatControl.shift(fromValue, toValue, updatePeriod);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }


        out.println
            ("\n>> The shift(float fromValue, float toValue, int microseconds) method: toValue > maximum");

        fromValue = minValue;
        toValue = maxValue + 1.0f;
        try {
            testedFloatControl.shift(fromValue, toValue, updatePeriod);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        if ( testResult == STATUS_FAILED ) {
            out.println("\n==> test FAILED!");
        } else {
            out.println("\n==> test PASSED!");
        }
        return testResult;
    }
} // end of test class


class TestFloatControl extends FloatControl {

    TestFloatControl(
        FloatControl.Type type, //the kind of control represented by this float control object
        float minimum, //the smallest value permitted for the control
        float maximum, //the largest value permitted for the control
        float precision, //the resolution or granularity of the control
        int updatePeriod, //the smallest time interval, in microseconds,
                                //over which the control can change from one discrete value to other
        float initialValue, //the value that the control starts with when constructed
        String units, //the label for the units in which the control values are expressed
        String minLabel, //the label for the minimum value, such as "Left" or "Off"
        String midLabel, //the label for the midpoint value, such as "Center" or "Default"
        String maxLabel //the label for the maximum value, such as "Right" or "Full"
        ) {
                   
        super(type, minimum, maximum, precision, updatePeriod,
                initialValue, units, minLabel, midLabel, maxLabel);
    }

    TestFloatControl(
        FloatControl.Type type, //the kind of control represented by this float control object
        float minimum, //the smallest value permitted for the control
        float maximum, //the largest value permitted for the control
        float precision, //the resolution or granularity of the control
        int updatePeriod, //the smallest time interval, in microseconds,
                                //over which the control can change from one discrete value to other
        float initialValue, //the value that the control starts with when constructed
        String units //the label for the units in which the control values are expressed
        ) {
                   
        super(type, minimum, maximum, precision, updatePeriod, initialValue, units);
    }
}
-------------------------------------------------------------------------
 
======================================================================


Name: abR10010 Date: 04/22/2002




According to the specification of the javax.sound.sampled.FloatControl class
its main purpose is to provide control over a range of floating-point values
and for this purpose it provides methods to set and get the control's current
floating-point value,

But these methods are not in agreement as to whether it is permitted for the
current floating-point value to be outside the allowable range.

The setValue(float newValue) method throws IllegalArgumentException
if the value indicated doesn't fall within the allowable range, i.e. when
newValue is greater than the maximum value, or smaller than the minimum
value.

But the both FloatControl constructors permit the "initialValue" parameter
to not fall within the allowable range.
 
It seems this is ambiguity and it may make sense to forbid the values outside
the allowable range for constructor parameters.
 
The shift(float from, float to, int microseconds) method throws
IllegalArgumentException too if the final "to" value does not fall within
the allowable range.
 
But the spec for this method says nothing about the IllegalArgumentException.
 
As to the "from" value currently the shift(...) method doesn't throw any Exception
when the "from" value is outside the allowable range.
 
It seems that the shift(...) method should keep the consistent policy for both "from"
and "to" values and should throw IllegalArgumentException if any value is outside
the allowable range.

And the spec for the shift(...) method should say explicitly about the
IllegalArgumentException.

Please, see test below that shows the methods behavior described above.
Such behavior is shown by the test running with JDK 1.4.1-beta-b08.


Please, see test log:

% java -version
java version "1.4.1-beta"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-beta-b08)
Java HotSpot(TM) Client VM (build 1.4.1-beta-b08, mixed mode)

% java test

==> Test for FloatControl class methods:

>> The first FloatControl constructor: initialValue < minimum
## FAILED: no any Exception was thrown!
# testedFloatControl.getValue() = 9.0
# testedFloatControl.getMinimum() = 10.0
# testedFloatControl.getMaximum() = 100.0

>> The first FloatControl constructor: initialValue > maximum
## FAILED: no any Exception was thrown!
# testedFloatControl.getValue() = 101.0
# testedFloatControl.getMinimum() = 10.0
# testedFloatControl.getMaximum() = 100.0

>> The second FloatControl constructor: initialValue < minimum
## FAILED: no any Exception was thrown!
# testedFloatControl.getValue() = 9.0
# testedFloatControl.getMinimum() = 10.0
# testedFloatControl.getMaximum() = 100.0

>> The second FloatControl constructor: initialValue > maximum
## FAILED: no any Exception was thrown!
# testedFloatControl.getValue() = 101.0
# testedFloatControl.getMinimum() = 10.0
# testedFloatControl.getMaximum() = 100.0

>> The setValue(float newValue) method: newValue < minimum
> PASSED: expected IllegalArgumentException was thrown:
java.lang.IllegalArgumentException: Requested value 9.0 smaller than allowable minimum value 10.0.
at javax.sound.sampled.FloatControl.setValue(FloatControl.java:180)
at test.run(test.java:123)
at test.main(test.java:13)

>> The setValue(float newValue) method: newValue > maximum
> PASSED: expected IllegalArgumentException was thrown:
java.lang.IllegalArgumentException: Requested value 101.0 exceeds allowable maximum value 100.0.
at javax.sound.sampled.FloatControl.setValue(FloatControl.java:176)
at test.run(test.java:141)
at test.main(test.java:13)

>> The shift(float fromValue, float toValue, int microseconds) method: fromValue < minimum
## FAILED: no any Exception was thrown!
# testedFloatControl.getValue() = 100.0
# testedFloatControl.getMinimum() = 10.0
# testedFloatControl.getMaximum() = 100.0

>> The shift(float fromValue, float toValue, int microseconds) method: fromValue > maximum
## FAILED: no any Exception was thrown!
# testedFloatControl.getValue() = 10.0
# testedFloatControl.getMinimum() = 10.0
# testedFloatControl.getMaximum() = 100.0

>> The shift(float fromValue, float toValue, int microseconds) method: toValue < minimum
> PASSED: expected IllegalArgumentException was thrown:
java.lang.IllegalArgumentException: Requested value 9.0 smaller than allowable minimum value 10.0.
at javax.sound.sampled.FloatControl.setValue(FloatControl.java:180)
at javax.sound.sampled.FloatControl.shift(FloatControl.java:292)
at test.run(test.java:201)
at test.main(test.java:13)

>> The shift(float fromValue, float toValue, int microseconds) method: toValue > maximum
> PASSED: expected IllegalArgumentException was thrown:
java.lang.IllegalArgumentException: Requested value 101.0 exceeds allowable maximum value 100.0.
at javax.sound.sampled.FloatControl.setValue(FloatControl.java:176)
at javax.sound.sampled.FloatControl.shift(FloatControl.java:292)
at test.run(test.java:222)
at test.main(test.java:13)

==> test FAILED!
 
 
The test source:
------------------------------- test.java --------------------------------
// File: %Z%%M% %I% %E%
// Copyright %G% Sun Microsystems, Inc. All Rights Reserved

import javax.sound.sampled.*;

public class test {

    static final int STATUS_PASSED = 0;
    static final int STATUS_FAILED = 2;
    static final int STATUS_TEMP = 95;
    
    public static void main(String argv[]) {
        int testExitStatus = run(argv, System.out) + STATUS_TEMP;
        System.exit(testExitStatus);
    }

    public static int run(String argv[], java.io.PrintStream out) {
        int testResult = STATUS_PASSED;
    
        out.println("\n==> Test for FloatControl class methods:");

    
        FloatControl.Type testFloatControlType = FloatControl.Type.MASTER_GAIN;
        float minValue = 10.0f;
        float maxValue = 100.0f;
        float precision = 1.0f;
        int updatePeriod = 100;
        String units = "unit";
        String minLabel = "minLabel";
        String midLabel = "midLabel";
        String maxLabel = "maxLabel";
    
        out.println("\n>> The first FloatControl constructor: initialValue < minimum");

        float initialValue = minValue - 1.0f;
        FloatControl testedFloatControl = null;
        try {
            testedFloatControl
                = new TestFloatControl(testFloatControlType, minValue, maxValue, precision, updatePeriod,
                                        initialValue, units, minLabel, midLabel, maxLabel);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println("\n>> The first FloatControl constructor: initialValue > maximum");

        initialValue = maxValue + 1.0f;
        try {
            testedFloatControl
                = new TestFloatControl(testFloatControlType, minValue, maxValue, precision, updatePeriod,
                                        initialValue, units, minLabel, midLabel, maxLabel);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println("\n>> The second FloatControl constructor: initialValue < minimum");

        initialValue = minValue - 1.0f;
        try {
            testedFloatControl
                = new TestFloatControl(testFloatControlType, minValue, maxValue, precision, updatePeriod,
                                        initialValue, units);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println("\n>> The second FloatControl constructor: initialValue > maximum");

        initialValue = maxValue + 1.0f;
        try {
            testedFloatControl
                = new TestFloatControl(testFloatControlType, minValue, maxValue, precision, updatePeriod,
                                        initialValue, units, minLabel, midLabel, maxLabel);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        initialValue = minValue + 1.0f;
        testedFloatControl
            = new TestFloatControl(testFloatControlType, minValue, maxValue, precision, updatePeriod,
                                    initialValue, units, minLabel, midLabel, maxLabel);

        out.println("\n>> The setValue(float newValue) method: newValue < minimum");

        float newValue = minValue - 1.0f;
        try {
            testedFloatControl.setValue(newValue);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println("\n>> The setValue(float newValue) method: newValue > maximum");
    
        newValue = maxValue + 1.0f;
        try {
            testedFloatControl.setValue(newValue);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println
            ("\n>> The shift(float fromValue, float toValue, int microseconds) method: fromValue < minimum");

        float fromValue = minValue - 1.0f;
        float toValue = maxValue;
        try {
            testedFloatControl.shift(fromValue, toValue, updatePeriod);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println
            ("\n>> The shift(float fromValue, float toValue, int microseconds) method: fromValue > maximum");

        fromValue = maxValue + 1.0f;
        toValue = minValue;
        try {
            testedFloatControl.shift(fromValue, toValue, updatePeriod);
            out.println("## FAILED: no any Exception was thrown!");
            out.println("# testedFloatControl.getValue() = " + testedFloatControl.getValue() );
            out.println("# testedFloatControl.getMinimum() = " + testedFloatControl.getMinimum());
            out.println("# testedFloatControl.getMaximum() = " + testedFloatControl.getMaximum());
            testResult = STATUS_FAILED;
        } catch (IllegalArgumentException illegArgExcept) {
            out.println("> PASSED: expected IllegalArgumentException was thrown:");
            illegArgExcept.printStackTrace(out);
        } catch (Throwable thrown) {
            out.println("## FAILED: unexpected Exception was thrown!");
            thrown.printStackTrace(out);
        }

        out.println
            ("\n>> The shift(float fromValue, float toValue, int microseconds) method: toValue < minimum");

        fromValue = minValue;