Fix JPMS split-package error by bundling shims into the main JAR

.gitignore

@@ -6,3 +6,5 @@ target
 .settings
 .idea
 out
+PLAN.md
+dependency-reduced-pom.xml

change_log.md

@@ -1,6 +1,11 @@
 # OWASP Java HTML Sanitizer Change Log
 
 Most recent at top.
+  * Next release
+    * Fix: `java8-shim` and `java10-shim` are now bundled inside the main JAR,
+      resolving the JPMS split-package error on the module path. Consumers no
+      longer need to declare the shim artifacts as direct dependencies. Both
+      shim JARs remain published on Maven Central for backwards compatibility.
   * Release 20240325.1
     * Remove dependency on Guava
     * Raise minimum supported JVM release to 8

docs/maven.md

@@ -9,12 +9,16 @@ Including among your POMs `<dependencies>` this snippet of XML...
 <dependency>
     <groupId>com.googlecode.owasp-java-html-sanitizer</groupId>
     <artifactId>owasp-java-html-sanitizer</artifactId>
-    <version>20180219.1</version>
+    <version>20240325.1</version>
 </dependency>
 ```
 
 ...will make the sanitizer available.
 
+The sanitizer JAR is self-contained: the `java8-shim` and `java10-shim` artifacts
+are bundled inside it and do **not** need to be declared as separate dependencies,
+including when using the JPMS module path.
+
 Be sure to change the
 [version](https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution#DependencyMediationandConflictResolution-DependencyVersionRanges)
 to a range suitable to your project.  There are no unstable releases

owasp-java-html-sanitizer/pom.xml

@@ -67,6 +67,10 @@
         <configuration>
           <instructions>
             <Export-Package>org.owasp.html</Export-Package>
+            <!-- Explicit JPMS automatic module name so consumers using the
+                 module path can require this module by a stable name that
+                 is independent of the JAR filename. -->
+            <Automatic-Module-Name>owasp.java.html.sanitizer</Automatic-Module-Name>
           </instructions>
         </configuration>
       </plugin>
@@ -86,17 +90,57 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-shade-plugin</artifactId>
+        <executions>
+          <execution>
+            <phase>package</phase>
+            <goals><goal>shade</goal></goals>
+            <configuration>
+              <!-- Inline java8-shim and java10-shim into this JAR so that
+                   consumers using the JPMS module path do not encounter a
+                   split-package error from org.owasp.shim appearing in
+                   multiple JARs. See https://github.com/OWASP/java-html-sanitizer/issues/341 -->
+              <artifactSet>
+                <includes>
+                  <include>com.googlecode.owasp-java-html-sanitizer:java8-shim</include>
+                  <include>com.googlecode.owasp-java-html-sanitizer:java10-shim</include>
+                </includes>
+              </artifactSet>
+              <filters>
+                <filter>
+                  <artifact>*:*</artifact>
+                  <excludes>
+                    <!-- Exclude shim Maven metadata to avoid duplicate
+                         pom.properties / pom.xml entries in the JAR -->
+                    <exclude>META-INF/maven/com.googlecode.owasp-java-html-sanitizer/java*/**</exclude>
+                  </excludes>
+                </filter>
+              </filters>
+              <!-- Replace the original JAR with the shaded one as the
+                   main artifact; do not attach a separate shaded artifact -->
+              <shadedArtifactAttached>false</shadedArtifactAttached>
+              <!-- Generate a reduced POM that omits the now-inlined shim
+                   dependencies, keeping the published POM accurate -->
+              <createDependencyReducedPom>true</createDependencyReducedPom>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>
 
   <dependencies>
     <dependency>
       <groupId>com.googlecode.owasp-java-html-sanitizer</groupId>
       <artifactId>java8-shim</artifactId>
+      <optional>true</optional>
     </dependency>
     <dependency>
       <groupId>com.googlecode.owasp-java-html-sanitizer</groupId>
       <artifactId>java10-shim</artifactId>
+      <optional>true</optional>
     </dependency>
     <dependency>
       <groupId>commons-codec</groupId>

pom.xml

@@ -196,6 +196,11 @@ application while protecting against XSS.
             <artifactId>maven-verifier-plugin</artifactId>
             <version>1.1</version>
           </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-shade-plugin</artifactId>
+            <version>3.6.0</version>
+          </plugin>
       </plugins>
     </pluginManagement>
     <plugins>