#314 Maven plugin added to most of the documentation

README.adoc

@@ -28,15 +28,14 @@ image:https://img.shields.io/github/issues/aim42/htmlSanityCheck.svg[link="https
 HSC can be currently used
 
 * As a xref:{xrefToGradlePlugin}#sec:usage[Gradle plugin], or
+* An https://maven.apache.org[Apache 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.
+* A standalone Java (CLI) executable.
 ====
 
 [[sec:installation]]

generate-pages

@@ -1,3 +1,5 @@
+
+
 #!/usr/bin/env bash
 
 : "${DTC_VERSION:=latest}"

htmlSanityCheck-maven-plugin/README.adoc

@@ -27,7 +27,7 @@ Use the following snippet inside a Maven build file:
    <plugin>
                 <groupId>org.aim42.htmlSanityCheck</groupId>
                 <artifactId>htmlSanityCheck-maven-plugin</artifactId>
-                <version>2.0.0-rc1</version> // <1>
+                <version>{hsc-version}</version> // <1>
                 <executions>
                     <execution>
                         <phase>compile</phase>
@@ -48,6 +48,19 @@ Use the following snippet inside a Maven build file:
 <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/htmlsanitycheckmavenplugin/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();
 
@@ -108,6 +228,7 @@ public void execute() throws MojoExecutionException {
             throw new MojoExecutionException(e);
         }
     }
+    // end::maven-plugin-implementation[]
 
     private void logBuildParameter() {
         // Log build parameters
@@ -142,7 +263,7 @@ protected Configuration setupConfiguration() {
         if (httpSuccessCodes != null && !httpSuccessCodes.isEmpty()) {
             result.overrideHttpSuccessCodes(httpSuccessCodes);
         }
-        if (httpErrorCodes != null &&  !httpErrorCodes.isEmpty()) {
+        if (httpErrorCodes != null && !httpErrorCodes.isEmpty()) {
             result.overrideHttpErrorCodes(httpErrorCodes);
         }
         if (httpErrorCodes != null && !httpWarningCodes.isEmpty()) {
@@ -154,3 +275,20 @@ protected Configuration setupConfiguration() {
 
 
 }
+
+/*========================================================================
+ 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},

src/docs/arc42/chapters/chap-05-BuildingBlocks.adoc

@@ -33,7 +33,8 @@ Contained Blackboxes::
 | <<sec:checker_blackbox, HSC Core>> | hsc core: html parsing and sanity checking, configuration, reporting.
 | HSC Gradle Plugin | integrates the Gradle build tool with HSC,
 enabling arbitrary gradle builds to use HSC functionality.
-| HSC Maven Plugin | (planned, not yet implemented)
+| HSC Maven Plugin | integrates the Maven build tool with HSC,
+enabling arbitrary maven builds to use HSC functionality.
 | HSC Graphical Interface | (planned, not implemented)
 
 |===

src/docs/arc42/chapters/chap-08-Concepts.adoc

@@ -9,6 +9,7 @@ include::_config.adoc[]
 
 include::chap-08-checking-domain.adoc[]
 include::chap-08-gradle-plugin.adoc[]
+include::chap-08-maven-plugin.adoc[]
 
 include::chap-08-checking-algorithms.adoc[]
 include::chap-08-html-encapsulation.adoc[]