Apache Maven Compiler Plugin

The Maven Compiler Plugin is used to compile project source files. By default, it uses the JDK javac compiler. The plugin provides two primary goals that are automatically bound to the Maven Lifecycle:

• compiler:compile: Bound to the compile phase; used to compile main source files.
• compiler:testCompile: Bound to the test-compile phase; used to compile test source files.

When working with the Java Platform Module System (JPMS), certain arguments used during compilation (especially for tests) must also be provided at runtime to ensure the application behaves correctly. If your tests compile but fail at runtime due to module visibility or access issues, check the target/javac-test.args file for the following arguments:

• --upgrade-module-path
• --add-exports
• --add-reads
• --add-modules
• --limit-modules
• --patch-module

Note: These arguments should generally appear in javac-test.args (for tests) rather than javac.args (for main code). If they are required for main code, it may indicate that your module-info.java file is incomplete.

The module-info-patch.maven file uses a syntax similar to Java, C/C++, or JavaScript.

Rules:

• Comments: Use /* ... */ or //.
• Declaration: The first non-comment token must be patch-module followed by the name of the module being patched.
• Keywords: Use Java compiler/launcher options without the leading -- (e.g., use add-reads instead of --add-reads).
• Termination: Every option statement must end with a mandatory semicolon (;).
• Scope: Most options apply only to the module declared in the patch-module header. However, add-modules and limit-modules apply to all modules in a multi-module project.

A Multi-Release JAR allows you to include Java version-dependent classes within a single JAR file. The Java runtime automatically selects the best matching version of a class based on the current runtime.

To enable this behavior, the JAR must contain a MANIFEST.MF file with the attribute Multi-Release: true. Without this flag, the runtime will only use the base classes located in the root of the JAR and ignore version-specific classes located in META-INF/versions/.

.
├─ A.class
├─ B.class
├─ C.class
├─ D.class
└─ META-INF
   ├─ MANIFEST.MF { Multi-Release: true }
   └─ versions
      ├─ 9
      │  ├─ A.class
      │  └─ B.class
      └─ 10
         ├─ A.class
         └─ C.class

Black Box Testing

Tests executed without access to the internal code (package-private classes/methods or non-exported packages). Using the module source hierarchy, you can create a dedicated test module (e.g., org.foo.bar.test) that interacts with your main module (org.foo.bar) as an external client would.

White Box Testing

Tests that have access to internal classes. In Maven, any <source> element with the test scope automatically performs white box testing for the module declared in its <module> element. Access to package-private members is granted if the test code resides in the same package as the code under test. Access to non-exported modules is implicit for the module the tests belong to.

The Maven compiler plugin translates the .maven syntax into standard Java tool arguments. You can inspect the resulting arguments in target/javac.args, target/javac-test.args (if a build fails or --verbose is used), or target/test-classes/META-INF/maven/module-info-patch.args for test execution.

Translation Logic:

• add-modules mod1, mod2; $\rightarrow$ --add-modules mod1,mod2 (spaces are removed).
• limit-modules mod1, mod2; $\rightarrow$ --limit-modules mod1,mod2 (spaces are removed).
• add-reads mod1, mod2; $\rightarrow$ --add-reads [patched-module]=mod1,mod2.
• add-exports pkg to mod1, mod2; $\rightarrow$ --add-exports [patched-module]/pkg=mod1,mod2.
• add-opens pkg to mod1, mod2; $\rightarrow$ --add-opens [patched-module]/pkg=mod1,mod2 (applied to runtime execution).

There is a functional difference between how filters are applied in Maven 3 and Maven 4:

1. Maven 3 (Plugin-specific): Filters defined in the maven-compiler-plugin configuration apply to all source directories but are only respected by the compiler plugin.
2. Maven 4 (Directory-specific): Filters defined within a <source> element apply only to that specific directory. These filters are intended to be used by all plugins that have migrated to the Maven 4 API (e.g., not just the compiler plugin).

Use the Maven 4 <sources> approach to ensure filters are applied precisely to the intended directories and are available to the broader Maven ecosystem.

When performing white box testing, you often need compiler options like --patch-module, --add-modules, --add-reads, --add-exports, and --add-opens. Instead of manually managing these in <compilerArgs> in your pom.xml or duplicating your module-info.java in the test directory, you can use a module-info-patch.maven file.

This file allows you to declare only the changes needed for testing. The Maven compiler plugin then translates these declarations into the appropriate Java compiler or launcher options. This approach is less redundant, more readable, and prevents your test module information from getting out of sync with your main code.

/* 
 * Create a file named module-info-patch.maven in your module directory 
 */
patch-module your.module.name {
    add-reads some.dependency;
    add-exports your.package to some.test.module;
}

The module source hierarchy introduces an additional directory level named after the Java module. This allows a single Maven sub-project to contain multiple Java modules, facilitating easier sharing of test code and resolving compiler warnings.

For a module named org.foo.bar, the directory structure should include the module name as a parent to main and test directories. The compiled output in target/classes will also include this module name directory level (generated by javac).

To implement this, define the <sources> in your pom.xml using the <module> tag.

<build>
  <sources>
    <source>
      <module>org.foo.bar</module>
    </source>
    <source>
      <scope>test</scope>
      <module>org.foo.bar</module>
    </source>
  </sources>
</build>