From 8cd4c0270b6cd4e8a1b5c26341d23d057ce597c9 Mon Sep 17 00:00:00 2001 From: Stuart Douglas Date: Fri, 8 Oct 2021 09:35:04 +1100 Subject: [PATCH] Add convenience methods to IndexView --- .../main/java/org/jboss/jandex/IndexView.java | 260 +++++++++++++++++- 1 file changed, 249 insertions(+), 11 deletions(-) diff --git a/core/src/main/java/org/jboss/jandex/IndexView.java b/core/src/main/java/org/jboss/jandex/IndexView.java index 03fa2701..998b8608 100644 --- a/core/src/main/java/org/jboss/jandex/IndexView.java +++ b/core/src/main/java/org/jboss/jandex/IndexView.java @@ -33,7 +33,7 @@ public interface IndexView { * * @return a collection of known classes */ - public Collection getKnownClasses(); + Collection getKnownClasses(); /** * Gets the class (or interface, or annotation) that was scanned during the @@ -42,7 +42,29 @@ public interface IndexView { * @param className the name of the class * @return information about the class or null if it is not known */ - public ClassInfo getClassByName(DotName className); + ClassInfo getClassByName(DotName className); + + /** + * Gets the class (or interface, or annotation) that was scanned during the + * indexing phase. + * + * @param className the name of the class + * @return information about the class or null if it is not known + */ + default ClassInfo getClassByName(String className) { + return getClassByName(DotName.createSimple(className)); + } + + /** + * Gets the class (or interface, or annotation) that was scanned during the + * indexing phase. + * + * @param clazz the class + * @return information about the class or null if it is not known + */ + default ClassInfo getClassByName(Class clazz) { + return getClassByName(DotName.createSimple(clazz.getName())); + } /** * Gets all known direct subclasses of the specified class name. A known direct @@ -58,7 +80,53 @@ public interface IndexView { * @param className the super class of the desired subclasses * @return a non-null list of all known subclasses of className */ - public Collection getKnownDirectSubclasses(DotName className); + Collection getKnownDirectSubclasses(DotName className); + + /** + * Gets all known direct subclasses of the specified class name. A known direct + * subclass is one which was found during the scanning process; however, this is + * often not the complete universe of subclasses, since typically indexes are + * constructed per jar. It is expected that several indexes will need to be searched + * when analyzing a jar that is a part of a complex multi-module/classloader + * environment (like an EE application server). + *

+ * Note that this will only pick up direct subclasses of the class. It will not + * pick up subclasses of subclasses. + * + * @param className the super class of the desired subclasses + * @return a non-null list of all known subclasses of className + */ + default Collection getKnownDirectSubclasses(String className) { + return getKnownDirectSubclasses(DotName.createSimple(className)); + } + + /** + * Gets all known direct subclasses of the specified class name. A known direct + * subclass is one which was found during the scanning process; however, this is + * often not the complete universe of subclasses, since typically indexes are + * constructed per jar. It is expected that several indexes will need to be searched + * when analyzing a jar that is a part of a complex multi-module/classloader + * environment (like an EE application server). + *

+ * Note that this will only pick up direct subclasses of the class. It will not + * pick up subclasses of subclasses. + * + * @param clazz the super class of the desired subclasses + * @return a non-null list of all known subclasses of className + */ + default Collection getKnownDirectSubclasses(Class clazz) { + return getKnownDirectSubclasses(DotName.createSimple(clazz.getName())); + } + + /** + * Returns all known (including non-direct) sub classes of the given class. + * I.e., returns all known classes that are assignable to the given class. + * + * @param className The class + * + * @return All known subclasses + */ + Collection getAllKnownSubclasses(final DotName className); /** * Returns all known (including non-direct) sub classes of the given class. @@ -68,7 +136,21 @@ public interface IndexView { * * @return All known subclasses */ - public Collection getAllKnownSubclasses(final DotName className); + default Collection getAllKnownSubclasses(final String className) { + return getAllKnownSubclasses(DotName.createSimple(className)); + } + + /** + * Returns all known (including non-direct) sub classes of the given class. + * I.e., returns all known classes that are assignable to the given class. + * + * @param clazz The class + * + * @return All known subclasses + */ + default Collection getAllKnownSubclasses(final Class clazz) { + return getAllKnownSubclasses(DotName.createSimple(clazz.getName())); + } /** * Gets all known direct implementors of the specified interface name. A known @@ -86,7 +168,47 @@ public interface IndexView { * @param className the super class of the desired subclasses * @return a non-null list of all known subclasses of className */ - public Collection getKnownDirectImplementors(DotName className); + Collection getKnownDirectImplementors(DotName className); + + /** + * Gets all known direct implementors of the specified interface name. A known + * direct implementor is one which was found during the scanning process; however, + * this is often not the complete universe of implementors, since typically indexes + * are constructed per jar. It is expected that several indexes will need to + * be searched when analyzing a jar that is a part of a complex + * multi-module/classloader environment (like an EE application server). + *

+ * The list of implementors may also include other methodParameters, in order to get a complete + * list of all classes that are assignable to a given interface it is necessary to + * recursively call {@link #getKnownDirectImplementors(DotName)} for every implementing + * interface found. + * + * @param className the super class of the desired subclasses + * @return a non-null list of all known subclasses of className + */ + default Collection getKnownDirectImplementors(String className) { + return getKnownDirectImplementors(DotName.createSimple(className)); + } + + /** + * Gets all known direct implementors of the specified interface name. A known + * direct implementor is one which was found during the scanning process; however, + * this is often not the complete universe of implementors, since typically indexes + * are constructed per jar. It is expected that several indexes will need to + * be searched when analyzing a jar that is a part of a complex + * multi-module/classloader environment (like an EE application server). + *

+ * The list of implementors may also include other methodParameters, in order to get a complete + * list of all classes that are assignable to a given interface it is necessary to + * recursively call {@link #getKnownDirectImplementors(DotName)} for every implementing + * interface found. + * + * @param clazz the super class of the desired subclasses + * @return a non-null list of all known subclasses of className + */ + default Collection getKnownDirectImplementors(Class clazz) { + return getKnownDirectImplementors(DotName.createSimple(clazz.getName())); + } /** * Returns all known classes that implement the given interface, directly and indirectly. @@ -99,7 +221,47 @@ public interface IndexView { * @param interfaceName The interface * @return All known implementors of the interface */ - public Collection getAllKnownImplementors(final DotName interfaceName); + Collection getAllKnownImplementors(final DotName interfaceName); + + /** + * Returns all known classes that implement the given interface, directly and indirectly. + * This will all return classes that implement sub methodParameters of the interface, and + * sub-classes of classes that implement the interface. (In short, it will + * return every class that is assignable to the interface that is found in the index) + *

+ * This will only return classes, not methodParameters. + * + * @param interfaceName The interface + * @return All known implementors of the interface + */ + default Collection getAllKnownImplementors(final String interfaceName) { + return getAllKnownImplementors(DotName.createSimple(interfaceName)); + } + + /** + * Returns all known classes that implement the given interface, directly and indirectly. + * This will all return classes that implement sub methodParameters of the interface, and + * sub-classes of classes that implement the interface. (In short, it will + * return every class that is assignable to the interface that is found in the index) + *

+ * This will only return classes, not methodParameters. + * + * @param interfaceClass The interface + * @return All known implementors of the interface + */ + default Collection getAllKnownImplementors(final Class interfaceClass) { + return getAllKnownImplementors(DotName.createSimple(interfaceClass.getName())); + } + + /** + * Obtains a list of instances for the specified annotation. + * This is done using an O(1) lookup. Valid instance targets include + * field, method, parameter, and class. + * + * @param annotationName the name of the annotation to look for + * @return a non-null list of annotation instances + */ + Collection getAnnotations(DotName annotationName); /** * Obtains a list of instances for the specified annotation. @@ -109,7 +271,21 @@ public interface IndexView { * @param annotationName the name of the annotation to look for * @return a non-null list of annotation instances */ - public Collection getAnnotations(DotName annotationName); + default Collection getAnnotations(String annotationName) { + return getAnnotations(DotName.createSimple(annotationName)); + } + + /** + * Obtains a list of instances for the specified annotation. + * This is done using an O(1) lookup. Valid instance targets include + * field, method, parameter, and class. + * + * @param annotationType the type of the annotation to look for + * @return a non-null list of annotation instances + */ + default Collection getAnnotations(Class annotationType) { + return getAnnotations(DotName.createSimple(annotationType.getName())); + } /** * Obtains a list of instances for the specified annotation. If the specified annotation is repeatable (JLS 9.6), the result @@ -122,14 +298,44 @@ public interface IndexView { * @throws IllegalArgumentException If the index does not contain the annotation definition or if it does not represent * an annotation type */ - public Collection getAnnotationsWithRepeatable(DotName annotationName, IndexView index); + Collection getAnnotationsWithRepeatable(DotName annotationName, IndexView index); + + /** + * Obtains a list of instances for the specified annotation. If the specified annotation is repeatable (JLS 9.6), the result + * also contains all values from all instances of the container annotation. In this case, the + * {@link AnnotationInstance#target()} returns the target of the container annotation instance. + * + * @param annotationName the name of the repeatable annotation + * @param index the index containing the annotation class + * @return a non-null list of annotation instances + * @throws IllegalArgumentException If the index does not contain the annotation definition or if it does not represent + * an annotation type + */ + default Collection getAnnotationsWithRepeatable(String annotationName, IndexView index) { + return getAnnotationsWithRepeatable(DotName.createSimple(annotationName), index); + } + + /** + * Obtains a list of instances for the specified annotation. If the specified annotation is repeatable (JLS 9.6), the result + * also contains all values from all instances of the container annotation. In this case, the + * {@link AnnotationInstance#target()} returns the target of the container annotation instance. + * + * @param annotationType the name of the repeatable annotation + * @param index the index containing the annotation class + * @return a non-null list of annotation instances + * @throws IllegalArgumentException If the index does not contain the annotation definition or if it does not represent + * an annotation type + */ + default Collection getAnnotationsWithRepeatable(Class annotationType, IndexView index) { + return getAnnotationsWithRepeatable(DotName.createSimple(annotationType.getName()), index); + } /** * Gets all known modules by this index (those which were scanned). * * @return a collection of known modules */ - public Collection getKnownModules(); + Collection getKnownModules(); /** * Gets the module that was scanned during the indexing phase. @@ -137,7 +343,26 @@ public interface IndexView { * @param moduleName the name of the module * @return information about the module or null if it is not known */ - public ModuleInfo getModuleByName(DotName moduleName); + ModuleInfo getModuleByName(DotName moduleName); + + /** + * Gets the module that was scanned during the indexing phase. + * + * @param moduleName the name of the module + * @return information about the module or null if it is not known + */ + default ModuleInfo getModuleByName(String moduleName) { + return getModuleByName(DotName.createSimple(moduleName)); + } + + /** + * Obtains a list of classes that use the specified class. In other words, a list of classes that include + * a reference to the specified class in their constant pool. + * + * @param className the name of the class to look for + * @return a non-null list of classes that use the specified class + */ + Collection getKnownUsers(DotName className); /** * Obtains a list of classes that use the specified class. In other words, a list of classes that include @@ -146,5 +371,18 @@ public interface IndexView { * @param className the name of the class to look for * @return a non-null list of classes that use the specified class */ - public Collection getKnownUsers(DotName className); + default Collection getKnownUsers(String className) { + return getKnownUsers(DotName.createSimple(className)); + } + + /** + * Obtains a list of classes that use the specified class. In other words, a list of classes that include + * a reference to the specified class in their constant pool. + * + * @param clazz the class to look for + * @return a non-null list of classes that use the specified class + */ + default Collection getKnownUsers(Class clazz) { + return getKnownUsers(DotName.createSimple(clazz.getName())); + } }