#314 Add Maven plugin to most of the documentation

README.adoc

@@ -4,6 +4,7 @@ include::asciidoctor-config.ad[]
 
 ifndef::xrefToCli[:xrefToCli: htmlSanityCheck-cli/README.adoc]
 ifndef::xrefToGradlePlugin[:xrefToGradlePlugin: htmlSanityCheck-gradle-plugin/README.adoc]
+ifndef::xrefToMavenPlugin[:xrefToMavenPlugin: htmlSanityCheck-maven-plugin/README.adoc]
 
 [.lead]
 ====
@@ -31,23 +32,17 @@ HSC can be currently used
 
 * As a xref:{xrefToGradlePlugin}#sec:usage[Gradle plugin], or
 * As a xref:{xrefToCli}#sec:usage[Command Line Interface tool] (CLI), or
+* As a xref:{xrefToMavenPlugin}#sec:usage[Maven Plugin], or
 * Programmatically from Java or other JVM languages (TBD).
 
-[NOTE]
-.Future releases
-====
-In the future, we plan to provide
-
-* A standalone Java (CLI) executable, and
-* An https://maven.apache.org[Apache Maven] Plugin.
-====
-
 [[sec:installation]]
 == Installation
 
 Depending on your <<sec:usage>> you have to
 
 * Install the xref:{xrefToGradlePlugin}#sec:installation[Gradle Plugin], or
+* Install the xref:{xrefToCli}#sec:installation[Command Line Interface tool] (CLI), or
+* Install the xref:{xrefToMavenPlugin}#sec:installation[Maven Plugin], or
 * Install the core library for programmatic use (TBD).
 
 [[sec:examples]]

htmlSanityCheck-maven-plugin/README.adoc

@@ -24,30 +24,43 @@ Use the following snippet inside a Maven build file:
 .build.maven
 [source,xml,subs="attributes+"]
 ----
-   <plugin>
-                <groupId>org.aim42.htmlSanityCheck</groupId>
-                <artifactId>htmlSanityCheck-maven-plugin</artifactId>
-                <version>2.0.0-rc1</version> // <1>
-                <executions>
-                    <execution>
-                        <phase>compile</phase>
-                        <goals>
-                            <goal>sanity-check</goal>
-                        </goals>
-                    </execution>
-                </executions>
-                <configuration>
-                    <sourceDocuments>
-                        <file>src/file-to-test.html</file> <2>
-                    </sourceDocuments>
-                    <sourceDir>src</sourceDir> <3>
-                </configuration>
-            </plugin>
+<plugin>
+    <groupId>org.aim42.htmlSanityCheck</groupId>
+    <artifactId>htmlSanityCheck-maven-plugin</artifactId>
+    <version>{hsc-version}</version> // <1>
+    <executions>
+        <execution>
+            <phase>compile</phase>
+            <goals>
+                <goal>sanity-check</goal>
+            </goals>
+        </execution>
+    </executions>
+    <configuration>
+        <sourceDocuments>
+            <file>src/file-to-test.html</file> <2>
+        </sourceDocuments>
+        <sourceDir>src</sourceDir> <3>
+    </configuration>
+</plugin>
 ----
 <1> Checkout <<box:current-version,current version>>
 <2> List the files you want tio check here.
 <3> Directory where the HTML files are located.
 
+[[box:current-version]]
+[IMPORTANT]
+.Latest (development) versions
+====
+* The latest https://github.com/aim42/htmlSanityCheck/releases[release version] is defined in https://github.com/aim42/htmlSanityCheck/blob/main/gradle.properties[`gradle.properties` on `main` branch].
+* The current (development) version is defined in {gradleProperties}
++
+[source]
+.Development version
+----
+include::../gradle.properties[tag=version]
+----
+====
 
 [[sec:usage]]
 == Usage
@@ -120,7 +133,7 @@ Type: List.
 +
 Default:
 +
-[source,groovy]
+[source,java]
 ----
 include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_WARNING_CODES,indent=0]
 // Redirects included
@@ -154,7 +167,7 @@ Type: List.
 +
 Default:
 +
-[source,groovy]
+[source,java]
 ----
 include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_SUCCESS_CODES,indent=0]
 ----
@@ -172,15 +185,15 @@ The mentioned configurations effectively move the configured codes around, i.e.,
 
 === Small Example
 `build.maven`
-[source,groovy]
+[source,xml]
 ----
 tbd
 ----
 
 === Extended example
 
 .`build.maven`
-[source,groovy,subs='attributes']
+[source,xml,subs='attributes']
 ----
 
 tbd

htmlSanityCheck-maven-plugin/src/main/java/org/aim42/htmlsanitycheck/maven/HtmlSanityCheckMojo.java

@@ -21,49 +21,169 @@
 
 /*
  No Javadoc for class due to https://stackoverflow.com/questions/28428833/maven-error-when-doing-packaging
+
+ This Mojo-Class is the core of the maven plugin.
+ It uses the maven capabilities to take the configuration parameters from the mavens pom.xml and calls the hsc core
+ with the parameters.
+
+ It does not include any checking functionality itself.
  */
 
 
 @Mojo(name = "sanity-check", defaultPhase = LifecyclePhase.VERIFY, requiresDependencyResolution = ResolutionScope.RUNTIME)
 public class HtmlSanityCheckMojo extends AbstractMojo {
 
-
+    /**
+     * (optional) Directory where the checking results written to.
+     * <p>
+     * Type: Directory.
+     * <p>
+     * Default: {buildDir}/reports/htmlSanityCheck/
+     */
     @Parameter(defaultValue = "${project.build.directory}/reports/htmlSanityCheck/", required = true)
     private File checkingResultsDir;
 
+
+    /**
+     * (optional) Directory where the results are written to in JUnit XML format. JUnit XML can be read by many tools, including CI environments.
+     * <p>
+     * Type: Directory.
+     * <p>
+     * Default: {buildDir}/test-results/htmlchecks/
+     */
     @Parameter(defaultValue = "${project.build.directory}/test-results/htmlSanityCheck/", required = true)
     private File junitResultsDir;
 
+    /**
+     * (mandatory)
+     * Directory where the HTML files are located.
+     */
     @Parameter
     private File sourceDir;
 
+    /**
+     * (optional) An override to process several source files, which may be a subset of all files available in {sourceDir}.
+     * <p>
+     * Type: org.maven.api.file.FileCollection.
+     * <p>
+     * Default: All files in {sourceDir} whose names end with .html.
+     */
     @Parameter
     private Set<File> sourceDocuments;
 
+    /**
+     * (optional)
+     * Fail the build if any error was found in the checked pages.
+     * <p>
+     * Type: Boolean.
+     * <p>
+     * Default: false.
+     */
     @Parameter(defaultValue = "false")
     private boolean failOnErrors;
 
+    /**
+     * (optional) Timeout for http requests in ms.
+     * <p>
+     * Type: Integer.
+     * <p>
+     * Default: 5000.
+     */
     @Parameter(defaultValue = "5000")
     private int httpConnectionTimeout;
 
+    /**
+     * (optional) Ignore localhost as hostname.
+     * <p>
+     * Type: Boolean.
+     * <p>
+     * Default: false.
+     */
     @Parameter(defaultValue = "false")
     private boolean ignoreLocalHost;
 
+    /**
+     * (optional) Ignore IP addresses as hostname.
+     * <p>
+     * Type: Boolean.
+     * <p>
+     * Default: false.
+     */
     @Parameter(defaultValue = "false")
     private boolean ignoreIPAddresses;
 
+    /**
+     * (optional) Additional HTTP response codes treated as warning.
+     * <p>
+     * Type: List.
+     * <p>
+     * Default:
+     * <p>
+     * 100, 101, 102
+     * // Redirects included
+     * 301, 302, 303, 307, 308
+     * HTTP Redirects
+     * Note that HTTP redirects are treated as a warning to make the user aware of the correct or new location (cf. Issue 244). Some HSC reports often contain the respective location.
+     */
     @Parameter
     private Set<Integer> httpWarningCodes;
 
+    /**
+     * (optional) Additional HTTP response codes treated as error.
+     * <p>
+     * Type: List.
+     * <p>
+     * Default:
+     * <p>
+     * 400, 401, 402, 403, 404,
+     * 405, 406, 407, 408, 409,
+     * 410, 411, 412, 413, 414,
+     * 415, 416, 417, 418, 421,
+     * 422, 423, 424, 425, 426,
+     * 428, 429, 431, 451,
+     * 500, 501, 502, 503, 504,
+     * 505, 506, 507, 508, 510,
+     * 511
+     */
     @Parameter
     private Set<Integer> httpErrorCodes;
 
+    /**
+     * (optional) Additional HTTP response codes treated as success.
+     * <p>
+     * Type: List.
+     * <p>
+     * Default:
+     * <p>
+     * 200, 201, 202, 203, 204,
+     * 205, 206, 207, 208, 226
+     */
     @Parameter
     private Set<Integer> httpSuccessCodes;
 
+    /**
+     * (optional) The set of checker classes to be executed.
+     * <p>
+     * Type: List.
+     * <p>
+     * Default: All available checker classes.
+     * <p>
+     * Checker Classes
+     * // Keep the list ordering to ensure
+     * // report ordering comparability
+     * // with HSC 1.x versions
+     * MissingAltInImageTagsChecker.class,
+     * MissingImageFilesChecker.class,
+     * DuplicateIdChecker.class,
+     * BrokenHttpLinksChecker.class,
+     * ImageMapChecker.class,
+     * BrokenCrossReferencesChecker.class,
+     * MissingLocalResourcesChecker.class
+     */
     @Parameter
     private List<Class<? extends Checker>> checkerClasses = AllCheckers.CHECKER_CLASSES;
 
+    // tag::maven-plugin-implementation[]
     public void execute() throws MojoExecutionException {
         logBuildParameter();
 
@@ -106,6 +226,7 @@ public void execute() throws MojoExecutionException {
             throw new MojoExecutionException(e);
         }
     }
+    // end::maven-plugin-implementation[]
 
     private void logBuildParameter() {
         // Log build parameters
@@ -150,3 +271,20 @@ protected Configuration setupConfiguration() {
         return result;
     }
 }
+
+/*========================================================================
+ Copyright Gernot Starke and aim42 contributors
+
+ Licensed 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.
+ ========================================================================*/

src/docs/arc42/chapters/_config.adoc

@@ -33,14 +33,18 @@ ifndef::projectRootDir[:projectRootDir: ../../../..]
 :core-test-path:   {projectRootDir}/htmlSanityCheck-core/src/test/groovy/org/aim42
 :gradle-plugin-source-path: {projectRootDir}/htmlSanityCheck-gradle-plugin/src/main/groovy/org/aim42
 :gradle-plugin-test-path:   {projectRootDir}/htmlSanityCheck-gradle-plugin/src/test/groovy/org/aim42
+:maven-plugin-source-path: {projectRootDir}/htmlSanityCheck-maven-plugin/src/main/java/org/aim42
+:maven-plugin-test-path:   {projectRootDir}/htmlSanityCheck-maven-plugin/src/test/java/org/aim42
 
 :asciidoctor-gradle-plugin-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin
+:asciidoctor-maven-plugin-url: https://github.com/asciidoctor/asciidoctor-maven-plugin
 
 :arc42-url: https://github.com/arc42
 :aim42-url: https://github.com/aim42
 
 :asciidoc-url: https://asciidoctor.org
 :gradle-url: https://gradle.org/
+:maven-url: https://maven.apache.org
 :groovy-url: https://www.groovy-lang.org/
 :template-method-pattern-url: https://sourcemaking.com/design_patterns/template_method
 
@@ -60,6 +64,7 @@ ifndef::projectRootDir[:projectRootDir: ../../../..]
 :xrefConceptHtmlEncapsulation: <<sec:html-encapsulation,HTML encapsulation concept>>
 :xrefConceptReporting: <<sec:reporting-concept,reporting concept>>
 :xrefConceptGradlePlugin: <<sec:gradle-plugin-concept,Gradle plugin concept>>
+:xrefConceptMavenPlugin: <<sec:maven-plugin-concept,Maven plugin concept>>
 :xrefDeplomentView: <<sec:deployment-view,deployment view>>
 :xrefRequirementsGradleIntegration: <<sec:requirements,required Gradle integration>>
 :xrefRequirementsRequiredChecks: <<sec:requiredChecks,Required Checks>>
@@ -79,6 +84,7 @@ ifdef::jbake-type[]
 :xrefConceptHtmlEncapsulation: xref:chap-08-Concepts.adoc#sec:html-encapsulation[HTML encapsulation concept]
 :xrefConceptReporting: xref:chap-08-Concepts.adoc#sec:reporting-concept[reporting concept]
 :xrefConceptGradlePlugin: xref:chap-08-Concepts.adoc#sec:gradle-plugin-concept[Gradle plugin concept]
+:xrefConceptMavenPlugin: xref:chap-08-Concepts.adoc#sec:maven-plugin-concept[Maven plugin concept]
 :xrefDeplomentView: xref:chap-07-Deployment.adoc#sec:deployment-view[deployment view]
 :xrefRequirementsGradleIntegration: xref:chap-01-Requirements.adoc#sec:requirements[required Gradle integration]
 :xrefRequirementsRequiredChecks: xref:chap-01-Requirements.adoc#sec:requiredChecks[Required Checks]

src/docs/arc42/chapters/chap-01-Requirements.adoc

@@ -33,7 +33,9 @@ Reports its results either on the console or as HTML report.
 HSC can run
 
 * From the command line (CLI), or
-* As {gradle-url}[Gradle]-plugin.
+* As {gradle-url}[Gradle]-plugin, or
+* As {maven-url}[Maven]-plugin.
+
 
 
 .Terminology: What Can Go Wrong in HTML Files?

src/docs/arc42/chapters/chap-04-SolutionStrategy.adoc

@@ -7,10 +7,11 @@ include::_config.adoc[]
 
 :filename: arc42/chapters/chap-04-SolutionStrategy.adoc
 
-* Implement HSC in Java with minimal
-external dependencies. Wrap this implementation into a {gradle-url}[Gradle]
-plugin, so it can be used within automated builds. Details are given
-in the {xrefConceptGradlePlugin}.
+* Implement HSC in Java with minimal external dependencies.
+** Implement a core libary for the functionality with minimal external dependencies and tool independent.
+** Wrap this implementation into a {gradle-url}[Gradle] and a {maven-url}[Maven] plugin, so it can be used within automated builds.
+Details are given in the {xrefConceptGradlePlugin} and {xrefConceptMavenPlugin}.
+** Create a command line interface.
 
 * Apply the _template-method-pattern_ (see e.g. {template-method-pattern-url}) to enable:
 ** multiple checking algorithms. See the {xrefConceptCheckingAlgorithms},