diff --git a/sharing-rules-between-projects/project/.jqassistant.yml b/sharing-rules-between-projects/project/.jqassistant.yml new file mode 100644 index 0000000..d5035b8 --- /dev/null +++ b/sharing-rules-between-projects/project/.jqassistant.yml @@ -0,0 +1,15 @@ +jqassistant: + plugins: + #<1> + - group-id: my.organization + artifact-id: rules + version: 1.0.0-SNAPSHOT + + analyze: + #<2> + groups: + - my-organization:Default + - project:Default + #<3> + rule-parameters: + rootPackage: my.organization \ No newline at end of file diff --git a/sharing-rules-between-projects/project/jqassistant/index.adoc b/sharing-rules-between-projects/project/jqassistant/index.adoc deleted file mode 100644 index 5c277b1..0000000 --- a/sharing-rules-between-projects/project/jqassistant/index.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Project - -[[project:Default]] -[role=group] -== Default Project Rules - -This section describes the default rules for this project. - -// project specific rules to be added below or in other documents diff --git a/sharing-rules-between-projects/project/jqassistant/index.xml b/sharing-rules-between-projects/project/jqassistant/index.xml new file mode 100644 index 0000000..9cb8afa --- /dev/null +++ b/sharing-rules-between-projects/project/jqassistant/index.xml @@ -0,0 +1,10 @@ + + + + + + + \ No newline at end of file diff --git a/sharing-rules-between-projects/project/pom.xml b/sharing-rules-between-projects/project/pom.xml index 86fedc4..d209079 100644 --- a/sharing-rules-between-projects/project/pom.xml +++ b/sharing-rules-between-projects/project/pom.xml @@ -7,26 +7,22 @@ parent 1.0.0-SNAPSHOT - - 1.8.0 - - org.apache.maven.plugins maven-compiler-plugin - 3.7.0 + 3.11.0 - 1.8 - 1.8 + 11 + 11 com.buschmais.jqassistant jqassistant-maven-plugin - ${jqassistant.version} + 2.0.6 default @@ -36,26 +32,6 @@ - - - - my-organization:Default - - project:Default - - - - my.organization - - - - - - my.organization - rules - 1.0.0-SNAPSHOT - - diff --git a/sharing-rules-between-projects/index.adoc b/sharing-rules-between-projects/readme.adoc similarity index 74% rename from sharing-rules-between-projects/index.adoc rename to sharing-rules-between-projects/readme.adoc index 4aaab33..6aa51ee 100644 --- a/sharing-rules-between-projects/index.adoc +++ b/sharing-rules-between-projects/readme.adoc @@ -7,10 +7,10 @@ Dirk Mahler [.lead] // tag::lead[] -Create a plugin containing shared rules for using them in different projects. +This tutorial is about sharing rules between different projects. Specifically a plugin containing shared rules will be created that can be used in several different projects. // end::lead[] -NOTE: This tutorial is written for version 1.8.0 of jQAssistant. +NOTE: This tutorial is written for version 2.0.6 of jQAssistant. == Overview @@ -34,6 +34,8 @@ For convenience reasons the rules are bundled into groups to ease execution and == Providing Rules As Plugin +IMPORTANT: The following part of the tutorial refers to the `rules` directory. This directory itself represents a maven project, which creates a plugin that defines jQAssistant-rules. These can later be shared to other projects. (The plugin will be implemented into another project in section <>) + === The Plugin Structure The standard approach of sharing rules is by distributing them as a jQAssistant plugin. @@ -47,7 +49,7 @@ include::rules/pom.xml[indent=0] The file mainly declares test dependencies that will be used later for verifying the rules. -jQAssistant expects a plugin descriptor `/META-INF/jqassistant-plugin.xml` as classpath resource. +jQAssistant expects a plugin descriptor `resources/META-INF/jqassistant-plugin.xml` as classpath resource. It declares files containing rules that shall be shared: [source,xml] @@ -56,7 +58,7 @@ It declares files containing rules that shall be shared: include::rules/src/main/resources/META-INF/jqassistant-plugin.xml[] ---- -The referenced files are expected as classpath resources located in the folder `/META-INF/jqassistant-rules`. +The referenced files are expected as classpath resources located in the folder `resources/META-INF/jqassistant-rules`. This tutorial uses XML documents to declare the rules. Thus the following folder structure is expected: @@ -70,9 +72,6 @@ META-INF/ └── my-organization.xml ---- -NOTE: Asciidoc files are supported as well but take longer time to load at startup. -Therefore the recommended format is XML to not negatively affect the build process of other projects. - The next sections describe the shared rules in detail. === Maven Related Rules @@ -121,7 +120,7 @@ include::rules/src/test/java/my/organization/rules/PackageTest.java[tags=Test] === Grouping Rules For Execution -The file `my-organization.xml` contains defines a group: +The file `my-organization.xml` defines a group: [source,xml] .src/main/resources/META-INF/jqassistant-rules/my-organization.xml @@ -139,17 +138,19 @@ After validation they can be moved to `my-organization:Default` (or groups inclu == Using Shared Rules In A Maven Project +IMPORTANT: The following part of the tutorial refers to the `project` directory. This directory itself represents a maven project, which uses the rules from the plugin. (More precise the plugin that was created in section <>) + This section demonstrates how the set of shared rules may be activated in a Maven based project. The latter defines its own set of specific rules. These are bundled in the group `project:Default` which is declared in the file `jqassistant/index.adoc` -[source,asciidoc] +[source,xml] .jqassistant/index.adoc .... -include::project/jqassistant/index.adoc[] +include::project/jqassistant/index.xml[] .... -The Maven build descriptor `pom.xml` contains the declaration for the jQAssistant plugin: +The Maven build descriptor `pom.xml` enables jQAssistant and configures it to execute the goals "scan" and "analyze": [source,xml] .pom.xml @@ -157,41 +158,25 @@ The Maven build descriptor `pom.xml` contains the declaration for the jQAssistan include::project/pom.xml[tags=plugin,indent=0] ---- -- The plugin containing the shared rules is declared as dependency. -- The configuration section selects the groups `my-organization:Default` and `project:Default` for execution. -- Furthermore a value for the parameter `rootPackage` required by the constraint `package:RootPackage` is defined. - -The project can now be built as usual and all required rules will be executed: - -[source,raw] +[source,yml] +..jqassistant.yml ---- -mvn install +include::project/.jqassistant.yml[indent=0] ---- -== Using Shared Rules With The Command Line Utility +<1> JQAssistant is told to use the plugin containing the shared rules. +<2> The configuration section selects the groups `my-organization:Default` and `project:Default` for execution. +<3> Furthermore, a value for the parameter `rootPackage` required by the constraint `package:RootPackage` is defined. -For using shared rules the plugin JAR file must be copied to the folder `plugins/` of the command line utility. - -Furthermore a properties file must be created providing rule parameters, i.e. `rootPackage` required by the constraint `package:RootPackage`: - -[source,properties] -.ruleParameters.properties ----- -rootPackage=my.organization ----- - -Now the analysis can be executed using the following command: +The project can now be built as usual and all required rules will be executed: [source,raw] ---- -# Unix -jqassistant.sh analyze -groups my-organization:Default,project:Default -ruleParameters ruleParameters.properties - -# Windows -jqassistant.cmd analyze -groups my-organization:Default,project:Default -ruleParameters ruleParameters.properties +mvn install ---- == Resources -1. link:tutorial.zip[ZIP archive including a Maven example for sharing rules] +1. link:https://jqassistant.github.io/jqassistant/doc/2.0.0/manual/[jQAssistant manual] + diff --git a/sharing-rules-between-projects/rules/pom.xml b/sharing-rules-between-projects/rules/pom.xml index 4e96e51..6fcff54 100644 --- a/sharing-rules-between-projects/rules/pom.xml +++ b/sharing-rules-between-projects/rules/pom.xml @@ -12,78 +12,74 @@ org.apache.maven.plugins maven-compiler-plugin - 3.7.0 + 3.11.0 - 1.8 - 1.8 + 11 + 11 + + + + + com.buschmais.jqassistant + bom + 2.0.6 + pom + import + + + + com.buschmais.jqassistant.core - store - 1.8.0 - test-jar - test - - - com.buschmais.jqassistant.core - plugin - 1.8.0 + test + 2.0.6 test com.buschmais.jqassistant.plugin common test-jar - 1.8.0 + 2.0.6 test com.buschmais.jqassistant.plugin java test-jar - 1.8.0 + 2.0.6 test com.buschmais.jqassistant.plugin java - 1.8.0 - test - - - com.buschmais.jqassistant.neo4jserver - neo4jv3 - 1.8.0 + 2.0.6 test org.junit.jupiter junit-jupiter-engine - 5.5.2 test org.assertj assertj-core - 3.14.0 test org.hamcrest java-hamcrest - 2.0.0.0 test org.slf4j slf4j-simple - 1.8.0-beta4 test diff --git a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-plugin.xml b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-plugin.xml index 58a3dd0..9f67aa3 100644 --- a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-plugin.xml +++ b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-plugin.xml @@ -1,6 +1,6 @@ - Provides shared rules for my organization. diff --git a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/maven.xml b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/maven.xml index 63e0f22..d76872d 100644 --- a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/maven.xml +++ b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/maven.xml @@ -1,7 +1,7 @@ + xsi:schemaLocation="http://schema.jqassistant.org/rule/v2.0 https://schema.jqassistant.org/rule/jqassistant-rule-v2.0.xsd"> diff --git a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/my-organization.xml b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/my-organization.xml index e8f9dc5..46a9efa 100644 --- a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/my-organization.xml +++ b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/my-organization.xml @@ -1,7 +1,7 @@ + xsi:schemaLocation="http://schema.jqassistant.org/rule/v2.0 https://schema.jqassistant.org/rule/jqassistant-rule-v2.0.xsd"> diff --git a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/package.xml b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/package.xml index 1aa7cf8..1a82b23 100644 --- a/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/package.xml +++ b/sharing-rules-between-projects/rules/src/main/resources/META-INF/jqassistant-rules/package.xml @@ -1,7 +1,7 @@ + xsi:schemaLocation="http://schema.jqassistant.org/rule/v2.0 https://schema.jqassistant.org/rule/jqassistant-rule-v2.0.xsd"> @@ -14,7 +14,7 @@ MATCH (package:Package)-[:CONTAINS]->(type:Type) WHERE NOT - package.fqn starts with {rootPackage} + package.fqn starts with $rootPackage RETURN type as TypeOutsideRootPackage ]]> diff --git a/sharing-rules-between-projects/rules/src/test/java/my/organization/rules/PackageTest.java b/sharing-rules-between-projects/rules/src/test/java/my/organization/rules/PackageTest.java index d011604..585dfb1 100644 --- a/sharing-rules-between-projects/rules/src/test/java/my/organization/rules/PackageTest.java +++ b/sharing-rules-between-projects/rules/src/test/java/my/organization/rules/PackageTest.java @@ -1,6 +1,7 @@ package my.organization.rules; import com.buschmais.jqassistant.core.report.api.model.Result; +import com.buschmais.jqassistant.core.report.api.model.Row; import com.buschmais.jqassistant.core.rule.api.model.Constraint; import com.buschmais.jqassistant.core.rule.api.model.RuleException; import com.buschmais.jqassistant.plugin.java.api.model.TypeDescriptor; @@ -10,7 +11,6 @@ import java.util.HashMap; import java.util.List; -import java.util.Map; import static com.buschmais.jqassistant.core.report.api.model.Result.Status.FAILURE; import static com.buschmais.jqassistant.core.report.api.model.Result.Status.SUCCESS; @@ -47,10 +47,10 @@ public void invalidRootPackage() throws RuleException { store.beginTransaction(); assertThat(result.getStatus()).isEqualTo(FAILURE); - List> rows = result.getRows(); + List rows = result.getRows(); assertThat(rows.size()).isEqualTo(1); - Map row = rows.get(0); - TypeDescriptor typeOutsideRootPackage = (TypeDescriptor) row.get("TypeOutsideRootPackage"); + Row row = rows.get(0); + TypeDescriptor typeOutsideRootPackage = (TypeDescriptor) row.getColumns().get("TypeOutsideRootPackage").getValue(); MatcherAssert.assertThat(typeOutsideRootPackage, typeDescriptor(PackageTest.class)); store.commitTransaction(); }