    001    package org.junit.experimental.theories;
    002
    003    import static java.lang.annotation.ElementType.FIELD;
    004    import static java.lang.annotation.ElementType.METHOD;
    005
    006    import java.lang.annotation.Retention;
    007    import java.lang.annotation.RetentionPolicy;
    008    import java.lang.annotation.Target;
    009
    010    /**
    011     * Annotating an array or iterable-typed field or method with &#064;DataPoints
    012     * will cause the values in the array or iterable given to be used as potential
    013     * parameters for theories in that class when run with the
    014     * {@link org.junit.experimental.theories.Theories Theories} runner.
    015     * <p>
    016     * DataPoints will only be considered as potential values for parameters for
    017     * which their types are assignable. When multiple sets of DataPoints exist with
    018     * overlapping types more control can be obtained by naming the DataPoints using
    019     * the value of this annotation, e.g. with
    020     * <code>&#064;DataPoints({"dataset1", "dataset2"})</code>, and then specifying
    021     * which named set to consider as potential values for each parameter using the
    022     * {@link org.junit.experimental.theories.FromDataPoints &#064;FromDataPoints}
    023     * annotation.
    024     * <p>
    025     * Parameters with no specified source (i.e. without &#064;FromDataPoints or
    026     * other {@link org.junit.experimental.theories.ParametersSuppliedBy
    027     * &#064;ParameterSuppliedBy} annotations) will use all DataPoints that are
    028     * assignable to the parameter type as potential values, including named sets of
    029     * DataPoints.
    030     * <p>
    031     * DataPoints methods whose array types aren't assignable from the target
    032     * parameter type (and so can't possibly return relevant values) will not be
    033     * called when generating values for that parameter. Iterable-typed datapoints
    034     * methods must always be called though, as this information is not available
    035     * here after generic type erasure, so expensive methods returning iterable
    036     * datapoints are a bad idea.
    037     *
    038     * <pre>
    039     * &#064;DataPoints
    040     * public static String[] dataPoints = new String[] { ... };
    041     *
    042     * &#064;DataPoints
    043     * public static String[] generatedDataPoints() {
    044     *     return new String[] { ... };
    045     * }
    046     *
    047     * &#064;Theory
    048     * public void theoryMethod(String param) {
    049     *     ...
    050     * }
    051     * </pre>
    052     *
    053     * @see org.junit.experimental.theories.Theories
    054     * @see org.junit.experimental.theories.Theory
    055     * @see org.junit.experimental.theories.DataPoint
    056     * @see org.junit.experimental.theories.FromDataPoints
    057     */
    058    @Retention(RetentionPolicy.RUNTIME)
    059    @Target({ FIELD, METHOD })
    060    public @interface DataPoints {
    061        String[] value() default {};
    062
    063        Class<? extends Throwable>[] ignoredExceptions() default {};
    064    }