@Param support for enum

[Joe Kearney]

The particular thing about enums was that when you add more constants or
rename you'll want those to be included in the parameter space, but without
the double book-keeping of adding the constant name in @Param as well.

For booleans obviously the set of values won't change. As you described
with enums, the set of possible boolean value is *small* and countable, so
it can be done. I'd argue that (@Param boolean) is so simple to add and so
obvious in what it means that it should be included.

On the other hand I'd argue that larger types (byte, short, int) have
cardinalities that one would not reasonably expect to be traversed in their
entirety as a parameter space.

I completely agree that you'd expect specified values in @Param to be seen
in that order. Rearranging enum values is easy if the enum is in your code,
and if it's not your enum (consider @Param TimeUnit?) then you're in the
boolean case where the set of values won't change so it's fine to require
specifying them in the annotation.


On 25 June 2014 14:24, Aleksey Shipilev <aleksey.shipilev at oracle.com> wrote:

> On 06/24/2014 02:35 PM, Joe Kearney wrote:
> > Interesting point about ordering; I hadn't expected that you'd place any
> > guarantees on it. Do you know of any use cases which would be order
> > dependent? The analogy that comes to mind is unit tests, in which order
> > dependency is strongly discouraged.
>
> Yes, from the performance standpoint, the runs with different parameters
> values are distinct in either case. But, humans expect the parameter
> space to be traversed in a particular order for better presentation.
> There are basically two things to consider:
>
>  a) Users normally expect natural ordering for parameter values. But in
> our case, since @Param values in the Java code are Strings, and they are
> coerced into the target field type automatically, the natural ordering
> is different (e.g. lexicographical vs integer).
>
>  b) Users sometimes need the special ordering inconsistent with natural
> ordering, to make default text report look good. This is mostly for
> String parameters. (Note that in enum parameters, you can rearrange the
> constants to set the natural order you like).
>
> Merging these two requirements yield the compromise: maintain the
> declared order of parameter values, and let users either put the default
> values in their natural order, or make their own. JMH will maintain the
> declaration order to make this work.
>
> It was allured in Javadoc:
>
>     /**
>      * Default values for the parameter.
>      * @return values ***sequence*** to follow.
>      */
>     String[] value() default { BLANK_ARGS };
>
> Updated Javadoc a bit:
>  http://hg.openjdk.java.net/code-tools/jmh/rev/7ee95e9cf56c
>
> > In any case, the Comparable ordering for booleans would seem to be the
> > natural choice.
>
> True.
>
> > I imagine this would be easy to add in the same places as the
> > @Param-for-enums changes, generalising isEnum/getEnumConstants to
> > something like isAutoParam/getConstantNames.
>
> I am still not convinced we have to make implicit @Param-s for booleans,
> as we did with enums. What's the rationale for introducing this exception?
>
> -Aleksey.
>