jQAssistant 1.10.0 released

jQAssistant 1.10.0 is available now and it comes with the following new features:

Java Generics

The Java scanner – after a long time – finally supports generic types, e.g.

private List<FederationUploadKey> originalKeys;

is represented in the graph by

(field:Field)-[:OF_GENERIC_TYPE]->(parameterizedType:ParameterizedType),
(parameterizedType)-[:OF_RAW_TYPE]->(fieldType:Type{fqn:"java.util.List"}),
(parameterizedType)-[:HAS_ACTUAL_TYPE_ARGUMENT{index:0}]->(typeArgument),
(typeArgument)-[:OF_RAW_TYPE]->(elementType:Type{fqn:"app.coronawarn.server.common.persistence.domain.FederationUploadKey"})

The graph model has been designed such that it stays as close as possible to the generic type model of the Java reflections API, containing elements (i.e. labels) like TypeVariable, ParameterizedType, WildcardType or GenericArrayType. These can be applied to various elements of the language, e.g. type or method declarations, field types, method parameters or return types of methods. The generic model (similar to Java itself) is an addition to the raw non-generic model such that it is backwards compatible to existing queries or rules.

For details refer to the documentation of the Java plugin in the user manual.

Improved Spring Rules and Extensible Concepts

The rules for Spring Boot have been improved continuously over the last releases, including this one. Beside adding new rules the main focus is to eliminate false-positive constraint violations. In that context a recurring problem have been issues which were caused by generated code.

The Spring Boot constraints now have been extended such that they do no longer consider generated Java classes by filtering for the label „:Generated“ requiring a newly introduced concept „java:GeneratedType“ to be executed before.

These rules are pre-defined by jQAssistant plugins but an application may extend them by creating a project specific concept declaring „providesConcept(s)“ refering to the concept to be extended. The following concept extends „java:GeneratedType“ (Asciidoc) with classes from a project package:

[[adr:GeneratedProtobufTypes]]
[source,cypher,role=concept,providesConcepts="java:GeneratedType"]
.The generated Protobuf classes are located in the sub-packages of `app.coronawarn.server.common.protocol` and labeled with `Protobuf`.
----
MATCH
  (package:Package)-[:CONTAINS]->(protobufType:Java:Type)
WHERE
  protobufType.fqn STARTS WITH 'app.coronawarn.server.common.protocol'
SET
  protobufType:Protobuf:Generated
RETURN
  package AS Package, count(protobufType) AS ProtobufTypes
ORDER BY
  Package.fqn
----

The same concept specified in XML:

<concept id="adr:GeneratedProtobufTypes">
  <providesConcept refId="java:GeneratedType"/>
  <cypher><![CDATA[
    MATCH
      (package:Package)-[:CONTAINS]->(protobufType:Java:Type)
    WHERE
      protobufType.fqn STARTS WITH 'app.coronawarn.server.common.protocol'
    SET
      protobufType:Protobuf:Generated
    RETURN
      package AS Package, count(protobufType) AS ProtobufTypes
    ORDER BY
      Package.fqn
    ]]></cypher>
</concept>

As a consequence the types in this package are no longer considered by the constraints of the Spring plugin.

Docker Image for Jupyter Notebooks

Jupyter Notebooks are very helpful for performing reproducible analysis of software system, e.g. determining the impact of changes like migrating a framework.

To ease the setup a Docker image is now provided which comes with example queries and visualizations:

The easiest way for making use of it is to create a file „docker-compose.yml“ and run „docker-compose up“:

version: '3'
services:
  neo4j:
    image: neo4j:3.5.28
    ports:
      - 7474:7474
      - 7687:7687
    environment:
      - NEO4J_AUTH=none
    volumes:
      - ./target/jqassistant/store:/data/databases/graph.db
  jupyter:
    image: jqassistant/jupyter-notebook:1.10.0
    ports:
      - 8888:8888
    environment:
      - NEO4J_URL=http://neo4j:7474
    volumes:
      - ./jqassistant/jupyter:/home/jovyan/work

The image and usage instructions are available on DockerHub.

Changes for Plugin Developers

There are two noteworthy changes that affect plugin developers:

• The XML schema for plugin descriptors has been extended to support an id attribute for a plugin. This is currently optional but will become mandatory in later versions. The rationale behind is to allow per-plugin configurations (e.g. enabling/disabling). The schema is available here
• The core framework comes with an embedded Asciidoctor library. As part of this release the version has been migration from 1.5.x to 2.5.x including breaking changes in the API. The migration path is documented here.

Distributions, Release Notes and Examples

Users of the Maven plugin only need to update the jQAssistant version in their pom.xml file:

<plugin>
  <groupId>com.buschmais.jqassistant</groupId>
  <artifactId>jqassistant-maven-plugin</artifactId>
  <version>1.10.0</version>
  ...
</plugin>

The command line distribution is available for download here

A full list of changes is available in the Release Notes.

If you’re looking for examples refer to the Corona Warn App Server, Spring PetClinic and Piggy Metrics applications.