Skip to content

Commit 6209243

Browse files
aschemanascheman
committed
Add Java Modules documentation for Maven 4
Introduce docs/maven-modules/ with foundational documentation: - index.adoc: Landing page with scope and docs-as-code approach - vision.adoc: How Java Modules change Maven's compilation model - architecture.adoc: Maven 4 architecture overview (placeholder) - glossary.adoc: Terminology definitions - consumer-pom-challenge.adoc: Edge case analysis for requires static Update README.adoc to reference the new documentation section. Update pom.xml to include docs resources for AsciiDoc processing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> Refs: support-and-care/maven-support-and-care#158
1 parent 041a34a commit 6209243

File tree

7 files changed

+490
-0
lines changed

7 files changed

+490
-0
lines changed

‎README.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,13 @@ In this documentation, both terms may be used interchangeably, but "Java Modules
3434

3535
Meanwhile, we extended many examples to work (currently) with Maven 4 to demonstrate the current state of the art in terms of Maven support for Java Modules.
3636

37+
[IMPORTANT]
38+
.Maven 4 and Java Modules
39+
====
40+
This documentation, meanwhile, also contains general background information and discussions about xref:docs/maven-modules/index.adoc[Modules support in Maven 4].
41+
These contents might move to the official Maven documentation or other repositories in the future.
42+
====
43+
3744
== Setup
3845

3946
. Clone this repository

‎docs/maven-modules/architecture.adoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
= Current Architecture
2+
:icons: font
3+
:toc: left
4+
:toclevels: 2
5+
6+
ifdef::env-github[]
7+
:tip-caption: :bulb:
8+
:note-caption: :information_source:
9+
:important-caption: :heavy_exclamation_mark:
10+
:caution-caption: :fire:
11+
:warning-caption: :warning:
12+
endif::[]
13+
14+
[.lead]
15+
We should describe internals of the Maven (4) architecture which are important in this context.
16+
In the long run, this documentation might become part of the official Maven documentation. +
17+
Other xref:index.adoc#section:topics[topics] may pick up parts of this documentation or go into more detail on specific aspects.
18+
19+
20+
TBD

‎docs/maven-modules/consumer-pom-challenge.adoc‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
= Consumer POM and `requires static`: An Edge Case
2+
:icons: font
3+
:source-highlighter: rouge
4+
:toc: left
5+
:toclevels: 3
6+
// Local path for includes (relative to this document's location: docs/maven-modules/)
7+
:includedir: ../../jigsaw-examples
8+
:example-requires-static: {includedir}/example_requires-static
9+
10+
ifdef::env-github[]
11+
:tip-caption: :bulb:
12+
:note-caption: :information_source:
13+
:important-caption: :heavy_exclamation_mark:
14+
:caution-caption: :fire:
15+
:warning-caption: :warning:
16+
endif::[]
17+
18+
== Introduction
19+
20+
This document describes an edge case where the automatic mapping of Java module `requires static` to Maven's `<optional>true</optional>` may not fully capture the runtime requirements.
21+
22+
[NOTE]
23+
====
24+
In most cases, `requires static` maps correctly to `optional`.
25+
This document explores a specific scenario where additional consideration is needed.
26+
====
27+
28+
== Background
29+
30+
=== Java Module `requires static`
31+
32+
The `static` modifier on a `requires` directive indicates:
33+
34+
* The dependency is required at *compile time*
35+
* The dependency is *not automatically resolved* at runtime
36+
* If code actually uses the dependency, it must be present at runtime
37+
38+
Typical use cases where `requires static` works well:
39+
40+
* Annotation processors (compile-time only)
41+
* Optional features with runtime guards (`Class.forName()` checks)
42+
* Container-provided dependencies (e.g., Servlet API)
43+
44+
=== Maven `optional`
45+
46+
Maven's `<optional>true</optional>` means the dependency is not pulled transitively for consumers.
47+
This maps well to `requires static` in most scenarios.
48+
49+
== An Edge Case
50+
51+
The `example_requires-static` demonstrates a scenario where additional attention is needed.
52+
53+
=== Module Structure
54+
55+
[source,text]
56+
----
57+
modmain ──requires static──▶ modb ──requires static transitive──▶ modc
58+
----
59+
60+
=== The Code
61+
62+
`modb` declares `modc` as a static transitive dependency:
63+
64+
.modb/module-info.java
65+
[source,java]
66+
----
67+
include::{example-requires-static}/src/modb/module-info.java[]
68+
----
69+
70+
Class `B` has a public method returning type `C`:
71+
72+
.modb/pkgb/B.java
73+
[source,java]
74+
----
75+
include::{example-requires-static}/src/modb/pkgb/B.java[]
76+
----
77+
78+
[NOTE]
79+
====
80+
The Java compiler emits a warning here: `class C in module modc may not be visible to all clients`.
81+
This hints that consumers calling `getMyC()` will need `modc` at runtime.
82+
====
83+
84+
=== Runtime Requirement
85+
86+
When `Main` calls `B.getMyC()`, the `modc` module must be present:
87+
88+
.modmain/pkgmain/Main.java
89+
[source,java]
90+
----
91+
include::{example-requires-static}/src/modmain/pkgmain/Main.java[]
92+
----
93+
94+
The `run.sh` script handles this by explicitly adding the modules:
95+
96+
.run.sh (excerpt)
97+
[source,bash]
98+
----
99+
include::{example-requires-static}/run.sh[lines=20..23]
100+
----
101+
102+
== Consumer POM Mapping
103+
104+
With automatic mapping of `requires static` to `optional`, the consumer POM for `modb` would be:
105+
106+
[source,xml]
107+
----
108+
<dependency>
109+
<groupId>com.example.jigsaw</groupId>
110+
<artifactId>modc</artifactId>
111+
<version>1.0-SNAPSHOT</version>
112+
<optional>true</optional> <!--1-->
113+
</dependency>
114+
----
115+
<1> Consumers won't receive `modc` transitively
116+
117+
This is technically correct per the module declaration.
118+
However, consumers calling `B.getMyC()` need to be aware that they must add `modc` to their dependencies.
119+
120+
== Responsibility
121+
122+
This edge case is primarily a *design responsibility* of the library author (`modb`):
123+
124+
* Using `requires static` for a dependency exposed in public API signatures is unusual
125+
* The compiler warning already indicates potential issues
126+
* Library documentation should clarify which methods require the optional dependency
127+
128+
[TIP]
129+
====
130+
When designing APIs with `requires static` dependencies:
131+
132+
* Avoid exposing types from optional dependencies in public method signatures
133+
* If unavoidable, document clearly which methods require the optional module
134+
* Consider runtime guards for truly optional functionality
135+
====
136+
137+
== Conclusion
138+
139+
The automatic mapping of `requires static` to `<optional>true</optional>` works correctly in the vast majority of cases.
140+
This edge case—where an optional dependency's type appears in a public API signature—requires documentation by the library author to guide consumers.
141+
142+
Maven tooling cannot automatically detect all such cases, nor should it need to.
143+
The Java compiler's warning provides a hint, and proper API documentation completes the picture.
144+
145+
== References
146+
147+
* xref:{example-requires-static}/README.adoc[Example: requires-static]
148+
* https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html[Maven Optional Dependencies]

‎docs/maven-modules/glossary.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
= Glossary of Maven and Java Module Terms
2+
:icons: font
3+
:toc: left
4+
:toclevels: 2
5+
6+
ifdef::env-github[]
7+
:tip-caption: :bulb:
8+
:note-caption: :information_source:
9+
:important-caption: :heavy_exclamation_mark:
10+
:caution-caption: :fire:
11+
:warning-caption: :warning:
12+
endif::[]
13+
14+
Understanding the terminology is critical, as Maven and Java use similar terms with different meanings.
15+
16+
Maven Module (Subproject)::
17+
The traditional Maven concept of a child project in a multi-module (reactor) build.
18+
As of Maven 4.0.0-beta-4, these are officially renamed to *subprojects* in the POM schema (`<subproject>` replaces `<module>`).
19+
20+
Java Module::
21+
A JPMS construct defined by `module-info.java`, providing strong encapsulation and explicit dependencies at the language level.
22+
First introduced in Java 9 as part of Project Jigsaw (JSR 376, JEP 261).
23+
24+
Module Source Hierarchy (-> _modular sources_)::
25+
Maven 4's new source layout pattern `src/<module>/main/java` (and `src/<module>/test/java`) that allows a single Maven project to compile multiple Java Modules together.
26+
27+
Explicit Module::
28+
A Java Module with a `module-info.java` descriptor, providing full encapsulation and declared dependencies.
29+
30+
Automatic Module::
31+
A JAR placed on the module-path without a `module-info.java`.
32+
Its module name is derived from the `Automatic-Module-Name` manifest entry or the JAR filename.
33+
34+
Unnamed Module::
35+
Code on the classpath (non-modular code).
36+
Cannot be required by explicit modules but can read all other modules.

‎docs/maven-modules/index.adoc‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
= Java Modules in Maven: Internal Documentation
2+
:icons: font
3+
:toc: left
4+
:toclevels: 2
5+
:!example-caption:
6+
7+
ifdef::env-github[]
8+
:tip-caption: :bulb:
9+
:note-caption: :information_source:
10+
:important-caption: :heavy_exclamation_mark:
11+
:caution-caption: :fire:
12+
:warning-caption: :warning:
13+
endif::[]
14+
15+
[sidebar]
16+
.TL;DR
17+
====
18+
Want to jump directly to the <<section:topics,topics>> overview?
19+
We recommend starting with the <<table:topics:introduction,introduction topics>> first.
20+
====
21+
22+
== Purpose
23+
24+
This documentation captures internal knowledge about *Java Modules support* in Maven, particularly for *Maven 4*'s new architecture.
25+
On the one hand, it tries to explain the opportunities given by Java Modules for the Maven (4) vision.
26+
On the other hand, it outlines the challenges and possible design considerations to make full use of Java Modules in Maven and its boundaries.
27+
28+
=== Documentation Scope
29+
30+
The documentation effort should cover:
31+
32+
* Maven's current Java Modules support and limitations
33+
* How the Maven 4 API enables Java Modules support
34+
* How Maven handles the module-path, classpath, and mixed scenarios
35+
* Rationale behind design decisions for Java Modules support
36+
* Known issues and gaps in Java Modules support
37+
38+
=== Out of Scope
39+
40+
This initial documentation effort focuses on internal knowledge for the Maven team.
41+
The following topics are explicitly out of scope for now but may be addressed in follow-up efforts:
42+
43+
* End-user guides for building modular projects with Maven
44+
* Plugin developer documentation for module-aware plugins
45+
* Migration guides for users upgrading to Maven 4
46+
* Tutorials and how-to articles for general audiences
47+
48+
These topics are important but require the foundational internal documentation to be in place first.
49+
50+
== Background and Related Resources
51+
52+
This documentation is part of the effort described in https://github.com/support-and-care/maven-support-and-care/discussions/155[Discussion #155: Improving Documentation for Java Modules in Maven 4].
53+
54+
The work makes use of other resources and interacts with them.
55+
As described in the mentioned discussion, we will try to migrate and consolidate this knowledge here over time.
56+
Finally, the documentation might become part of the official Maven documentation.
57+
In any case, it is clear that it must be governed by the Apache Maven Project in the long run to become an official source of knowledge.
58+
59+
* xref:glossary.adoc[Glossary of Maven and Java Module Terms] defines important terminology used throughout this documentation
60+
* https://github.com/Geomatys/maven-compiler-plugin/wiki[Geomatys Maven Compiler Plugin Wiki] is perhaps the most comprehensive resource on Java Modules with Maven
61+
* https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=393677487[Full Java Modules Support - Current State] (Apache Confluence) was meant as a starting point to address current efforts about Java Modules in Maven
62+
* https://maven.apache.org/plugins-archives/maven-compiler-plugin-LATEST-4.x/modules.html[Maven Compiler Plugin: Module Source Hierarchy]
63+
* xref:../../README.adoc[This repository] contains several examples demonstrating Java Modules with Maven 4.
64+
65+
[[section:topics]]
66+
== Topics
67+
68+
Documentation is organized by topic:
69+
70+
[cols="2,3",options="header"]
71+
|===
72+
| Document | Description
73+
[[table:topics:introduction]]
74+
2+| *Introduction to Maven and Java Modules*
75+
76+
| xref:vision.adoc[Vision: Maven 4 and Java Modules]
77+
| Shift from Maven modules to Java Modules as primary compilation units
78+
79+
| xref:architecture.adoc[Maven 4 Architecture]
80+
| Overview of Maven 4's architecture enabling Java Modules support
81+
82+
2+| *Open Issues and Challenges*
83+
84+
| xref:consumer-pom-challenge.adoc[Consumer POM Challenge] (edge case)
85+
| Semantic gap between `requires static` and Maven's `optional`
86+
2+| *Appendices*
87+
| xref:glossary.adoc[Glossary of Maven and Java Module Terms]
88+
| Definitions of key terms used in this documentation
89+
|===
90+
91+
Future topics (to be documented):
92+
93+
* Automatic modules and dependency management
94+
* Testing strategies for modular projects
95+
* Migration patterns from Maven 3 to Maven 4
96+
* Resource handling in modular sources
97+
* Multi-release JAR considerations
98+
99+
100+
101+
== Documentation Approach
102+
103+
This documentation follows a *docs-as-code* approach:
104+
105+
Version control::
106+
Documentation lives alongside code in Git.
107+
Text-based formats produce meaningful diffs, enabling standard development workflows: branches, pull requests, and peer reviews.
108+
109+
Quality assurance::
110+
Changes go through the same review process as code.
111+
CI/CD can validate documentation builds and verify that referenced examples still work.
112+
113+
Live examples::
114+
AsciiDoc's include mechanism allows referencing actual source code from the `jigsaw-examples/` directory.
115+
This ensures that documentation stays in sync with working code.
116+
In case of outstanding changes (e.g., pending Maven 4 features), examples can be marked accordingly (or stay on separate branches).
117+
118+
For details on running examples or Maven 4 migration patterns, see the xref:../../README.adoc#maven-4-migration[Maven 4 Migration section] in the main README.
119+
120+
== Contributing
121+
122+
To add new documentation:
123+
124+
. Create an AsciiDoc file in this directory
125+
. If desired, use `include::` directives to reference actual code from examples (or even create new examples)
126+
. Add an entry to the table in the Topics section

0 commit comments

Comments
 (0)