RFR 8146458 Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize

[Paul Sandoz]

Hi,

When the new range check methods Object.check* were added the exception reporting was a little vague and lossy, but i got a CCC pass to revisit later on, and John nudged me to sort this out, so here is another more reflective approach:

  http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8146458-checkIndex-exception-reporting/webrev/
  http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8146458-checkIndex-exception-reporting/specdiff/overview-summary.html

To preserve all information the out of bounds exception mapping function is now BiFunction<String, List<Integer>>, where the first argument is the check kind (and when used with a check method conveniently corresponds to the method name) and the second argument is the list of out of bound integer values that failed the check (when used with a check method the list elements conveniently correspond to the method arguments, in order).

A new factory method rangeCheckExceptionMapper has been added that creates an out of bounds exception mapping function from a message exception function, thus one can do:

  BiFunction<String, List<Integer>> f = rangeCheckExceptionMapper(IndexOutOfBoundsException::new);
  checkIndex(index, length, f);
  checkFromToIndex(from, to length, f);
  checkFromIndexSize(from, size length, f);

which is equivalent in behaviour (exception throwing and message) to:

  checkIndex(index, length);
  checkFromToIndex(from, to length);
  checkFromIndexSize(from, size length);

In all three check* cases a specific exception message will be produced:

case "checkIndex":
    return String.format("Index %d out of bounds for length %d",
                         args.get(0), args.get(1));
case "checkFromToIndex":
    return String.format("Range [%d, %d) out of bounds for length %d",
                         args.get(0), args.get(1), args.get(2));
case "checkFromIndexSize":
    return String.format("Range [%d, %<d + %d) out of bounds for length %d",
                         args.get(0), args.get(1), args.get(2));


The two int arg constructors added to Array/String/IndexOutOfBoundsException have been removed.

I did ponder about adding a new constructors with String, List<Integer> arguments. I could still do that, but that does spread out the notion beyond that of Objects and i prefer that it be contained.

Paul.