Describes the jQAssistant setup for using a remote Neo4j server within a CI build to provide teams a shared instance for exploration and analysis of their project.

Note
This tutorial has been written for jQAssistant 1.7.0

1. Prerequisites

2. Overview

By default jQAssistant uses an embedded Neo4j database for scanning software structures and executing rules. That means that for interactive exploration using Cypher queries the project first needs to be built and the embedded Neo4j server to be started.

For discussions about proposed design changes or refactorings in a project team it is helpful to have a permanent Neo4j instance available that can be explored by team members on demand. Such instance can be updated on regular base by a build job, e.g. once per night.

Therefore both the jQAssistant Maven plugin and the CLI allow connecting to an existing Neo4j instance. Scanning and analysis will then be performed against this server, the scanned information as well as all applied concepts will be available in the graph.

This tutorial describes the setup for the jQAssistant Maven Plugin and Command Line Utility

3. jQAssistant Maven Plugin

Maven allows using profiles that can be used to control the build process. The setup described in this section will make use of this mechanism to allow switching between the default jQAssistant Maven plugin configuration using an embedded Neo4j database and a configuration for connecting to a remote Neo4j instance.

Therefore the plugin setup is defined as usual in the pom.xml of the project’s root module:

pom.xml
<plugin>
    <groupId>com.buschmais.jqassistant</groupId>
    <artifactId>jqassistant-maven-plugin</artifactId>
    <version>1.7.0</version>
    <executions>
        <execution>
            <id>default-cli</id>
            <goals>
                <goal>scan</goal>
                <goal>analyze</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The setup can be verified by running the following command:

mvn clean install

The console will contain the following lines from the plugin:

...
[INFO] --- jqassistant-maven-plugin:1.7.0:scan (default-cli) @ project ---
...
[INFO] Using embedded Neo4j server 3.x
[INFO] Resetting store.
...

If the setup works as expected the file pom.xml is extended by a build profile nightly that overrides the default store configuration:

pom.xml
<profiles>
    <profile>
        <id>nightly</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>com.buschmais.jqassistant</groupId>
                    <artifactId>jqassistant-maven-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>default-cli</id>
                            <configuration>
                                <store>
                                    <uri>bolt://localhost:7687</uri> <!-- 1 -->
                                    <username>neo4j</username>       <!-- 2 -->
                                    <password>secret</password>      <!-- 3 -->
                                </store>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>
  1. The URL of the running Neo4j 3.x server

  2. The user name to be used for the connection.

  3. The password of the user.

mvn clean install -Pnightly

The console now contains the following lines:

...
[INFO] --- jqassistant-maven-plugin:1.7.0:scan (default-cli) @ project ---
[INFO] Loaded jQAssistant plugins [CDI, Common, Core Analysis, Core Report, EJB3, GraphML, JAX-RS, JPA 2, JSON, JUnit, Java, Java 8, Java EE 6, Maven 3, OSGi, RDBMS, Spring, TestNG, Tycho, XML, YAML].
[INFO] Connecting to store at 'bolt://localhost:7687' (username=neo4j)
[INFO] Resetting store.
...

4. Command Line Utility

Similar to the jQAssistant Maven Plugin the command line utility by default uses an embedded Neo4j instance.

jqassistant.sh scan -f my-project.jar

The command above will create a local folder jqassistant/store containing the database.

This can be overridden by the parameters storeUri, storeUsername and storePassword for connecting to the already running server:

jqassistant.sh scan -f my-project.jar -storeUri bolt://localhost:7687 -storeUsername neo4j -storePassword secret

5. Notes

  • Using a remote Neo4j instance results in slower performance during scans but should be acceptable for nightly builds.

6. Resources