//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
:imagesdir: ../images/

== Using JQAssistant

In PLC4X we are using a tool called `https://jqassistant.org/[JQAssistant]` for enforcing quality assurance rules.

`JQAssistant` can be thought of as a set of two components:

- A set of scanners that analyse a project and stores the gathered information in for of linked graphs in a Neo4j database.
- An engine that executes defined rules against the graph created during the scan phase of the build

These rules can produce either reports and tables or they are used to enforce rules.

If a pre-defined rule is violated the failed checks can be marked as `warning` or `error` that breaks the build.

In contrast to using the `maven-enforcer-plugin` doing cross-domain checks is really simple as all information is available in one big graph.

Currently the following scanners are active:

- CDI
- Common
- Common Test
- Core Analysis
- EJB3
- GraphML
- JAX-RS
- JPA 2
- JSON
- JUnit
- Java
- Java 8
- Java EE 6
- Maven 3
- OSGi
- RDBMS
- TestNG
- Tycho
- XML
- YAML

These rules that are automatically checked during the build are defined in `src/jjqassistant`.
If defined in a reactor project, the rules apply to all modules of that (sub-)reactor.
So if they are defined in the root module of the project, it applies to all modules.

=== Defining JQAssistant rules

TODO: Finish this "little detail" ...

=== Using the Web-UI

The scan and analysis is automatically performed during a normal Maven build.
In order to do ad-hoc queries against the project or develop new rules, the Web-UI is very helpful.

To start the Web-UI, all you need to do, is run the following command (after a build):

   mvn jqassistant:server

This will start a Neo4j server with web console.

   [INFO] --- jqassistant-maven-plugin:1.3.0:server (default-cli) @ plclogger ---
   [INFO] Connecting to store at 'file:/Users/christofer.dutz/Projects/Apache/PLC4X/target/jqassistant/store/'
   2018-04-05 19:11:14.369+0200 INFO  [o.n.s.CommunityNeoServer] No SSL certificate found, generating a self-signed certificate..
   2018-04-05 19:11:14.683+0200 INFO  [o.n.s.CommunityNeoServer] Starting HTTP on port 7474 (8 threads available)
   2018-04-05 19:11:14.859+0200 INFO  [o.n.s.w.Jetty9WebServer] Mounting static content at /webadmin
   2018-04-05 19:11:14.892+0200 INFO  [o.n.s.w.Jetty9WebServer] Mounting static content at /browser
   Apr 05, 2018 7:11:15 PM com.sun.jersey.server.impl.application.WebApplicationImpl _initiate
   INFORMATION: Initiating Jersey application, version 'Jersey: 1.19 02/11/2015 03:25 AM'
   Apr 05, 2018 7:11:15 PM com.sun.jersey.server.impl.application.WebApplicationImpl _initiate
   INFORMATION: Initiating Jersey application, version 'Jersey: 1.19 02/11/2015 03:25 AM'
   Apr 05, 2018 7:11:15 PM com.sun.jersey.server.impl.application.WebApplicationImpl _initiate
   INFORMATION: Initiating Jersey application, version 'Jersey: 1.19 02/11/2015 03:25 AM'
   2018-04-05 19:11:15.396+0200 INFO  [o.n.s.CommunityNeoServer] Remote interface ready and available at http://localhost:7474/
   [INFO] Running server for module org.apache.plc4x:plc4x-parent:0.0.1-SNAPSHOT
   [INFO] Press <Enter> to finish.

So when visiting the anounced url with a browser, you can use the pretty useful neo4j web console.

image::neo4j-web-console.png[Neo4j Web Console]

=== Using IntelliJ Idea

IntelliJ comes with some interesting Neo4J support. Unfortunately this only supports `Neo4j 3`.

Unfortunately the process of enabling this toolset is a little less comfortable than the Web-UI version.

Even if JQAssistant uses `Neo4j 2` per default, we can force it to use `Neo4j 3` by providing an additional commandline parameter.

    mvn -Djqassistant.neo4jVersion=3 clean install

JQAssistant uses Neo4j 3 and the resulting data directory is then in Neo4j 3 format.

In this case the server has to be started with the same parameter:

   mvn -Djqassistant.neo4jVersion=3 jqassistant:server

As soon as the server is started, we can connect from the IntelliJ plugin.

Note: The connection settings also contain a username and a password.

image::neo4j-intellij-settings.png[width=800]

It appears that this can simply be left empty of can contain random values.

After creating the connection, the `Graph Neo4j` view should list the new connection.

image::neo4j-intellij-database-connections-view.png[width=300]

You can now use this to perform queries

image::neo4j-intellij-query-results.png[width=800]