Skip to content

Commit bb9605a

Browse files
jeffjensenjeffjensen
committed
docs(site): Add initial Maven site docs
1 parent 07c0d19 commit bb9605a

6 files changed

Lines changed: 597 additions & 0 deletions

File tree

‎src/site/asciidoc/developing.adoc‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
= Developing
2+
:toc: left
3+
:toc-title: Contents
4+
:toclevels: 2
5+
6+
== Prerequisites
7+
8+
* Java 21 or later (required because the integration tests build the generated projects, which set `maven.compiler.release=21`)
9+
* Maven 3.9 or later (or use the included wrapper: `./mvnw` / `mvnw.cmd`, which provides 3.9.9)
10+
11+
== Build and Install
12+
13+
The project includes a Maven wrapper — no local Maven installation required.
14+
15+
[source,bash]
16+
----
17+
./mvnw install
18+
----
19+
20+
This installs the archetype into your local Maven repository so it can be used immediately.
21+
22+
On Windows use `mvnw.cmd install`.
23+
24+
== Running the Full Build
25+
26+
Run the full build including all integration tests:
27+
28+
[source,bash]
29+
----
30+
./mvnw verify
31+
----
32+
33+
On Windows use `mvnw.cmd verify`.
34+
35+
== Integration Tests
36+
37+
Each integration test generates a complete project from the archetype using a fixed set of inputs,
38+
then runs Groovy assertions against the result.
39+
All test cases live under `src/test/resources/projects/`.
40+
41+
=== Test structure
42+
43+
Each test is a directory containing three files:
44+
45+
`archetype.properties`::
46+
Property values passed to the archetype at generation time — the Maven coordinates plus the
47+
four archetype-specific properties (`integrations`, `singleService`, `serviceAreas`, `presentationTypes`).
48+
49+
`goal.txt`::
50+
The Maven goal to run against the generated project after generation.
51+
All tests use `-f parent/pom.xml verify`.
52+
53+
`verify.groovy`::
54+
Groovy assertions that run after generation.
55+
The script receives `basedir` pointing at the generated project root and asserts on
56+
file existence, POM content, source structure, and dependency wiring.
57+
58+
=== Test output
59+
60+
Generated projects are written to:
61+
62+
[source]
63+
----
64+
target/test-classes/projects/{test-name}/project/{artifactId}/
65+
----
66+
67+
These files persist until the next `mvn clean` and can be inspected directly to see exactly
68+
what the archetype produces for a given set of inputs.
69+
70+
Each test also writes a `build.log` in the generated project root.
71+
The `verify.groovy` script prepends the test name and the `archetype.properties` content
72+
to the log before appending any output, so a single file captures both the inputs and the
73+
build result for that test run.
74+
75+
=== Running a single integration test
76+
77+
To run one test case in isolation (faster feedback during development):
78+
79+
[source,bash]
80+
----
81+
./mvnw verify -Dinvoker.test=basic
82+
----
83+
84+
Replace `basic` with the name of the directory under `src/test/resources/projects/`.
85+
On Windows use `mvnw.cmd verify -Dinvoker.test=basic`.
86+
87+
=== Adding a new integration test
88+
89+
. Create a directory under `src/test/resources/projects/{test-name}/`.
90+
. Add `archetype.properties` with the inputs to test.
91+
. Add `goal.txt` containing `-f parent/pom.xml verify`.
92+
. Add `verify.groovy` with assertions against the generated output.
93+
. Run `./mvnw verify` — the new test is picked up automatically.
94+
95+
== Project Structure
96+
97+
[source]
98+
----
99+
src/
100+
├── main/resources/
101+
│ ├── META-INF/
102+
│ │ ├── archetype-post-generate.groovy (all module generation logic)
103+
│ │ └── maven/
104+
│ │ └── archetype-metadata.xml (property declarations and defaults)
105+
│ └── archetype-resources/
106+
│ └── pom.xml (placeholder; deleted by post-generate script)
107+
├── site/
108+
│ ├── site.xml (navigation)
109+
│ └── asciidoc/ (site pages)
110+
└── test/resources/projects/
111+
└── {test-name}/
112+
├── archetype.properties
113+
├── goal.txt
114+
└── verify.groovy
115+
----
116+
117+
All module generation logic lives in `archetype-post-generate.groovy`.
118+
It reads the archetype properties, computes the full module list, and writes every
119+
`pom.xml`, source directory, and `package-info.java` from scratch.
120+
The placeholder `archetype-resources/pom.xml` satisfies the Maven Archetype Plugin's
121+
packaging requirements and is deleted immediately by the script.

‎src/site/asciidoc/index.adoc‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
= Java Service Archetype
2+
:toc: left
3+
:toc-title: Contents
4+
:toclevels: 2
5+
6+
Maven archetype that generates a structured multi-module Java service project.
7+
Describe your integrations, service areas, and presentation architectural tiers at generation time;
8+
the archetype builds the full module tree and wires up all POMs.
9+
10+
== Quick Start
11+
12+
[source,bash]
13+
----
14+
mvn archetype:generate \
15+
-DarchetypeGroupId=io.github.jeffjensen \
16+
-DarchetypeArtifactId=java-service-archetype \
17+
-DarchetypeVersion=1.0.0-SNAPSHOT
18+
----
19+
20+
Maven prompts for standard coordinates (`groupId`, `artifactId`, `version`, `package`)
21+
followed by four archetype-specific properties.
22+
See link:usage.html[Usage] for the full prompts reference.
23+
24+
== Example Output
25+
26+
Given `integrations=database:users,rest:orders`, `singleService=y`, `presentationTypes=rest`,
27+
the archetype produces:
28+
29+
[source]
30+
----
31+
my-service/
32+
├── parent/ (aggregator POM — build entry point)
33+
│ └── pom.xml
34+
├── acceptance-tests/
35+
├── app/
36+
├── common-domain/
37+
├── common-testing/
38+
├── domain-db-users/ (integration domain — database:users)
39+
├── domain-rest/ (presentation domain — presentationTypes=rest)
40+
├── domain-rest-orders/ (integration domain — rest:orders)
41+
├── integration-db-users/
42+
├── integration-rest-orders/
43+
├── presentation-rest/
44+
└── service/
45+
----
46+
47+
`parent/` is a sibling directory — there is no `pom.xml` at the project root.
48+
Each module contains a full `src/` scaffold and a `package-info.java` in every leaf package.
49+
50+
See link:modules.html[Modules] for a description of each module, its dependencies, and how to build.

‎src/site/asciidoc/modules.adoc‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
= Generated Modules
2+
:toc: left
3+
:toc-title: Contents
4+
:toclevels: 2
5+
6+
Every module contains a full `src/` scaffold
7+
(`src/main/java`, `src/main/resources`, `src/test/java`, `src/test/resources`)
8+
and a `package-info.java` in every applicable leaf package directory.
9+
10+
== Fixed Modules
11+
12+
These modules are always generated regardless of input.
13+
14+
`common-domain`::
15+
Domain classes shared across all other modules. No dependencies on other generated modules.
16+
+
17+
_Package_: `{base.package}.common.domain`
18+
19+
`common-testing`::
20+
Shared test utilities. Has no test-scope Java packages.
21+
+
22+
_Package_: `{base.package}.common.testing` +
23+
_Depends on_: `common-domain`
24+
25+
`service` _or_ `service-{name}`::
26+
Business logic for a service area (see `singleService` and `serviceAreas` prompts).
27+
+
28+
_Package_: `{base.package}.service` or `{base.package}.service.{name}` +
29+
_Depends on_: `common-domain`
30+
31+
`app`::
32+
Application assembly — produces the runnable artifact (e.g. Spring Boot über-jar).
33+
+
34+
_Package_: `{base.package}.app` +
35+
_Depends on_: all non-test modules (`common-domain`, all domain and integration modules,
36+
all service modules, all presentation modules)
37+
38+
`acceptance-tests`::
39+
Functional acceptance tests that exercise the application from the outside.
40+
Has no main-scope Java packages.
41+
+
42+
_Package_: `{base.package}.at` +
43+
_Depends on_: `app`, `common-domain`, all `domain-{type}-{name}` integration domain modules,
44+
all `domain-{type}` presentation domain modules +
45+
_Plugin_: `maven-failsafe-plugin` (`integration-test` + `verify` goals)
46+
47+
== Integration Modules
48+
49+
Generated per `type:name` pair in the `integrations` prompt.
50+
The `database` type is abbreviated to `db` in all names.
51+
52+
`domain-{type}-{name}`::
53+
Domain classes for a specific integration (e.g. `domain-db-users`, `domain-rest-orders`).
54+
+
55+
_Package_: `{base.package}.domain.{type}.{name}` +
56+
_Depends on_: `common-domain`
57+
58+
`integration-{type}-{name}`::
59+
Integration implementation classes — DAOs, Spring Data JPA repositories, REST clients, etc.
60+
(e.g. `integration-db-users`, `integration-rest-orders`).
61+
+
62+
_Package_: `{base.package}.integration.{type}.{name}` +
63+
_Depends on_: `common-domain`, `domain-{type}-{name}` +
64+
_Plugin_: `maven-failsafe-plugin` (`integration-test` + `verify` goals)
65+
66+
== Presentation Modules
67+
68+
Generated per type in the `presentationTypes` prompt.
69+
70+
`domain-{type}`::
71+
Domain classes for a presentation tier (e.g. `domain-rest`, `domain-graphql`).
72+
+
73+
_Package_: `{base.package}.domain.{type}` +
74+
_Depends on_: `common-domain`
75+
76+
`presentation-{type}`::
77+
Request-handling classes — controllers, resolvers, etc.
78+
(e.g. `presentation-rest`, `presentation-graphql`).
79+
+
80+
_Package_: `{base.package}.presentation.{type}` +
81+
_Depends on_: `common-domain`, `domain-{type}`
82+
83+
== Parent POM
84+
85+
`parent/pom.xml` is the aggregator and BOM for all sibling modules.
86+
There is no `pom.xml` at the project root — `parent/` is a sibling of all other modules.
87+
88+
It contains:
89+
90+
* `<packaging>pom</packaging>`
91+
* `<modules>` — all sibling modules referenced as `../module` relative paths, sorted alphabetically
92+
* `<dependencyManagement>` — all modules pinned to `${project.version}`, sorted alphabetically by `artifactId`
93+
* Common properties: Java 21 via `maven.compiler.release`; UTF-8 source encoding
94+
* `<pluginManagement>` — pinned versions for `maven-compiler-plugin`, `maven-failsafe-plugin`,
95+
`maven-jar-plugin` (with `skipIfEmpty=true`), and `maven-surefire-plugin`
96+
97+
To build a generated project:
98+
99+
[source,bash]
100+
----
101+
cd my-service/parent
102+
mvn verify
103+
----
104+
105+
Use `mvn install` instead if other local projects need to consume the generated modules from your local Maven repository.
106+
107+
== Package Reference
108+
109+
All type and name segments in package names are lowercased.
110+
111+
[cols="1,1"]
112+
|===
113+
|Module |Package
114+
115+
|`common-domain` |`{base.package}.common.domain`
116+
|`common-testing` |`{base.package}.common.testing`
117+
|`domain-{type}-{name}` |`{base.package}.domain.{type}.{name}`
118+
|`integration-{type}-{name}` |`{base.package}.integration.{type}.{name}`
119+
|`service` |`{base.package}.service`
120+
|`service-{name}` |`{base.package}.service.{name}`
121+
|`domain-{type}` |`{base.package}.domain.{type}`
122+
|`presentation-{type}` |`{base.package}.presentation.{type}`
123+
|`app` |`{base.package}.app`
124+
|`acceptance-tests` |`{base.package}.at`
125+
|===

0 commit comments

Comments
 (0)