A Java runtime metadata analysis, in the spirit of Scannotations

Reflections scans your classpath, indexes the metadata, allows you to query it on runtime and may save and collect that information for many modules within your project.

Using Reflections you can query your metadata such as:

get all subtypes of some type
get all types/methods/fields annotated with some annotation, w/o annotation parameters matching
get all resources matching matching a regular expression

How to use?

add Reflections to your project. for maven projects just add this dependency:

        <dependency>
            <groupId>org.reflections</groupId>
            <artifactId>reflections</artifactId>
            <version>0.9.5</version>
        </dependency>

otherwise add the relevant jars to your projects, this might help

a typical use of Reflections would be:

     Reflections reflections = new Reflections("my.project.prefix");
     //or
     Reflections reflections = new Reflections(new Object[] {"my.package", com.google.inject.Module, "javax.persistence"});

     Set<Class<? extends SomeClassOrInterface>> subTypes = reflections.getSubTypesOf(SomeClassOrInterface.class);

     Set<Class<?>> annotated = reflections.getTypesAnnotatedWith(SomeAnnotation.class);

     Set<Class<?>> annotated1 = reflections.getTypesAnnotatedWith(
          new SomeAnnotation() {public String value() {return "1";}
                                public Class<? extends Annotation> annotationType() {return SomeAnnotation.class;}});

     Set<String> propertiesFiles = reflections.getResources(Pattern.compile(".*\\.properties")); //depends on ResourcesScanner configured, as on next example

basically, to use Reflections first instantiate it with one of the constructors:

     new Reflections(new ConfigurationBuilder()
          .filterInputsBy(new FilterBuilder.Include(FilterBuilder.prefix("my.project.prefix")))
          .setUrls(ClasspathHelper.forPackage("my.project.prefix"))
          .setScanners(new SubTypesScanner(),
                       new TypeAnnotationsScanner().filterResultsBy(filter),
                       new ResourcesScanner()));

than use the convenient methods to query the metadata, such as:

getSubTypesOf
getTypesAnnotatedWith
getMethodsAnnotatedWith
getFieldsAnnotatedWith
getResources

You can use other scanners defined in Reflections as well, such as: SubTypesScanner, TypeAnnotationsScanner, MethodAnnotationsScanner, FieldAnnotationsScanner, ResourcrsScanner, or write a specialized scanner for your needs

browse the javadoc for more info

also, browse the tests directory to see some more examples

UseCases

Reflections can also:

save scanned metadata and collect it later on runtime, for quick bootstrap of your application
save your model entities metadata - fully qualified name of packages and types, fields and methods - so you can later reference these in a static manner
find all resources matching a regular expression (for example find all .properties files or .xml files)

see the UseCases wiki page

Reflections Maven plugin

There is the ReflectionsMojo Maven plugin available for your project. With simple configuration you can save all scanned metadata into xml files upon compiling. Later on, when your project is bootstrapping you can let Reflections collect all those resources and re-create that metadata for you, making it available at runtime without re-scanning the classpath - thus reducing the bootstrapping time.

Use this maven configuration in your pom file:

    <build>
        <plugins>
            <plugin>
                <groupId>org.reflections</groupId>
                <artifactId>reflections-maven</artifactId>
                <version>the latest version...</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>reflections</goal>
                        </goals>
                        <phase>process-classes</phase>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

than, on runtime:

        Reflections reflections =
                isProduction() ? Reflections.collect() : new Reflections("your.package.here");

Check out in the ReflectionsMojo wiki page

Extending Reflections

You can easily extend Reflections by :

create your specialized scan class, should implement Scanner
provide a query method within that scan class
next, use that scanner instance to first configure Reflections and than to query

patches and extension are welcomed!

Cheers