Class Reflections


  • public class Reflections
    extends java.lang.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, 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/

    • 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 instance
      Reflections collect​(java.io.File file)
      merges saved Reflections resources from the given file, using the serializer configured in this instance's Configuration
      Reflections collect​(java.io.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​(java.lang.String packagePrefix, java.util.function.Predicate<java.lang.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
      private void expandSupertypes​(Store store, java.lang.String key, java.lang.Class<?> type)  
      void expandSuperTypes()
      expand super types after scanning, for super types that were not scanned.
      protected java.util.Collection<java.lang.String> getAllAnnotated​(java.util.Collection<java.lang.String> annotated, java.lang.Class<? extends java.lang.annotation.Annotation> annotation, boolean honorInherited)  
      java.util.Set<java.lang.String> getAllTypes()
      get all types scanned.
      Configuration getConfiguration()
      returns the Configuration object of this instance
      java.util.List<java.lang.String> getConstructorParamNames​(java.lang.reflect.Constructor constructor)
      get parameter names of given constructor
      java.util.Set<java.lang.reflect.Constructor> getConstructorsAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get all constructors annotated with a 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 all constructors annotated with a given annotation
      java.util.Set<java.lang.reflect.Constructor> getConstructorsMatchParams​(java.lang.Class<?>... types)
      get constructors with parameter types matching given types
      java.util.Set<java.lang.reflect.Constructor> getConstructorsWithAnyParamAnnotated​(java.lang.annotation.Annotation annotation)
      get constructors with any parameter annotated with given annotation, including annotation member values matching
      java.util.Set<java.lang.reflect.Constructor> getConstructorsWithAnyParamAnnotated​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
      get constructors with any parameter annotated with given annotation
      java.util.Set<java.lang.reflect.Member> getConstructorUsage​(java.lang.reflect.Constructor constructor)
      get all given constructors usages in methods and constructors
      java.util.Set<java.lang.reflect.Field> getFieldsAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get all methods annotated with a 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 all fields annotated with a given annotation
      java.util.Set<java.lang.reflect.Member> getFieldUsage​(java.lang.reflect.Field field)
      get all given field usages in methods and constructors
      java.util.List<java.lang.String> getMethodParamNames​(java.lang.reflect.Method method)
      get parameter names of given method
      java.util.Set<java.lang.reflect.Method> getMethodsAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get all methods annotated with a 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 all methods annotated with a given annotation
      java.util.Set<java.lang.reflect.Method> getMethodsMatchParams​(java.lang.Class<?>... types)
      get methods with parameter types matching given types
      java.util.Set<java.lang.reflect.Method> getMethodsReturn​(java.lang.Class returnType)
      get methods with return type match given type
      java.util.Set<java.lang.reflect.Method> getMethodsWithAnyParamAnnotated​(java.lang.annotation.Annotation annotation)
      get methods with any parameter annotated with given annotation, including annotation member values matching
      java.util.Set<java.lang.reflect.Method> getMethodsWithAnyParamAnnotated​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
      get methods with any parameter annotated with given annotation
      java.util.Set<java.lang.reflect.Member> getMethodUsage​(java.lang.reflect.Method method)
      get all given method usages in methods and constructors
      java.util.Set<java.lang.String> getResources​(java.util.function.Predicate<java.lang.String> namePredicate)
      get resources relative paths where simple name (key) matches given namePredicate
      java.util.Set<java.lang.String> getResources​(java.util.regex.Pattern pattern)
      get resources relative paths where simple name (key) matches given regular expression
      Store getStore()
      returns the Store used for storing and querying the metadata
      <T> java.util.Set<java.lang.Class<? extends T>> getSubTypesOf​(java.lang.Class<T> type)
      gets all sub types in hierarchy of a given type
      java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.Annotation annotation)
      get types annotated with a 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 a 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 a 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 a given annotation, both classes and annotations
      private java.lang.ClassLoader[] loaders()  
      Reflections merge​(Reflections reflections)
      merges a Reflections instance metadata into this instance
      private static java.lang.String producingDescription​(Store store)  
      java.io.File save​(java.lang.String filename)
      serialize to a given directory and filename
      java.io.File save​(java.lang.String filename, Serializer serializer)
      serialize to a given directory and filename using given serializer
      protected void scan()  
      protected void scan​(java.net.URL url)  
      • Methods inherited from class java.lang.Object

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

      • log

        public static org.slf4j.Logger log
      • configuration

        protected final transient Configuration configuration
      • store

        protected Store store
    • Method Detail

      • scan

        protected void scan()
      • producingDescription

        private static java.lang.String producingDescription​(Store store)
      • scan

        protected void scan​(java.net.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​(java.lang.String packagePrefix,
                                          java.util.function.Predicate<java.lang.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

        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​(java.io.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​(java.io.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
      • 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 uses ReflectionUtils.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
      • expandSupertypes

        private void expandSupertypes​(Store store,
                                      java.lang.String key,
                                      java.lang.Class<?> type)
      • getSubTypesOf

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

        depends on SubTypesScanner configured

      • getTypesAnnotatedWith

        public java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.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 java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.Class<? extends java.lang.annotation.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 java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.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 java.util.Set<java.lang.Class<?>> getTypesAnnotatedWith​(java.lang.annotation.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 java.util.Collection<java.lang.String> getAllAnnotated​(java.util.Collection<java.lang.String> annotated,
                                                                         java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                                                         boolean honorInherited)
      • getMethodsAnnotatedWith

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

        depends on MethodAnnotationsScanner configured

      • getMethodsAnnotatedWith

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

        depends on MethodAnnotationsScanner configured

      • getMethodsMatchParams

        public java.util.Set<java.lang.reflect.Method> getMethodsMatchParams​(java.lang.Class<?>... types)
        get methods with parameter types matching given types
      • getMethodsReturn

        public java.util.Set<java.lang.reflect.Method> getMethodsReturn​(java.lang.Class returnType)
        get methods with return type match given type
      • getMethodsWithAnyParamAnnotated

        public java.util.Set<java.lang.reflect.Method> getMethodsWithAnyParamAnnotated​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
        get methods with any parameter annotated with given annotation
      • getMethodsWithAnyParamAnnotated

        public java.util.Set<java.lang.reflect.Method> getMethodsWithAnyParamAnnotated​(java.lang.annotation.Annotation annotation)
        get methods with any parameter annotated with given annotation, including annotation member values matching
      • getConstructorsAnnotatedWith

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

        depends on MethodAnnotationsScanner configured

      • getConstructorsAnnotatedWith

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

        depends on MethodAnnotationsScanner configured

      • getConstructorsMatchParams

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsMatchParams​(java.lang.Class<?>... types)
        get constructors with parameter types matching given types
      • getConstructorsWithAnyParamAnnotated

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsWithAnyParamAnnotated​(java.lang.Class<? extends java.lang.annotation.Annotation> annotation)
        get constructors with any parameter annotated with given annotation
      • getConstructorsWithAnyParamAnnotated

        public java.util.Set<java.lang.reflect.Constructor> getConstructorsWithAnyParamAnnotated​(java.lang.annotation.Annotation annotation)
        get constructors with any parameter annotated with given annotation, including annotation member values matching
      • getFieldsAnnotatedWith

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

        depends on FieldAnnotationsScanner configured

      • getFieldsAnnotatedWith

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

        depends on FieldAnnotationsScanner configured

      • getResources

        public java.util.Set<java.lang.String> getResources​(java.util.function.Predicate<java.lang.String> namePredicate)
        get resources relative paths where simple name (key) matches given namePredicate

        depends on ResourcesScanner configured

      • getResources

        public java.util.Set<java.lang.String> getResources​(java.util.regex.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 java.util.List<java.lang.String> getMethodParamNames​(java.lang.reflect.Method method)
        get parameter names of given method

        depends on MethodParameterNamesScanner configured

      • getConstructorParamNames

        public java.util.List<java.lang.String> getConstructorParamNames​(java.lang.reflect.Constructor constructor)
        get parameter names of given constructor

        depends on MethodParameterNamesScanner configured

      • getFieldUsage

        public java.util.Set<java.lang.reflect.Member> getFieldUsage​(java.lang.reflect.Field field)
        get all given field usages in methods and constructors

        depends on MemberUsageScanner configured

      • getMethodUsage

        public java.util.Set<java.lang.reflect.Member> getMethodUsage​(java.lang.reflect.Method method)
        get all given method usages in methods and constructors

        depends on MemberUsageScanner configured

      • getConstructorUsage

        public java.util.Set<java.lang.reflect.Member> getConstructorUsage​(java.lang.reflect.Constructor constructor)
        get all given constructors usages in methods and constructors

        depends on MemberUsageScanner configured

      • getAllTypes

        public java.util.Set<java.lang.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
      • save

        public java.io.File save​(java.lang.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 java.io.File save​(java.lang.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

      • loaders

        private java.lang.ClassLoader[] loaders()