001package org.junit.experimental.theories;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import java.lang.annotation.Target;
007
008import org.junit.experimental.theories.internal.SpecificDataPointsSupplier;
009
010/**
011 * Annotating a parameter of a {@link org.junit.experimental.theories.Theory
012 * &#064;Theory} method with <code>&#064;FromDataPoints</code> will limit the
013 * datapoints considered as potential values for that parameter to just the
014 * {@link org.junit.experimental.theories.DataPoints DataPoints} with the given
015 * name. DataPoint names can be given as the value parameter of the
016 * &#064;DataPoints annotation.
017 * <p>
018 * DataPoints without names will not be considered as values for any parameters
019 * annotated with &#064;FromDataPoints.
020 * <pre>
021 * &#064;DataPoints
022 * public static String[] unnamed = new String[] { ... };
023 * 
024 * &#064;DataPoints("regexes")
025 * public static String[] regexStrings = new String[] { ... };
026 * 
027 * &#064;DataPoints({"forMatching", "alphanumeric"})
028 * public static String[] testStrings = new String[] { ... }; 
029 * 
030 * &#064;Theory
031 * public void stringTheory(String param) {
032 *     // This will be called with every value in 'regexStrings',
033 *     // 'testStrings' and 'unnamed'.
034 * }
035 * 
036 * &#064;Theory
037 * public void regexTheory(&#064;FromDataPoints("regexes") String regex,
038 *                         &#064;FromDataPoints("forMatching") String value) {
039 *     // This will be called with only the values in 'regexStrings' as 
040 *     // regex, only the values in 'testStrings' as value, and none 
041 *     // of the values in 'unnamed'.
042 * }
043 * </pre>
044 * 
045 * @see org.junit.experimental.theories.Theory
046 * @see org.junit.experimental.theories.DataPoint
047 * @see org.junit.experimental.theories.DataPoints
048 */
049@Retention(RetentionPolicy.RUNTIME)
050@Target(ElementType.PARAMETER)
051@ParametersSuppliedBy(SpecificDataPointsSupplier.class)
052public @interface FromDataPoints {
053    String value();
054}