Basic query for Java and Kotlin code¶

Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.

For information about installing the CodeQL extension for Visual Studio code, see “Installing CodeQL for Visual Studio Code.”

About the query¶

The query we’re going to run searches for inefficient tests for empty strings. For example, Java code such as:

public class TestJava {
    void myJavaFun(String s) {
        boolean b = s.equals("");
    }
}

or Kotlin code such as:

void myKotlinFun(s: String) {
    var b = s.equals("")
}

In either case, replacing s.equals("") with s.isEmpty() would be more efficient.

Finding a CodeQL database to experiment with¶

Before you start writing queries for Java/Kotlin code, you need a CodeQL database to run them against. The simplest way to do this is to download a database for a repository that uses Java/Kotlin directly from GitHub.com.

In Visual Studio Code, click the QL icon in the left sidebar to display the CodeQL extension.
Click From GitHub or the GitHub logo at the top of the CodeQL extension to open an entry field.
Copy the URL for the repository into the field and press the keyboard Enter key. For example, https://github.com/apache/activemq.
Optionally, if the repository has more than one CodeQL database available, select java to download the database created from the Java/Kotlin code.

Information about the download progress for the database is shown in the bottom right corner of Visual Studio Code. When the download is complete, the database is shown with a check mark in the Databases section of the CodeQL extension (see screenshot below).

Running a quick query¶

The CodeQL extension for Visual Studio Code adds several CodeQL: commands to the command palette including Quick Query, which you can use to run a query without any set up.

From the command palette in Visual Studio Code, select CodeQL: Quick Query.
After a moment, a new tab quick-query.ql is opened, ready for you to write a query for your currently selected CodeQL database (here a java database). If you are prompted to reload your workspace as a multi-folder workspace to allow Quick queries, accept or create a new workspace using the starter workflow.

In the quick query tab, delete select "" and paste the following query beneath the import statement import java.
```
from MethodAccess ma
where
    ma.getMethod().hasName("equals") and
    ma.getArgument(0).(StringLiteral).getValue() = ""
select ma, "This comparison to empty string is inefficient, use isEmpty() instead."
```
Note that CodeQL treats Java and Kotlin as part of the same language, so even though this query starts with import java, it will work for both Java and Kotlin code.

Save the query in its default location (a temporary “Quick Queries” directory under the workspace for GitHub.vscode-codeql/quick-queries).

Right-click in the query tab and select CodeQL: Run Query on Selected Database. (Alternatively, run the command from the Command Palette.)

The query will take a few moments to return results. When the query completes, the results are displayed in a CodeQL Query Results view, next to the main editor view.

The query results are listed in two columns, corresponding to the expressions in the select clause of the query. The first column corresponds to the expression ma and is linked to the location in the source code of the project where ma occurs. The second column is the alert message.

../../_images/basic-java-query-results-1.png

If any matching code is found, click a link in the ma column to view the .equals expression in the code viewer.

../../_images/basic-java-query-results-2.png

Note

If you want to move your experimental query somewhere more permanent, you need to move the whole Quick Queries directory. The directory is a CodeQL pack with a qlpack.yml file that defines the content as queries for Java/Kotlin CodeQL databases. For more information about CodeQL packs, see “Managing CodeQL query packs and library packs.”

About the query structure¶

After the initial import statement, this simple query comprises three parts that serve similar purposes to the FROM, WHERE, and SELECT parts of an SQL query.

Query part	Purpose	Details
`import java`	Imports the standard CodeQL libraries for Java and Kotlin.	Every query begins with one or more `import` statements.
`from MethodAccess ma`	Defines the variables for the query. Declarations are of the form: `<type> <variable name>`	We use: a `MethodAccess` variable for call expressions
`where ma.getMethod().hasName("equals") and ma.getArgument(0).(StringLiteral).getValue() = ""`	Defines a condition on the variables.	`ma.getMethod().hasName("equals")` restricts `ma` to only calls to methods call `equals`. `ma.getArgument(0).(StringLiteral).getValue() = ""` says the argument must be literal `""`.
`select ma, "This comparison to empty string is inefficient, use isEmpty() instead."`	Defines what to report for each match. `select` statements for queries that are used to find instances of poor coding practice are always in the form: `select <program element>, "<alert message>"`	Reports the resulting `.equals` expression with a string that explains the problem.

Extend the query¶

Query writing is an inherently iterative process. You write a simple query and then, when you run it, you discover examples that you had not previously considered, or opportunities for improvement.

Remove false positive results¶

Browsing the results of our basic query shows that it could be improved. For example, you may find results for code like:

public class TestJava {
    void myJavaFun(Object o) {
        boolean b = o.equals("");
    }
}

In this case, it is not possible to simply use o.isEmpty() instead, as o has type Object rather than String. One solution to this is to modify the query to only return results where the expression being tested has type String:

Extend the where clause to include the following extra condition:

ma.getQualifier().getType() instanceof TypeString

The where clause is now:

where
  ma.getQualifier().getType() instanceof TypeString and
  ma.getMethod().hasName("equals") and
  ma.getArgument(0).(StringLiteral).getValue() = ""

Re-run the query.

There are now fewer results because .equals expressions with different types are no longer included.