Text of codeql.github.com › docs › codeql-language-guides › codeql-library-for-java as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

CodeQL library for Java and Kotlin — CodeQL

CodeQL » CodeQL language guides » CodeQL for Java and Kotlin » CodeQL library for Java and Kotlin ¶ When you’re analyzing a Java/Kotlin program, you can make use of the large collection of classes in the CodeQL library for Java/Kotlin. About the CodeQL library for Java and Kotlin ¶ There is an extensive library for analyzing CodeQL databases extracted from Java/Kotlin projects. The classes in this library present the data from a database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.

The library is implemented as a set of QL modules, that is, files with the extension .qll . The module java.qll imports all the core Java library modules, so you can include the complete library by beginning your query with: import java The rest of this article briefly summarizes the most important classes and predicates provided by this library. Note The example queries in this article illustrate the types of results returned by different library classes.

The results themselves are not interesting but can be used as the basis for developing a more complex query. The other articles in this section of the help show how you can take a simple query and fine-tune it to find precisely the results you’re interested in. Summary of the library classes ¶ The most important classes in the standard Java/Kotlin library can be grouped into five main categories: Classes for representing program elements (such as classes and methods) Classes for representing AST nodes (such as statements and expressions) Classes for representing metadata (such as annotations and comments) Classes for computing metrics (such as cyclomatic complexity and coupling) Classes for navigating the program’s call graph We will discuss each of these in turn, briefly describing the most important classes for each category.

Program elements ¶ These classes represent named program elements: packages ( Package ), compilation units ( CompilationUnit ), types ( Type ), methods ( Method ), constructors ( Constructor ), and variables ( Variable ). Their common superclass is Element , which provides general member predicates for determining the name of a program element and checking whether two elements are nested inside each other. It’s often convenient to refer to an element that might either be a method or a constructor; the class Callable , which is a common superclass of Method and Constructor , can be used for this purpose.

Types ¶ Class Type has a number of subclasses for representing different kinds of types: PrimitiveType represents a primitive type , that is, one of boolean , byte , char , double , float , int , long , short ; QL also classifies void and <nulltype> (the type of the null literal) as primitive types. RefType represents a reference (that is, non-primitive) type; it in turn has several subclasses: Class represents a Java class.

Interface represents a Java interface. EnumType represents a Java enum type. Array represents a Java array type. For example, the following query finds all variables of type int in the program: import java from Variable v , PrimitiveType pt where pt = v . getType () and pt . hasName ( "int" ) select v You’re likely to get many results when you run this query because most projects contain many variables of type int .

Reference types are also categorized according to their declaration scope: TopLevelType represents a reference type declared at the top-level of a compilation unit. NestedType is a type declared inside another type. For instance, this query finds all top-level types whose name is not the same as that of their compilation unit: import java from TopLevelType tl where tl . getName () != tl . getCompilationUnit (). getName () select tl You will typically see this pattern in the source code of a repository, with many more instances in the files referenced by the source code.

Several more specialized classes are available as well: TopLevelClass represents a class declared at the top-level of a compilation unit. NestedClass represents a class declared inside another type , such as: A LocalClass , which is a class declared inside a method or constructor . An AnonymousClass , which is an anonymous class . Finally, the library also has a number of singleton classes that wrap frequently used Java standard library classes: TypeObject , TypeCloneable , TypeRuntime , TypeSerializable , TypeString , TypeSystem and TypeClass .

Each CodeQL class represents the standard Java class suggested by its name. As an example, we can write a query that finds all nested classes that directly extend Object : import java from NestedClass nc where nc . getASupertype () instanceof TypeObject select nc You’re likely to get many results when you run this query because many projects include nested classes that extend Object directly. Generics ¶ There are also several subclasses of Type for dealing with generic types.

A GenericType is either a GenericInterface or a GenericClass . It represents a generic type declaration such as interface java.util.Map from the Java standard library: package java.util. ; public interface Map < K , V > { int size (); // ... } Type parameters, such as K and V in this example, are represented by class TypeVariable . A parameterized instance of a generic type provides a concrete type to instantiate the type parameter with, as in Map<String, File> .

Such a type is represented by a ParameterizedType , which is distinct from the GenericType representing the generic type it was instantiated from. To go from a ParameterizedType to its corresponding GenericType , you can use predicate getSourceDeclaration . For instance, we could use the following query to find all parameterized instances of java.util.Map : import java from GenericInterface map , ParameterizedType pt where map . hasQualifiedName ( "java.util" , "Map" ) and pt . getSourceDeclaration () = map select pt In general, generic types may restrict which types a type parameter can be bound to.

For instance, a type of maps from strings to numbers could be declared as follows: class StringToNumMap < N extends Number > implements Map < String , N > { // ... } This means that a parameterized instance of StringToNumberMap can only instantiate type parameter N with type Number or one of its subtypes but not, for example, with File . We say that N is a bounded type parameter, with Number as its upper bound. In QL, a type variable can be queried for its type bound using predicate getATypeBound .

The type bounds themselves are represented by class TypeBound , which has a member predicate getType to retrieve the type the variable is bounded by. As an example, the following query finds all type variables with type bound Number : import java from TypeVariable tv , TypeBound tb where tb = tv . getATypeBound () and tb . getType (). hasQualifiedName ( "java.lang" , "Number" ) select tv For dealing with legacy code that is unaware of generics, every generic type has a “raw” version without any type parameters.

In the CodeQL libraries, raw types are represented using class RawType , which has the expected subclasses RawClass and RawInterface . Again, there is a predicate getSourceDeclaration for obtaining the corresponding generic type. As an example, we can find variables of (raw) type Map : import java from Variable v , RawType rt where rt = v . getType () and rt . getSourceDeclaration (). hasQualifiedName ( "java.util" , "Map" ) select v For example, in the following code snippet this query would find m1 , but not m2 : Map m1 = new HashMap (); Map < String , String > m2 = new HashMap < String , String > (); Finally, variables can be declared to be of a wildcard type : Map <? extends Number , ? super Float > m ; The wildcards ? extends Number and ? super Float are represented by class WildcardTypeAccess .

Like type parameters, wildcards may have type bounds. Unlike type parameters, wildcards can have upper bounds (as in ? extends Number ), and also

The rest of this page is on the live site.