001package org.junit.experimental.theories;
002
003import static java.lang.annotation.ElementType.FIELD;
004import static java.lang.annotation.ElementType.METHOD;
005
006import java.lang.annotation.Retention;
007import java.lang.annotation.RetentionPolicy;
008import 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 })
060public @interface DataPoints {
061    String[] value() default {};
062
063    Class<? extends Throwable>[] ignoredExceptions() default {};
064}