Class Reflections
- java.lang.Object
-
- org.reflections.Reflections
-
public class Reflections extends Object
Reflections one-stop-shop objectReflections 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 directlyIn order to save the store metadata, use
save(String)
orsave(String, org.reflections.serializers.Serializer)
for example withXmlSerializer
orJavaCodeSerializer
In order to collect pre saved metadata and avoid re-scanning, use
collect(String, java.util.function.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 Description protected Configuration
configuration
static org.slf4j.Logger
log
protected Store
store
-
Constructor Summary
Constructors Modifier Constructor Description protected
Reflections()
Reflections(Object... params)
a convenient constructor for Reflections, where givenObject...
parameter types can be either:String
- would add urls usingClasspathHelper.forPackage(String, ClassLoader...)
()}Class
- would add urls usingClasspathHelper.forClass(Class, ClassLoader...)
ClassLoader
- would use this classloaders in order to find urls inClasspathHelper.forPackage(String, ClassLoader...)
andClasspathHelper.forClass(Class, ClassLoader...)
Scanner
- would use given scanner, overriding the default scannersURL
- would add the given url for scanningObject
- 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.Reflections(Configuration configuration)
constructs a Reflections instance and scan according to givenConfiguration
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Reflections
collect()
collect saved Reflection xml resources and merge it into a Reflections instanceReflections
collect(File file)
merges saved Reflections resources from the given file, using the serializer configured in this instance's ConfigurationReflections
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 classpathstatic Reflections
collect(String packagePrefix, 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 serializerXmlSerializer
or using the optionally supplied optionalSerializervoid
expandSuperTypes()
expand super types after scanning, for super types that were not scanned.protected Collection<String>
getAllAnnotated(Collection<String> annotated, Class<? extends Annotation> annotation, boolean honorInherited)
Set<String>
getAllTypes()
get all types scanned.Configuration
getConfiguration()
returns theConfiguration
object of this instanceList<String>
getConstructorParamNames(Constructor constructor)
get parameter names of givenconstructor
Set<Constructor>
getConstructorsAnnotatedWith(Annotation annotation)
get all constructors annotated with a given annotation, including annotation member values matchingSet<Constructor>
getConstructorsAnnotatedWith(Class<? extends Annotation> annotation)
get all constructors annotated with a given annotationSet<Constructor>
getConstructorsMatchParams(Class<?>... types)
get constructors with parameter types matching giventypes
Set<Constructor>
getConstructorsWithAnyParamAnnotated(Annotation annotation)
get constructors with any parameter annotated with given annotation, including annotation member values matchingSet<Constructor>
getConstructorsWithAnyParamAnnotated(Class<? extends Annotation> annotation)
get constructors with any parameter annotated with given annotationSet<Member>
getConstructorUsage(Constructor constructor)
get all givenconstructors
usages in methods and constructorsSet<Field>
getFieldsAnnotatedWith(Annotation annotation)
get all methods annotated with a given annotation, including annotation member values matchingSet<Field>
getFieldsAnnotatedWith(Class<? extends Annotation> annotation)
get all fields annotated with a given annotationSet<Member>
getFieldUsage(Field field)
get all givenfield
usages in methods and constructorsList<String>
getMethodParamNames(Method method)
get parameter names of givenmethod
Set<Method>
getMethodsAnnotatedWith(Annotation annotation)
get all methods annotated with a given annotation, including annotation member values matchingSet<Method>
getMethodsAnnotatedWith(Class<? extends Annotation> annotation)
get all methods annotated with a given annotationSet<Method>
getMethodsMatchParams(Class<?>... types)
get methods with parameter types matching giventypes
Set<Method>
getMethodsReturn(Class returnType)
get methods with return type match given typeSet<Method>
getMethodsWithAnyParamAnnotated(Annotation annotation)
get methods with any parameter annotated with given annotation, including annotation member values matchingSet<Method>
getMethodsWithAnyParamAnnotated(Class<? extends Annotation> annotation)
get methods with any parameter annotated with given annotationSet<Member>
getMethodUsage(Method method)
get all givenmethod
usages in methods and constructorsSet<String>
getResources(Predicate<String> namePredicate)
get resources relative paths where simple name (key) matches given namePredicateSet<String>
getResources(Pattern pattern)
get resources relative paths where simple name (key) matches given regular expressionStore
getStore()
returns theStore
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 typeSet<Class<?>>
getTypesAnnotatedWith(Annotation annotation)
get types annotated with a given annotation, both classes and annotations, including annotation member values matchingSet<Class<?>>
getTypesAnnotatedWith(Annotation annotation, boolean honorInherited)
get types annotated with a given annotation, both classes and annotations, including annotation member values matchingSet<Class<?>>
getTypesAnnotatedWith(Class<? extends Annotation> annotation)
get types annotated with a given annotation, both classes and annotationsSet<Class<?>>
getTypesAnnotatedWith(Class<? extends Annotation> annotation, boolean honorInherited)
get types annotated with a given annotation, both classes and annotationsReflections
merge(Reflections reflections)
merges a Reflections instance metadata into this instanceFile
save(String filename)
serialize to a given directory and filenameFile
save(String filename, Serializer serializer)
serialize to a given directory and filename using given serializerprotected void
scan()
protected void
scan(URL url)
-
-
-
Field Detail
-
log
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 givenConfiguration
it is preferred to use
ConfigurationBuilder
-
Reflections
public Reflections(String prefix, Scanner... scanners)
a convenient constructor for scanning within a package prefix.this actually create a
Configuration
with:
- urls that contain resources with nameprefix
- filterInputsBy where name starts with the givenprefix
- scanners set to the givenscanners
, otherwise defaults toTypeAnnotationsScanner
andSubTypesScanner
.- Parameters:
prefix
- package prefix, to be used withClasspathHelper.forPackage(String, ClassLoader...)
)}scanners
- optionally supply scanners, otherwise defaults toTypeAnnotationsScanner
andSubTypesScanner
-
Reflections
public Reflections(Object... params)
a convenient constructor for Reflections, where givenObject...
parameter types can be either:String
- would add urls usingClasspathHelper.forPackage(String, ClassLoader...)
()}Class
- would add urls usingClasspathHelper.forClass(Class, ClassLoader...)
ClassLoader
- would use this classloaders in order to find urls inClasspathHelper.forPackage(String, ClassLoader...)
andClasspathHelper.forClass(Class, ClassLoader...)
Scanner
- would use given scanner, overriding the default scannersURL
- would add the given url for scanningObject
- would use each element as above
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 instanceby 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, 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 serializerXmlSerializer
or using the optionally supplied optionalSerializerit 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 Configurationuseful 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
-
expandSuperTypes
public void expandSuperTypes()
expand super types after scanning, for super types that were not scanned. this is helpful in finding the transitive closure without scanning all 3rd party dependencies. it usesReflectionUtils.getSuperTypes(Class)
.for example, for classes A,B,C where A supertype of B, B supertype of C:
- if scanning C resulted in B (B->C in store), but A was not scanned (although A supertype of B) - then getSubTypes(A) will not return C
- if expanding supertypes, B will be expanded with A (A->B in store) - then getSubTypes(A) will return C
-
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 annotationsInherited
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 annotationsInherited
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
depends on TypeAnnotationsScanner configuredInherited
is not honored by default
-
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
depends on TypeAnnotationsScanner configuredInherited
is honored according to given honorInherited
-
getAllAnnotated
protected Collection<String> getAllAnnotated(Collection<String> annotated, Class<? extends Annotation> annotation, 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 giventypes
-
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 giventypes
-
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(Predicate<String> namePredicate)
get resources relative paths where simple name (key) matches given namePredicatedepends on ResourcesScanner configured
-
getResources
public Set<String> getResources(Pattern pattern)
get resources relative paths where simple name (key) matches given regular expressiondepends on ResourcesScanner configured
Set
xmls = reflections.getResources(".*\\.xml");
-
getMethodParamNames
public List<String> getMethodParamNames(Method method)
get parameter names of givenmethod
depends on MethodParameterNamesScanner configured
-
getConstructorParamNames
public List<String> getConstructorParamNames(Constructor constructor)
get parameter names of givenconstructor
depends on MethodParameterNamesScanner configured
-
getFieldUsage
public Set<Member> getFieldUsage(Field field)
get all givenfield
usages in methods and constructorsdepends on MemberUsageScanner configured
-
getMethodUsage
public Set<Member> getMethodUsage(Method method)
get all givenmethod
usages in methods and constructorsdepends on MemberUsageScanner configured
-
getConstructorUsage
public Set<Member> getConstructorUsage(Constructor constructor)
get all givenconstructors
usages in methods and constructorsdepends 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)
, otherwiseReflectionsException
is thrownnote using this might be a bad practice. it is better to get types matching some criteria, such as
getSubTypesOf(Class)
orgetTypesAnnotatedWith(Class)
- Returns:
- Set of String, and not of Class, in order to avoid definition of all types in PermGen
-
getConfiguration
public Configuration getConfiguration()
returns theConfiguration
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
-
-