You could easily modify this to load a bean from a Spring Context, read a properties file, get data from a database, ...

Use the  custom supplier

Let's use this new supplier and fix our test case:

@RunWith(Theories.class)
public class GuessTheMurdererTest {
    @DataPointsRef("suspects")
    public static String[] whoMadeIt = {
        "Miss Rose", "Mrs. Peacock", "Professor Plum"
    };
    @DataPointsRef("rooms")
    public static String[] whereWasIt = {
        "Library", "Lounge"
    };

    @Theory
    public void dummyTest(
    @WithDataPoints(clazz=GuessTheMurdererTest.class, name="suspects")
    String murderer,
    @WithDataPoints(clazz=GuessTheMurdererTest.class, name="rooms")
    String murderScene) {
        System.out.println(String.format("%s murdered Colonel Mustard in the %s", murderer, murderScene));
    }
}

Our @Datapoints can now have a name, and the @Theory parameters get a new annotation referencing this name.

If we run this test, we get this output:

Miss Rose murdered Colonel Mustard in the Library
Miss Rose murdered Colonel Mustard in the Lounge
Mrs. Peacock murdered Colonel Mustard in the Library
Mrs. Peacock murdered Colonel Mustard in the Lounge
Professor Plum murdered Colonel Mustard in the Library
Professor Plum murdered Colonel Mustard in the Lounge

Much better...

Let's push it just a little more...
We just purchased the new edition of the game, new suspects are available...

@RunWith(Theories.class)
public class GuessTheMurdererTest {
    @DataPointsRef("suspects")
    public static String[] whoMadeIt = {
        "Miss Rose", "Mrs. Peacock", "Professor Plum"
    }
    ;
    @DataPointsRef("suspects")
    public static String[] orMaybeItWasSomeoneElse = {
        "Mr. Slate-Grey", "Captain Brown"
    }
    ;
    @DataPointsRef("rooms")
    public static String[] whereWasIt = {
        "Hall", "Kitchen"
    }
    ;
    @Theory
    public void dummyTest(
    @WithDataPoints(clazz=GuessTheMurdererTest.class, name="suspects")
    String murderer,
    @WithDataPoints(clazz=GuessTheMurdererTest.class, name="rooms")
    String murderScene) {
        System.out.println(String.format("%s murdered Colonel Mustard in the %s", murderer, murderScene));
    }
}

Miss Rose murdered Colonel Mustard in the Hall
Miss Rose murdered Colonel Mustard in the Kitchen
Mrs. Peacock murdered Colonel Mustard in the Hall
Mrs. Peacock murdered Colonel Mustard in the Kitchen
Professor Plum murdered Colonel Mustard in the Hall
Professor Plum murdered Colonel Mustard in the Kitchen
Mr. Slate-Grey murdered Colonel Mustard in the Hall
Mr. Slate-Grey murdered Colonel Mustard in the Kitchen
Captain Brown murdered Colonel Mustard in the Hall
Captain Brown murdered Colonel Mustard in the Kitchen

Good! Datapoints values are now aggregated by name rather than type.

Enhancing the custom supplier: introducing "Tags"

Suppose we buy yet another game's extention, the murderer now has an accomplice.
Some suspects can only be "murderers", some can only be "accomplices", some can be both "murderer" or "accomplice"

We could easily imagine extending the Supplier to add multiple "tags" to a @Datapoint.
Let's modify our annotations and supplier:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface TaggedDataPoints {
    //Multiple values allowed
    String[] value();
}

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
@ParametersSuppliedBy(TaggedDataPointsSupplier.class)
public @interface WithTags {
    Class<?> clazz();
    String name();
}
public static class TaggedDataPointsSupplier extends ParameterSupplier {
    @Override
    public List<PotentialAssignment> getValueSources(ParameterSignature sig) {
        List<PotentialAssignment> list = new ArrayList<PotentialAssignment>();
        WithTags withTag = (WithTags) sig.getAnnotation(WithTags.class);
        Field[] fields = withTag.clazz().getFields();
        for (Field field : fields) {
            TaggedDataPoints taggedDataPoints = field.getAnnotation(TaggedDataPoints.class);
            if (taggedDataPoints != null) {
                //browse tags, an select values if one matches
                for (String tag : taggedDataPoints.value()) {
                    if (tag.equals(withTag.name())) {
                        Class<?> fieldType = field.getType();
                        if (!fieldType.isArray()) {
                            throw new RuntimeException("Referenced Datapoint must be an array.");
                        }
                        try {
                            Object values = field.get(null);
                            for (int i = 0; i < Array.getLength(values); i++) {
                                Object value = Array.get(values, i);
                                list.add(PotentialAssignment.forValue(withTag.name(), value));
                            }
                        }
                        catch (IllegalArgumentException e) {
                            throw new RuntimeException(e);
                        }
                        catch (IllegalAccessException e) {
                            throw new RuntimeException(e);
                        }
                    }
                }
            }
        }
        return list;
    }
}

We can now distinguish those new "suspects" and "accomplices", and add an accomplice to the @Theory:

@RunWith(Theories.class)
public class GuessTheMurdererTest {
    @TaggedDataPoints("suspects")
    public static String[] suscpectsOnly = {
        "Miss Rose", "Mrs. Peacock", "Professor Plum"
    };
    @TaggedDataPoints({ "suspects", "accomplices" })
    public static String[] suspectsOrAccomplices = {
        "Mr. Slate-Grey"
    };
    @TaggedDataPoints("accomplices")
    public static String[] accomplicesOnly = {
        "Captain Brown"
    };
    @TaggedDataPoints("rooms")
    public static String[] whereWasIt = {
        "Hall", "Kitchen"
    };

    @Theory
    public void dummyTest(
    @WithTags(clazz = GuessTheMurdererTest.class, name = "suspects") String murderer,
    @WithTags(clazz = GuessTheMurdererTest.class, name = "accomplices") String accomplice,
    @WithTags(clazz = GuessTheMurdererTest.class, name = "rooms") String murderScene) {
        // Ensure no-one is accompliced to himself...
        Assume.assumeTrue(!murderer.equalsIgnoreCase(accomplice));
        System.out.println(String.format("%s and his/her accomplice %s both murdered Colonel Mustard in the %s", murderer, accomplice, murderScene));
        // Assert that Captain brown cannot be the murderer
        Assert.assertFalse(murderer.equalsIgnoreCase("Captain Brown"));
        // Assert that Professor Plum cannot be an accomplice
        Assert.assertFalse(accomplice.equalsIgnoreCase("Professor Plum"));
    }
}

If everything went fine, asserts are all ok, and you get:

Miss Rose and his/her accomplice Mr. Slate-Grey both murdered Colonel Mustard in the Hall
Miss Rose and his/her accomplice Mr. Slate-Grey both murdered Colonel Mustard in the Kitchen
Miss Rose and his/her accomplice Captain Brown both murdered Colonel Mustard in the Hall
Miss Rose and his/her accomplice Captain Brown both murdered Colonel Mustard in the Kitchen
Mrs. Peacock and his/her accomplice Mr. Slate-Grey both murdered Colonel Mustard in the Hall
Mrs. Peacock and his/her accomplice Mr. Slate-Grey both murdered Colonel Mustard in the Kitchen
Mrs. Peacock and his/her accomplice Captain Brown both murdered Colonel Mustard in the Hall
Mrs. Peacock and his/her accomplice Captain Brown both murdered Colonel Mustard in the Kitchen
Professor Plum and his/her accomplice Mr. Slate-Grey both murdered Colonel Mustard in the Hall
Professor Plum and his/her accomplice Mr. Slate-Grey both murdered Colonel Mustard in the Kitchen
Professor Plum and his/her accomplice Captain Brown both murdered Colonel Mustard in the Hall
Professor Plum and his/her accomplice Captain Brown both murdered Colonel Mustard in the Kitchen
Mr. Slate-Grey and his/her accomplice Captain Brown both murdered Colonel Mustard in the Hall
Mr. Slate-Grey and his/her accomplice Captain Brown both murdered Colonel Mustard in the Kitchen

Pretty nice isn't it?

A few final words...

This could give you a neat way of dividing values of a same list according to a fonctional property.

Suppose we get a "Folder" list, some of them are "Input folders", some others are "Output folders", and a few are "Input/Output folders"
Of course, ideally, you would create different objects, but if the tested method just takes two String, that's a lot of boilerplate...

Additionally, this could be used as an easy way to qualify the test dataitself, some information that does not belong to the "Domain", but belongs to the test itself.
eg: you might want to test some theories against only a subset of the @Datapoints.

Well, that's it for today, I hope this article gave you some insights on how you can use @Theory, and how you can improve the data you feed to it using custom suppliers.