Setting Up A Team Server

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.8.0

1. Prerequisites

Existing Neo4j 3.x installation.

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.8.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.8.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 -->
                                    <!-- optional settings -->
                                    <!--
                                    <encryption>true</encryption>                                        (4)
                                    <trustStrategy>trustAllCertificates</trustStrategy>                  (5)
                                    <trustCertificate>path-to-self-signed-certificate</trustCertificate> (6)
                                    -->
                                </store>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

The URL of the running Neo4j 3.x server
The user name to be used for the connection.
The password of the user.
Defines if encryption shall be used for the server connection, valid values are true (default) or false.
The trust strategy in case encryption is enabled, valid values are trustAllCertificates, trustCustomCaSignedCertificates or trustSystemCaSignedCertificates
The file name of the custom CA certificate (in case of selected trust strategy trustCustomCaSignedCertificates).

mvn clean install -Pnightly

The console now contains the following lines:

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

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

ZIP archive including the application