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 @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    }