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 modulejava.qll imports all the core Java library modules, so you can include the complete library by beginning your query with:

importjava

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:

1. Classes for representing program elements (such as classes and methods)

2. Classes for representing AST nodes (such as statements and expressions)

3. Classes for representing metadata (such as annotations and comments)

4. Classes for computing metrics (such as cyclomatic complexity and coupling)

5. 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 isElement, 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 classCallable, which is a common superclass ofMethod andConstructor, can be used for this purpose.

importjavafromVariablev,PrimitiveTypeptwherept=v.getType()andpt.hasName("int")selectv

importjavafromTopLevelTypetlwheretl.getName()!=tl.getCompilationUnit().getName()selecttl

importjavafromNestedClassncwherenc.getASupertype()instanceofTypeObjectselectnc

packagejava.util.;publicinterfaceMap<K,V>{intsize();// ...}

importjavafromGenericInterfacemap,ParameterizedTypeptwheremap.hasQualifiedName("java.util","Map")andpt.getSourceDeclaration()=mapselectpt

classStringToNumMap<NextendsNumber>implementsMap<String,N>{// ...}

importjavafromTypeVariabletv,TypeBoundtbwheretb=tv.getATypeBound()andtb.getType().hasQualifiedName("java.lang","Number")selecttv

importjavafromVariablev,RawTypertwherert=v.getType()andrt.getSourceDeclaration().hasQualifiedName("java.util","Map")selectv

Mapm1=newHashMap();Map<String,String>m2=newHashMap<String,String>();

Map<?extendsNumber,?superFloat>m;

Abstract syntax tree¶

Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (classStmt) and expressions (classExpr). For a full list of expression and statement types available in the standard QL library, see “Abstract syntax tree classes for working with Java and Kotlin programs.”

BothExpr andStmt provide member predicates for exploring the abstract syntax tree of a program:

• Expr.getAChildExpr returns a sub-expression of a given expression.

• Stmt.getAChild returns a statement or expression that is nested directly inside a given statement.

• Expr.getParent andStmt.getParent return the parent node of an AST node.

For example, the following query finds all expressions whose parents arereturn statements:

importjavafromExprewheree.getParent()instanceofReturnStmtselecte

Many projects have examples ofreturn statements with child expressions.

Therefore, if the program contains a return statementreturnx+y;, this query will returnx+y.

As another example, the following query finds statements whose parent is anif statement:

importjavafromStmtswheres.getParent()instanceofIfStmtselects

Many projects have examples ofif statements with child statements.

This query will find boththen branches andelse branches of allif statements in the program.

Finally, here is a query that finds method bodies:

importjavafromStmtswheres.getParent()instanceofMethodselects

As these examples show, the parent node of an expression is not always an expression: it may also be a statement, for example, anIfStmt. Similarly, the parent node of a statement is not always a statement: it may also be a method or a constructor. To capture this, the QL Java library provides two abstract classExprParent andStmtParent, the former representing any node that may be the parent node of an expression, and the latter any node that may be the parent node of a statement.

For more information on working with AST classes, see thearticle on overflow-prone comparisons in Java and Kotlin.

Metadata¶

Java/Kotlin programs have several kinds of metadata, in addition to the program code proper. In particular, there areannotations andJavadoc comments. Since this metadata is interesting both for enhancing code analysis and as an analysis subject in its own right, the QL library defines classes for accessing it.

For annotations, classAnnotatable is a superclass of all program elements that can be annotated. This includes packages, reference types, fields, methods, constructors, and local variable declarations. For every such element, its predicategetAnAnnotation allows you to retrieve any annotations the element may have. For example, the following query finds all annotations on constructors:

importjavafromConstructorcselectc.getAnAnnotation()

You may see examples where annotations are used to suppress warnings or to mark code as deprecated.

These annotations are represented by classAnnotation. An annotation is simply an expression whose type is anAnnotationType. For example, you can amend this query so that it only reports deprecated constructors:

importjavafromConstructorc,Annotationann,AnnotationTypeanntpwhereann=c.getAnAnnotation()andanntp=ann.getType()andanntp.hasQualifiedName("java.lang","Deprecated")selectann

Only constructors with the@Deprecated annotation are reported this time.

For more information on working with annotations, see thearticle on annotations.

For Javadoc, classElement has a member predicategetDoc that returns a delegateDocumentable object, which can then be queried for its attached Javadoc comments. For example, the following query finds Javadoc comments on private fields:

importjavafromFieldf,Javadocjdocwheref.isPrivate()andjdoc=f.getDoc().getJavadoc()selectjdoc

You can see this pattern in many projects.

ClassJavadoc represents an entire Javadoc comment as a tree ofJavadocElement nodes, which can be traversed using member predicatesgetAChild andgetParent. For instance, you could edit the query so that it finds all@author tags in Javadoc comments on private fields:

importjavafromFieldf,Javadocjdoc,AuthorTagatwheref.isPrivate()andjdoc=f.getDoc().getJavadoc()andat.getParent+()=jdocselectat

Note

On line 5 we usedgetParent+ to capture tags that are nested at any depth within the Javadoc comment.

For more information on working with Javadoc, see thearticle on Javadoc.

Metrics¶

The standard QL Java library provides extensive support for computing metrics on Java program elements. To avoid overburdening the classes representing those elements with too many member predicates related to metric computations, these predicates are made available on delegate classes instead.

Altogether, there are six such classes:MetricElement,MetricPackage,MetricRefType,MetricField,MetricCallable, andMetricStmt. The corresponding element classes each provide a member predicategetMetrics that can be used to obtain an instance of the delegate class, on which metric computations can then be performed.

For example, the following query finds methods with acyclomatic complexity greater than 40:

importjavafromMethodm,MetricCallablemcwheremc=m.getMetrics()andmc.getCyclomaticComplexity()>40selectm

Most large projects include some methods with a very high cyclomatic complexity. These methods are likely to be difficult to understand and test.

Call graph¶

CodeQL databases generated from Java and Kotlin code bases include precomputed information about the program’s call graph, that is, which methods or constructors a given call may dispatch to at runtime.

The classCallable, introduced above, includes both methods and constructors. Call expressions are abstracted using classCall, which includes method calls,new expressions, and explicit constructor calls usingthis orsuper.

We can use predicateCall.getCallee to find out which method or constructor a specific call expression refers to. For example, the following query finds all calls to methods calledprintln:

importjavafromCallc,Methodmwherem=c.getCallee()andm.hasName("println")selectc

Conversely,Callable.getAReference returns aCall that refers to it. So we can find methods and constructors that are never called using this query:

importjavafromCallablecwherenotexists(c.getAReference())selectc

Codebases often have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see “Navigating the call graph.”

For more information about callables and calls, see thearticle on the call graph.

Further reading¶

• CodeQL queries for Java

• Example queries for Java

• CodeQL library reference for Java

• “QL language reference”

• “CodeQL tools”