зеркало из https://github.com/github/codeql.git
Docs: Update Java
This commit is contained in:
Shati Patel
Родитель
fbc11e505f
Коммит
6090867542
|
|
@ -4,9 +4,9 @@ Tutorial: Annotations
|
|||
Overview
|
||||
--------
|
||||
|
||||
Snapshots of Java projects contain information about all annotations attached to program elements.
|
||||
CodeQL databases of Java projects contain information about all annotations attached to program elements.
|
||||
|
||||
In QL, annotations are represented as follows:
|
||||
Annotations are represented by the following CodeQL classes:
|
||||
|
||||
- The class ``Annotatable`` represents all entities that may have an annotation attached to them (that is, packages, reference types, fields, methods, and local variables).
|
||||
- The class ``AnnotationType`` represents a Java annotation type, such as ``java.lang.Override``; annotation types are interfaces.
|
||||
|
|
@ -23,7 +23,7 @@ As an example, recall that the Java standard library defines an annotation ``Sup
|
|||
String[] value;
|
||||
}
|
||||
|
||||
In QL, ``SuppressWarnings`` is represented as an ``AnnotationType``, with ``value`` as its only ``AnnotationElement``.
|
||||
``SuppressWarnings`` is represented as an ``AnnotationType``, with ``value`` as its only ``AnnotationElement``.
|
||||
|
||||
A typical usage of ``SuppressWarnings`` would be the following annotation to prevent a warning about using raw types:
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ A typical usage of ``SuppressWarnings`` would be the following annotation to pre
|
|||
}
|
||||
}
|
||||
|
||||
In QL, the expression ``@SuppressWarnings("rawtypes")`` is represented as an ``Annotation``. The string literal ``"rawtypes"`` is used to initialize the annotation element ``value``, and its value can be extracted from the annotation by means of the ``getValue`` predicate.
|
||||
The expression ``@SuppressWarnings("rawtypes")`` is represented as an ``Annotation``. The string literal ``"rawtypes"`` is used to initialize the annotation element ``value``, and its value can be extracted from the annotation by means of the ``getValue`` predicate.
|
||||
|
||||
We could then write the following query to find all ``@SuppressWarnings`` annotations attached to constructors, and return both the annotation itself and the value of its ``value`` element:
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ As a first step, let us write a query that finds all ``@Override`` annotations.
|
|||
where ann.getType().hasQualifiedName("java.lang", "Override")
|
||||
select ann
|
||||
|
||||
As always, it is a good idea to try this query on a Java snapshot to make sure it actually produces some results. On the earlier example, it should find the annotation on ``Sub1.m``. Next, we encapsulate the concept of an ``@Override`` annotation as a QL class:
|
||||
As always, it is a good idea to try this query on a CodeQL database for a Java project to make sure it actually produces some results. On the earlier example, it should find the annotation on ``Sub1.m``. Next, we encapsulate the concept of an ``@Override`` annotation as a CodeQL class:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -147,7 +147,7 @@ For example, consider the following example program:
|
|||
|
||||
Here, both ``A.m`` and ``A.n`` are marked as deprecated. Methods ``n`` and ``r`` both call ``m``, but note that ``n`` itself is deprecated, so we probably should not warn about this call.
|
||||
|
||||
Like in the previous example, we start by defining a QL class for representing ``@Deprecated`` annotations:
|
||||
Like in the previous example, we start by defining a class for representing ``@Deprecated`` annotations:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -204,7 +204,7 @@ For instance, consider this slightly updated example:
|
|||
|
||||
Here, the programmer has explicitly suppressed warnings about deprecated calls in ``A.r``, so our query should not flag the call to ``A.m`` any more.
|
||||
|
||||
To do so, we first introduce a QL class for representing all ``@SuppressWarnings`` annotations where the string ``deprecated`` occurs among the list of warnings to suppress:
|
||||
To do so, we first introduce a class for representing all ``@SuppressWarnings`` annotations where the string ``deprecated`` occurs among the list of warnings to suppress:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -238,6 +238,6 @@ Now we can extend our query to filter out calls in methods carrying a ``Suppress
|
|||
What next?
|
||||
----------
|
||||
|
||||
- Take a look at some of the other tutorials: :doc:`Tutorial: Javadoc <javadoc>`, :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Take a look at some of the other tutorials: :doc:`Tutorial: Javadoc <javadoc>` and :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Statement classes
|
|||
This table lists all subclasses of `Stmt`_.
|
||||
|
||||
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
|
||||
| Statement syntax | QL class | Superclasses | Remarks |
|
||||
| Statement syntax | CodeQL class | Superclasses | Remarks |
|
||||
+========================================================================+===========================================================================================================================================================+===================================+=============================================+
|
||||
| ``;`` | `EmptyStmt <https://help.semmle.com/qldoc/java/semmle/code/java/Statement.qll/type.Statement$EmptyStmt.html>`__ | | |
|
||||
+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------+---------------------------------------------+
|
||||
|
|
@ -87,7 +87,7 @@ Literals
|
|||
All classes in this subsection are subclasses of `Literal <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Literal.html>`__.
|
||||
|
||||
+---------------------------+--------------------------+
|
||||
| Expression syntax example | QL class |
|
||||
| Expression syntax example | CodeQL class |
|
||||
+===========================+==========================+
|
||||
| ``true`` | ``BooleanLiteral`` |
|
||||
+---------------------------+--------------------------+
|
||||
|
|
@ -112,7 +112,7 @@ Unary expressions
|
|||
All classes in this subsection are subclasses of `UnaryExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$UnaryExpr.html>`__.
|
||||
|
||||
+---------------------------+-----------------+---------------------+---------------------------------------------------+
|
||||
| Expression syntax example | QL class | Superclasses | Remarks |
|
||||
| Expression syntax example | CodeQL class | Superclasses | Remarks |
|
||||
+===========================+=================+=====================+===================================================+
|
||||
| ``x++`` | ``PostIncExpr`` | ``UnaryAssignExpr`` | |
|
||||
+---------------------------+-----------------+---------------------+---------------------------------------------------+
|
||||
|
|
@ -137,7 +137,7 @@ Binary expressions
|
|||
All classes in this subsection are subclasses of `BinaryExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$BinaryExpr.html>`__.
|
||||
|
||||
+---------------------------+--------------------+--------------------+
|
||||
| Expression syntax example | QL class | Superclasses |
|
||||
| Expression syntax example | CodeQL class | Superclasses |
|
||||
+===========================+====================+====================+
|
||||
| ``x * y`` | ``MulExpr`` | |
|
||||
+---------------------------+--------------------+--------------------+
|
||||
|
|
@ -184,7 +184,7 @@ Assignment expressions
|
|||
All classes in this table are subclasses of `Assignment <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$Assignment.html>`__.
|
||||
|
||||
+---------------------------+-----------------------+--------------+
|
||||
| Expression syntax example | QL class | Superclasses |
|
||||
| Expression syntax example | CodeQL class | Superclasses |
|
||||
+===========================+=======================+==============+
|
||||
| ``x = y`` | ``AssignExpr`` | |
|
||||
+---------------------------+-----------------------+--------------+
|
||||
|
|
@ -215,7 +215,7 @@ Accesses
|
|||
~~~~~~~~
|
||||
|
||||
+--------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
|
||||
| Expression syntax examples | QL class |
|
||||
| Expression syntax examples | CodeQL class |
|
||||
+======================================+=========================================================================================================================+
|
||||
| ``this`` | `ThisAccess <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$ThisAccess.html>`__ |
|
||||
+--------------------------------------+ +
|
||||
|
|
@ -250,7 +250,7 @@ Miscellaneous
|
|||
~~~~~~~~~~~~~
|
||||
|
||||
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
|
||||
| Expression syntax examples | QL class | Remarks |
|
||||
| Expression syntax examples | CodeQL class | Remarks |
|
||||
+==================================================================+=======================================================================================================================+=============================================================================+
|
||||
| ``(int) f`` | `CastExpr <https://help.semmle.com/qldoc/java/semmle/code/java/Expr.qll/type.Expr$CastExpr.html>`__ | |
|
||||
+------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------+
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Tutorial: Navigating the call graph
|
|||
Call graph API
|
||||
--------------
|
||||
|
||||
The QL Java library provides two abstract classes for representing a program's call graph: ``Callable`` and ``Call``. The former is simply the common superclass of ``Method`` and ``Constructor``, the latter is a common superclass of ``MethodAccess``, ``ClassInstanceExpression``, ``ThisConstructorInvocationStmt`` and ``SuperConstructorInvocationStmt``. Simply put, a ``Callable`` is something that can be invoked, and a ``Call`` is something that invokes a ``Callable``.
|
||||
The CodeQL library for Java provides two abstract classes for representing a program's call graph: ``Callable`` and ``Call``. The former is simply the common superclass of ``Method`` and ``Constructor``, the latter is a common superclass of ``MethodAccess``, ``ClassInstanceExpression``, ``ThisConstructorInvocationStmt`` and ``SuperConstructorInvocationStmt``. Simply put, a ``Callable`` is something that can be invoked, and a ``Call`` is something that invokes a ``Callable``.
|
||||
|
||||
For example, in the following program all callables and calls have been annotated with comments:
|
||||
|
||||
|
|
@ -160,6 +160,6 @@ Finally, on many Java projects there are methods that are invoked indirectly by
|
|||
What next?
|
||||
----------
|
||||
|
||||
- Find out how to query metadata and white space: :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out how to query metadata and white space: :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, and :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ Analyzing data flow in Java
|
|||
Overview
|
||||
--------
|
||||
|
||||
This topic describes how data flow analysis is implemented in the QL for Java library and includes examples to help you write your own data flow queries.
|
||||
The following sections describe how to utilize the QL libraries for local data flow, global data flow and taint tracking.
|
||||
This topic describes how data flow analysis is implemented in the CodeQL libraries for Java and includes examples to help you write your own data flow queries.
|
||||
The following sections describe how to utilize the libraries for local data flow, global data flow, and taint tracking.
|
||||
|
||||
For a more general introduction to modeling data flow in QL, see :doc:`Introduction to data flow analysis in QL <../intro-to-data-flow>`.
|
||||
For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
|
||||
|
||||
Local data flow
|
||||
---------------
|
||||
|
|
|
|||
|
|
@ -22,12 +22,12 @@ If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``
|
|||
|
||||
All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value.
|
||||
|
||||
We will develop a query that finds code that looks like it might exhibit this kind of behavior. We will be using several of the standard QL library classes for representing statements and functions, a full list of which can be found in the :doc:`AST class reference <ast-class-reference>`.
|
||||
We will develop a query that finds code that looks like it might exhibit this kind of behavior. We will be using several of the standard library classes for representing statements and functions, a full list of which can be found in the :doc:`AST class reference <ast-class-reference>`.
|
||||
|
||||
Initial query
|
||||
-------------
|
||||
|
||||
We start out by writing a query that finds less-than expressions (QL class ``LTExpr``) where the left operand is of type ``int`` and the right operand is of type ``long``:
|
||||
We start out by writing a query that finds less-than expressions (CodeQL class ``LTExpr``) where the left operand is of type ``int`` and the right operand is of type ``long``:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ Notice that we use the predicate ``getType`` (available on all subclasses of ``E
|
|||
|
||||
The class ``LoopStmt`` is a common superclass of all loops, including, in particular, ``for`` loops as in our example above. While different kinds of loops have different syntax, they all have a loop condition, which can be accessed through predicate ``getCondition``. We use the reflexive transitive closure operator ``*`` applied to the ``getAChildExpr`` predicate to express the requirement that ``expr`` should be nested inside the loop condition. In particular, it can be the loop condition itself.
|
||||
|
||||
The final conjunct in the ``where`` clause takes advantage of the fact that QL predicates can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
|
||||
The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
|
||||
|
||||
Generalizing the query
|
||||
----------------------
|
||||
|
|
@ -76,7 +76,7 @@ In order to compare the ranges of types, we define a predicate that returns the
|
|||
(pt.hasName("long") and result=64)
|
||||
}
|
||||
|
||||
We now want to generalize our query to apply to any comparison where the width of the type on the smaller end of the comparison is less than the width of the type on the greater end. Let us call such a comparison *overflow prone*, and introduce an abstract QL class to model it:
|
||||
We now want to generalize our query to apply to any comparison where the width of the type on the smaller end of the comparison is less than the width of the type on the greater end. Let us call such a comparison *overflow prone*, and introduce an abstract class to model it:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -121,6 +121,6 @@ Now we rewrite our query to make use of these new classes:
|
|||
What next?
|
||||
----------
|
||||
|
||||
- Have a look at some of the other tutorials: :doc:`Tutorial: Types and the class hierarchy <types-class-hierarchy>`, :doc:`Tutorial: Navigating the call graph <call-graph>`, :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Have a look at some of the other tutorials: :doc:`Tutorial: Types and the class hierarchy <types-class-hierarchy>`, :doc:`Tutorial: Navigating the call graph <call-graph>`, :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, and :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,25 @@
|
|||
Introducing the QL libraries for Java
|
||||
=====================================
|
||||
Introducing the CodeQL libraries for Java
|
||||
=========================================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
There is an extensive QL library for analyzing Java code. The QL classes in this library present the data from a snapshot database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.
|
||||
There is an extensive library for analyzing CodeQL databases extracted from Java 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 other standard library modules, so you can include the complete library by beginning your query with:
|
||||
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 C/C++ library modules, so you can include the complete library by beginning your query with:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import java
|
||||
|
||||
The rest of this topic briefly summarizes the most important QL classes and predicates provided by this library.
|
||||
The rest of this topic briefly summarizes the most important classes and predicates provided by this library.
|
||||
|
||||
The example queries in this topic 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 tutorial topics 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 QL Java library can be grouped into five main categories:
|
||||
The most important classes in the standard Java 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)
|
||||
|
|
@ -89,7 +89,7 @@ Several more specialized classes are available as well:
|
|||
- A ``LocalClass``, which is `a class declared inside a method or constructor <http://docs.oracle.com/javase/tutorial/java/javaOO/localclasses.html>`__.
|
||||
- An ``AnonymousClass``, which is an `anonymous class <http://docs.oracle.com/javase/tutorial/java/javaOO/anonymousclasses.html>`__.
|
||||
|
||||
Finally, the QL 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 QL class represents the standard Java class suggested by its name.
|
||||
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``:
|
||||
|
||||
|
|
@ -160,7 +160,7 @@ As an example, the following query finds all type variables with type bound ``Nu
|
|||
|
||||
➤ `See this in the query console <https://lgtm.com/query/690010016/>`__. When we ran it on the LGTM.com demo projects, the *neo4j/neo4j*, *gradle/gradle* and *hibernate/hibernate-orm* projects all contained examples of this pattern.
|
||||
|
||||
For dealing with legacy code that is unaware of generics, every generic type has a "raw" version without any type parameters. In QL, 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``:
|
||||
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``:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -342,7 +342,7 @@ For example, the following query finds methods with a `cyclomatic complexity <ht
|
|||
Call graph
|
||||
----------
|
||||
|
||||
Snapshots databases generated from Java 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.
|
||||
CodeQL databases generated from Java 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 class ``Callable``, introduced above, includes both methods and constructors. Call expressions are abstracted using class ``Call``, which includes method calls, ``new`` expressions, and explicit constructor calls using ``this`` or ``super``.
|
||||
|
||||
|
|
@ -376,6 +376,6 @@ For more information about callables and calls, see the :doc:`call graph tutoria
|
|||
What next?
|
||||
----------
|
||||
|
||||
- Experiment with the worked examples in the QL for Java tutorial topics: :doc:`Types and the class hierarchy <types-class-hierarchy>`, :doc:`Expressions and statements <expressions-statements>`, :doc:`Navigating the call graph <call-graph>`, :doc:`Annotations <annotations>`, :doc:`Javadoc <javadoc>` and :doc:`Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Experiment with the worked examples in the CodeQL for Java tutorial topics: :doc:`Types and the class hierarchy <types-class-hierarchy>`, :doc:`Expressions and statements <expressions-statements>`, :doc:`Navigating the call graph <call-graph>`, :doc:`Annotations <annotations>`, :doc:`Javadoc <javadoc>` and :doc:`Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ The ``JavadocTag`` has several subclasses representing specific kinds of Javadoc
|
|||
Example: Finding spurious @param tags
|
||||
-------------------------------------
|
||||
|
||||
As an example of using the QL Javadoc API, let us write a query that finds ``@param`` tags that refer to a non-existent parameter.
|
||||
As an example of using the CodeQL Javadoc API, let us write a query that finds ``@param`` tags that refer to a non-existent parameter.
|
||||
|
||||
For example, consider the following program:
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ For example, consider the following Java program:
|
|||
|
||||
Notice that the Javadoc comment of ``A.foo`` documents two thrown exceptions: ``IOException`` and ``RuntimeException``. The former is clearly spurious: ``A.foo`` does not have a ``throws IOException`` clause, and thus cannot throw this kind of exception. On the other hand, ``RuntimeException`` is an unchecked exception, so it can be thrown even if there is no explicit ``throws`` clause listing it. Therefore, our query should flag the ``@throws`` tag for ``IOException``, but not the one for ``RuntimeException.``
|
||||
|
||||
Recall from above that QL represents ``@throws`` tags using class ``ThrowsTag``. This class does not provide a member predicate for determining the exception type that is being documented, so we first need to implement our own version. A simple version might look as follows:
|
||||
Recall from above that the CodeQL library represents ``@throws`` tags using class ``ThrowsTag``. This class does not provide a member predicate for determining the exception type that is being documented, so we first need to implement our own version. A simple version might look as follows:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ This program defines its own class ``IOException``, which is unrelated to the cl
|
|||
|
||||
As an example of the second problem, method ``A.foo`` from our previous example was annotated with a ``@throws RuntimeException`` tag. Our current version of ``mayThrow``, however, would think that ``A.foo`` cannot throw a ``RuntimeException``, and thus flag the tag as spurious.
|
||||
|
||||
We can make ``mayThrow`` less restrictive by introducing a new QL class to represent unchecked exceptions, which are just the subtypes of ``java.lang.RuntimeException`` and ``java.lang.Error``:
|
||||
We can make ``mayThrow`` less restrictive by introducing a new class to represent unchecked exceptions, which are just the subtypes of ``java.lang.RuntimeException`` and ``java.lang.Error``:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -220,5 +220,5 @@ What next?
|
|||
----------
|
||||
|
||||
- Find out how you can use the location API to define queries on whitespace: :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
QL for Java
|
||||
===========
|
||||
CodeQL for Java
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
|
@ -15,31 +15,31 @@ QL for Java
|
|||
source-locations
|
||||
ast-class-reference
|
||||
|
||||
These topics provide an overview of the QL Java standard library and show examples of how to use them.
|
||||
These topics provide an overview of the CodeQL libraries for Java and show examples of how to use them.
|
||||
|
||||
- `Basic Java QL query <https://lgtm.com/help/lgtm/console/ql-java-basic-example>`__ describes how to write and run queries using LGTM.
|
||||
- `Basic Java query <https://lgtm.com/help/lgtm/console/ql-java-basic-example>`__ describes how to write and run queries using LGTM.
|
||||
|
||||
- :doc:`Introducing the QL libraries for Java <introduce-libraries-java>` an introduction to the organization of the standard libraries used to write queries for Java code.
|
||||
- :doc:`Introducing the CodeQL libraries for Java <introduce-libraries-java>` introduces the standard libraries used to write queries for Java code.
|
||||
|
||||
- :doc:`Tutorial: Analyzing data flow in Java <dataflow>` demonstrates how to write queries using the standard QL for Java data flow and taint tracking libraries.
|
||||
- :doc:`Tutorial: Analyzing data flow in Java <dataflow>` demonstrates how to write queries using the standard data flow and taint tracking libraries for Java.
|
||||
|
||||
- :doc:`Tutorial: Types and the class hierarchy <types-class-hierarchy>` introduces the QL classes for representing a program's class hierarchy by means of examples.
|
||||
- :doc:`Tutorial: Types and the class hierarchy <types-class-hierarchy>` introduces the classes for representing a program's class hierarchy by means of examples.
|
||||
|
||||
- :doc:`Tutorial: Expressions and statements <expressions-statements>` introduces the QL classes for representing a program's syntactic structure by means of examples.
|
||||
- :doc:`Tutorial: Expressions and statements <expressions-statements>` introduces the classes for representing a program's syntactic structure by means of examples.
|
||||
|
||||
- :doc:`Tutorial: Navigating the call graph <call-graph>` a worked example of how to write a query that navigates a program's call graph to find unused methods.
|
||||
- :doc:`Tutorial: Navigating the call graph <call-graph>` is a worked example of how to write a query that navigates a program's call graph to find unused methods.
|
||||
|
||||
- :doc:`Tutorial: Annotations <annotations>` introduces the QL classes for representing annotations by means of examples.
|
||||
- :doc:`Tutorial: Annotations <annotations>` introduces the classes for representing annotations by means of examples.
|
||||
|
||||
- :doc:`Tutorial: Javadoc <javadoc>` introduces the QL classes for representing Javadoc comments by means of examples.
|
||||
- :doc:`Tutorial: Javadoc <javadoc>` introduces the classes for representing Javadoc comments by means of examples.
|
||||
|
||||
- :doc:`Tutorial: Working with source locations <source-locations>` a worked example of how to write a query that uses the location information provided in the snapshot for finding likely bugs.
|
||||
- :doc:`Tutorial: Working with source locations <source-locations>` is a worked example of how to write a query that uses the location information provided in the database for finding likely bugs.
|
||||
|
||||
- :doc:`AST class reference <ast-class-reference>` an overview of all AST classes in the QL standard library for Java.
|
||||
- :doc:`AST class reference <ast-class-reference>` gives an overview of all AST classes in the standard CodeQL library for Java.
|
||||
|
||||
Other resources
|
||||
---------------
|
||||
|
||||
- For examples of how to query common Java elements, see the `Java QL cookbook <https://help.semmle.com/wiki/display/CBJAVA>`__.
|
||||
- For the queries used in LGTM, display a `Java query <https://lgtm.com/search?q=language%3Ajava&t=rules>`__ and click **Open in query console** to see the QL code used to find alerts.
|
||||
- For more information about the Java QL library see the `QL library for Java <https://help.semmle.com/qldoc/java>`__.
|
||||
- For examples of how to query common Java elements, see the `Java cookbook <https://help.semmle.com/wiki/display/CBJAVA>`__.
|
||||
- For the queries used in LGTM, display a `Java query <https://lgtm.com/search?q=language%3Ajava&t=rules>`__ and click **Open in query console** to see the code used to find alerts.
|
||||
- For more information about the library for Java see the `CodeQL library for Java <https://help.semmle.com/qldoc/java>`__.
|
||||
|
|
|
|||
|
|
@ -16,12 +16,12 @@ Note that the source layout gives a fairly clear indication of the intended mean
|
|||
|
||||
We will now develop a query that finds this kind of suspicious nesting, where the operator of the inner expression has more white space around it than the operator of the outer expression. This pattern may not necessarily indicate a bug, but at the very least it makes the code hard to read and prone to misinterpretation.
|
||||
|
||||
White space is not directly represented in the snapshot database, but we can deduce its presence from the location information associated with program elements and AST nodes. So we will start by providing an overview of source location management in the QL standard library.
|
||||
White space is not directly represented in the CodeQL database, but we can deduce its presence from the location information associated with program elements and AST nodes. So we will start by providing an overview of source location management in the standard library for Java.
|
||||
|
||||
Location API
|
||||
------------
|
||||
|
||||
For every entity that has a representation in Java source code (including, in particular, program elements and AST nodes), the QL standard library provides the following predicates for accessing source location information:
|
||||
For every entity that has a representation in Java source code (including, in particular, program elements and AST nodes), the standard CodeQL library provides the following predicates for accessing source location information:
|
||||
|
||||
- ``getLocation`` returns a ``Location`` object describing the start and end position of the entity.
|
||||
- ``getFile`` returns a ``File`` object representing the file containing the entity.
|
||||
|
|
@ -123,7 +123,7 @@ If we run this initial query, we might notice some false positives arising from
|
|||
|
||||
i< start + 100
|
||||
|
||||
Note that our predicate ``operatorWS`` computes the **total** amount of white space around the operator, which, in this case, is one for the ``<`` and two for the ``+``. Ideally, we would like to exclude cases where the amount of white space before and after the operator are not the same. Currently, snapshot databases do not record enough information to figure this out, but as an approximation we could require that the total number of white space characters is even:
|
||||
Note that our predicate ``operatorWS`` computes the **total** amount of white space around the operator, which, in this case, is one for the ``<`` and two for the ``+``. Ideally, we would like to exclude cases where the amount of white space before and after the operator are not the same. Currently, CodeQL databases do not record enough information to figure this out, but as an approximation we could require that the total number of white space characters is even:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -141,7 +141,7 @@ Note that our predicate ``operatorWS`` computes the **total** amount of white sp
|
|||
|
||||
➤ `See this in the query console <https://lgtm.com/query/665761067/>`__. Any results will be refined by our changes to the query.
|
||||
|
||||
Another source of false positives are associative operators: in an expression of the form ``x + y+z``, the first plus is syntactically nested inside the second, since + in Java associates to the left; hence the expression is flagged as suspicious. But since + is associative to begin with, it does not matter which way around the operators are nested, so this is a false positive.To exclude these cases, let us define a new QL class identifying binary expressions with an associative operator:
|
||||
Another source of false positives are associative operators: in an expression of the form ``x + y+z``, the first plus is syntactically nested inside the second, since + in Java associates to the left; hence the expression is flagged as suspicious. But since + is associative to begin with, it does not matter which way around the operators are nested, so this is a false positive.To exclude these cases, let us define a new class identifying binary expressions with an associative operator:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -184,5 +184,5 @@ Whitespace suggests that the programmer meant to toggle ``i`` between zero and o
|
|||
What next?
|
||||
----------
|
||||
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Tutorial: Types and the class hierarchy
|
|||
Overview
|
||||
--------
|
||||
|
||||
The standard QL library for Java represents Java types by means of the ``Type`` class and its various subclasses.
|
||||
The standard CodeQL library represents Java types by means of the ``Type`` class and its various subclasses.
|
||||
|
||||
In particular, class ``PrimitiveType`` represents primitive types that are built into the Java language (such as ``boolean`` and ``int``), whereas ``RefType`` and its subclasses represent reference types, that is classes, interfaces, array types, and so on. This includes both types from the Java standard library (like ``java.lang.Object``) and types defined by non-library code.
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ In this tutorial, we do not try to distinguish these two cases. Our query should
|
|||
- Both ``source`` and ``target`` are array types.
|
||||
- The element type of ``source`` is a transitive super type of the element type of ``target``.
|
||||
|
||||
This recipe is not too difficult to translate into a QL query:
|
||||
This recipe is not too difficult to translate into a query:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -93,7 +93,7 @@ In code that does not use generics, this method is often used in the following w
|
|||
|
||||
Here, ``l`` has the raw type ``List``, so ``l.toArray`` has return type ``Object[]``, independent of the type of its argument array. Hence the cast goes from ``Object[]`` to ``A[]`` and will be flagged as problematic by our query, although at runtime this cast can never go wrong.
|
||||
|
||||
To identify these cases, we can create two QL classes that represent, respectively, the ``Collection.toArray`` class, and calls to this method or any method that overrides it:
|
||||
To identify these cases, we can create two CodeQL classes that represent, respectively, the ``Collection.toArray`` class, and calls to this method or any method that overrides it:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -160,7 +160,7 @@ Since ``zkProp`` is a map from ``Object`` to ``Object``, ``zkProp.entrySet`` ret
|
|||
|
||||
In general, we want to find calls to ``Collection.contains`` (or any of its overriding methods in any parameterized instance of ``Collection``), such that the type ``E`` of collection elements and the type ``A`` of the argument to ``contains`` are unrelated, that is, they have no common subtype.
|
||||
|
||||
We start by creating a QL class that describes ``java.util.Collection``:
|
||||
We start by creating a class that describes ``java.util.Collection``:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -179,7 +179,7 @@ To make sure we have not mistyped anything, we can run a simple test query:
|
|||
|
||||
This query should return precisely one result.
|
||||
|
||||
Next, we can create a QL class that describes ``java.util.Collection.contains``:
|
||||
Next, we can create a class that describes ``java.util.Collection.contains``:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -198,9 +198,9 @@ Notice that we use ``hasStringSignature`` to check that:
|
|||
|
||||
Alternatively, we could have implemented these three checks more verbosely using ``hasName``, ``getNumberOfParameters``, and ``getParameter(0).getType() instanceof TypeObject``.
|
||||
|
||||
As before, it is a good idea to test the new QL class by running a simple query to select all instances of ``JavaUtilCollectionContains``; again there should only be a single result.
|
||||
As before, it is a good idea to test the new class by running a simple query to select all instances of ``JavaUtilCollectionContains``; again there should only be a single result.
|
||||
|
||||
Now we want to identify all calls to ``Collection.contains``, including any methods that override it, and considering all parameterized instances of ``Collection`` and its subclasses. That is, we are looking for method accesses where the source declaration of the invoked method (reflexively or transitively) overrides ``Collection.contains``. We encode this in a QL class ``JavaUtilCollectionContainsCall``:
|
||||
Now we want to identify all calls to ``Collection.contains``, including any methods that override it, and considering all parameterized instances of ``Collection`` and its subclasses. That is, we are looking for method accesses where the source declaration of the invoked method (reflexively or transitively) overrides ``Collection.contains``. We encode this in a CodeQL class ``JavaUtilCollectionContainsCall``:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -230,7 +230,7 @@ For the latter, we proceed as follows:
|
|||
- Find a (reflexive or transitive) super type ``S`` of ``D`` that is a parameterized instance of ``java.util.Collection``.
|
||||
- Return the (only) type argument of ``S``.
|
||||
|
||||
We encode this in QL as follows:
|
||||
We encode this as follows:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
|
|
@ -268,11 +268,11 @@ Now we are ready to write a first version of our query:
|
|||
Improvements
|
||||
~~~~~~~~~~~~
|
||||
|
||||
For many programs, this query yields a large number of false positive results due to type variables and wild cards: if the collection element type is some type variable ``E`` and the argument type is ``String``, for example, QL will consider that the two have no common subtype, and our query will flag the call. An easy way to exclude such false positive results is to simply require that neither ``collEltType`` nor ``argType`` are instances of ``TypeVariable``.
|
||||
For many programs, this query yields a large number of false positive results due to type variables and wild cards: if the collection element type is some type variable ``E`` and the argument type is ``String``, for example, CodeQL will consider that the two have no common subtype, and our query will flag the call. An easy way to exclude such false positive results is to simply require that neither ``collEltType`` nor ``argType`` are instances of ``TypeVariable``.
|
||||
|
||||
Another source of false positives is autoboxing of primitive types: if, for example, the collection's element type is ``Integer`` and the argument is of type ``int``, predicate ``haveCommonDescendant`` will fail, since ``int`` is not a ``RefType``. Thus, our query should check that ``collEltType`` is not the boxed type of ``argType``.
|
||||
|
||||
Finally, ``null`` is special because its type (known as ``<nulltype>`` in QL) is compatible with every reference type, so we should exclude it from consideration.
|
||||
Finally, ``null`` is special because its type (known as ``<nulltype>`` in the CodeQL library) is compatible with every reference type, so we should exclude it from consideration.
|
||||
|
||||
Adding these three improvements, our final query becomes:
|
||||
|
||||
|
|
@ -295,6 +295,6 @@ Adding these three improvements, our final query becomes:
|
|||
What next?
|
||||
----------
|
||||
|
||||
- Take a look at some of the other tutorials: :doc:`Tutorial: Expressions and statements <expressions-statements>`, :doc:`Tutorial: Navigating the call graph <call-graph>`, :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the QL standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Take a look at some of the other tutorials: :doc:`Tutorial: Expressions and statements <expressions-statements>`, :doc:`Tutorial: Navigating the call graph <call-graph>`, :doc:`Tutorial: Annotations <annotations>`, :doc:`Tutorial: Javadoc <javadoc>`, and :doc:`Tutorial: Working with source locations <source-locations>`.
|
||||
- Find out how specific classes in the AST are represented in the standard library for Java: :doc:`AST class reference <ast-class-reference>`.
|
||||
- Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче