org.reflections

Class Reflections

java.lang.Object

org.reflections.Reflections

public class Reflections
extends Object

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/constructors/methods/fields annotated with some annotation, optionally with annotation parameters matching
• get all resources matching matching a regular expression
• get all methods with specific signature including parameters, parameter annotations and return type
• get all methods parameter names
• get all fields/methods/constructors usages in code

A typical use of Reflections would be:

      Reflections reflections = new Reflections("my.project.prefix");

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

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

Basically, to use Reflections first instantiate it with one of the constructors, then depending on the scanners, use the convenient query methods:

      Reflections reflections = new Reflections("my.package.prefix");
      //or
      Reflections reflections = new Reflections(ClasspathHelper.forPackage("my.package.prefix"), 
            new SubTypesScanner(), new TypesAnnotationScanner(), new FilterBuilder().include(...), ...);

       //or using the ConfigurationBuilder
       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(optionalFilter), ...));
 

And then query, for example:

       Set<Class<? extends Module>> modules = reflections.getSubTypesOf(com.google.inject.Module.class);
       Set<Class<?>> singletons =             reflections.getTypesAnnotatedWith(javax.inject.Singleton.class);

       Set<String> properties =       reflections.getResources(Pattern.compile(".\*\.properties"));
       Set<Constructor> injectables = reflections.getConstructorsAnnotatedWith(javax.inject.Inject.class);
       Set<Method> deprecateds =      reflections.getMethodsAnnotatedWith(javax.ws.rs.Path.class);
       Set<Field> ids =               reflections.getFieldsAnnotatedWith(javax.persistence.Id.class);

       Set<Method> someMethods =      reflections.getMethodsMatchParams(long.class, int.class);
       Set<Method> voidMethods =      reflections.getMethodsReturn(void.class);
       Set<Method> pathParamMethods = reflections.getMethodsWithAnyParamAnnotated(PathParam.class);
       Set<Method> floatToString =    reflections.getConverters(Float.class, String.class);
       List<String> parameterNames =  reflections.getMethodsParamNames(Method.class);

       Set<Member> fieldUsage =       reflections.getFieldUsage(Field.class);
       Set<Member> methodUsage =      reflections.getMethodUsage(Method.class);
       Set<Member> constructorUsage = reflections.getConstructorUsage(Constructor.class);
 

You can use other scanners defined in Reflections as well, such as: SubTypesScanner, TypeAnnotationsScanner (both default), ResourcesScanner, MethodAnnotationsScanner, ConstructorAnnotationsScanner, FieldAnnotationsScanner, MethodParameterScanner, MethodParameterNamesScanner, MemberUsageScanner or any custom scanner.

Use getStore() to access and query the store directly

In order to save the store 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...)}

Make sure to scan all the transitively relevant packages.
for instance, given your class C extends B extends A, and both B and A are located in another package than C, when only the package of C is scanned - then querying for sub types of A returns nothing (transitive), but querying for sub types of B returns C (direct). In that case make sure to scan all relevant packages a priori.

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

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Reflections()
	Reflections(Configuration configuration) constructs a Reflections instance and scan according to given Configuration
	Reflections(Object... params) a convenient constructor for Reflections, where given Object... parameter types can be either: String - would add urls using ClasspathHelper.forPackage(String, ClassLoader...) ()} Class - would add urls using ClasspathHelper.forClass(Class, ClassLoader...) ClassLoader - would use this classloaders in order to find urls in ClasspathHelper.forPackage(String, ClassLoader...) and ClasspathHelper.forClass(Class, ClassLoader...) Scanner - would use given scanner, overriding the default scanners URL - would add the given url for scanning Object[] - would use each element as above use any parameter type in any order.
	Reflections(String prefix, Scanner... scanners) a convenient constructor for scanning within a package prefix.

Method Summary

Modifier and Type	Method and Description
static Reflections	collect() collect saved Reflection xml resources and merge it into a Reflections instance
Reflections	collect(File file) merges saved Reflections resources from the given file, using the serializer configured in this instance's Configuration
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(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
protected Iterable<String>	getAllAnnotated(Iterable<String> annotated, boolean inherited, boolean honorInherited)
Set<String>	getAllTypes() get all types scanned.
Configuration	getConfiguration() returns the Configuration object of this instance
List<String>	getConstructorParamNames(Constructor constructor) get parameter names of given constructor
Set<Constructor>	getConstructorsAnnotatedWith(Annotation annotation) get all constructors annotated with a given annotation, including annotation member values matching depends on MethodAnnotationsScanner configured
Set<Constructor>	getConstructorsAnnotatedWith(Class<? extends Annotation> annotation) get all constructors annotated with a given annotation depends on MethodAnnotationsScanner configured
Set<Constructor>	getConstructorsMatchParams(Class<?>... types) get constructors with parameter types matching given types
Set<Constructor>	getConstructorsWithAnyParamAnnotated(Annotation annotation) get constructors with any parameter annotated with given annotation, including annotation member values matching
Set<Constructor>	getConstructorsWithAnyParamAnnotated(Class<? extends Annotation> annotation) get constructors with any parameter annotated with given annotation
Set<Member>	getConstructorUsage(Constructor constructor) get all given constructors usages in methods and constructors
Set<Field>	getFieldsAnnotatedWith(Annotation annotation) get all methods annotated with a given annotation, including annotation member values matching depends on FieldAnnotationsScanner configured
Set<Field>	getFieldsAnnotatedWith(Class<? extends Annotation> annotation) get all fields annotated with a given annotation depends on FieldAnnotationsScanner configured
Set<Member>	getFieldUsage(Field field) get all given field usages in methods and constructors
List<String>	getMethodParamNames(Method method) get parameter names of given method
Set<Method>	getMethodsAnnotatedWith(Annotation annotation) get all methods annotated with a given annotation, including annotation member values matching depends on MethodAnnotationsScanner configured
Set<Method>	getMethodsAnnotatedWith(Class<? extends Annotation> annotation) get all methods annotated with a given annotation depends on MethodAnnotationsScanner configured
Set<Method>	getMethodsMatchParams(Class<?>... types) get methods with parameter types matching given types
Set<Method>	getMethodsReturn(Class returnType) get methods with return type match given type
Set<Method>	getMethodsWithAnyParamAnnotated(Annotation annotation) get methods with any parameter annotated with given annotation, including annotation member values matching
Set<Method>	getMethodsWithAnyParamAnnotated(Class<? extends Annotation> annotation) get methods with any parameter annotated with given annotation
Set<Member>	getMethodUsage(Method method) get all given method usages in methods and constructors
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
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()
protected void	scan(URL url)

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

store

protected Store store

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(Object... params)

a convenient constructor for Reflections, where given Object... parameter types can be either:

• String - would add urls using ClasspathHelper.forPackage(String, ClassLoader...) ()}
• Class - would add urls using ClasspathHelper.forClass(Class, ClassLoader...)
• ClassLoader - would use this classloaders in order to find urls in ClasspathHelper.forPackage(String, ClassLoader...) and ClasspathHelper.forClass(Class, ClassLoader...)
• Scanner - would use given scanner, overriding the default scanners
• URL - would add the given url for scanning
• Object[] - would use each element as above

use any parameter type in any order. this constructor uses instanceof on each param and instantiate a ConfigurationBuilder appropriately. if you prefer the usual statically typed constructor, don't use this, although it can be very useful.

for example:

     new Reflections("my.package", classLoader);
     //or
     new Reflections("my.package", someScanner, anotherScanner, classLoader);
     //or
     new Reflections(myUrl, myOtherUrl);
 

Reflections

protected Reflections()

Method Detail

scan

protected void scan()

scan

protected void scan(URL url)

collect

public static Reflections collect()

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

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 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

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

getTypesAnnotatedWith

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

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

Inherited is not honored by default.

when honoring @Inherited, meta-annotation should only effect annotated super classes and its sub types

Note that this (@Inherited) meta-annotation type has no effect if the annotated type is used for anything other then 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

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.

when honoring @Inherited, meta-annotation should only effect annotated super classes and it's sub types

when not honoring @Inherited, meta annotation effects all subtypes, including annotations interfaces and classes

Note that this (@Inherited) meta-annotation type has no effect if the annotated type is used for anything other then 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

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 not honored by default

depends on TypeAnnotationsScanner configured

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

getAllAnnotated

protected Iterable<String> getAllAnnotated(Iterable<String> annotated,
                                           boolean inherited,
                                           boolean honorInherited)

getMethodsAnnotatedWith

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

get all methods annotated with a given annotation

depends on MethodAnnotationsScanner configured

getMethodsAnnotatedWith

public Set<Method> getMethodsAnnotatedWith(Annotation annotation)

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

depends on MethodAnnotationsScanner configured

getMethodsMatchParams

public Set<Method> getMethodsMatchParams(Class<?>... types)

get methods with parameter types matching given types

getMethodsReturn

public Set<Method> getMethodsReturn(Class returnType)

get methods with return type match given type

getMethodsWithAnyParamAnnotated

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

get methods with any parameter annotated with given annotation

getMethodsWithAnyParamAnnotated

public Set<Method> getMethodsWithAnyParamAnnotated(Annotation annotation)

get methods with any parameter annotated with given annotation, including annotation member values matching

getConstructorsAnnotatedWith

public Set<Constructor> getConstructorsAnnotatedWith(Class<? extends Annotation> annotation)

get all constructors annotated with a given annotation

depends on MethodAnnotationsScanner configured

getConstructorsAnnotatedWith

public Set<Constructor> getConstructorsAnnotatedWith(Annotation annotation)

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

depends on MethodAnnotationsScanner configured

getConstructorsMatchParams

public Set<Constructor> getConstructorsMatchParams(Class<?>... types)

get constructors with parameter types matching given types

getConstructorsWithAnyParamAnnotated

public Set<Constructor> getConstructorsWithAnyParamAnnotated(Class<? extends Annotation> annotation)

get constructors with any parameter annotated with given annotation

getConstructorsWithAnyParamAnnotated

public Set<Constructor> getConstructorsWithAnyParamAnnotated(Annotation annotation)

get constructors with any parameter annotated with given annotation, including annotation member values matching

getFieldsAnnotatedWith

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

get all fields annotated with a given annotation

depends on FieldAnnotationsScanner configured

getFieldsAnnotatedWith

public Set<Field> getFieldsAnnotatedWith(Annotation annotation)

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

depends on FieldAnnotationsScanner configured

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

getResources

public Set<String> getResources(Pattern pattern)

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

depends on ResourcesScanner configured

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

getMethodParamNames

public List<String> getMethodParamNames(Method method)

get parameter names of given method

depends on MethodParameterNamesScanner configured

getConstructorParamNames

public List<String> getConstructorParamNames(Constructor constructor)

get parameter names of given constructor

depends on MethodParameterNamesScanner configured

getFieldUsage

public Set<Member> getFieldUsage(Field field)

get all given field usages in methods and constructors

depends on MemberUsageScanner configured

getMethodUsage

public Set<Member> getMethodUsage(Method method)

get all given method usages in methods and constructors

depends on MemberUsageScanner configured

getConstructorUsage

public Set<Member> getConstructorUsage(Constructor constructor)

get all given constructors usages in methods and constructors

depends on MemberUsageScanner configured

getAllTypes

public Set<String> getAllTypes()

get all types scanned. this is effectively similar to getting all subtypes of Object.

depends on SubTypesScanner configured with SubTypesScanner(false), otherwise ReflectionsException is thrown

note using this might be a bad practice. it is better to get types matching some criteria, such as getSubTypesOf(Class) or getTypesAnnotatedWith(Class)

Returns:

Set of String, and not of Class, in order to avoid definition of all types in PermGen

getStore

public Store getStore()

returns the Store used for storing and querying the metadata

getConfiguration

public Configuration getConfiguration()

returns the Configuration object of this instance

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