Generating sources
Plenty of Java starts life as something that is not Java: an XML schema, a . file, an Avro record, a
WSDL, an OpenAPI document, a grammar. Plugins compile all six into sources and hand them to the compiler in
the same module. Each runs in a module whose configuration folder holds its <name>., such as
avro.: the build resolves the official plugin by itself, and nothing else names it.
The generated package is compiled into the module like any hand-written one, so module-info. may export
it, and what the generated code imports - jakarta., protobuf-java, avro - stays an ordinary
declared dependency of the module.
The six generators
| File | Tool | Compiles | Binds |
|---|---|---|---|
xjc. |
JAXB binding compiler | . schemas, with . bindings |
@schemas/ |
protoc. |
protoc | . definitions |
@definitions/ |
avro. |
avro-tools | . schemas and . protocols |
@schemas/ |
wsimport. |
JAX-WS wsimport |
. descriptions, with . bindings |
@descriptions/ |
openapi. |
OpenAPI Generator | an OpenAPI document | @specification/ |
antlr. |
ANTLR | . grammars |
@grammars/ |
A file that only binds the contracts is a complete configuration. This is a working Avro setup:
avro/build.jenesis/avro.properties # @schemas/avro=sources/META-INF/build.jenesis
avro/sources/META-INF/build.jenesis/user.avsc
Every generator resolves its tool in a dependency group of its own, such as avro:tool, kept apart from your
project's dependencies. The version floats RELEASE until you pin it - see Pinning & bills of
materials, which is also where the checksums for these tools belong.
Where the contracts live
A generator does not search your project. It reads one folder, and the binding fills that folder for it:
@schemas/ places the folder, resolved against the module's own folder, as
avro/ of the plugin's input schemas. Files keep the path they had below the bound folder, and only the kinds
a tool compiles are read: a . beside user. never reaches avro-tools.
META-INF/ under the sources is a good home for a contract: the compiler never copies that
folder into the artifact. The contract shapes the build without shipping in the jar.
When a contract must ship, bind the folder it ships from instead:
# soap/META-INF/build.jenesis/wsimport.properties
@descriptions/wsimport=wsdl
A JAX-WS client is the common case, since it reads its WSDL when the service class is constructed. In a
module-info. project a folder beside the sources ships as it stands, as soap/ does in the
service-contracts demo. In a pom. project the folder has to be in a resource directory to ship: as with
Maven, only what a compiler reads - ., ., ., . - is taken from a source directory,
and every other file there stays out of the jar.
Configuring each generator
Only the values listed for a tool are accepted; anything else fails the build by name. Every generator takes
arguments, a whitespace-separated line passed to the tool verbatim.
XML Schema
# xml/build.jenesis/xjc.properties
package=demo.order
@schemas/xjc=sources/META-INF/build.jenesis
Every . in the bound folder is compiled and every . passed as a binding, and a file named catalog
is the catalog; package= sets the generated package.
Protocol buffers
# protobuf/build.jenesis/protoc.properties
plugins=grpc-java=io.grpc/protoc-gen-grpc-java
@definitions/protoc=sources/META-INF/build.jenesis
Every . in the bound folder is compiled, and the folder itself is the include path, so an import
resolves as it is written. Every . that a compile dependency carries is on the include path as well.
The protoc executable from Maven Central ships without the well-known types, but protobuf-java, which the
generated code needs anyway, carries them, so import "google/ resolves without
copying the file into the project.
protoc is a native executable rather than a jar, resolved per operating system and chipset from a Maven
classifier. Each platform therefore needs its own checksum pin, guarded by platform token - a build on
Linux and a build on macOS fetch different bytes. plugins= resolves a protoc
plugin the same way, in its own protoc:<name> group beside protoc's protoc:tool; classifier= overrides the detected platform.
A version pinned for the artifact itself, protoc:tool/, sets the version of
every platform's executable, but its checksum is that of another file, so each platform still pins its own.
pin refreshes only the line of the platform it runs on. To add another platform from one machine, write its
line yourself, guarded by that platform's tokens, with the SHA-256 of the executable Maven Central publishes
for its classifier, protoc-<version>-<classifier>.:
@jenesis.pin protoc:tool/maven/com.google.protobuf/protoc/exe/osx-aarch_64 <version> SHA-256/<hash> (macos,aarch64)
Avro
# avro/build.jenesis/avro.properties
@schemas/avro=sources/META-INF/build.jenesis
Schemas and protocols compile in separate steps, so a module may carry either or both.
WSDL
# soap/META-INF/build.jenesis/wsimport.properties
package=demo.greeter
location=/wsdl/greeter.wsdl
@descriptions/wsimport=wsdl
location is required, and states where the description is served at run time: a class-path path for a
description the module ships, an endpoint URL otherwise. Without it, wsimport would compile the path the
build happened to read the file from into the artifact, which then fails on any other machine.
OpenAPI
# rest/META-INF/build.jenesis/openapi.properties
package=demo.greeting
arguments=--library native --additional-properties useJakartaEe=true
@specification/openapi/openapi.yaml=META-INF/build.jenesis/greeting.yaml
The specification is bound as openapi., or openapi. or openapi., whatever the file is called in
the project. generator= selects the OpenAPI generator (default java).
The OpenAPI Generator writes a whole project - a POM, a README, documentation, test scaffolding. Jenesis
collects only its source folder and discards the rest, so no generated pom. can reach your build.
That folder is src/ by default; a generator that writes elsewhere is named with sources=.
Grammars
# calc/build.jenesis/antlr.properties
package=demo.antlr.calc
arguments=-visitor -no-listener
@grammars/antlr=META-INF/build.jenesis
Every . in the bound folder is compiled into a lexer, a parser and, when asked for, a visitor or a listener.
arguments reaches the tool verbatim, so every ANTLR flag applies.
package= does double duty. ANTLR takes it as -package, which decides the package the generated
code declares, and the build takes it as the directory the sources are written to - so package=
generates demo/ and it compiles like any other source of the module. Without the
key the sources land in the default package, which a module declaration cannot export.
ANTLR writes . and . files beside its sources while it runs. Only the . files survive
the step, so nothing but sources reaches the jar.
As with every generator, the tool is not a dependency of your module. ANTLR resolves in its own antlr:tool
group, and what the generated code calls into - org. - stays an ordinary requires of
the module, pinned separately. Upgrading the parser generator never moves the runtime your program links
against.
Kotlin symbol processing
KSP is Kotlin's counterpart of annotation processing: a processor reads the module's own Kotlin and Java
sources and writes new ones beside them, as Moshi's code generator writes a JSON adapter for each class
annotated @JsonClass(generateAdapter =. The KSP plugin runs where a configuration folder holds a
ksp., and the processors are declared like javac's, by coordinate in the plugin's processor
group, ksp:processor:
/**
* @jenesis.plugin ksp:processor maven/com.squareup.moshi/moshi-kotlin-codegen
*/
module demo.json { ... }
or, in a pom., as the comment <!--jenesis..
Each line of ksp. is an option handed to the processors, the arg(. of Gradle's ksp { }
block; an empty file runs them without any:
# build.jenesis/ksp.properties
moshi.generated=javax.annotation.processing.Generated
Unlike the six generators above, KSP binds no contract and reads the module's sources and its compile
dependencies, which is what lets a processor resolve the types the code uses. It runs before the compilers,
so the sources it writes are compiled with the module's own and the resources it writes, as a service file
or ProGuard rules, join the jar. KSP itself resolves in the group ksp:tool, apart from the processors in
ksp:processor, because a processor brings a Kotlin standard library of its own that KSP does not use. Its arguments
go in process-ksp..
Turning one off
Each generator is switched off by jenesis., which keeps its configuration in place:
-Djenesis.generate.xjc=false
The same shape works for protoc, avro, wsimport, openapi, antlr and ksp.