org.jboss.jandex

Class Index

java.lang.Object

org.jboss.jandex.Index

All Implemented Interfaces:

IndexView

public final class Index
extends Object
implements IndexView

An index useful for quickly processing annotations. The index is read-only and supports concurrent access. Also, the index is optimized for memory efficiency by using componentized DotName values.

It contains the following information:

1. All annotations and a collection of targets they refer to
2. All classes (including interfaces) scanned during the indexing process (typically all classes in a jar)
3. All modules scanned during the indexing process (typically one module in a jar)
4. All subclasses for each class known to this index
5. All subinterfaces for each interface known to this index
6. All implementors for each interface known to this index
7. All users of each class known to this index

Author:

Jason T. Greene

Method Summary

Modifier and Type	Method and Description
static Index	create(Map<DotName,List<AnnotationInstance>> annotations, Map<DotName,List<ClassInfo>> subclasses, Map<DotName,List<ClassInfo>> implementors, Map<DotName,ClassInfo> classes) Constructs a "mock" Index using the passed values.
static Index	create(Map<DotName,List<AnnotationInstance>> annotations, Map<DotName,List<ClassInfo>> subclasses, Map<DotName,List<ClassInfo>> implementors, Map<DotName,ClassInfo> classes, Map<DotName,List<ClassInfo>> users) Constructs a "mock" Index using the passed values.
static Index	create(Map<DotName,List<AnnotationInstance>> annotations, Map<DotName,List<ClassInfo>> subclasses, Map<DotName,List<ClassInfo>> subinterfaces, Map<DotName,List<ClassInfo>> implementors, Map<DotName,ClassInfo> classes, Map<DotName,List<ClassInfo>> users) Constructs a "mock" Index using the passed values.
Set<ClassInfo>	getAllKnownImplementors(DotName interfaceName) Returns all known classes that implement the given interface, directly and indirectly.
Collection<ClassInfo>	getAllKnownSubclasses(DotName className) Returns all known (including non-direct) subclasses of the given class.
Collection<ClassInfo>	getAllKnownSubinterfaces(DotName interfaceName) Returns all known interfaces that extend the given interface, directly and indirectly.
List<AnnotationInstance>	getAnnotations(DotName annotationName) Obtains a list of instances for the specified annotation.
Collection<AnnotationInstance>	getAnnotationsWithRepeatable(DotName annotationName, IndexView index) Obtains a list of instances for the specified annotation.
ClassInfo	getClassByName(DotName className) Gets the class (or interface, or annotation) that was scanned during the indexing phase.
Collection<ClassInfo>	getClassesInPackage(DotName packageName) Returns all classes known to this index that are present in given package.
Collection<ClassInfo>	getKnownClasses() Gets all known classes by this index (those which were scanned).
List<ClassInfo>	getKnownDirectImplementors(DotName className) Gets all known direct implementors of the specified interface.
List<ClassInfo>	getKnownDirectSubclasses(DotName className) Gets all known direct subclasses of the specified class.
List<ClassInfo>	getKnownDirectSubinterfaces(DotName interfaceName) Gets all known direct subinterfaces of the specified interface.
Collection<ModuleInfo>	getKnownModules() Gets all known modules by this index (those which were scanned).
List<ClassInfo>	getKnownUsers(DotName className) Obtains a list of classes that use the specified class.
ModuleInfo	getModuleByName(DotName moduleName) Gets the module that was scanned during the indexing phase.
Set<DotName>	getSubpackages(DotName packageName) Returns a set of packages known to this index that are direct subpackages of given package.
static Index	of(Class<?>... classes) Constructs an Index of the passed classes.
static Index	of(File... files) Constructs an Index of the passed files and directories.
static Index	of(Iterable<Class<?>> classes) Constructs an Index of the passed classes.
void	printAnnotations() Print all annotations known by this index to stdout.
void	printSubclasses() Print all classes that have known subclasses, and all their subclasses
static ClassInfo	singleClass(byte[] classData) Creates a temporary Indexer, indexes given classData, and returns the corresponding ClassInfo.
static ClassInfo	singleClass(Class<?> clazz) Creates a temporary Indexer, indexes given clazz, and returns the corresponding ClassInfo.
static ClassInfo	singleClass(InputStream classData) Creates a temporary Indexer, indexes given classData, and returns the corresponding ClassInfo.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jboss.jandex.IndexView

getAllKnownImplementors, getAllKnownImplementors, getAllKnownSubclasses, getAllKnownSubclasses, getAllKnownSubinterfaces, getAllKnownSubinterfaces, getAnnotations, getAnnotations, getAnnotationsWithRepeatable, getAnnotationsWithRepeatable, getClassByName, getClassByName, getClassesInPackage, getKnownDirectImplementors, getKnownDirectImplementors, getKnownDirectSubclasses, getKnownDirectSubclasses, getKnownDirectSubinterfaces, getKnownDirectSubinterfaces, getKnownUsers, getKnownUsers, getModuleByName, getSubpackages

Method Detail

create

public static Index create(Map<DotName,List<AnnotationInstance>> annotations,
                           Map<DotName,List<ClassInfo>> subclasses,
                           Map<DotName,List<ClassInfo>> implementors,
                           Map<DotName,ClassInfo> classes)

Constructs a "mock" Index using the passed values. All passed values MUST NOT BE MODIFIED AFTER THIS CALL. Otherwise the resulting object would not conform to the contract outlined above. Also, to conform to the memory efficiency contract this method should be passed componentized DotNames, which all share common root instances. Of course for testing code this doesn't really matter.

Parameters:

annotations - A map to lookup annotation instances by class name

subclasses - A map to lookup subclasses by super class name

implementors - A map to lookup implementing classes by interface name

classes - A map to lookup classes by class name

Returns:

the index

create

public static Index create(Map<DotName,List<AnnotationInstance>> annotations,
                           Map<DotName,List<ClassInfo>> subclasses,
                           Map<DotName,List<ClassInfo>> implementors,
                           Map<DotName,ClassInfo> classes,
                           Map<DotName,List<ClassInfo>> users)

Constructs a "mock" Index using the passed values. All passed values MUST NOT BE MODIFIED AFTER THIS CALL. Otherwise the resulting object would not conform to the contract outlined above. Also, to conform to the memory efficiency contract this method should be passed componentized DotNames, which all share common root instances. Of course for testing code this doesn't really matter.

Parameters:

annotations - A map to lookup annotation instances by class name

subclasses - A map to lookup subclasses by super class name

implementors - A map to lookup implementing classes by interface name

classes - A map to lookup classes by class name

users - A map to lookup class users

Returns:

the index

create

public static Index create(Map<DotName,List<AnnotationInstance>> annotations,
                           Map<DotName,List<ClassInfo>> subclasses,
                           Map<DotName,List<ClassInfo>> subinterfaces,
                           Map<DotName,List<ClassInfo>> implementors,
                           Map<DotName,ClassInfo> classes,
                           Map<DotName,List<ClassInfo>> users)

Constructs a "mock" Index using the passed values. All passed values MUST NOT BE MODIFIED AFTER THIS CALL. Otherwise the resulting object would not conform to the contract outlined above. Also, to conform to the memory efficiency contract this method should be passed componentized DotNames, which all share common root instances. Of course for testing code this doesn't really matter.

Parameters:

annotations - A map to lookup annotation instances by class name

subclasses - A map to lookup subclasses by super class name

subinterfaces - A map to lookup subinterfaces by super interface name

implementors - A map to lookup implementing classes by interface name

classes - A map to lookup classes by class name

users - A map to lookup class users

Returns:

the index

of

public static Index of(Iterable<Class<?>> classes)
                throws IOException

Constructs an Index of the passed classes.

Parameters:

classes - Classes to index

Returns:

the index

Throws:

IOException

of

public static Index of(Class<?>... classes)
                throws IOException

Constructs an Index of the passed classes.

Parameters:

classes - Classes to index

Returns:

the index

Throws:

IOException

of

public static Index of(File... files)
                throws IOException

Constructs an Index of the passed files and directories. Files may be class files or JAR files. Directories are scanned for class files, but not recursively.

Parameters:

files - class files, JAR files or directories containing class files to index

Returns:

the index

Throws:

IllegalArgumentException - if any passed File is null or not a class file, JAR file or directory

IOException

singleClass

public static ClassInfo singleClass(Class<?> clazz)
                             throws IOException

Creates a temporary Indexer, indexes given clazz, and returns the corresponding ClassInfo.

Parameters:

clazz - the class to index, must not be null

Returns:

the corresponding ClassInfo

Throws:

IOException

singleClass

public static ClassInfo singleClass(byte[] classData)
                             throws IOException

Creates a temporary Indexer, indexes given classData, and returns the corresponding ClassInfo.

Parameters:

classData - the class bytecode to index, must not be null

Returns:

the corresponding ClassInfo

Throws:

IOException

singleClass

public static ClassInfo singleClass(InputStream classData)
                             throws IOException

Creates a temporary Indexer, indexes given classData, and returns the corresponding ClassInfo. Closing the input stream is the caller's responsibility.

Parameters:

classData - the class bytecode to index, must not be null

Returns:

the corresponding ClassInfo

Throws:

IOException

getAnnotations

public List<AnnotationInstance> getAnnotations(DotName 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.

Specified by:

getAnnotations in interface IndexView

Parameters:

annotationName - the name of the annotation to look for

Returns:

a non-null list of annotation instances

getAnnotationsWithRepeatable

public Collection<AnnotationInstance> 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 AnnotationInstance.target() returns the target of the container annotation instance.

Specified by:

getAnnotationsWithRepeatable in interface IndexView

Parameters:

annotationName - the name of the repeatable annotation

index - the index containing the annotation class

Returns:

a non-null list of annotation instances

getKnownDirectSubclasses

public List<ClassInfo> getKnownDirectSubclasses(DotName className)

Gets all known direct subclasses of the specified class. 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.

Specified by:

getKnownDirectSubclasses in interface IndexView

Parameters:

className - the super class of the desired subclasses

Returns:

a non-null list of all known subclasses of className

getAllKnownSubclasses

public Collection<ClassInfo> getAllKnownSubclasses(DotName className)

Description copied from interface: IndexView

Returns all known (including non-direct) subclasses of the given class. I.e., returns all known classes that are assignable to the given class.

Specified by:

getAllKnownSubclasses in interface IndexView

Parameters:

className - The class

Returns:

All known subclasses

getKnownDirectSubinterfaces

public List<ClassInfo> getKnownDirectSubinterfaces(DotName interfaceName)

Gets all known direct subinterfaces of the specified interface. A known direct subinterface is one which was found during the scanning process; however, this is often not the complete universe of subinterfaces, 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 subinterfaces of the interface. It will not pick up subinterfaces of subinterfaces.

Specified by:

getKnownDirectSubinterfaces in interface IndexView

Parameters:

interfaceName - the super interface of the desired subinterfaces

Returns:

a non-null list of all known subinterfaces of interfaceName

getAllKnownSubinterfaces

public Collection<ClassInfo> getAllKnownSubinterfaces(DotName interfaceName)

Returns all known interfaces that extend the given interface, directly and indirectly. I.e., returns every interface in the index that is assignable to the given interface.

Specified by:

getAllKnownSubinterfaces in interface IndexView

Parameters:

interfaceName - The interace

Returns:

all known subinterfaces

getKnownDirectImplementors

public List<ClassInfo> getKnownDirectImplementors(DotName className)

Gets all known direct implementors of the specified interface. 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 also includes direct subinterfaces. This is inconsistent with IndexView.getAllKnownImplementors(DotName), which doesn't return subinterfaces.

Note that this will only pick up classes that directly implement given interface. It will not pick up classes implementing subinterfaces.

Specified by:

getKnownDirectImplementors in interface IndexView

Parameters:

className - the super class of the desired subclasses

Returns:

a non-null list of all known subclasses of className

getAllKnownImplementors

public Set<ClassInfo> getAllKnownImplementors(DotName interfaceName)

Returns all known classes that implement the given interface, directly and indirectly. This will return all classes that implement the interface and its subinterfaces, as well as subclasses of classes that implement the interface and its subinterfaces. (In short, it will return every class in the index that is assignable to the interface.)

Note that this method only returns classes. Unlike IndexView.getKnownDirectImplementors(DotName), this method does not return subinterfaces of given interface.

Specified by:

getAllKnownImplementors in interface IndexView

Parameters:

interfaceName - The interface

Returns:

All known implementors of the interface

getClassByName

public ClassInfo getClassByName(DotName className)

Gets the class (or interface, or annotation) that was scanned during the indexing phase.

Specified by:

getClassByName in interface IndexView

Parameters:

className - the name of the class

Returns:

information about the class or null if it is not known

getKnownClasses

public Collection<ClassInfo> getKnownClasses()

Gets all known classes by this index (those which were scanned).

Specified by:

getKnownClasses in interface IndexView

Returns:

a collection of known classes

getKnownModules

public Collection<ModuleInfo> getKnownModules()

Gets all known modules by this index (those which were scanned).

Specified by:

getKnownModules in interface IndexView

Returns:

a collection of known modules

getModuleByName

public ModuleInfo getModuleByName(DotName moduleName)

Gets the module that was scanned during the indexing phase.

Specified by:

getModuleByName in interface IndexView

Parameters:

moduleName - the name of the module

Returns:

information about the module or null if it is not known

getKnownUsers

public List<ClassInfo> getKnownUsers(DotName 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.

Specified by:

getKnownUsers in interface IndexView

Parameters:

className - the name of the class to look for

Returns:

a non-null list of classes that use the specified class

getClassesInPackage

public Collection<ClassInfo> getClassesInPackage(DotName packageName)

Description copied from interface: IndexView

Returns all classes known to this index that are present in given package. Classes present in subpackages of given package are not returned. Classes present in the unnamed package may be looked up using null as the package name. If this index does not contain any class in given package, returns an empty collection.

In the default Index implementation, this information is not stored in the index initially. Instead, an index of classes by package name is constructed on demand (on the first invocation of this method).

Specified by:

getClassesInPackage in interface IndexView

Parameters:

packageName - package name in the common, dot-separated form (e.g. com.example.foobar); null means the unnamed package

Returns:

immutable collection of classes present in given package, never null

getSubpackages

public Set<DotName> getSubpackages(DotName packageName)

Description copied from interface: IndexView

Returns a set of packages known to this index that are direct subpackages of given package. Indirect subpackages of given package (subpackages of subpackages) are not returned. If this index does not contain any class in a direct or indirect subpackage of given package, returns an empty collection.

Given that the unnamed package may not contain subpackages, passing null as the package name is permitted, but always results in an empty set.

In the default Index implementation, this information is not stored in the index initially. Instead, an index of packages is constructed on demand (on the first invocation of this method).

Specified by:

getSubpackages in interface IndexView

Parameters:

packageName - package name in the common, dot-separated form (e.g. com.example.foobar); null means the unnamed package

Returns:

immutable set of subpackages of given package, never null

printAnnotations

public void printAnnotations()

Print all annotations known by this index to stdout.

printSubclasses

public void printSubclasses()

Print all classes that have known subclasses, and all their subclasses