Class Reflections

  • All Implemented Interfaces:
    NameHelper

    public class Reflections
    extends java.lang.Object
    implements NameHelper
    Reflections one-stop-shop object

    Reflections scans and indexes your project's classpath, allowing reverse query of the type system metadata on runtime.

    Using Reflections you can query for example:

    • Subtypes of a type
    • Types annotated with an annotation
    • Methods with annotation, parameters, return type
    • Resources found in classpath
      And more...

    Create Reflections instance, preferably using ConfigurationBuilder:

    
     Reflections reflections = new Reflections(
       new ConfigurationBuilder()
         .forPackage("com.my.project"));
    
     // or similarly
     Reflections reflections = new Reflections("com.my.project");
    
     // another example
     Reflections reflections = new Reflections(
       new ConfigurationBuilder()
         .forPackage("com.my.project")
         .setScanners(Scanners.values())     // all standard scanners
         .filterInputsBy(new FilterBuilder().includePackage("com.my.project").excludePackage("com.my.project.exclude")));
     

    All relevant URLs should be configured.
    If required, Reflections will expandSuperTypes(Map, Map) in order to get the transitive closure metadata without scanning large 3rd party urls.

    Scanners must be configured in order to be queried, otherwise an empty result is returned.
    Default scanners are SubTypes and TypesAnnotated. For all standard scanners use Scanners.values().

    Classloader can optionally be used for resolving runtime classes from names.

    Query using get(QueryFunction), such as:
    
     Set<Class<?>> modules = reflections.get(SubTypes.of(Module.class).asClass());
     Set<Class<?>> singletons = reflections.get(TypesAnnotated.with(Singleton.class).asClass());
     Set<String> properties   = reflections.get(Resources.with(".*\\.properties"));
     Set<Method> requests     = reflections.get(MethodsAnnotated.with(RequestMapping.class).as(Method.class));
     Set<Method> voidMethods  = reflections.get(MethodsReturn.with(void.class).as(Method.class));
     Set<Method> someMethods  = reflections.get(MethodsSignature.of(long.class, int.class).as(Method.class));
     
    If not using asClass() or as() query results are strings, such that:
    Set<String> modules    = reflections.get(SubTypes.of(Module.class));
     Set<String> singletons = reflections.get(TypesAnnotated.with(Singleton.class));
     

    Note that previous 0.9.x API is still supported, for example:

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

    Queries can combine Scanners and ReflectionUtils functions, and compose fluent functional methods from QueryFunction.

    
     

    Scanned metadata can be saved using save(String), and collected using collect(String, java.util.function.Predicate, org.reflections.serializers.Serializer)

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

      Constructors 
      Modifier Constructor Description
      protected Reflections()  
        Reflections​(java.lang.Object... params)
      Convenient constructor for Reflections.
        Reflections​(java.lang.String prefix, Scanner... scanners)
      constructs Reflections instance and scan according to the given package prefix and optional scanners
        Reflections​(Configuration configuration)
      constructs Reflections instance and scan according to the given Configuration
        Reflections​(Store store)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static Reflections collect()
      collect saved Reflection xml resources and merge it into a Reflections instance
      Reflections collect​(java.io.File file, Serializer serializer)
      deserialize and merge saved Reflections metadata from the given file and serializer
      Reflections collect​(java.io.InputStream inputStream, Serializer serializer)
      deserialize and merge saved Reflections metadata from the given inputStream and serializer
      static Reflections collect​(java.lang.String packagePrefix, java.util.function.Predicate<java.lang.String> resourceNameFilter)
      collect saved Reflections metadata from all urls that contains the given packagePrefix and matches the given resourceNameFilter, and deserialize using the default serializer XmlSerializer
      static Reflections collect​(java.lang.String packagePrefix, java.util.function.Predicate<java.lang.String> resourceNameFilter, Serializer serializer)
      collect saved Reflections metadata from all urls that contains the given packagePrefix and matches the given resourceNameFilter, and deserializes using the given serializer
      private boolean doFilter​(Vfs.File file, java.util.function.Predicate<java.lang.String> predicate)  
      private void expandSupertypes​(java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> subTypesStore, java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> typesAnnotatedStore, java.lang.String key, java.lang.Class<?> type)  
      void expandSuperTypes​(java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> subTypesStore, java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> typesAnnotatedStore)
      expand super types after scanning, for super types that were not scanned.
      <T> java.util.Set<T> get​(QueryFunction<Store,​T> query)
      java.util.Set<java.lang.String> getAll​(Scanner scanner)
      returns all key and values scanned by the given scanner
      java.util.Set<java.lang.String> getAllTypes()
      Deprecated.
      private javassist.bytecode.ClassFile getClassFile​(Vfs.File file)  
      Configuration getConfiguration()
      returns the Configuration object of this instance
      java.util.Set<java.lang.reflect.Constructor> getConstructorsAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get constructors annotated with the given annotation, including annotation member values matching
      java.util.Set<java.lang.reflect.Constructor> getConstructorsAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
      get constructors annotated with the given annotation
      java.util.Set<java.lang.reflect.Constructor> getConstructorsWithParameter​(java.lang.reflect.AnnotatedElement type)
      get constructors with any parameter matching the given type, either class or annotation
      java.util.Set<java.lang.reflect.Constructor> getConstructorsWithSignature​(java.lang.Class<?>... types)
      get constructors with signature matching the given types
      java.util.Set<java.lang.reflect.Field> getFieldsAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get fields annotated with the given annotation, including annotation member values matching
      java.util.Set<java.lang.reflect.Field> getFieldsAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
      get fields annotated with the given annotation
      java.util.List<java.lang.String> getMemberParameterNames​(java.lang.reflect.Member member)
      get parameter names of the given member, either method or constructor
      java.util.Collection<java.lang.reflect.Member> getMemberUsage​(java.lang.reflect.Member member)
      get code usages for the given member, either field, method or constructor
      java.util.Set<java.lang.reflect.Method> getMethodsAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get methods annotated with the given annotation, including annotation member values matching
      java.util.Set<java.lang.reflect.Method> getMethodsAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
      get methods annotated with the given annotation
      java.util.Set<java.lang.reflect.Method> getMethodsReturn​(java.lang.Class<?> type)
      get methods with return type matching the given returnType
      java.util.Set<java.lang.reflect.Method> getMethodsWithParameter​(java.lang.reflect.AnnotatedElement type)
      get methods with any parameter matching the given type, either class or annotation
      java.util.Set<java.lang.reflect.Method> getMethodsWithSignature​(java.lang.Class<?>... types)
      get methods with signature matching the given types
      java.util.Set<java.lang.String> getResources​(java.lang.String pattern)
      get resources matching the given pattern regex
      java.util.Set<java.lang.String> getResources​(java.util.regex.Pattern pattern)
      get resources matching the given pattern regex
      Store getStore()
      returns the Store object used for storing and querying the metadata
      <T> java.util.Set<java.lang.Class<? extends T>> getSubTypesOf​(java.lang.Class<T> type)
      gets all subtypes in hierarchy of a given type.
      java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get types annotated with the given annotation, both classes and annotations, including annotation member values matching
      java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.Annotation annotation, boolean honorInherited)
      get types annotated with the given annotation, both classes and annotations, including annotation member values matching
      java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
      get types annotated with the given annotation, both classes and annotations
      java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation, boolean honorInherited)
      get types annotated with the given annotation, both classes and annotations
      (package private) java.lang.ClassLoader[] loaders()  
      Reflections merge​(Reflections reflections)
      merges the given reflections instance metadata into this instance
      java.io.File save​(java.lang.String filename)
      serialize metadata to the given filename
      java.io.File save​(java.lang.String filename, Serializer serializer)
      serialize metadata to the given filename and serializer
      protected java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​java.util.Set<java.lang.String>>> scan()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • log

        public static final org.slf4j.Logger log
      • configuration

        protected final transient Configuration configuration
      • store

        protected final Store store
    • Method Detail

      • scan

        protected java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​java.util.Set<java.lang.String>>> scan()
      • doFilter

        private boolean doFilter​(Vfs.File file,
                                 @Nullable
                                 java.util.function.Predicate<java.lang.String> predicate)
      • getClassFile

        private javassist.bytecode.ClassFile getClassFile​(Vfs.File file)
      • 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​(java.lang.String packagePrefix,
                                          java.util.function.Predicate<java.lang.String> resourceNameFilter)
        collect saved Reflections metadata from all urls that contains the given packagePrefix and matches the given resourceNameFilter, and deserialize using the default serializer XmlSerializer
        Reflections.collect("META-INF/reflections/",
           new FilterBuilder().includePattern(".*-reflections\\.xml")
        prefer using a designated directory (for example META-INF/reflections but not just META-INF), so that collect can work much faster
      • collect

        public static Reflections collect​(java.lang.String packagePrefix,
                                          java.util.function.Predicate<java.lang.String> resourceNameFilter,
                                          Serializer serializer)
        collect saved Reflections metadata from all urls that contains the given packagePrefix and matches the given resourceNameFilter, and deserializes using the given serializer
        Reflections reflections = Reflections.collect(
           "META-INF/reflections/",
           new FilterBuilder().includePattern(".*-reflections\\.xml"),
           new XmlSerializer())
        prefer using a designated directory (for example META-INF/reflections but not just META-INF), so that collect can work much faster
      • collect

        public Reflections collect​(java.io.InputStream inputStream,
                                   Serializer serializer)
        deserialize and merge saved Reflections metadata from the given inputStream and serializer

        useful if you know the serialized resource location and prefer not to look it up the classpath

      • collect

        public Reflections collect​(java.io.File file,
                                   Serializer serializer)
        deserialize and merge saved Reflections metadata from the given file and serializer

        useful if you know the serialized resource location and prefer not to look it up the classpath

      • merge

        public Reflections merge​(Reflections reflections)
        merges the given reflections instance metadata into this instance
      • expandSuperTypes

        public void expandSuperTypes​(java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> subTypesStore,
                                     java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> typesAnnotatedStore)
        expand super types after scanning, for super types that were not scanned.
        this is helpful for finding the transitive closure without scanning all 3rd party dependencies.

        for example, for classes A,B,C where A supertype of B, B supertype of C (A -> B -> C):
        • if scanning C resulted in B (B->C in store), but A was not scanned (although A is 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
      • expandSupertypes

        private void expandSupertypes​(java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> subTypesStore,
                                      java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> typesAnnotatedStore,
                                      java.lang.String key,
                                      java.lang.Class<?> type)
      • get

        public <T> java.util.Set<T> get​(QueryFunction<Store,​T> query)
        apply QueryFunction on Store
        Set<T> ts = get(query)

        use Scanners and ReflectionUtils query functions, such as:

        
         Set<String> annotated = get(Scanners.TypesAnnotated.with(A.class))
         Set<Class<?>> subtypes = get(Scanners.SubTypes.of(B.class).asClass())
         Set<Method> methods = get(ReflectionUtils.Methods.of(B.class))
         
      • getSubTypesOf

        public <T> java.util.Set<java.lang.Class<? extends T>> getSubTypesOf​(java.lang.Class<T> type)
        gets all subtypes in hierarchy of a given type.

        similar to get(SubTypes.of(type))

        depends on Scanners.SubTypes configured
      • getTypesAnnotatedWith

        public java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
        get types annotated with the given annotation, both classes and annotations

        Inherited is not honored by default, see getTypesAnnotatedWith(Class, boolean).

        similar to get(SubTypes.of(TypesAnnotated.with(annotation)))

        depends on Scanners.TypesAnnotated and Scanners.SubTypes configured
      • getTypesAnnotatedWith

        public java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                                                       boolean honorInherited)
        get types annotated with the given annotation, both classes and annotations

        Inherited is honored according to the given honorInherited.

        when honoring @Inherited, meta-annotation should only effect annotated super classes and subtypes

        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 Scanners.TypesAnnotated and Scanners.SubTypes configured
      • getTypesAnnotatedWith

        public java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.Annotation annotation)
        get types annotated with the given annotation, both classes and annotations, including annotation member values matching

        Inherited is not honored by default, see getTypesAnnotatedWith(Annotation, boolean).

        depends on Scanners.TypesAnnotated and Scanners.SubTypes configured
      • getTypesAnnotatedWith

        public java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.Annotation annotation,
                                                                       boolean honorInherited)
        get types annotated with the given annotation, both classes and annotations, including annotation member values matching

        Inherited is honored according to given honorInherited

        depends on Scanners.TypesAnnotated and Scanners.SubTypes configured
      • getMethodsAnnotatedWith

        public java.util.Set<java.lang.reflect.Method> getMethodsAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
        get methods annotated with the given annotation

        similar to get(MethodsAnnotated.with(annotation))

        depends on Scanners.MethodsAnnotated configured
      • getMethodsAnnotatedWith

        public java.util.Set<java.lang.reflect.Method> getMethodsAnnotatedWith​(java.lang.annotation.Annotation annotation)
        get methods annotated with the given annotation, including annotation member values matching

        similar to get(MethodsAnnotated.with(annotation))

        depends on Scanners.MethodsAnnotated configured
      • getMethodsWithSignature

        public java.util.Set<java.lang.reflect.Method> getMethodsWithSignature​(java.lang.Class<?>... types)
        get methods with signature matching the given types

        similar to get(MethodsSignature.of(types))

        depends on Scanners.MethodsSignature configured
      • getMethodsWithParameter

        public java.util.Set<java.lang.reflect.Method> getMethodsWithParameter​(java.lang.reflect.AnnotatedElement type)
        get methods with any parameter matching the given type, either class or annotation

        similar to get(MethodsParameter.with(type))

        depends on Scanners.MethodsParameter configured
      • getMethodsReturn

        public java.util.Set<java.lang.reflect.Method> getMethodsReturn​(java.lang.Class<?> type)
        get methods with return type matching the given returnType

        similar to get(MethodsReturn.of(type))

        depends on Scanners.MethodsParameter configured
      • getConstructorsAnnotatedWith

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
        get constructors annotated with the given annotation

        similar to get(ConstructorsAnnotated.with(annotation))

        depends on Scanners.ConstructorsAnnotated configured
      • getConstructorsAnnotatedWith

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsAnnotatedWith​(java.lang.annotation.Annotation annotation)
        get constructors annotated with the given annotation, including annotation member values matching

        similar to get(ConstructorsAnnotated.with(annotation))

        depends on Scanners.ConstructorsAnnotated configured
      • getConstructorsWithSignature

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsWithSignature​(java.lang.Class<?>... types)
        get constructors with signature matching the given types

        similar to get(ConstructorsSignature.with(types))

        depends on Scanners.ConstructorsSignature configured
      • getConstructorsWithParameter

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsWithParameter​(java.lang.reflect.AnnotatedElement type)
        get constructors with any parameter matching the given type, either class or annotation

        similar to get(ConstructorsParameter.with(types))

        depends on Scanners.ConstructorsParameter configured
      • getFieldsAnnotatedWith

        public java.util.Set<java.lang.reflect.Field> getFieldsAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
        get fields annotated with the given annotation

        similar to get(FieldsAnnotated.with(annotation))

        depends on Scanners.FieldsAnnotated configured
      • getFieldsAnnotatedWith

        public java.util.Set<java.lang.reflect.Field> getFieldsAnnotatedWith​(java.lang.annotation.Annotation annotation)
        get fields annotated with the given annotation, including annotation member values matching

        similar to get(FieldsAnnotated.with(annotation))

        depends on Scanners.FieldsAnnotated configured
      • getResources

        public java.util.Set<java.lang.String> getResources​(java.lang.String pattern)
        get resources matching the given pattern regex
        Set<String> xmls = reflections.getResources(".*\\.xml")

        similar to get(Resources.with(pattern))

        depends on Scanners.Resources configured
      • getResources

        public java.util.Set<java.lang.String> getResources​(java.util.regex.Pattern pattern)
        get resources matching the given pattern regex
        Set<String> xmls = reflections.getResources(Pattern.compile(".*\\.xml"))

        similar to get(Resources.with(pattern))

        depends on Scanners.Resources configured
      • getMemberParameterNames

        public java.util.List<java.lang.String> getMemberParameterNames​(java.lang.reflect.Member member)
        get parameter names of the given member, either method or constructor

        depends on MethodParameterNamesScanner configured

      • getMemberUsage

        public java.util.Collection<java.lang.reflect.Member> getMemberUsage​(java.lang.reflect.Member member)
        get code usages for the given member, either field, method or constructor

        depends on MemberUsageScanner configured

      • getAllTypes

        @Deprecated
        public java.util.Set<java.lang.String> getAllTypes()
        Deprecated.
        returns all keys and values scanned by Scanners.SubTypes scanner

        using this api is discouraged, it is better to get elements by specific criteria such as SubTypes.of(Class) or TypesAnnotated.with(Class)

        deprecated, use getAll(Scanner) instead
      • getAll

        public java.util.Set<java.lang.String> getAll​(Scanner scanner)
        returns all key and values scanned by the given scanner
        Set<String> all = reflections.getAll(SubTypes)

        using this is discouraged, it is better to get elements by specific criteria such as SubTypes.of(Class) or TypesAnnotated.with(Class)

      • getStore

        public Store getStore()
        returns the Store object used for storing and querying the metadata

        Store is basically Map<String, Map<String, Set<String>>>

      • save

        public java.io.File save​(java.lang.String filename)
        serialize metadata to the given filename

        prefer using a designated directory (for example META-INF/reflections but not just META-INF), so that collect(String, Predicate) can work much faster
      • save

        public java.io.File save​(java.lang.String filename,
                                 Serializer serializer)
        serialize metadata to the given filename and serializer

        prefer using a designated directory (for example META-INF/reflections but not just META-INF), so that collect(String, Predicate, Serializer) can work much faster
      • loaders

        java.lang.ClassLoader[] loaders()