You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2018/04/09 08:42:49 UTC
[incubator-plc4x] 01/04: Added some documentation on jQAssistant
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-plc4x.git
commit 3c1c5dc502dd4e2b9f7461b55f82ece798957657
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Mon Apr 9 10:40:27 2018 +0200
Added some documentation on jQAssistant
---
pom.xml | 19 ++++
src/site/asciidoc/developers/jqassistant.adoc | 126 +++++++++++++++++++++
.../neo4j-intellij-database-connections-view.png | Bin 0 -> 54579 bytes
.../resources/img/neo4j-intellij-query-results.png | Bin 0 -> 177104 bytes
src/site/resources/img/neo4j-intellij-settings.png | Bin 0 -> 75308 bytes
src/site/resources/img/neo4j-web-console.png | Bin 0 -> 1194388 bytes
src/site/site.xml | 1 +
7 files changed, 146 insertions(+)
diff --git a/pom.xml b/pom.xml
index c16bf4e..4070479 100644
--- a/pom.xml
+++ b/pom.xml
@@ -262,7 +262,14 @@
<goal>analyze</goal>
</goals>
<configuration>
+ <rulesDirectory>${project.basedir}/src/jqassistant</rulesDirectory>
<failOnSeverity>MAJOR</failOnSeverity>
+ <warnOnSeverity>MINOR</warnOnSeverity>
+ <scanIncludes>
+ <scanInclude>
+ <path>${project.basedir}/.git</path>
+ </scanInclude>
+ </scanIncludes>
</configuration>
</execution>
</executions>
@@ -863,6 +870,18 @@
<issueLinkUrl>https://issues.apache.org/jira/browse/%ISSUE%</issueLinkUrl>
</configuration>
</plugin>
+
+ <plugin>
+ <groupId>com.buschmais.jqassistant</groupId>
+ <artifactId>jqassistant-maven-plugin</artifactId>
+ <reportSets>
+ <reportSet>
+ <reports>
+ <report>report</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
</plugins>
</reporting>
diff --git a/src/site/asciidoc/developers/jqassistant.adoc b/src/site/asciidoc/developers/jqassistant.adoc
new file mode 100644
index 0000000..08d7b61
--- /dev/null
+++ b/src/site/asciidoc/developers/jqassistant.adoc
@@ -0,0 +1,126 @@
+//
+// 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: ../img/
+
+== 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]
diff --git a/src/site/resources/img/neo4j-intellij-database-connections-view.png b/src/site/resources/img/neo4j-intellij-database-connections-view.png
new file mode 100644
index 0000000..170e301
Binary files /dev/null and b/src/site/resources/img/neo4j-intellij-database-connections-view.png differ
diff --git a/src/site/resources/img/neo4j-intellij-query-results.png b/src/site/resources/img/neo4j-intellij-query-results.png
new file mode 100644
index 0000000..aa09217
Binary files /dev/null and b/src/site/resources/img/neo4j-intellij-query-results.png differ
diff --git a/src/site/resources/img/neo4j-intellij-settings.png b/src/site/resources/img/neo4j-intellij-settings.png
new file mode 100644
index 0000000..084558b
Binary files /dev/null and b/src/site/resources/img/neo4j-intellij-settings.png differ
diff --git a/src/site/resources/img/neo4j-web-console.png b/src/site/resources/img/neo4j-web-console.png
new file mode 100644
index 0000000..c4569bc
Binary files /dev/null and b/src/site/resources/img/neo4j-web-console.png differ
diff --git a/src/site/site.xml b/src/site/site.xml
index 44a71f3..0a1ae55 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -103,6 +103,7 @@
<item name="Code Analysis" href="developers/sonar.html"/>
<item name="Continuous Integration" href="developers/ci.html"/>
<item name="Contributing" href="developers/contributing.html"/>
+ <item name="JQassistant" href="developers/jqassistant.html"/>
<item name="VM Access" href="developers/vm.html"/>
<item name="Website" href="developers/website.html"/>
<item name="Wiki" href="developers/wiki.html"/>
--
To stop receiving notification emails like this one, please contact
cdutz@apache.org.