org.reflections

Class Reflections

java.lang.Object

org.reflections.ReflectionUtils

org.reflections.Reflections

public class Reflections
extends ReflectionUtils

Reflections one-stop-shop object

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

a typical use of Reflections would be:

 Reflections reflections = new Reflections("my.package.prefix"); //replace my.package.prefix with your package prefix, of course

 Set<Class<? extends SomeType>> subTypes = reflections.getSubTypesOf(SomeType.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;}});
 

basically, to use Reflections for scanning and querying, instantiate it with a Configuration, for example

      new Reflections(
          new ConfigurationBuilder()
              .filterInputsBy(new FilterBuilder().include("your project's common package prefix here..."))
              .setUrls(ClasspathHelper.forClassLoader())
              .setScanners(new SubTypesScanner(), new TypeAnnotationsScanner()));
 

and than use the convenient methods to query the metadata, such as getSubTypesOf(java.lang.Class<T>), getTypesAnnotatedWith(java.lang.Class<? extends java.lang.annotation.Annotation>), getMethodsAnnotatedWith(java.lang.Class<? extends java.lang.annotation.Annotation>), getFieldsAnnotatedWith(java.lang.Class<? extends java.lang.annotation.Annotation>), getResources(com.google.common.base.Predicate<java.lang.String>)
use getStore() to access and query the store directly

in order to save a metadata use save(String) or save(String, org.reflections.serializers.Serializer) for example with XmlSerializer or JavaCodeSerializer

in order to collect pre saved metadata and avoid re-scanning, use collect(String, com.google.common.base.Predicate, org.reflections.serializers.Serializer...)}

* be aware that when using the constructor new Reflections("my.package"), only urls with prefix 'my.package' will be scanned, and any transitive classes in other urls will not be scanned (for example if my.package.SomeClass extends other.package.OtherClass, than the later will not be scanned). in that case use the other constructors and specify the relevant packages/urls Reflections(Object[], org.reflections.scanners.Scanner...)()} or Reflections(Configuration)

For Javadoc, source code, and more information about Reflections Library, see http://code.google.com/p/reflections/

Field Summary

Fields

Modifier and Type	Field and Description
protected Configuration	configuration
static org.slf4j.Logger	log

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Reflections()
	Reflections(Configuration configuration) constructs a Reflections instance and scan according to given Configuration
	Reflections(Object[] urlHints, Scanner... scanners) a convenient constructor for scanning within given package prefixes and/or urls containing given classes.
	Reflections(String[] prefixes, Scanner... scanners) a convenient constructor for scanning within given package prefixes.
	Reflections(String prefix, Scanner... scanners) a convenient constructor for scanning within a package prefix.

Method Summary

Methods

Modifier and Type	Method and Description
Reflections	collect(File file) merges saved Reflections resources from the given file, using the serializer configured in this instance's Configuration useful if you know the serialized resource location and prefer not to look it up the classpath
Reflections	collect(InputStream inputStream) merges saved Reflections resources from the given input stream, using the serializer configured in this instance's Configuration useful if you know the serialized resource location and prefer not to look it up the classpath
static Reflections	collect(Serializer... optionalSerializer) collect saved Reflection xml resources and merge it into a Reflections instance
static Reflections	collect(String packagePrefix, com.google.common.base.Predicate<String> resourceNameFilter, Serializer... optionalSerializer) collect saved Reflections resources from all urls that contains the given packagePrefix and matches the given resourceNameFilter and de-serializes them using the default serializer XmlSerializer or using the optionally supplied optionalSerializer
static Reflections	collect(String packagePrefix, com.google.common.base.Predicate<String> resourceNameFilter, Serializer serializer) collect saved Reflections resources from all urls that contains the given packagePrefix and matches the given resourceNameFilter and de-serializes them using the serializer configured in the configuration
<T extends Scanner> T	get(Class<T> scannerClass)
Set<Field>	getFieldsAnnotatedWith(Annotation annotation) get all methods annotated with a given annotation, including annotation member values matching depends on FieldAnnotationsScanner configured, otherwise an empty set is returned
Set<Field>	getFieldsAnnotatedWith(Class<? extends Annotation> annotation) get all fields annotated with a given annotation depends on FieldAnnotationsScanner configured, otherwise an empty set is returned
Set<Method>	getMethodsAnnotatedWith(Annotation annotation) get all methods annotated with a given annotation, including annotation member values matching depends on MethodAnnotationsScanner configured, otherwise an empty set is returned
Set<Method>	getMethodsAnnotatedWith(Class<? extends Annotation> annotation) get all methods annotated with a given annotation depends on MethodAnnotationsScanner configured, otherwise an empty set is returned
Set<String>	getResources(Pattern pattern) get resources relative paths where simple name (key) matches given regular expression
Set<String>	getResources(com.google.common.base.Predicate<String> namePredicate) get resources relative paths where simple name (key) matches given namePredicate
Store	getStore() returns the store used for storing and querying the metadata
<T> Set<Class<? extends T>>	getSubTypesOf(Class<T> type) gets all sub types in hierarchy of a given type depends on SubTypesScanner configured, otherwise an empty set is returned
Set<Class<?>>	getTypesAnnotatedWith(Annotation annotation) get types annotated with a given annotation, both classes and annotations, including annotation member values matching
Set<Class<?>>	getTypesAnnotatedWith(Annotation annotation, boolean honorInherited) get types annotated with a given annotation, both classes and annotations, including annotation member values matching
Set<Class<?>>	getTypesAnnotatedWith(Class<? extends Annotation> annotation) get types annotated with a given annotation, both classes and annotations
Set<Class<?>>	getTypesAnnotatedWith(Class<? extends Annotation> annotation, boolean honorInherited) get types annotated with a given annotation, both classes and annotations
Reflections	merge(Reflections reflections) merges a Reflections instance metadata into this instance
File	save(String filename) serialize to a given directory and filename
File	save(String filename, Serializer serializer) serialize to a given directory and filename using given serializer
protected void	scan()

Methods inherited from class org.reflections.ReflectionUtils

areAnnotationMembersMatching, forName, forNames, getAll, getAllFields, getAllFields, getAllMethods, getAllMethods, getAllSuperTypes, getAllSuperTypes, getMatchingAnnotations, getPrimitiveDescriptors, getPrimitiveNames, getPrimitiveTypes, names, withAnnotation, withAnnotation, withAnnotations, withAnnotations, withModifier, withName, withParameterAnnotations, withParameterAnnotations, withParameters, withParametersAssignableTo, withParametersCount, withPrefix, withReturnType, withReturnTypeAssignableTo, withType, withTypeAssignableTo

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

@Nullable
public static org.slf4j.Logger log

configuration

protected final transient Configuration configuration

Constructor Detail

Reflections

public Reflections(Configuration configuration)

constructs a Reflections instance and scan according to given Configuration

it is preferred to use ConfigurationBuilder

Reflections

public Reflections(String prefix,
           @Nullable
           Scanner... scanners)

a convenient constructor for scanning within a package prefix.

this actually create a Configuration with:
- urls that contain resources with name prefix
- filterInputsBy where name starts with the given prefix
- scanners set to the given scanners, otherwise defaults to TypeAnnotationsScanner and SubTypesScanner.

Parameters:

prefix - package prefix, to be used with ClasspathHelper.forPackage(String, ClassLoader...) )}

scanners - optionally supply scanners, otherwise defaults to TypeAnnotationsScanner and SubTypesScanner

Reflections

public Reflections(String[] prefixes,
           @Nullable
           Scanner... scanners)

a convenient constructor for scanning within given package prefixes.
for example

 Reflections reflections = new Reflections(new String[] {"my.package.prefix", "my.other.package.prefix"});
 

this actually create a Configuration with:
- urls that contain resources with prefixes prefixes
- filterInputsBy to include names starting with the given prefixes
- scanners set to the given scanners, otherwise defaults to TypeAnnotationsScanner and SubTypesScanner.

Parameters:

prefixes - string array of package prefixes, to be used with ClasspathHelper.forPackage(String, ClassLoader...) )}

scanners - optionally supply scanners, otherwise defaults to TypeAnnotationsScanner and SubTypesScanner

Reflections

public Reflections(Object[] urlHints,
           @Nullable
           Scanner... scanners)

a convenient constructor for scanning within given package prefixes and/or urls containing given classes.

given urlHints is an array of either String or Class elements, where Strings results in scanning package prefix and Class results in scanning url that contains that class, for example

     new Reflections(new Object[] {"my.package", com.google.inject.Module.class, "javax.persistence"})
 

would result in scanning packages 'my.package' and 'javax.persistence' and also the url that contains the class of com.google.inject.Module

this actually create a Configuration with:
- urls that contain resources with name prefix or that contains given classes
- acceptsInput where name starts with the given prefix or with the classes package name
- scanners set to the given scanners, otherwise defaults to TypeAnnotationsScanner and SubTypesScanner.

Parameters:

urlHints - is an array of either String or Class elements, where Strings results in scanning package prefix and Class results in scanning urls containing the class

scanners - optionally supply scanners, otherwise defaults to TypeAnnotationsScanner and SubTypesScanner

Reflections

protected Reflections()

Method Detail

scan

protected void scan()

collect

public static Reflections collect(@Nullable
                  Serializer... optionalSerializer)

collect saved Reflection xml resources and merge it into a Reflections instance

by default, resources are collected from all urls that contains the package META-INF/reflections and includes files matching the pattern .*-reflections.xml

Parameters:

optionalSerializer - - optionally supply one serializer instance. if not specified or null, XmlSerializer will be used

collect

public static Reflections collect(String packagePrefix,
                  com.google.common.base.Predicate<String> resourceNameFilter,
                  @Nullable
                  Serializer... optionalSerializer)

collect saved Reflections resources from all urls that contains the given packagePrefix and matches the given resourceNameFilter and de-serializes them using the default serializer XmlSerializer or using the optionally supplied optionalSerializer

it is preferred to use a designated resource prefix (for example META-INF/reflections but not just META-INF), so that relevant urls could be found much faster

Parameters:

optionalSerializer - - optionally supply one serializer instance. if not specified or null, XmlSerializer will be used

collect

public static Reflections collect(String packagePrefix,
                  com.google.common.base.Predicate<String> resourceNameFilter,
                  Serializer serializer)

collect saved Reflections resources from all urls that contains the given packagePrefix and matches the given resourceNameFilter and de-serializes them using the serializer configured in the configuration

it is preferred to use a designated resource prefix (for example META-INF/reflections but not just META-INF), so that relevant urls could be found much faster

collect

public Reflections collect(InputStream inputStream)

merges saved Reflections resources from the given input stream, using the serializer configured in this instance's Configuration
useful if you know the serialized resource location and prefer not to look it up the classpath

collect

public Reflections collect(File file)

merges saved Reflections resources from the given file, using the serializer configured in this instance's Configuration useful if you know the serialized resource location and prefer not to look it up the classpath

merge

public Reflections merge(Reflections reflections)

merges a Reflections instance metadata into this instance

get

@Nullable
public <T extends Scanner> T get(Class<T> scannerClass)

getSubTypesOf

public <T> Set<Class<? extends T>> getSubTypesOf(Class<T> type)

gets all sub types in hierarchy of a given type

depends on SubTypesScanner configured, otherwise an empty set is returned

getTypesAnnotatedWith

public Set<Class<?>> getTypesAnnotatedWith(Class<? extends Annotation> annotation)

get types annotated with a given annotation, both classes and annotations

Inherited is honored

Note that this (@Inherited) meta-annotation type has no effect if the annotated type is used for anything other than a class. Also, this meta-annotation causes annotations to be inherited only from superclasses; annotations on implemented interfaces have no effect.

depends on TypeAnnotationsScanner and SubTypesScanner configured, otherwise an empty set is returned

getTypesAnnotatedWith

public Set<Class<?>> getTypesAnnotatedWith(Class<? extends Annotation> annotation,
                                  boolean honorInherited)

get types annotated with a given annotation, both classes and annotations

Inherited is honored according to given honorInherited

Note that this (@Inherited) meta-annotation type has no effect if the annotated type is used for anything other than a class. Also, this meta-annotation causes annotations to be inherited only from superclasses; annotations on implemented interfaces have no effect.

depends on TypeAnnotationsScanner and SubTypesScanner configured, otherwise an empty set is returned

getTypesAnnotatedWith

public Set<Class<?>> getTypesAnnotatedWith(Annotation annotation)

get types annotated with a given annotation, both classes and annotations, including annotation member values matching

Inherited is honored

depends on TypeAnnotationsScanner configured, otherwise an empty set is returned

getTypesAnnotatedWith

public Set<Class<?>> getTypesAnnotatedWith(Annotation annotation,
                                  boolean honorInherited)

get types annotated with a given annotation, both classes and annotations, including annotation member values matching

Inherited is honored according to given honorInherited

depends on TypeAnnotationsScanner configured, otherwise an empty set is returned

getMethodsAnnotatedWith

public Set<Method> getMethodsAnnotatedWith(Class<? extends Annotation> annotation)

get all methods annotated with a given annotation

depends on MethodAnnotationsScanner configured, otherwise an empty set is returned

getMethodsAnnotatedWith

public Set<Method> getMethodsAnnotatedWith(Annotation annotation)

get all methods annotated with a given annotation, including annotation member values matching

depends on MethodAnnotationsScanner configured, otherwise an empty set is returned

getFieldsAnnotatedWith

public Set<Field> getFieldsAnnotatedWith(Class<? extends Annotation> annotation)

get all fields annotated with a given annotation

depends on FieldAnnotationsScanner configured, otherwise an empty set is returned

getFieldsAnnotatedWith

public Set<Field> getFieldsAnnotatedWith(Annotation annotation)

get all methods annotated with a given annotation, including annotation member values matching

depends on FieldAnnotationsScanner configured, otherwise an empty set is returned

getResources

public Set<String> getResources(com.google.common.base.Predicate<String> namePredicate)

get resources relative paths where simple name (key) matches given namePredicate

depends on ResourcesScanner configured, otherwise an empty set is returned

getResources

public Set<String> getResources(Pattern pattern)

get resources relative paths where simple name (key) matches given regular expression

depends on ResourcesScanner configured, otherwise an empty set is returned

Set xmls = reflections.getResources(".\*\.xml");

getStore

public Store getStore()

returns the store used for storing and querying the metadata

save

public File save(String filename)

serialize to a given directory and filename

* it is preferred to specify a designated directory (for example META-INF/reflections), so that it could be found later much faster using the load method

see the documentation for the save method on the configured Serializer

save

public File save(String filename,
        Serializer serializer)

serialize to a given directory and filename using given serializer

* it is preferred to specify a designated directory (for example META-INF/reflections), so that it could be found later much faster using the load method