`
+ linked to `#_ObjectDetailsList`, which is the name of the list rather than of anything a page
+ describes. A list is drawn as a count and the type in it, so the type in it is what is linked to.
+- **A field description was not escaped**, so a `<` or an `&` in one — and the specifications hold
+ both — produced a page no parser accepts. It also nested `` inside `
`.
+- **The index was a `HashMap`**, written out in whatever order it iterated in.
+- **Every page had an empty `
`.**
+
+**What is deliberately different beyond those fixes.**
+
+- **A message field says whether it may be omitted.** The old generator passed `isOptional=false`
+ for every field of a message, so the expanded drawing showed nullability for the fields of a
+ composite and never for the fields of the message holding it. The document tables have said it
+ all along.
+- **A publish-subscribe message names its parts.** What a NOTIFY carries is not what the
+ specification writes — the message holds the subscription it answers and a header per update, and
+ carries a list of each published value rather than one of each — and the old generator drew that
+ correctly but labelled all three "Part".
+- **A drawing is bounded at 120 fields.** Opening a composite replaces one field with all of its
+ own, so a message of nested composites grows by multiplication rather than addition: MPS's plan
+ status report opened to 824 fields, a drawing thirty metres wide, in a page of twenty megabytes.
+ Types are opened a level at a time and the last level that does not fit is closed again, so what
+ a reader gets is the first so-many levels of everything rather than the whole of whichever branch
+ came first. The widest drawing anywhere outside MPS is 46 fields, so nothing else is touched;
+ within MPS the median is 5 and 24 of 264 reach the limit.
+- **The page carries a style sheet**, as a resource rather than a string, and the requirement lists
+ the specifications write as `<ol>`/`<li>` are rendered as lists — this is the one output format
+ where that markup is native, and §7.5 was waiting on somewhere to put it.
+
+**One thing this needed from the model.** `TypeDefinition.getService()` was never set: the field
+existed, the linker never filled it, and nothing had read it. A type declared by a service belongs
+to that service — two services of one area may each declare a type of the same name — so the linker
+now sets it. Nothing else read it, and the Java and document golden trees are unmoved.
+
+The five `svg.*` options of `extraProperties` are not reproduced, per invariant 4: descriptive
+text, indexes, collapsed and expanded messages are all included, and SVG is not split out into
+files of its own, which is what every default already said.
+
+### 10.8 Where the tests live
+
+The main build compiles; testbeds test. That is not a new rule — `testbeds` is commented out of the
+root reactor at `pom.xml:60`, the CI main build runs `-DskipTests clean install`, and every testbed
+is run separately against its own `working-directory`. The library follows it like everything else.
+
+**`api-generator-lib` is in the reactor** (`api-generator/pom.xml`), for compilation. What that
+costs the main build is the compile, because the main build skips tests:
+
+| | Time |
+| --- | --- |
+| `clean compile` | 2.8 s |
+| `clean test`, the 73 unit tests that stayed | 3.5 s |
+
+**`testbeds/testbed-api-generator` holds the 39 tests that read a corpus** — the Java and document
+golden trees, the XML importer and validator corpus walks, the XHTML corpus, and the XML and MOSpec
+round trips, together with the `ModelComparison`, `GoldenTree` and `Corpus` helpers they share. The
+line between the two is whether a test reads anything outside its own module: a test of
+`JumpTable` or `JavaMethodBuilder` stays with the code it tests, a test that walks
+`xml-service-specifications/` or the captured baseline does not.
+
+The point of the split is that building the library is a compile. The point of *not* deleting the
+unit tests along with the rest is that they are what fails when someone breaks a builder, and they
+cost 70 ms.
+
+**What CI runs.** `.github/workflows/testbeds.yml` gains a `testbed-api-generator` job on each of
+the four JDKs, and all 39 tests run there, golden trees included.
+
+That last part took a correction. The baseline was gitignored, on the Phase 0 note that it is
+"~20 MB and regenerable", so on a fresh runner the nine golden-tree tests found nothing to compare
+against and `Assume`-skipped — the strongest check in the suite was the one CI did not perform. The
+proposed fix was to run `golden.sh capture` in the workflow, rebuilding every `apis/*` module with
+the old generators before the testbed built them again with the new.
+
+That was the wrong trade, and the 20 MB was the wrong number. It is repetitive generated Java and
+XML, so it **packs to 1.5 MB** against a repository of 11 MB, and it changes only when the old
+generators change, which is to say almost never while they are frozen through 14.x. Spending
+minutes of CI on four JDKs on every push, forever, to avoid committing 1.5 MB once is not a saving.
+
+So the baseline is committed, at `testbeds/testbed-api-generator/baseline/`, next to the tests that
+read it — deliberately not under `src/test/resources/`, since the tests reach it as files and Maven
+would otherwise copy 20 MB into `target/` on every build. `golden.sh` captures to and compares
+against the same path.
+
+The benefit that decided it is one neither option had been weighed for: a committed baseline makes
+a change in generated output **visible in review**. Change the Java generator and the diff names
+the files that moved. A test that reports "7 files differ" says less than a diff that shows what.
+
+### 10.9 Cut-over — v15.0
+
+The cut-over is **flipping the default**, not proving the new path works — that has been
+demonstrable since Phase 3, by building the whole reactor with `-Pnew-generator` (§3). By this point
+the two implementations should have been producing agreed output in CI for some time, so v15.0 is
+bookkeeping rather than a leap:
+
+- `esa.stubgen.generator` defaults to the new generator, and the profile disappears;
+- `parent/pom.xml` points the plugin's dependency at `api-generator-lib`;
+- `generator-interfaces`, `generator-java` and `generator-docs` are deleted, along with everything
+ in §10.10;
+- the golden tree is re-baselined from the new library, since there is no longer a second
+ implementation to agree with.
+
+If the new path is not producing agreed output by then, the correct response is to leave the default
+alone and ship 15.0 without the deletion — nothing else in the release depends on it.
+
+### 10.10 Removed at cut-over (v15.0)
+
+The new library never carries any of these; they disappear from the repository when the old modules
+are deleted. Until then they stay exactly as they are — no clean-up of the old code during 14.x,
+since the whole point of keeping it is that it goes on working untouched.
+
+- `GeneratorGwt` — dead (§8).
+- `Generator.loadXSD()`, `XsdSpecification`, the `w3c.xsd` package, `src/main/xsd-ref/` and
+ `MOTypeRegistry.loadTypesFromXsdList()`. The only `xsd-ref` directory in the repository is the
+ generator's own, so no module feeds this path. Removing it deletes the second `xjc` execution and
+ the checked-in `XMLSchema.xsd`/DTD copies.
+- `org.reflections` generator discovery.
+- **The plugin's configuration options** — `packageBindings`, `generateStructures`, `generateCOM`,
+ `extraProperties`, `forceGeneration`, `xsdRefDirectory`. Two independent reasons they cannot go
+ earlier:
+ 1. **They are still wired to live code during 14.x.** The plugin goes on driving the old
+ generators, which genuinely read all six (§5.2). They are not vestigial parameters being kept
+ for compatibility — they still do exactly what they do today. Only when the old generators are
+ deleted is there nothing behind them, and that is the cut-over by definition.
+ 2. Removing a Mojo `@Parameter` breaks any external pom that sets one, since Maven fails on
+ unknown plugin configuration. That is a major-version change, announced in the release notes.
+
+ Note the removal is then optional rather than required: the plugin may keep its surface and
+ quietly ignore the options, at no cost to the library, which never had them (§3, invariant 4).
+- `XmlSpecification.modifyFileToBeBackwardsCompatible()`.
+- `ParserMOSDL`'s comment string-replacement.
+- `OperationSummary`, `ServiceSummary`, `FieldInfo`, `TypeKey` — superseded by the model.
+ `CompositeField` is not carried over either — whatever the Java generator needs to render a field
+ is re-derived from the model rather than inherited (§8).
+
+## 11. Decisions taken
+
+No open points outstanding. Decisions taken while writing this document are recorded where they apply, with
+the evidence that settled them, so that they are not silently reopened:
+
+| Decision | Where |
+| --- | --- |
+| One library, not several; the Maven plugin stays separate | §3 |
+| No configuration — invariant 4 | §3 |
+| Java 1.8 | §3 |
+| Area identity keyed on `(name, number, version)`; collisions are a `WARNING` | §4.1 |
+| Type references resolve against the loaded area version, not the schema version | §4.1 |
+| MAL attribute types come from the MAL specification; the Java mapping stays in the generator | §4.2 |
+| `CompositeType.superType` always set — `extends` written explicitly | §4.3 |
+| COM first-class, always generated | §4.4 |
+| The model is the union of v001 and v003; the exporter refuses cross-version constructs | §4.5 |
+| Requirement IDs only where the specification authored them | §4.6 |
+| Documentation markup: existing `DocxBaseWriter` behaviour is normative | §4.6 |
+| `import → link → validate → generate`; ERROR halts, WARNING proceeds | §5.1, §5.3 |
+| Targets are an argument to `generate`, not model state | §5.2 |
+| Schema validation on export, against the real v001/v003 schemas | §6.1 |
+| MOSpec: name, hand-written parser, no MOSDL compatibility | §7.1, §7.2 |
+| A `.mospec` file is a specification, holding one or more areas | §7.1, §7.9 |
+| Diagrams as sidecar SVGs | §7.6 |
+| `BULK` the default doc mode | §7.7 |
+| Type-first field declarations, `replayable`, arrows unchanged | §7.8 |
+| Numbers always explicit; no auto-numbering | §7.7 |
+| MOSpec normalises the older `ObjectRef(X)` spelling; the XML comes back modernised | §7.9 |
+| A comment written empty stays empty, and is shown as one | §7.5 |
+| docx: output unchanged, OOXML layer lifted, styles to resource files | §8 |
+| No third-party dependencies; Batik went with diagram rasterisation | §3, §8.3 |
+| The XHTML generator is ported, not dropped, as Phase 6 | §8, §10.7 |
+| The XHTML page is named after its specification, so two versions of an area no longer collide | §10.7 |
+| A type that contains itself is drawn once and linked, not expanded | §10.7 |
+| A drawing stops at 120 fields, a level at a time | §10.7 |
+| A type knows the service that declares it: the linker now sets it | §10.7 |
+| Rewrite rather than port; no language abstraction before a second language | §8, §8.1 |
+| Parallel generation, with determinism as the binding constraint | §8.2 |
+| Parallel running through 14.x, cut-over at v15.0 | §3, §10.9 |
+| Inline SVG diagrams are not rendered; removed from prototype XML, recorded as a difference for published files | §8.3 |
+| The library compiles in the reactor; its corpus tests live in a testbed | §10.8 |
diff --git a/api-generator/api-generator-lib/pom.xml b/api-generator/api-generator-lib/pom.xml
new file mode 100644
index 00000000..5bb7c642
--- /dev/null
+++ b/api-generator/api-generator-lib/pom.xml
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed under the European Space Agency Public License, Version 2.0
+ You may not use this file except in compliance with the License.
+
+ Except as expressly set forth in this License, the Software is provided to
+ You on an "as is" basis and without warranties of any kind, including without
+ limitation merchantability, fitness for a particular purpose, absence of
+ defects or errors, accuracy or non-infringement of intellectual property rights.
+
+ See the License for the specific language governing permissions and limitations under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>int.esa.ccsds.mo</groupId>
+ <artifactId>parent</artifactId>
+ <version>14.2</version>
+ <relativePath>../../parent/pom.xml</relativePath>
+ </parent>
+
+ <artifactId>api-generator-lib</artifactId>
+ <version>14.2</version>
+ <packaging>jar</packaging>
+
+ <name>ESA MO API Generator - Library</name>
+ <description>Model of MO service specifications, with importers, exporters and generators</description>
+
+ <organization>
+ <name>ESA</name>
+ <url>http://www.esa.int</url>
+ </organization>
+
+ <licenses>
+ <license>
+ <name>The European Space Agency Public License, Version 2.0</name>
+ <url>https://raw.githubusercontent.com/esa/mo-services-java/master/LICENCE.md</url>
+ <distribution>repo</distribution>
+ </license>
+ </licenses>
+
+ <scm>
+ <connection>scm:git:git@github.com:esa/mo-services-java.git</connection>
+ <developerConnection>scm:git:git@github.com:esa/mo-services-java.git</developerConnection>
+ <url>https://github.com/esa/mo-services-java</url>
+ </scm>
+
+ <issueManagement>
+ <system>GitHub</system>
+ <url>https://github.com/esa/mo-services-java/issues</url>
+ </issueManagement>
+
+ <properties>
+ <!--
+ The schemas are unpacked into the library's resources so that exported XML can
+ be validated against the normative definition (design section 6.1). Nothing is
+ code-generated from them.
+ -->
+ <ccsds.specification.download.skip>false</ccsds.specification.download.skip>
+ <ccsds.specification.download.artifact>xml-ccsds-mo-standards</ccsds.specification.download.artifact>
+ <ccsds.specification.download.directory>${project.build.outputDirectory}</ccsds.specification.download.directory>
+ <ccsds.specification.download.filter>**/*.xsd</ccsds.specification.download.filter>
+ </properties>
+
+ <!--
+ No third-party dependencies. The model is plain Java, XML I/O uses StAX from the
+ JDK, the MOSpec parser is hand-written, and docx and XHTML output are written as
+ text. Batik was here to rasterise diagrams declared inside a specification; that
+ support is gone, and with it the last third party. See DESIGN.md, sections 3
+ and 8.3.
+
+ The heavy tests - the golden trees, the corpus walks and the round trips - live in
+ testbeds/testbed-api-generator, not here, so that building this module stays a
+ compile. See DESIGN.md, section 10.8.
+ -->
+ <dependencies>
+ <!-- Build-time only: supplies the XSDs unpacked above, and orders the reactor. -->
+ <dependency>
+ <groupId>int.esa.ccsds.mo</groupId>
+ <artifactId>xml-ccsds-mo-standards</artifactId>
+ <version>14.2</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <resources>
+ <resource>
+ <directory>${basedir}/..</directory>
+ <includes>
+ <include>LICENCE.md</include>
+ </includes>
+ </resource>
+ <!-- Naming any resource directory replaces the default, so the module's own
+ has to be named again: it holds the fixed parts of a .docx package. -->
+ <resource>
+ <directory>src/main/resources</directory>
+ </resource>
+ </resources>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ </plugin>
+ </plugins>
+ </build>
+</project>
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/ExportException.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/ExportException.java
new file mode 100644
index 00000000..86452c71
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/ExportException.java
@@ -0,0 +1,37 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters;
+
+/**
+ * Thrown when a model cannot be written in the requested format.
+ * <p>
+ * The commonest cause is a construct the target schema version does not have. An exporter
+ * refuses rather than dropping it: writing a v003 model into a v001 file would silently
+ * lose its subscription keys.
+ */
+public class ExportException extends Exception {
+
+ private static final long serialVersionUID = 1L;
+
+ public ExportException(String message) {
+ super(message);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/Exporter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/Exporter.java
new file mode 100644
index 00000000..d6d43eb8
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/Exporter.java
@@ -0,0 +1,44 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters;
+
+import esa.mo.apigen.model.Specification;
+import java.io.IOException;
+import java.nio.file.Path;
+
+/**
+ * Writes a specification out.
+ * <p>
+ * Exporters write to a directory rather than to a stream because no export is necessarily
+ * one document: a MOSpec specification is a text file plus a sidecar for each diagram.
+ */
+public interface Exporter {
+
+ /**
+ * Writes a specification.
+ *
+ * @param spec The specification to write.
+ * @param outputDir The directory to write into. Created if it does not exist.
+ * @throws IOException if writing fails.
+ * @throws ExportException if the specification cannot be represented in this format.
+ */
+ void write(Specification spec, Path outputDir) throws IOException, ExportException;
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/DocMode.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/DocMode.java
new file mode 100644
index 00000000..3e019f0c
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/DocMode.java
@@ -0,0 +1,44 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.mospec;
+
+/**
+ * Where the documentation of an operation's fields and errors is placed.
+ */
+public enum DocMode {
+
+ /**
+ * Hoisted into one block above the signature, tagged by what it describes. The default,
+ * because it keeps the signature scannable in one glance.
+ */
+ BULK,
+
+ /**
+ * Written beside the field or error it describes, inside the signature.
+ */
+ INLINE,
+
+ /**
+ * Left out. The only mode that does not preserve the model, and so the only one the
+ * round-trip test cannot hold to equality.
+ */
+ SUPPRESS
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/MOSpecExporter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/MOSpecExporter.java
new file mode 100644
index 00000000..5da969ea
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/MOSpecExporter.java
@@ -0,0 +1,720 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.mospec;
+
+import esa.mo.apigen.exporters.ExportException;
+import esa.mo.apigen.exporters.Exporter;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.CapabilitySet;
+import esa.mo.apigen.model.ErrorDefinition;
+import esa.mo.apigen.model.ErrorReference;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.Specification;
+import esa.mo.apigen.model.com.COMFeatures;
+import esa.mo.apigen.model.com.COMObject;
+import esa.mo.apigen.model.com.ObjectLink;
+import esa.mo.apigen.model.com.ObjectReference;
+import esa.mo.apigen.model.docs.Diagram;
+import esa.mo.apigen.model.docs.DocSection;
+import esa.mo.apigen.model.types.AttributeType;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationItem;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.FundamentalType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.io.Writer;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes a specification as MOSpec.
+ * <p>
+ * A MOSpec specification is a directory: one {@code .mospec} file holding the specification,
+ * and one {@code .svg} beside it per diagram. Inlining a diagram would put a hundred lines of
+ * drawing in the middle of a readable file, and dropping it would make the text format the
+ * one place the round trip leaks.
+ * <p>
+ * The exporter defines the dialect: whatever it writes, the parser must read back. That is
+ * what the round-trip test holds it to.
+ */
+public final class MOSpecExporter implements Exporter {
+
+ private static final Charset UTF8 = Charset.forName("UTF-8");
+
+ private final DocMode mode;
+
+ /**
+ * An exporter writing in the default mode, with each operation's documentation gathered
+ * above its signature.
+ */
+ public MOSpecExporter() {
+ this(DocMode.BULK);
+ }
+
+ /**
+ * @param mode Where to put the documentation of fields and errors.
+ */
+ public MOSpecExporter(DocMode mode) {
+ this.mode = mode;
+ }
+
+ @Override
+ public void write(Specification spec, Path outputDir) throws IOException, ExportException {
+ Files.createDirectories(outputDir);
+ SourceFormatter out = new SourceFormatter();
+ writeSpecification(out, spec);
+
+ String name = spec.getAreas().isEmpty() ? "specification"
+ : spec.getAreas().get(0).getName();
+ write(outputDir.resolve(name + ".mospec"), out.toText());
+
+ for (Area area : spec.getAreas()) {
+ writeDiagrams(outputDir, area.getDocumentation().getDiagrams());
+ for (Service service : area.getServices()) {
+ writeDiagrams(outputDir, service.getDocumentation().getDiagrams());
+ if (service.getCom() != null) {
+ writeDiagrams(outputDir, service.getCom().getDocumentation().getDiagrams());
+ }
+ }
+ }
+ }
+
+ /**
+ * @return the text of a specification, for a caller that wants it without the sidecars.
+ */
+ public String toText(Specification spec) {
+ SourceFormatter out = new SourceFormatter();
+ writeSpecification(out, spec);
+ return out.toText();
+ }
+
+ private void writeSpecification(SourceFormatter out, Specification spec) {
+ if (mode == DocMode.SUPPRESS) {
+ out.suppressDocumentation();
+ }
+ out.doc(spec.getComment());
+ out.line("specification [" + spec.getSchemaVersion().name().toLowerCase() + "]");
+ for (Area area : spec.getAreas()) {
+ out.blank();
+ writeArea(out, area);
+ }
+ }
+
+ private void writeArea(SourceFormatter out, Area area) {
+ out.doc(area.getComment());
+ out.line("area " + MOSpecTypes.identifier(area.getName())
+ + " [" + area.getNumber() + "." + area.getVersion() + "]");
+ writeDocSections(out, area.getDocumentation().getSections());
+ writeDiagramReferences(out, area.getDocumentation().getDiagrams());
+ writeDataTypes(out, area, null, area.getDataTypes());
+ writeErrorDefinitions(out, area.getErrors());
+
+ for (Service service : area.getServices()) {
+ out.blank();
+ writeService(out, area, service);
+ }
+ }
+
+ private void writeService(SourceFormatter out, Area area, Service service) {
+ out.doc(service.getComment());
+ // A service can be a COM extended service and declare nothing at all under com, so
+ // being one is said on the service rather than inferred from what follows.
+ out.line((service.isExtended() ? "extended service " : "service ")
+ + MOSpecTypes.identifier(service.getName())
+ + " [" + service.getNumber() + "] {");
+ out.in();
+
+ writeDocSections(out, service.getDocumentation().getSections());
+ writeDiagramReferences(out, service.getDocumentation().getDiagrams());
+
+ for (CapabilitySet set : service.getCapabilitySets()) {
+ out.blank();
+ writeCapabilitySet(out, area, service, set);
+ }
+
+ writeDataTypes(out, area, service, service.getDataTypes());
+ writeErrorDefinitions(out, service.getErrors());
+
+ if (service.getCom() != null) {
+ out.blank();
+ writeCom(out, area, service, service.getCom());
+ }
+
+ out.out();
+ out.line("}");
+ }
+
+ private void writeCapabilitySet(SourceFormatter out, Area area, Service service,
+ CapabilitySet set) {
+ out.doc(set.getComment());
+ out.line("capability [" + set.getNumber() + "] {");
+ out.in();
+ for (Operation operation : set.getOperations()) {
+ out.blank();
+ writeOperation(out, area, service, operation);
+ }
+ out.out();
+ out.line("}");
+ }
+
+ /**
+ * One operation: its documentation, then the pattern, the name, the number, and the
+ * messages it exchanges in the order they travel.
+ */
+ private void writeOperation(SourceFormatter out, Area area, Service service,
+ Operation operation) {
+ if (mode == DocMode.BULK) {
+ out.doc(operation.getComment(), bulkTags(area, operation));
+ } else if (mode == DocMode.INLINE) {
+ // A message's own comment stays in the block even inline, tagged by its stage.
+ // Written inside the parentheses it could not be told from the documentation of
+ // the first field, which sits in the same place and looks the same.
+ out.doc(operation.getComment(), messageTags(operation));
+ }
+ writeDocSections(out, operation.getDocumentation().getSections());
+
+ StringBuilder head = new StringBuilder();
+ if (operation.isSupportInReplay()) {
+ head.append("replayable ");
+ }
+ head.append(patternOf(operation)).append(' ')
+ .append(MOSpecTypes.identifier(operation.getName()))
+ .append(" [").append(operation.getNumber()).append(']');
+ // The opening message is left out where the operation declares none: a
+ // publish-subscribe operation that keys its subscription on nothing is not the same
+ // as one that keys it on an empty list.
+ InteractionStage first = firstStageOf(operation);
+ boolean opened = operation.getMessage(first) != null;
+
+ if (mode == DocMode.INLINE) {
+ if (opened) {
+ writeInlineMessage(out, area, service, operation, first, head + " ");
+ } else {
+ out.line(head.toString());
+ }
+ out.in();
+ for (InteractionStage stage : replyStagesOf(operation)) {
+ writeInlineMessage(out, area, service, operation, stage, "-> ");
+ if (repeats(operation, stage)) {
+ out.line("*");
+ }
+ }
+ writeThrows(out, area, service, operation);
+ out.out();
+ return;
+ }
+
+ if (opened) {
+ head.append(' ').append(message(area, service, operation, first));
+ }
+ out.line(head.toString());
+
+ out.in();
+ for (InteractionStage stage : replyStagesOf(operation)) {
+ out.line("-> " + message(area, service, operation, stage)
+ + (repeats(operation, stage) ? "*" : ""));
+ }
+ writeThrows(out, area, service, operation);
+ out.out();
+ }
+
+ /**
+ * The errors an operation may answer with, each with the type of whatever extra
+ * information it carries.
+ */
+ private void writeThrows(SourceFormatter out, Area area, Service service,
+ Operation operation) {
+ if (operation.getErrors().isEmpty()) {
+ return;
+ }
+ if (mode == DocMode.INLINE) {
+ out.line("throws");
+ out.in();
+ List<ErrorReference> errors = operation.getErrors();
+ for (int i = 0; i < errors.size(); i++) {
+ ErrorReference error = errors.get(i);
+ out.doc(error.getComment());
+ String written = errorName(area, error) + (i == errors.size() - 1 ? "" : ",");
+ if (error.getExtraInformation() == null) {
+ out.line(written);
+ continue;
+ }
+ out.line(errorName(area, error) + ":");
+ out.in();
+ out.doc(error.getExtraInformation().getComment());
+ out.line(MOSpecTypes.of(area, service, error.getExtraInformation().getType())
+ + (i == errors.size() - 1 ? "" : ","));
+ out.out();
+ }
+ out.out();
+ return;
+ }
+
+ List<String> raised = new ArrayList<String>();
+ for (ErrorReference error : operation.getErrors()) {
+ String written = errorName(area, error);
+ if (error.getExtraInformation() != null) {
+ written += ": " + MOSpecTypes.of(area, service,
+ error.getExtraInformation().getType());
+ }
+ raised.add(written);
+ }
+ out.line("throws " + join(raised, ", "));
+ }
+
+ /**
+ * @return the fields of one message, in parentheses.
+ */
+ private String message(Area area, Service service, Operation operation,
+ InteractionStage stage) {
+ if (stage == null) {
+ return "()";
+ }
+ List<Field> fields = fieldsOf(operation, stage);
+ List<String> written = new ArrayList<String>();
+ for (Field field : fields) {
+ written.add(MOSpecTypes.field(area, service, field));
+ }
+ return "(" + join(written, ", ") + ")";
+ }
+
+ /**
+ * Writes a message with the documentation of each field beside it, which is what inline
+ * mode is for: the signature is longer, and nothing about a field is anywhere else.
+ *
+ * @return true if anything was written, false where the message is empty and the
+ * caller should write it on the line it is already on.
+ */
+ private boolean writeInlineMessage(SourceFormatter out, Area area, Service service,
+ Operation operation, InteractionStage stage, String opening) {
+ List<Field> fields = stage == null ? new ArrayList<Field>()
+ : fieldsOf(operation, stage);
+
+ if (fields.isEmpty()) {
+ out.line(opening + "()");
+ return true;
+ }
+ out.line(opening + "(");
+ out.in();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ out.doc(field.getComment());
+ out.line(MOSpecTypes.field(area, service, field)
+ + (i == fields.size() - 1 ? "" : ","));
+ }
+ out.out();
+ out.line(")");
+ return true;
+ }
+
+ /**
+ * The tagged lines of a bulk documentation block: one per documented field, then one
+ * per error and its extra information.
+ */
+ /**
+ * @return one tag per message that documents itself, and nothing else.
+ */
+ private List<String> messageTags(Operation operation) {
+ List<String> tags = new ArrayList<String>();
+ for (InteractionStage stage : allStagesOf(operation)) {
+ MessageBody body = operation.getMessage(stage);
+ if (body != null && body.getComment() != null) {
+ tags.add("@" + tagOf(stage) + ": " + body.getComment());
+ }
+ }
+ return tags;
+ }
+
+ private List<String> bulkTags(Area area, Operation operation) {
+ List<String> tags = new ArrayList<String>();
+ for (InteractionStage stage : allStagesOf(operation)) {
+ MessageBody body = operation.getMessage(stage);
+ if (body != null && body.getComment() != null) {
+ tags.add("@" + tagOf(stage) + ": " + body.getComment());
+ }
+ for (Field field : fieldsOf(operation, stage)) {
+ // Written whenever there is a comment at all, empty or not: the empty one
+ // is a thing the specification says, and it has to come back.
+ if (field.getComment() != null) {
+ tags.add("@" + tagOf(stage) + "param " + field.getName() + ": "
+ + field.getComment());
+ }
+ }
+ }
+ for (ErrorReference error : operation.getErrors()) {
+ String name = errorName(area, error);
+ if (error.getComment() != null) {
+ tags.add("@error " + name + ": " + error.getComment());
+ }
+ Field extra = error.getExtraInformation();
+ if (extra != null && extra.getComment() != null) {
+ tags.add("@errorinfo " + name + ": " + extra.getComment());
+ }
+ }
+ return tags;
+ }
+
+ private void writeDataTypes(SourceFormatter out, Area area, Service service,
+ List<TypeDefinition> types) {
+ for (TypeDefinition type : types) {
+ out.blank();
+ if (type instanceof FundamentalType) {
+ writeFundamental(out, area, service, (FundamentalType) type);
+ } else if (type instanceof AttributeType) {
+ writeAttribute(out, (AttributeType) type);
+ } else if (type instanceof EnumerationType) {
+ writeEnumeration(out, (EnumerationType) type);
+ } else if (type instanceof CompositeType) {
+ writeComposite(out, area, service, (CompositeType) type);
+ }
+ }
+ }
+
+ private void writeFundamental(SourceFormatter out, Area area, Service service,
+ FundamentalType type) {
+ out.doc(type.getComment());
+ String head = "fundamental " + MOSpecTypes.identifier(type.getName());
+ if (type.getSuperType() != null) {
+ head += " extends " + MOSpecTypes.of(area, service, type.getSuperType());
+ }
+ out.line(head);
+ }
+
+ private void writeAttribute(SourceFormatter out, AttributeType type) {
+ out.doc(type.getComment());
+ out.line("attribute " + MOSpecTypes.identifier(type.getName())
+ + " [" + type.getShortFormPart() + "]");
+ }
+
+ private void writeEnumeration(SourceFormatter out, EnumerationType type) {
+ out.doc(type.getComment());
+ out.line("enumeration " + MOSpecTypes.identifier(type.getName())
+ + " [" + type.getShortFormPart() + "] {");
+ out.in();
+ for (EnumerationItem item : type.getItems()) {
+ out.doc(item.getComment());
+ out.line(MOSpecTypes.identifier(item.getValue())
+ + " [" + item.getNumericValue() + "]");
+ }
+ out.out();
+ out.line("}");
+ }
+
+ private void writeComposite(SourceFormatter out, Area area, Service service,
+ CompositeType type) {
+ out.doc(type.getComment());
+ StringBuilder head = new StringBuilder();
+ if (type.isAbstract()) {
+ head.append("abstract ");
+ }
+ head.append("composite ").append(MOSpecTypes.identifier(type.getName()));
+ if (type.getShortFormPart() != null) {
+ head.append(" [").append(type.getShortFormPart()).append(']');
+ }
+ if (type.getSuperType() != null) {
+ head.append(" extends ").append(MOSpecTypes.of(area, service, type.getSuperType()));
+ }
+ out.line(head.append(" {").toString());
+ out.in();
+ for (Field field : type.getFields()) {
+ out.doc(field.getComment());
+ out.line(MOSpecTypes.field(area, service, field));
+ }
+ out.out();
+ out.line("}");
+ }
+
+ private void writeErrorDefinitions(SourceFormatter out, List<ErrorDefinition> errors) {
+ for (ErrorDefinition error : errors) {
+ out.blank();
+ out.doc(error.getComment());
+ out.line("error " + MOSpecTypes.identifier(error.getName())
+ + " [" + error.getNumber() + "]");
+ }
+ }
+
+ /**
+ * What the service adds to the COM: the objects it stores, the events it raises, and
+ * how it uses the archive and the activity tracking.
+ */
+ private void writeCom(SourceFormatter out, Area area, Service service, COMFeatures com) {
+ out.line("com {");
+ out.in();
+ writeDiagramReferences(out, com.getDocumentation().getDiagrams());
+ writeDocSections(out, com.getDocumentation().getSections());
+
+ if (com.declaresObjects()) {
+ out.blank();
+ out.doc(com.getObjectsComment());
+ out.line("objects {");
+ out.in();
+ for (COMObject object : com.getObjects()) {
+ out.blank();
+ writeComObject(out, area, service, "object", object);
+ }
+ out.out();
+ out.line("}");
+ }
+ if (com.declaresEvents()) {
+ out.blank();
+ out.doc(com.getEventsComment());
+ out.line("events {");
+ out.in();
+ for (COMObject event : com.getEvents()) {
+ out.blank();
+ writeComObject(out, area, service, "event", event);
+ }
+ out.out();
+ out.line("}");
+ }
+ if (com.declaresArchiveUsage()) {
+ out.blank();
+ out.doc(com.getArchiveUsage());
+ out.line("archiveUsage");
+ }
+ if (com.declaresActivityUsage()) {
+ out.blank();
+ out.doc(com.getActivityUsage());
+ out.line("activityUsage");
+ }
+ out.out();
+ out.line("}");
+ }
+
+ /**
+ * One COM object or event. The braces are left off where it links to nothing, which is
+ * most of them.
+ */
+ private void writeComObject(SourceFormatter out, Area area, Service service,
+ String keyword, COMObject object) {
+ out.doc(object.getComment());
+ StringBuilder head = new StringBuilder(keyword);
+ head.append(' ').append(MOSpecTypes.identifier(object.getName()))
+ .append(" [").append(object.getNumber()).append(']');
+ if (object.getBodyType() != null) {
+ head.append(" (").append(MOSpecTypes.of(area, service, object.getBodyType()))
+ .append(')');
+ }
+
+ boolean hasLinks = object.getRelated() != null || object.getSource() != null;
+ if (!hasLinks) {
+ out.line(head.toString());
+ return;
+ }
+ out.line(head.append(" {").toString());
+ out.in();
+ writeLink(out, area, "related", object.getRelated());
+ writeLink(out, area, "source", object.getSource());
+ out.out();
+ out.line("}");
+ }
+
+ /**
+ * A link to another COM object, by name where the target is known and by number where
+ * it is not - a specification whose target area is absent still has to round-trip.
+ */
+ private void writeLink(SourceFormatter out, Area area, String keyword, ObjectLink link) {
+ if (link == null) {
+ return;
+ }
+ out.doc(link.getComment());
+ ObjectReference target = link.getTarget();
+ if (target == null) {
+ out.line(keyword + " -");
+ return;
+ }
+ StringBuilder written = new StringBuilder(keyword).append(' ');
+ if (!area.getName().equals(target.getArea())) {
+ written.append(target.getArea()).append("::");
+ }
+ if (target.getService() != null && !target.getService().isEmpty()) {
+ written.append(target.getService());
+ }
+ out.line(written.append('#').append(target.getNumber()).toString());
+ }
+
+ private void writeDocSections(SourceFormatter out, List<DocSection> sections) {
+ if (mode == DocMode.SUPPRESS) {
+ return;
+ }
+ for (DocSection section : sections) {
+ out.blank();
+ String head = "doc \"" + section.getName() + "\" [" + section.getOrder() + "]";
+ if (section.getContent() == null || section.getContent().isEmpty()) {
+ out.line(head);
+ continue;
+ }
+ out.line(head + " \"\"\"");
+ out.in();
+ for (String written : section.getContent().split("\n", -1)) {
+ out.line(written);
+ }
+ out.out();
+ out.line("\"\"\"");
+ }
+ }
+
+ private void writeDiagramReferences(SourceFormatter out, List<Diagram> diagrams) {
+ for (Diagram diagram : diagrams) {
+ out.blank();
+ out.line("diagram " + MOSpecTypes.identifier(diagram.getName())
+ + " \"" + diagram.getName() + ".svg\"");
+ }
+ }
+
+ private void writeDiagrams(Path outputDir, List<Diagram> diagrams) throws IOException {
+ for (Diagram diagram : diagrams) {
+ write(outputDir.resolve(diagram.getName() + ".svg"), diagram.getSvg());
+ }
+ }
+
+ private static void write(Path file, String content) throws IOException {
+ Writer out = new OutputStreamWriter(Files.newOutputStream(file), UTF8);
+ try {
+ out.write(content == null ? "" : content);
+ } finally {
+ out.close();
+ }
+ }
+
+ // ------------------------------------------------------------- the stages
+
+ private static String patternOf(Operation operation) {
+ return operation.getPattern().name().toLowerCase();
+ }
+
+ /**
+ * @return the stage the consumer starts the interaction with.
+ */
+ private static InteractionStage firstStageOf(Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ return InteractionStage.SEND;
+ case SUBMIT:
+ return InteractionStage.SUBMIT;
+ case REQUEST:
+ return InteractionStage.REQUEST;
+ case INVOKE:
+ return InteractionStage.INVOKE;
+ case PROGRESS:
+ return InteractionStage.PROGRESS;
+ case PUBSUB:
+ return InteractionStage.SUBSCRIPTION_KEYS;
+ default:
+ return null;
+ }
+ }
+
+ /**
+ * @return the stages the provider answers with, in the order they travel.
+ */
+ private static List<InteractionStage> replyStagesOf(Operation operation) {
+ List<InteractionStage> stages = new ArrayList<InteractionStage>();
+ switch (operation.getPattern()) {
+ case REQUEST:
+ stages.add(InteractionStage.RESPONSE);
+ break;
+ case INVOKE:
+ stages.add(InteractionStage.ACK);
+ stages.add(InteractionStage.RESPONSE);
+ break;
+ case PROGRESS:
+ stages.add(InteractionStage.ACK);
+ stages.add(InteractionStage.UPDATE);
+ stages.add(InteractionStage.RESPONSE);
+ break;
+ case PUBSUB:
+ stages.add(InteractionStage.PUBLISH_NOTIFY);
+ break;
+ default:
+ break;
+ }
+ return stages;
+ }
+
+ private static List<InteractionStage> allStagesOf(Operation operation) {
+ List<InteractionStage> stages = new ArrayList<InteractionStage>();
+ InteractionStage first = firstStageOf(operation);
+ if (first != null) {
+ stages.add(first);
+ }
+ stages.addAll(replyStagesOf(operation));
+ return stages;
+ }
+
+ /**
+ * @return true where the stage may be sent more than once, which only the update of a
+ * progress is.
+ */
+ private static boolean repeats(Operation operation, InteractionStage stage) {
+ return operation.getPattern() == InteractionPattern.PROGRESS
+ && stage == InteractionStage.UPDATE;
+ }
+
+ /**
+ * @return the tag that documents a field of this stage, which is the stage's own name.
+ */
+ private static String tagOf(InteractionStage stage) {
+ if (stage == InteractionStage.PUBLISH_NOTIFY) {
+ return "publish";
+ }
+ if (stage == InteractionStage.SUBSCRIPTION_KEYS) {
+ return "subscriptionkeys";
+ }
+ return stage.name().toLowerCase();
+ }
+
+ private static String errorName(Area area, ErrorReference error) {
+ TypeRef ref = error.getError();
+ StringBuilder buf = new StringBuilder();
+ if (ref.getArea() != null && !ref.getArea().equals(area.getName())) {
+ buf.append(ref.getArea()).append("::");
+ }
+ if (ref.getService() != null && !ref.getService().isEmpty()) {
+ buf.append(ref.getService()).append('.');
+ }
+ return buf.append(MOSpecTypes.identifier(ref.getName())).toString();
+ }
+
+ private static List<Field> fieldsOf(Operation operation, InteractionStage stage) {
+ MessageBody body = operation.getMessage(stage);
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ private static String join(List<String> parts, String separator) {
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < parts.size(); i++) {
+ buf.append(i == 0 ? "" : separator).append(parts.get(i));
+ }
+ return buf.toString();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/MOSpecTypes.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/MOSpecTypes.java
new file mode 100644
index 00000000..d1a360d2
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/MOSpecTypes.java
@@ -0,0 +1,171 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.mospec;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * How a type is written in MOSpec.
+ * <p>
+ * Type-first, with the list and object-reference wrappers around the name and nullability
+ * postfix on the whole thing: {@code List<ObjectRef<Product>>? refs}. The area and service
+ * are left off only when both match where the type is being mentioned, so a name is never
+ * ambiguous about where it comes from.
+ */
+public final class MOSpecTypes {
+
+ /**
+ * Words the grammar gives a meaning to. An identifier that collides with one is quoted,
+ * so that a specification is never prevented from naming something what it likes.
+ */
+ private static final Set<String> KEYWORDS = new HashSet<String>(Arrays.asList(
+ "specification", "area", "service", "capability", "com", "objects", "events",
+ "object", "event", "related", "source", "archiveUsage", "activityUsage",
+ "diagram", "doc", "composite", "enumeration", "attribute", "fundamental",
+ "abstract", "extends", "extended", "error", "errors", "throws", "replayable",
+ "send", "submit", "request", "invoke", "progress", "pubsub", "subscriptionKeys"));
+
+ private MOSpecTypes() {
+ }
+
+ /**
+ * Writes a type as it is referred to from somewhere.
+ *
+ * @param area The area doing the referring.
+ * @param service The service doing the referring, or null at area level.
+ * @param reference The type referred to.
+ * @return the type, written.
+ */
+ public static String of(Area area, Service service, TypeRef reference) {
+ TypeRef ref = reference.unwrapped();
+ StringBuilder buf = new StringBuilder(qualified(area, service, ref));
+ if (ref.isObjectRef()) {
+ buf.insert(0, "ObjectRef<").append('>');
+ }
+ if (ref.isList()) {
+ buf.insert(0, "List<").append('>');
+ }
+ return buf.toString();
+ }
+
+ /**
+ * Writes a field: its type, then its name, with the nullable marker between them.
+ *
+ * @param area The area the field is declared in.
+ * @param service The service it is declared in, or null at area level.
+ * @param field The field.
+ * @return the declaration.
+ */
+ public static String field(Area area, Service service, Field field) {
+ return of(area, service, field.getType())
+ + (field.isCanBeNull() ? "? " : " ") + identifier(field.getName());
+ }
+
+ /**
+ * Writes a name.
+ * <p>
+ * Quoted where the grammar would otherwise read it as a keyword, and where it is not a
+ * bare name at all: the MAL's own errors are called things like "Authentication Failed",
+ * and a specification is not going to be told what it may call things.
+ *
+ * @param name An identifier out of a specification.
+ * @return the name, quoted where it has to be.
+ */
+ public static String identifier(String name) {
+ if (name == null) {
+ return null;
+ }
+ return KEYWORDS.contains(name) || !isBare(name) ? "\"" + name + "\"" : name;
+ }
+
+ /**
+ * @return true if the name is one the lexer would read as a single word.
+ */
+ private static boolean isBare(String name) {
+ if (name.isEmpty() || !(Character.isLetter(name.charAt(0)) || name.charAt(0) == '_')) {
+ return false;
+ }
+ for (int i = 0; i < name.length(); i++) {
+ char c = name.charAt(i);
+ if (!Character.isLetterOrDigit(c) && c != '_') {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /**
+ * Names a type from where it is mentioned.
+ * <p>
+ * The area is left off when it is the area doing the mentioning, and the service
+ * likewise - a type of another service in the same area still says which service. MAL
+ * is left off as well: its types are named in every specification and the language
+ * imports them implicitly, exactly as the format it descends from did. The one case
+ * that would be ambiguous - an area declaring a type of its own with the same name as a
+ * MAL type - is written out in full.
+ */
+ /**
+ * @return true if the area or the service being written declares a type of this name,
+ * in which case an unqualified name would mean that one rather than the MAL's.
+ */
+ private static boolean declaresLocally(Area area, Service service, String name) {
+ if (area != null) {
+ for (TypeDefinition type : area.getDataTypes()) {
+ if (name.equals(type.getName())) {
+ return true;
+ }
+ }
+ }
+ if (service != null) {
+ for (TypeDefinition type : service.getDataTypes()) {
+ if (name.equals(type.getName())) {
+ return true;
+ }
+ }
+ }
+ return false;
+ }
+
+ private static String qualified(Area area, Service service, TypeRef ref) {
+ StringBuilder buf = new StringBuilder();
+ boolean sameArea = area != null && area.getName().equals(ref.getArea());
+ boolean implicitMal = !sameArea && "MAL".equals(ref.getArea())
+ && !declaresLocally(area, service, ref.getName());
+ if (!sameArea && !implicitMal) {
+ buf.append(ref.getArea()).append("::");
+ }
+ if (ref.getService() != null && !ref.getService().isEmpty()) {
+ boolean sameService = sameArea && service != null
+ && ref.getService().equals(service.getName());
+ if (!sameService) {
+ buf.append(ref.getService()).append('.');
+ }
+ }
+ return buf.append(identifier(ref.getName())).toString();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/SourceFormatter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/SourceFormatter.java
new file mode 100644
index 00000000..87053db0
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/mospec/SourceFormatter.java
@@ -0,0 +1,188 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.mospec;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * How a MOSpec file is laid out, apart from what it says.
+ * <p>
+ * The exporter decides what to write; this decides how it reads - where the indentation
+ * goes, how a doc comment is written, where the blank lines fall. Keeping them apart means
+ * the layout can be changed without touching the traversal, and the round-trip test says
+ * whether the change was safe.
+ */
+public final class SourceFormatter {
+
+ private final StringBuilder buffer = new StringBuilder();
+
+ private int indent = 0;
+
+ /**
+ * True where documentation is left out entirely. The one mode that does not preserve
+ * the model, and the reason the round-trip test holds it to a weaker standard.
+ */
+ private boolean suppressed = false;
+
+ /**
+ * Stops anything being written as documentation.
+ */
+ public void suppressDocumentation() {
+ this.suppressed = true;
+ }
+
+ /**
+ * Steps in. Everything written until the matching {@link #out} is indented one further.
+ */
+ public void in() {
+ indent++;
+ }
+
+ public void out() {
+ if (indent > 0) {
+ indent--;
+ }
+ }
+
+ /**
+ * Writes one line at the current indentation.
+ *
+ * @param text The line, which may be empty for a blank one.
+ */
+ public void line(String text) {
+ if (text.isEmpty()) {
+ buffer.append('\n');
+ return;
+ }
+ for (int i = 0; i < indent; i++) {
+ buffer.append('\t');
+ }
+ buffer.append(text).append('\n');
+ }
+
+ /**
+ * Writes a blank line, unless the last thing written was already one. A traversal that
+ * separates everything from everything else would otherwise leave gaps of two and three
+ * lines wherever two rules meet.
+ */
+ public void blank() {
+ int length = buffer.length();
+ if (length == 0 || (length >= 2 && buffer.charAt(length - 1) == '\n'
+ && buffer.charAt(length - 2) == '\n')) {
+ return;
+ }
+ buffer.append('\n');
+ }
+
+ /**
+ * Writes a documentation comment, as one line where it fits and as a block where it
+ * does not.
+ *
+ * @param text The documentation, may be null or empty for none.
+ */
+ public void doc(String text) {
+ doc(text, new ArrayList<String>());
+ }
+
+ /**
+ * Writes a documentation comment followed by tagged lines, which is how an operation
+ * documents its fields and errors in bulk mode.
+ *
+ * @param text The documentation of the thing itself, may be null.
+ * @param tags The tagged lines, each already beginning with its tag.
+ */
+ public void doc(String text, List<String> tags) {
+ if (suppressed) {
+ return;
+ }
+ // Nothing is re-wrapped. A comment is written with the line breaks it has and no
+ // others: wrapping a long paragraph would turn one paragraph into several, and the
+ // text that came back would say something the model no longer does. Long lines are
+ // the price of a round trip that returns what it was given.
+ List<String> body = new ArrayList<String>(paragraphs(text));
+ if (!tags.isEmpty() && !body.isEmpty()) {
+ body.add("");
+ }
+ for (String tag : tags) {
+ body.addAll(paragraphs(tag));
+ }
+ if (body.isEmpty()) {
+ // An empty comment is written as an empty one. The specifications are full of
+ // comment="", which says nothing but is not the same as saying nothing, and a
+ // format that could not tell them apart would not round-trip.
+ if (text != null) {
+ line("///");
+ }
+ return;
+ }
+ // One line is written as one line; anything longer becomes a block, so that a short
+ // comment does not cost three lines to say one thing.
+ if (body.size() == 1) {
+ line("/// " + body.get(0));
+ return;
+ }
+ line("/**");
+ for (String written : body) {
+ line(written.isEmpty() ? " *" : " * " + written);
+ }
+ line(" **/");
+ }
+
+ /**
+ * Writes text that has to survive exactly as it is - a requirement, or anything else
+ * whose own line breaks carry meaning.
+ *
+ * @param text The text.
+ */
+ public void verbatim(String text) {
+ line("\"\"\"");
+ in();
+ for (String written : text.split("\n", -1)) {
+ line(written);
+ }
+ out();
+ line("\"\"\"");
+ }
+
+ /**
+ * @return what has been written.
+ */
+ public String toText() {
+ return buffer.toString();
+ }
+
+ /**
+ * Splits documentation where the writer put a line break, so that a comment written as
+ * several paragraphs stays several paragraphs.
+ */
+ private static List<String> paragraphs(String text) {
+ List<String> found = new ArrayList<String>();
+ if (text == null || text.isEmpty()) {
+ return found;
+ }
+ for (String paragraph : text.split("\n", -1)) {
+ found.add(paragraph);
+ }
+ return found;
+ }
+
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/SchemaValidation.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/SchemaValidation.java
new file mode 100644
index 00000000..ef196526
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/SchemaValidation.java
@@ -0,0 +1,145 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.xml;
+
+import esa.mo.apigen.model.SchemaVersion;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.StringReader;
+import java.util.EnumMap;
+import java.util.Map;
+import javax.xml.XMLConstants;
+import javax.xml.transform.Source;
+import javax.xml.transform.stream.StreamSource;
+import javax.xml.validation.Schema;
+import javax.xml.validation.SchemaFactory;
+import javax.xml.validation.Validator;
+import org.xml.sax.ErrorHandler;
+import org.xml.sax.SAXException;
+import org.xml.sax.SAXParseException;
+
+/**
+ * Validates exported XML against the normative schema, using JAXP - part of the JDK, so
+ * this adds no dependency.
+ * <p>
+ * The schema encodes constraints a hand-written validator would otherwise have to
+ * duplicate, so anything the XSD can state is left to it. Each specification is checked
+ * against its own version rather than against the backwards-compatible hybrid, which
+ * accepts documents neither version does.
+ * <p>
+ * The schemas are unpacked into this library's resources at build time from
+ * {@code xml-ccsds-mo-standards}. Copying rather than keeping a hand-maintained copy
+ * matters: a hand-kept copy is how a divergent snapshot of this schema came to be shipped
+ * elsewhere.
+ */
+public final class SchemaValidation {
+
+ private static final Map<SchemaVersion, Schema> CACHE
+ = new EnumMap<SchemaVersion, Schema>(SchemaVersion.class);
+
+ private SchemaValidation() {
+ }
+
+ /**
+ * Validates a document.
+ *
+ * @param xml The document.
+ * @param version The schema version to check it against.
+ * @return null if the document is valid, otherwise a description of the first problem.
+ */
+ public static synchronized String check(String xml, SchemaVersion version) {
+ Schema schema;
+ try {
+ schema = schemaFor(version);
+ } catch (SAXException ex) {
+ return "the " + version + " schema could not be loaded: " + ex.getMessage();
+ } catch (IOException ex) {
+ return "the " + version + " schema could not be read: " + ex.getMessage();
+ }
+ if (schema == null) {
+ return null; // no schema available; nothing to check against
+ }
+ final StringBuilder first = new StringBuilder();
+ try {
+ Validator validator = schema.newValidator();
+ validator.setErrorHandler(new ErrorHandler() {
+ @Override
+ public void warning(SAXParseException ex) {
+ // not a failure
+ }
+
+ @Override
+ public void error(SAXParseException ex) throws SAXException {
+ record(ex);
+ }
+
+ @Override
+ public void fatalError(SAXParseException ex) throws SAXException {
+ record(ex);
+ }
+
+ private void record(SAXParseException ex) throws SAXException {
+ if (first.length() == 0) {
+ first.append("line ").append(ex.getLineNumber())
+ .append(", column ").append(ex.getColumnNumber())
+ .append(": ").append(ex.getMessage());
+ }
+ throw ex;
+ }
+ });
+ validator.validate(new StreamSource(new StringReader(xml)));
+ } catch (SAXException ex) {
+ return first.length() > 0 ? first.toString() : ex.getMessage();
+ } catch (IOException ex) {
+ return "could not read the document: " + ex.getMessage();
+ }
+ return null;
+ }
+
+ private static Schema schemaFor(SchemaVersion version) throws SAXException, IOException {
+ Schema cached = CACHE.get(version);
+ if (cached != null) {
+ return cached;
+ }
+ // v001 documents may carry COM features; no v003 specification does, which is
+ // consistent with COMSchema importing the v001 service schema.
+ String[] resources = version == SchemaVersion.V001
+ ? new String[]{"/xsd/ServiceSchema.xsd", "/xsd/COMSchema.xsd"}
+ : new String[]{"/xsd/ServiceSchema-v003.xsd"};
+
+ Source[] sources = new Source[resources.length];
+ for (int i = 0; i < resources.length; i++) {
+ InputStream in = SchemaValidation.class.getResourceAsStream(resources[i]);
+ if (in == null) {
+ return null; // schemas not on the classpath in this build
+ }
+ StreamSource source = new StreamSource(in);
+ // A system id so that COMSchema's relative import of the service schema
+ // resolves against its sibling.
+ source.setSystemId(SchemaValidation.class.getResource(resources[i]).toExternalForm());
+ sources[i] = source;
+ }
+ SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+ Schema schema = factory.newSchema(sources);
+ CACHE.put(version, schema);
+ return schema;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/XmlExporter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/XmlExporter.java
new file mode 100644
index 00000000..c4fc4345
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/XmlExporter.java
@@ -0,0 +1,444 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.xml;
+
+import esa.mo.apigen.exporters.ExportException;
+import esa.mo.apigen.exporters.Exporter;
+import esa.mo.apigen.importers.xml.XmlNames;
+import esa.mo.apigen.model.*;
+import esa.mo.apigen.model.com.COMFeatures;
+import esa.mo.apigen.model.com.COMObject;
+import esa.mo.apigen.model.com.ObjectLink;
+import esa.mo.apigen.model.docs.Diagram;
+import esa.mo.apigen.model.docs.DocSection;
+import esa.mo.apigen.model.docs.Documentation;
+import esa.mo.apigen.model.types.*;
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.io.StringWriter;
+import java.io.Writer;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * Writes a specification back to the CCSDS service schema XML, in the version the
+ * specification declares.
+ * <p>
+ * Constructs the target version does not have are refused rather than dropped: writing a
+ * v003 model into a v001 file would silently lose its subscription keys, and a silent
+ * loss is worse than a failed export.
+ */
+public final class XmlExporter implements Exporter {
+
+ @Override
+ public void write(Specification spec, Path outputDir) throws IOException, ExportException {
+ Files.createDirectories(outputDir);
+ String name = spec.getSource() == null ? "specification.xml" : spec.getSource().getName();
+ Writer out = new OutputStreamWriter(
+ Files.newOutputStream(outputDir.resolve(name)), Charset.forName("UTF-8"));
+ try {
+ writeTo(spec, out);
+ } finally {
+ out.close();
+ }
+ }
+
+ /**
+ * Writes a specification to any writer. The directory form above is a wrapper over
+ * this, so that in-memory use and file use are the same code.
+ *
+ * @param spec The specification to write.
+ * @param out Where to write it.
+ * @throws IOException if writing fails.
+ * @throws ExportException if the model cannot be represented in its schema version.
+ */
+ public void writeTo(Specification spec, Writer out) throws IOException, ExportException {
+ SchemaVersion version = spec.getSchemaVersion();
+ if (version == null) {
+ throw new ExportException("The specification does not say which schema it uses");
+ }
+ StringWriter buffered = new StringWriter();
+ XmlWriter xml = new XmlWriter(buffered);
+ xml.start("mal:specification");
+ xml.attr("xmlns:mal", version.getNamespace());
+ xml.attr("xmlns:com", XmlNames.COM);
+ xml.attr("xmlns:svg", XmlNames.SVG);
+ xml.attr("xmlns:xsi", XmlNames.XSI);
+ xml.attr("comment", spec.getComment());
+ for (Area area : spec.getAreas()) {
+ writeArea(xml, version, area);
+ }
+ xml.end();
+ xml.flush();
+
+ // Validated before it is written, so a failed export cannot leave an invalid
+ // document behind (design section 6.1).
+ String document = buffered.toString();
+ String problem = SchemaValidation.check(document, version);
+ if (problem != null) {
+ throw new ExportException("The exported document does not satisfy the "
+ + version + " schema - " + problem);
+ }
+ out.write(document);
+ out.flush();
+ }
+
+ /**
+ * Returns the specification as a string.
+ *
+ * @param spec The specification to write.
+ * @return the XML document.
+ * @throws ExportException if the model cannot be represented in its schema version.
+ */
+ public String toXml(Specification spec) throws ExportException {
+ StringWriter out = new StringWriter();
+ try {
+ writeTo(spec, out);
+ } catch (IOException ex) {
+ throw new IllegalStateException("a StringWriter cannot fail", ex);
+ }
+ return out.toString();
+ }
+
+ // ----------------------------------------------------------------- area
+
+ private void writeArea(XmlWriter xml, SchemaVersion version, Area area)
+ throws IOException, ExportException {
+ xml.start("mal:area");
+ xml.attr("name", area.getName());
+ xml.attr("number", area.getNumber());
+ xml.attr("version", area.getVersion());
+ xml.attr("comment", area.getComment());
+ writeDocumentation(xml, area.getDocumentation());
+ for (Service service : area.getServices()) {
+ writeService(xml, version, service);
+ }
+ writeDataTypes(xml, version, area.getDataTypes(), true);
+ writeErrorDefinitions(xml, area.getErrors());
+ xml.end();
+ }
+
+ // -------------------------------------------------------------- service
+
+ private void writeService(XmlWriter xml, SchemaVersion version, Service service)
+ throws IOException, ExportException {
+ if (version == SchemaVersion.V003) {
+ if (!service.getDataTypes().isEmpty()) {
+ throw new ExportException("Service '" + service.getName() + "' declares data "
+ + "types, which the v003 schema does not have");
+ }
+ if (!service.getErrors().isEmpty()) {
+ throw new ExportException("Service '" + service.getName() + "' declares errors, "
+ + "which the v003 schema does not have");
+ }
+ }
+ xml.start("mal:service");
+ xml.attr("name", service.getName());
+ xml.attr("number", service.getNumber());
+ xml.attr("comment", service.getComment());
+ if (service.isExtended()) {
+ xml.attr("xsi:type", "com:ExtendedServiceType");
+ }
+ writeDocumentation(xml, service.getDocumentation());
+ for (CapabilitySet set : service.getCapabilitySets()) {
+ writeCapabilitySet(xml, version, set);
+ }
+ writeDataTypes(xml, version, service.getDataTypes(), false);
+ writeErrorDefinitions(xml, service.getErrors());
+ if (service.getCom() != null) {
+ writeCom(xml, service.getCom());
+ }
+ xml.end();
+ }
+
+ private void writeCapabilitySet(XmlWriter xml, SchemaVersion version, CapabilitySet set)
+ throws IOException, ExportException {
+ xml.start("mal:capabilitySet");
+ xml.attr("number", set.getNumber());
+ xml.attr("comment", set.getComment());
+ for (Operation op : set.getOperations()) {
+ writeOperation(xml, version, op);
+ }
+ xml.end();
+ }
+
+ // ------------------------------------------------------------ operation
+
+ private void writeOperation(XmlWriter xml, SchemaVersion version, Operation op)
+ throws IOException, ExportException {
+ if (op.getPattern() == null) {
+ throw new ExportException("Operation '" + op.getName() + "' has no interaction pattern");
+ }
+ if (version == SchemaVersion.V003 && op.isSupportInReplay()) {
+ throw new ExportException("Operation '" + op.getName() + "' sets supportInReplay, "
+ + "which the v003 schema does not have");
+ }
+ if (version == SchemaVersion.V001 && !op.getDocumentation().isEmpty()) {
+ throw new ExportException("Operation '" + op.getName() + "' carries documentation, "
+ + "which the v001 schema does not have");
+ }
+ String element = "mal:" + op.getPattern().name().toLowerCase() + "IP";
+ xml.start(element);
+ xml.attr("name", op.getName());
+ xml.attr("number", op.getNumber());
+ if (version == SchemaVersion.V001) {
+ xml.attr("supportInReplay", op.isSupportInReplay());
+ }
+ xml.attr("comment", op.getComment());
+ writeDocumentation(xml, op.getDocumentation());
+
+ xml.start("mal:messages");
+ for (InteractionStage stage : op.getPattern().getStages()) {
+ MessageBody body = op.getMessage(stage);
+ if (body == null) {
+ continue;
+ }
+ if (stage == InteractionStage.SUBSCRIPTION_KEYS && version == SchemaVersion.V001) {
+ throw new ExportException("Operation '" + op.getName() + "' declares subscription "
+ + "keys, which the v001 schema does not have");
+ }
+ xml.start("mal:" + stage.getXmlName());
+ xml.attr("comment", body.getComment());
+ for (Field field : body.getFields()) {
+ writeField(xml, field);
+ }
+ xml.end();
+ }
+ xml.end();
+
+ if (!op.getErrors().isEmpty()) {
+ xml.start("mal:errors");
+ for (ErrorReference ref : op.getErrors()) {
+ xml.start("mal:errorRef");
+ xml.attr("comment", ref.getComment());
+ writeTypeRef(xml, ref.getError());
+ writeExtraInformation(xml, ref.getExtraInformation());
+ xml.end();
+ }
+ xml.end();
+ }
+ xml.end();
+ }
+
+ private void writeField(XmlWriter xml, Field field) throws IOException {
+ xml.start("mal:field");
+ xml.attr("name", field.getName());
+ xml.attr("canBeNull", field.isCanBeNull());
+ xml.attr("comment", field.getComment());
+ writeTypeRef(xml, field.getType());
+ xml.end();
+ }
+
+ private void writeTypeRef(XmlWriter xml, TypeRef ref) throws IOException {
+ if (ref == null) {
+ return;
+ }
+ xml.start("mal:type");
+ xml.attr("area", ref.getArea());
+ if (ref.getService() != null) {
+ xml.attr("service", ref.getService());
+ }
+ xml.attr("name", ref.getName());
+ xml.attr("list", ref.isList());
+ if (ref.isObjectRef()) {
+ xml.attr("objectRef", true);
+ }
+ xml.end();
+ }
+
+ private void writeExtraInformation(XmlWriter xml, Field extra) throws IOException {
+ if (extra == null) {
+ return;
+ }
+ xml.start("mal:extraInformation");
+ xml.attr("comment", extra.getComment());
+ writeTypeRef(xml, extra.getType());
+ xml.end();
+ }
+
+ // ---------------------------------------------------------------- types
+
+ private void writeDataTypes(XmlWriter xml, SchemaVersion version,
+ List<TypeDefinition> types, boolean areaLevel) throws IOException, ExportException {
+ if (types.isEmpty()) {
+ return;
+ }
+ xml.start("mal:dataTypes");
+ for (TypeDefinition type : types) {
+ if (type instanceof FundamentalType) {
+ FundamentalType fundamental = (FundamentalType) type;
+ xml.start("mal:fundamental");
+ xml.attr("name", type.getName());
+ xml.attr("comment", type.getComment());
+ writeExtends(xml, fundamental.getSuperType());
+ xml.end();
+ } else if (type instanceof AttributeType) {
+ xml.start("mal:attribute");
+ xml.attr("name", type.getName());
+ xml.attr("shortFormPart", ((AttributeType) type).getShortFormPart());
+ xml.attr("comment", type.getComment());
+ xml.end();
+ } else if (type instanceof CompositeType) {
+ CompositeType composite = (CompositeType) type;
+ xml.start("mal:composite");
+ xml.attr("name", type.getName());
+ if (composite.getShortFormPart() != null) {
+ xml.attr("shortFormPart", composite.getShortFormPart().intValue());
+ }
+ xml.attr("comment", type.getComment());
+ writeExtends(xml, composite.getSuperType());
+ for (Field field : composite.getFields()) {
+ writeField(xml, field);
+ }
+ xml.end();
+ } else if (type instanceof EnumerationType) {
+ EnumerationType enumeration = (EnumerationType) type;
+ xml.start("mal:enumeration");
+ xml.attr("name", type.getName());
+ xml.attr("shortFormPart", enumeration.getShortFormPart());
+ xml.attr("comment", type.getComment());
+ for (EnumerationItem item : enumeration.getItems()) {
+ xml.start("mal:item");
+ xml.attr("value", item.getValue());
+ xml.attr("nvalue", item.getNumericValue());
+ xml.attr("comment", item.getComment());
+ xml.end();
+ }
+ xml.end();
+ }
+ }
+ xml.end();
+ }
+
+ private void writeExtends(XmlWriter xml, TypeRef superType) throws IOException {
+ if (superType == null) {
+ return;
+ }
+ xml.start("mal:extends");
+ writeTypeRef(xml, superType);
+ xml.end();
+ }
+
+ private void writeErrorDefinitions(XmlWriter xml, List<ErrorDefinition> errors)
+ throws IOException {
+ if (errors.isEmpty()) {
+ return;
+ }
+ xml.start("mal:errors");
+ for (ErrorDefinition error : errors) {
+ xml.start("mal:error");
+ xml.attr("name", error.getName());
+ xml.attr("number", error.getNumber());
+ xml.attr("comment", error.getComment());
+ writeExtraInformation(xml, error.getExtraInformation());
+ xml.end();
+ }
+ xml.end();
+ }
+
+ // ------------------------------------------------------------------ COM
+
+ private void writeCom(XmlWriter xml, COMFeatures com) throws IOException {
+ xml.start("com:features");
+ writeDocumentation(xml, com.getDocumentation());
+ if (!com.getObjects().isEmpty() || com.getObjectsComment() != null) {
+ xml.start("com:objects");
+ xml.attr("comment", com.getObjectsComment());
+ writeComObjects(xml, "object", com.getObjects());
+ xml.end();
+ }
+ if (!com.getEvents().isEmpty() || com.getEventsComment() != null) {
+ xml.start("com:events");
+ xml.attr("comment", com.getEventsComment());
+ writeComObjects(xml, "event", com.getEvents());
+ xml.end();
+ }
+ if (com.declaresArchiveUsage()) {
+ xml.start("com:archiveUsage");
+ xml.attr("comment", com.getArchiveUsage());
+ xml.end();
+ }
+ if (com.declaresActivityUsage()) {
+ xml.start("com:activityUsage");
+ xml.attr("comment", com.getActivityUsage());
+ xml.end();
+ }
+ xml.end();
+ }
+
+ private void writeComObjects(XmlWriter xml, String element, List<COMObject> objects)
+ throws IOException {
+ for (COMObject object : objects) {
+ xml.start("com:" + element);
+ xml.attr("name", object.getName());
+ xml.attr("number", object.getNumber());
+ xml.attr("comment", object.getComment());
+ if (object.getBodyType() != null) {
+ xml.start("com:objectType");
+ writeTypeRef(xml, object.getBodyType());
+ xml.end();
+ }
+ writeObjectLink(xml, "relatedObject", object.getRelated());
+ writeObjectLink(xml, "sourceObject", object.getSource());
+ xml.end();
+ }
+ }
+
+ private void writeObjectLink(XmlWriter xml, String element, ObjectLink link)
+ throws IOException {
+ if (link == null) {
+ return;
+ }
+ xml.start("com:" + element);
+ xml.attr("comment", link.getComment());
+ if (link.getTarget() != null) {
+ xml.start("com:objectType");
+ xml.attr("area", link.getTarget().getArea());
+ xml.attr("service", link.getTarget().getService());
+ xml.attr("number", link.getTarget().getNumber());
+ xml.end();
+ }
+ xml.end();
+ }
+
+ // -------------------------------------------------------- documentation
+
+ private void writeDocumentation(XmlWriter xml, Documentation docs) throws IOException {
+ if (docs == null) {
+ return;
+ }
+ for (DocSection section : docs.getSections()) {
+ xml.start("mal:documentation");
+ xml.attr("name", section.getName());
+ xml.attr("order", section.getOrder());
+ xml.text(section.getContent());
+ xml.end();
+ }
+ for (Diagram diagram : docs.getDiagrams()) {
+ xml.start("mal:diagram");
+ xml.attr("name", diagram.getName());
+ xml.raw(diagram.getSvg());
+ xml.end();
+ }
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/XmlWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/XmlWriter.java
new file mode 100644
index 00000000..7408742a
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/exporters/xml/XmlWriter.java
@@ -0,0 +1,150 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.exporters.xml;
+
+import java.io.IOException;
+import java.io.Writer;
+import java.util.ArrayDeque;
+import java.util.Deque;
+
+/**
+ * A small indenting XML writer.
+ * <p>
+ * Hand-written rather than StAX because the output has to be laid out predictably: the
+ * round-trip test compares documents, and a writer that decides its own line breaks makes
+ * every comparison a negotiation.
+ */
+public final class XmlWriter {
+
+ private final Writer out;
+ private final Deque<String> open = new ArrayDeque<String>();
+ private boolean elementOpen;
+ private boolean hasChildren;
+
+ public XmlWriter(Writer out) throws IOException {
+ this.out = out;
+ out.write("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n");
+ }
+
+ public void start(String name) throws IOException {
+ closeStartTag(true);
+ indent(open.size());
+ out.write("<" + name);
+ open.push(name);
+ elementOpen = true;
+ hasChildren = false;
+ }
+
+ public void attr(String name, String value) throws IOException {
+ if (value != null) {
+ out.write(" " + name + "=\"" + escapeAttr(value) + "\"");
+ }
+ }
+
+ public void attr(String name, int value) throws IOException {
+ out.write(" " + name + "=\"" + value + "\"");
+ }
+
+ public void attr(String name, long value) throws IOException {
+ out.write(" " + name + "=\"" + value + "\"");
+ }
+
+ public void attr(String name, boolean value) throws IOException {
+ out.write(" " + name + "=\"" + value + "\"");
+ }
+
+ /**
+ * Writes the element's text content. Must be called before any child element.
+ *
+ * @param text The content, written escaped.
+ * @throws IOException if writing fails.
+ */
+ public void text(String text) throws IOException {
+ if (text == null) {
+ return;
+ }
+ closeStartTag(false);
+ out.write(escapeText(text));
+ hasChildren = true;
+ }
+
+ /**
+ * Writes pre-serialised markup as-is - used for diagrams, whose SVG the model carries
+ * as text.
+ *
+ * @param markup The markup to write verbatim.
+ * @throws IOException if writing fails.
+ */
+ public void raw(String markup) throws IOException {
+ if (markup == null) {
+ return;
+ }
+ closeStartTag(false);
+ out.write(markup);
+ hasChildren = true;
+ }
+
+ public void end() throws IOException {
+ String name = open.pop();
+ if (elementOpen) {
+ out.write("/>\n");
+ elementOpen = false;
+ } else {
+ if (!hasChildren) {
+ indent(open.size());
+ }
+ out.write("</" + name + ">\n");
+ }
+ hasChildren = false;
+ }
+
+ private void closeStartTag(boolean newline) throws IOException {
+ if (elementOpen) {
+ out.write(">");
+ if (newline) {
+ out.write("\n");
+ }
+ elementOpen = false;
+ }
+ }
+
+ private void indent(int depth) throws IOException {
+ for (int i = 0; i < depth; i++) {
+ out.write(" ");
+ }
+ }
+
+ public void flush() throws IOException {
+ out.flush();
+ }
+
+ private static String escapeText(String text) {
+ return text.replace("&", "&").replace("<", "<").replace(">", ">");
+ }
+
+ private static String escapeAttr(String text) {
+ return escapeText(text)
+ .replace("\"", """)
+ .replace("\n", "
")
+ .replace("\r", "
")
+ .replace("\t", " ");
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/Generator.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/Generator.java
new file mode 100644
index 00000000..0bc0bd75
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/Generator.java
@@ -0,0 +1,59 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.MOModel;
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * Turns a model into output of some kind.
+ * <p>
+ * The caller says which areas to generate: the model itself holds every specification
+ * loaded, including those present only so that references resolve, and which of them are
+ * wanted is a property of the build rather than of the model.
+ * <p>
+ * There is no configuration phase. A generator is constructed and then called.
+ */
+public interface Generator {
+
+ /**
+ * @return the short name used to select this generator, for example "Java".
+ */
+ String getShortName();
+
+ /**
+ * @return a one-line description.
+ */
+ String getDescription();
+
+ /**
+ * Generates output for the given areas.
+ *
+ * @param model Every loaded specification, linked and validated.
+ * @param targets The areas to generate. Others are available for reference only.
+ * @param outputDir The directory to write into.
+ * @throws IOException if writing fails.
+ */
+ void generate(MOModel model, List<Area> targets, Path outputDir) throws IOException;
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxBody.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxBody.java
new file mode 100644
index 00000000..1cf60c1b
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxBody.java
@@ -0,0 +1,320 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+/**
+ * The body of a Word document, built up as it is written.
+ * <p>
+ * Everything a document is made of goes through here - titles, paragraphs, tables,
+ * captions - and comes out as the WordprocessingML that says it. Nothing in this class
+ * knows anything about MO: it is told what to write, not what it means.
+ */
+public final class DocxBody {
+
+ /**
+ * The numbering of the document this body belongs to, so that a numbered list can ask
+ * for one of its own. Null for a body that is built up on the side and appended later,
+ * which is how the data type sections are assembled.
+ */
+ private final DocxNumbering numbering;
+
+ /**
+ * A caption is the same construction whether it names a table or a figure: the word,
+ * the chapter number, a sequence number, and an entry for the table of contents. Only
+ * the word and the two sequence names differ, so the block is written once.
+ */
+ private static final String CAPTION
+ = "<w:pPr><w:pStyle w:val=\"TableTitle\"/></w:pPr><w:r>"
+ + "<w:t xml:space=\"preserve\">${kind} </w:t></w:r>";
+
+ private final StringBuilder buffer = new StringBuilder();
+
+ /**
+ * @param numbering The numbering of the document, which numbered lists draw from.
+ */
+ public DocxBody(DocxNumbering numbering) {
+ this.numbering = numbering;
+ }
+
+ /**
+ * A body that cannot number a list, for text assembled on the side.
+ */
+ public DocxBody() {
+ this(null);
+ }
+
+ /**
+ * Writes a heading.
+ *
+ * @param level How deep the heading is, 1 being a chapter.
+ * @param name What the heading says.
+ */
+ public void title(int level, String name) {
+ title(level, "", name, null);
+ }
+
+ /**
+ * Writes a heading that can be linked to from elsewhere in the document.
+ *
+ * @param level How deep the heading is, 1 being a chapter.
+ * @param section The number in front of the name, empty for none.
+ * @param name What the heading says.
+ * @param bookmark What to call the anchor, or null not to place one.
+ */
+ public void title(int level, String section, String name, String bookmark) {
+ append(2, "<w:p><w:pPr><w:pStyle w:val=\"Heading" + level + "\"/></w:pPr>");
+ if (bookmark != null) {
+ append(3, "<w:bookmarkStart w:id=\"1\" w:name=\"" + bookmark + "_" + name
+ + "\"/><w:bookmarkEnd w:id=\"1\"/>");
+ }
+ append(3, "<w:r><w:t>" + section + name + "</w:t></w:r>");
+ append(2, "</w:p>");
+ }
+
+ /**
+ * Writes a comment out of a specification as running text.
+ * <p>
+ * The comments carry a little markup of their own: a line inside {@code _li_} becomes a
+ * bullet, and the {@code _ul_} around a group of them says nothing a Word document
+ * needs, so it is dropped.
+ *
+ * @param text The comment, may be null.
+ */
+ public void comment(String text) {
+ for (String line : DocxText.split(text)) {
+ if ("<ul>".equals(line) || "</ul>".equals(line)) {
+ continue;
+ }
+ if (line.contains("<li>")) {
+ String item = line.substring(line.indexOf("<li>") + 4, line.indexOf("</li>"));
+ append(2, "<w:p><w:pPr><w:pStyle w:val=\"ListParagraph\"/><w:numPr>"
+ + "<w:ilvl w:val=\"0\"/><w:numId w:val=\"1\"/></w:numPr></w:pPr><w:r><w:t>"
+ + DocxText.escape(item) + "</w:t></w:r></w:p>");
+ } else {
+ append(2, "<w:p><w:pPr><w:keepNext/></w:pPr><w:r><w:t>"
+ + DocxText.escape(line) + "</w:t></w:r></w:p>");
+ }
+ }
+ }
+
+ /**
+ * Writes a numbered list, which gets a numbering of its own so that it starts from the
+ * top rather than carrying on from the last list.
+ *
+ * @param lines The items. An {@code _ol_} among them opens a nested list and the
+ * matching close ends it.
+ * @throws java.io.IOException if the numbering template is missing from the build.
+ */
+ public void numberedComment(java.util.List<String> lines) throws java.io.IOException {
+ if (lines == null || lines.isEmpty()) {
+ return;
+ }
+ int instance = numbering == null ? 0 : numbering.nextInstance();
+ numbered(instance, 0, lines.iterator());
+ }
+
+ /**
+ * Writes the items of a list, descending into a nested one where it starts.
+ */
+ private void numbered(int instance, int level, java.util.Iterator<String> lines) {
+ while (lines.hasNext()) {
+ String line = lines.next();
+ if (line == null || line.trim().isEmpty()) {
+ continue;
+ }
+ if ("<ol>".equalsIgnoreCase(line)) {
+ numbered(instance, level + 1, lines);
+ } else if ("</ol>".equalsIgnoreCase(line)) {
+ return;
+ } else {
+ numberedItem(instance, level, line);
+ }
+ }
+ }
+
+ /**
+ * Writes one item, which may itself be several lines, and which is written as a note
+ * instead where it announces itself as one.
+ */
+ private void numberedItem(int instance, int level, String text) {
+ java.util.List<String> parts = DocxText.split(text);
+ if (parts.size() > 1) {
+ for (String part : parts) {
+ numberedItem(instance, level, part);
+ }
+ return;
+ }
+ if (text.toLowerCase().contains("note:")) {
+ note(text);
+ return;
+ }
+ for (String part : parts) {
+ if (!part.isEmpty()) {
+ append(2, "<w:p><w:pPr><w:numPr><w:ilvl w:val=\"" + level + "\"/><w:numId w:val=\""
+ + instance + "\"/></w:numPr></w:pPr><w:r><w:t>" + DocxText.escape(part)
+ + "</w:t></w:r></w:p>");
+ }
+ }
+ }
+
+ /**
+ * Writes a note, which the documents set apart from the text around it.
+ *
+ * @param text The note, with or without the word that announces it.
+ */
+ public void note(String text) {
+ String body = text.replace("Note: ", "").replace("NOTE: ", "");
+ append(2, "<w:p w14:paraId=\"7F00DCB7\" w14:textId=\"77777777\" w:rsidR=\"00B06274\""
+ + " w:rsidRPr=\"00B06274\" w:rsidRDefault=\"00B06274\" w:rsidP=\"00B06274\">");
+ append(3, "<w:pPr><w:keepLines/><w:tabs><w:tab w:val=\"left\" w:pos=\"806\"/></w:tabs>"
+ + "<w:spacing w:before=\"240\" w:after=\"0\" w:line=\"280\" w:lineRule=\"atLeast\"/>"
+ + "<w:ind w:left=\"1138\" w:hanging=\"1138\"/><w:jc w:val=\"both\"/><w:rPr>"
+ + "<w:kern w:val=\"0\"/><w:sz w:val=\"24\"/><w:szCs w:val=\"20\"/>"
+ + "<w14:ligatures w14:val=\"none\"/></w:rPr></w:pPr>");
+ append(3, "<w:r w:rsidRPr=\"00B06274\"><w:t>NOTE</w:t></w:r>");
+ append(3, "<w:r w:rsidRPr=\"00B06274\"><w:tab/><w:t>\u2013</w:t></w:r>");
+ append(3, "<w:r w:rsidRPr=\"00B06274\"><w:tab/><w:t>" + body + "</w:t></w:r>");
+ append(2, "</w:p>");
+ }
+
+ /**
+ * Writes the one field a message carries, named and described.
+ *
+ * @param fieldName The name of the field.
+ * @param fieldComment What the field holds.
+ */
+ public void singleTypeSignature(String fieldName, String fieldComment) {
+ append(2, "<w:p><w:pPr><w:numPr><w:ilvl w:val=\"0\"/><w:numId w:val=\"1\"/></w:numPr>"
+ + "</w:pPr><w:r><w:rPr><w:b/><w:bCs/></w:rPr><w:t>" + DocxText.escape(fieldName)
+ + "</w:t></w:r><w:r><w:t xml:space=\"preserve\"> - "
+ + DocxText.escape(fieldComment) + "</w:t></w:r></w:p>");
+ }
+
+ /**
+ * Starts a table.
+ *
+ * @param widths The width of each column, in twentieths of a point.
+ * @return the table, to add rows to.
+ */
+ public DocxTable table(int[] widths) {
+ return new DocxTable(this, widths);
+ }
+
+ /**
+ * Starts a table under a caption that names it.
+ *
+ * @param widths The width of each column, in twentieths of a point.
+ * @param caption What the table is called.
+ * @return the table, to add rows to.
+ */
+ public DocxTable table(int[] widths, String caption) {
+ if (caption != null) {
+ caption("Table", caption);
+ }
+ return new DocxTable(this, widths);
+ }
+
+ /**
+ * Writes the caption of a figure, which follows the figure rather than preceding it.
+ *
+ * @param caption What the figure is called.
+ */
+ public void figureCaption(String caption) {
+ if (caption != null) {
+ caption("Figure", caption);
+ }
+ }
+
+ /**
+ * Writes a caption: the word, the chapter it is in, its number within the chapter, and
+ * the field that puts it in the table of contents.
+ *
+ * @param kind "Table" or "Figure", which is both the word shown and the sequence the
+ * number comes from.
+ * @param caption What is being named.
+ */
+ private void caption(String kind, String caption) {
+ String bookmark = "Table".equals(kind) ? "T_" : "F_";
+ append(2, "<w:p>");
+ append(3, CAPTION.replace("${kind}", kind));
+ append(3, "<w:bookmarkStart w:id=\"0\" w:name=\"" + bookmark + caption + "\"/>");
+ append(3, "<w:r><w:fldChar w:fldCharType=\"begin\"/></w:r><w:r><w:instrText"
+ + " xml:space=\"preserve\"> STYLEREF \"Heading 1\"\\l \\n \\t \\* MERGEFORMAT"
+ + " </w:instrText></w:r><w:r><w:fldChar w:fldCharType=\"separate\"/></w:r><w:r>"
+ + "<w:t>1</w:t></w:r><w:r><w:fldChar w:fldCharType=\"end\"/></w:r><w:r>"
+ + "<w:noBreakHyphen/></w:r><w:r><w:fldChar w:fldCharType=\"begin\"/></w:r><w:r>"
+ + "<w:instrText xml:space=\"preserve\"> SEQ " + kind + " \\s 1 </w:instrText>"
+ + "</w:r><w:r><w:fldChar w:fldCharType=\"separate\"/></w:r><w:r><w:t>1</w:t>"
+ + "</w:r><w:r><w:fldChar w:fldCharType=\"end\"/></w:r><w:bookmarkEnd w:id=\"0\"/>"
+ + "<w:r><w:fldChar w:fldCharType=\"begin\"/></w:r><w:r><w:instrText>tc \\f T \""
+ + "</w:instrText></w:r><w:fldSimple w:instr=\" STYLEREF "Heading 1""
+ + "\\l \\n \\t \\* MERGEFORMAT \">");
+ append(3, "<w:bookmarkStart w:id=\"1\" w:name=\"_" + caption + "\"/><w:r><w:instrText>1"
+ + "</w:instrText></w:r></w:fldSimple>");
+ append(3, "<w:r><w:instrText>-</w:instrText></w:r><w:r><w:fldChar"
+ + " w:fldCharType=\"begin\"/></w:r><w:r><w:instrText xml:space=\"preserve\"> SEQ "
+ + kind + "_TOC \\s 1 </w:instrText></w:r><w:r><w:fldChar"
+ + " w:fldCharType=\"separate\"/></w:r><w:r><w:instrText>1</w:instrText></w:r><w:r>"
+ + "<w:fldChar w:fldCharType=\"end\"/></w:r>");
+ append(3, "<w:r><w:instrText>" + caption + "</w:instrText></w:r>");
+ append(3, "<w:bookmarkEnd w:id=\"1\"/><w:r><w:instrText>\"</w:instrText></w:r><w:r>"
+ + "<w:fldChar w:fldCharType=\"end\"/></w:r>");
+ append(3, "<w:r><w:t>: " + caption + "</w:t></w:r>");
+ append(2, "</w:p>");
+ }
+
+ /**
+ * Starts the next page.
+ */
+ public void pageBreak() {
+ buffer.append("<w:p><w:r><w:br w:type=\"page\"/></w:r></w:p>");
+ }
+
+ /**
+ * Ends a section without starting a new page, which is what separates one data type
+ * from the next.
+ */
+ public void sectionBreak() {
+ buffer.append("<w:p><w:pPr><w:sectPr><w:type w:val=\"continuous\"/></w:sectPr></w:pPr></w:p>");
+ }
+
+ /**
+ * @return everything written so far.
+ */
+ public String toXml() {
+ return buffer.toString();
+ }
+
+ /**
+ * Appends a body built up on the side, as it stands. The data types are gathered while
+ * the services are walked and land at the end of the document.
+ *
+ * @param other The body to append.
+ */
+ public void append(DocxBody other) {
+ buffer.append(other.buffer);
+ }
+
+ public void append(int indent, String text) {
+ buffer.append(DocxText.line(indent, text, DocxText.BODY_SEPARATOR));
+ }
+
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxCell.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxCell.java
new file mode 100644
index 00000000..4d9b4a61
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxCell.java
@@ -0,0 +1,166 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+/**
+ * One cell of a table, described before it is written.
+ * <p>
+ * The generator this replaces reached a cell through nine overloads of one method, taking
+ * a column index, the widths of every column, and four flags in a fixed order. Here a cell
+ * says what it is: the row knows which column it is in and how wide that is, and anything
+ * unusual about the cell is named at the point it is asked for.
+ */
+public final class DocxCell {
+
+ /**
+ * How a cell takes part in a run of cells merged down the page.
+ */
+ enum Merge {
+ /**
+ * Not merged with anything.
+ */
+ NONE,
+ /**
+ * The top of a merged run, which is where the content goes.
+ */
+ START,
+ /**
+ * Continues the run above it, and so is written empty.
+ */
+ CONTINUE
+ }
+
+ private final DocxRow row;
+
+ private final String content;
+
+ private String shade = null;
+
+ private boolean centered = false;
+
+ private int span = 1;
+
+ private Merge merge = Merge.NONE;
+
+ DocxCell(DocxRow row, String content) {
+ this.row = row;
+ this.content = content;
+ }
+
+ /**
+ * Fills the cell with a background colour.
+ *
+ * @param colour The colour, as six hexadecimal digits.
+ * @return this cell.
+ */
+ public DocxCell shaded(String colour) {
+ this.shade = colour;
+ return this;
+ }
+
+ /**
+ * @return this cell, with its content centred.
+ */
+ public DocxCell centered() {
+ this.centered = true;
+ return this;
+ }
+
+ /**
+ * Widens the cell over the columns that follow it.
+ *
+ * @param columns How many columns the cell covers, including its own.
+ * @return this cell.
+ */
+ public DocxCell spanning(int columns) {
+ this.span = columns;
+ return this;
+ }
+
+ /**
+ * @return this cell, as the top of a run merged down the page.
+ */
+ public DocxCell mergeStart() {
+ this.merge = Merge.START;
+ return this;
+ }
+
+ /**
+ * @return this cell, continuing the merged run above it.
+ */
+ public DocxCell mergeContinue() {
+ this.merge = Merge.CONTINUE;
+ return this;
+ }
+
+ /**
+ * Finishes the cell and returns to the row, so that cells read one after another.
+ *
+ * @return the row this cell belongs to.
+ */
+ public DocxRow next() {
+ row.write(this);
+ return row;
+ }
+
+ /**
+ * Finishes the cell and the row.
+ */
+ public void endRow() {
+ row.write(this);
+ row.end();
+ }
+
+ String toXml(int width) {
+ StringBuilder buf = new StringBuilder("<w:tc><w:tcPr>");
+ buf.append("<w:tcW w:w=\"").append(width).append("\" w:type=\"dxa\"/>");
+
+ if (merge == Merge.START) {
+ buf.append("<w:vMerge w:val=\"restart\"/><w:vAlign w:val=\"center\"/>");
+ } else if (merge == Merge.CONTINUE) {
+ buf.append("<w:vMerge/>");
+ }
+ if (span > 1) {
+ buf.append("<w:gridSpan w:val=\"").append(span).append("\"/>");
+ }
+ if (shade != null) {
+ buf.append("<w:shd w:val=\"clear\" w:color=\"auto\" w:fill=\"").append(shade).append("\"/>");
+ }
+ buf.append("</w:tcPr>");
+
+ // A cell that only continues the run above it holds nothing: the content sits in
+ // the cell that started the run.
+ if (merge == Merge.CONTINUE) {
+ buf.append("<w:p/>");
+ } else {
+ buf.append("<w:p>");
+ if (centered) {
+ buf.append("<w:pPr><w:jc w:val=\"center\"/></w:pPr>");
+ }
+ buf.append(content).append("</w:p>");
+ }
+ return buf.append("</w:tc>").toString();
+ }
+
+ int getSpan() {
+ return span;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxDocument.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxDocument.java
new file mode 100644
index 00000000..0dcaae8b
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxDocument.java
@@ -0,0 +1,131 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.OutputStreamWriter;
+import java.io.Writer;
+import java.nio.charset.Charset;
+
+/**
+ * One Word document: its body, its numbering, and the parts that go around them.
+ * <p>
+ * A .docx is a zip of XML parts. Everything fixed comes out of the module's resources; what
+ * is left is the body, the numbering, and the relationships. This writes the parts into a
+ * directory, which is what the comparison against the reference output reads and what a zip
+ * is made from.
+ */
+public final class DocxDocument {
+
+ private static final Charset UTF8 = Charset.forName("UTF-8");
+
+ /**
+ * How wide a diagram is drawn, in English Metric Units: the width of the text on the
+ * page. The height follows from the proportions of the diagram.
+ */
+ private static final int WIDTH_EMU = 5722620;
+
+ private static final String HEADER
+ = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
+ + DocxText.BODY_SEPARATOR
+ + "<w:document xmlns:wpc=\"http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas\""
+ + " xmlns:mc=\"http://schemas.openxmlformats.org/markup-compatibility/2006\""
+ + " xmlns:o=\"urn:schemas-microsoft-com:office:office\""
+ + " xmlns:r=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships\""
+ + " xmlns:m=\"http://schemas.openxmlformats.org/officeDocument/2006/math\""
+ + " xmlns:v=\"urn:schemas-microsoft-com:vml\""
+ + " xmlns:wp14=\"http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing\""
+ + " xmlns:wp=\"http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing\""
+ + " xmlns:w10=\"urn:schemas-microsoft-com:office:word\""
+ + " xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\""
+ + " xmlns:w14=\"http://schemas.microsoft.com/office/word/2010/wordml\""
+ + " xmlns:wpg=\"http://schemas.microsoft.com/office/word/2010/wordprocessingGroup\""
+ + " xmlns:wpi=\"http://schemas.microsoft.com/office/word/2010/wordprocessingInk\""
+ + " xmlns:wne=\"http://schemas.microsoft.com/office/word/2006/wordml\""
+ + " xmlns:wps=\"http://schemas.microsoft.com/office/word/2010/wordprocessingShape\""
+ + " mc:Ignorable=\"w14 wp14\">" + DocxText.BODY_SEPARATOR;
+
+ private static final String RELATIONSHIPS
+ = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
+ + "<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">"
+ + "<Relationship Id=\"rId2\" Type=\"http://schemas.openxmlformats.org/officeDocument/"
+ + "2006/relationships/styles\" Target=\"styles.xml\"/>"
+ + "<Relationship Id=\"rId1\" Type=\"http://schemas.openxmlformats.org/officeDocument/"
+ + "2006/relationships/numbering\" Target=\"numbering.xml\"/>";
+
+ private final File folder;
+
+ private final DocxNumbering numbering;
+
+ private final DocxBody body;
+
+ /**
+ * @param folder The directory the parts are written into.
+ * @throws IOException if the fixed parts are missing from the build.
+ */
+ public DocxDocument(File folder) throws IOException {
+ this.folder = folder;
+ this.numbering = new DocxNumbering();
+ this.body = new DocxBody(numbering);
+ }
+
+ /**
+ * @return the body of the document, to write into.
+ */
+ public DocxBody getBody() {
+ return body;
+ }
+
+ /**
+ * Writes every part of the document.
+ *
+ * @throws IOException if a part cannot be written.
+ */
+ public void write() throws IOException {
+ write(new File(folder, "[Content_Types].xml"),
+ DocxResources.read(DocxResources.CONTENT_TYPES));
+ write(new File(folder, "_rels/.rels"),
+ DocxResources.read(DocxResources.PACKAGE_RELS));
+ write(new File(folder, "word/styles.xml"), DocxResources.read(DocxResources.STYLES));
+ write(new File(folder, "word/numbering.xml"), numbering.toXml());
+ write(new File(folder, "word/document.xml"), HEADER
+ + DocxText.line(1, "<w:body>", DocxText.BODY_SEPARATOR)
+ + body.toXml()
+ + DocxText.line(1, "</w:body>", DocxText.BODY_SEPARATOR)
+ + DocxText.line(0, "</w:document>", DocxText.BODY_SEPARATOR));
+
+ write(new File(folder, "word/_rels/document.xml.rels"),
+ RELATIONSHIPS + "</Relationships>");
+ }
+
+ private static void write(File file, String content) throws IOException {
+ file.getParentFile().mkdirs();
+ Writer out = new OutputStreamWriter(new FileOutputStream(file), UTF8);
+ try {
+ out.write(content);
+ } finally {
+ out.close();
+ }
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxGenerator.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxGenerator.java
new file mode 100644
index 00000000..74f827ee
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxGenerator.java
@@ -0,0 +1,911 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+import esa.mo.apigen.generators.Generator;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.CapabilitySet;
+import esa.mo.apigen.model.ErrorDefinition;
+import esa.mo.apigen.model.ErrorReference;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.com.COMFeatures;
+import esa.mo.apigen.model.com.COMObject;
+import esa.mo.apigen.model.com.ObjectLink;
+import esa.mo.apigen.model.com.ObjectReference;
+import esa.mo.apigen.model.docs.DocSection;
+import esa.mo.apigen.model.types.AttributeType;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationItem;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.FundamentalType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the Word document that describes a specification.
+ * <p>
+ * One document per area: what the area is, then a chapter per service and a section per
+ * operation, then the data types and the errors. The data types are built up in a second
+ * body as the services are walked and appended at the end, which is why the document is
+ * assembled rather than written straight through.
+ */
+public final class DocxGenerator implements Generator {
+
+ /**
+ * The blue every table header is filled with.
+ */
+ static final String HEADER_COLOUR = "00CCFF";
+
+ /**
+ * The grey a fixed part of a message is filled with, as against a field the
+ * specification chose.
+ */
+ static final String FIXED_COLOUR = "E0E0E0";
+
+ private static final int[] SERVICE_OVERVIEW_WIDTHS = {2250, 2801, 1382, 1185, 1382};
+
+ private static final int[] ERROR_TABLE_WIDTHS = {2302, 1430, 5268};
+
+ private static final int[] OPERATION_OVERVIEW_WIDTHS = {2200, 1700, 800, 4300};
+
+ private static final int[] OPERATION_ERROR_WIDTHS = {1500, 1000, 2500, 4000};
+
+ /**
+ * What is shown where an error carries no extra information.
+ */
+ private static final String NOT_USED = "Not Used";
+
+ private static final int[] LIST_WIDTHS = {2302, 6698};
+
+ private static final int[] ENUM_WIDTHS = {2302, 2430, 4268};
+
+ private static final int[] COMPOSITE_WIDTHS = {2302, 1830, 1100, 3768};
+
+ private static final int[] COM_TYPES_WIDTHS = {1010, 2250, 2500, 1150, 2196};
+
+ @Override
+ public String getShortName() {
+ return "docx";
+ }
+
+ @Override
+ public String getDescription() {
+ return "Generates the Word document of a set of MO service specifications";
+ }
+
+ @Override
+ public void generate(MOModel model, List<Area> targets, Path outputDir) throws IOException {
+ for (Area area : targets) {
+ generateArea(model, area, outputDir);
+ }
+ }
+
+ /**
+ * @return the name of the document of an area, which says what it documents.
+ */
+ public static String documentNameOf(Area area) {
+ return String.format("Service_Specification_area%03d-v%03d-%s",
+ area.getNumber(), area.getVersion(), area.getName());
+ }
+
+ private void generateArea(MOModel model, Area area, Path outputDir) throws IOException {
+ File folder = new File(outputDir.toFile(), documentNameOf(area));
+ DocxDocument document = new DocxDocument(folder);
+ DocxBody body = document.getBody();
+ // The data types are described after everything else, but which of them matter is
+ // only known once the services have been walked, so they are gathered as we go.
+ DocxBody types = new DocxBody();
+
+ body.title(1, "Specification: " + area.getName());
+ body.title(2, "General");
+ body.comment("This section contains the specifications for the "
+ + area.getName() + " services.");
+ body.comment(area.getComment());
+ body.comment("This area contains the following services:");
+
+ List<String> names = new ArrayList<String>();
+ for (Service service : area.getServices()) {
+ names.add(service.getName());
+ }
+ body.numberedComment(names);
+
+ for (DocSection section : area.getDocumentation().getSections()) {
+ body.title(2, section.getName());
+ body.numberedComment(DocxText.split(section.getContent()));
+ }
+
+ for (Service service : area.getServices()) {
+ writeService(body, document, model, area, service);
+ }
+
+ writeDataTypes(types, model, area);
+ writeErrors(types, area);
+
+ body.append(types);
+ document.write();
+ }
+
+ /**
+ * A chapter per service: what it is, what it must do, and a section per operation.
+ */
+ private void writeService(DocxBody body, DocxDocument document, MOModel model, Area area,
+ Service service) throws IOException {
+ body.pageBreak();
+ body.title(2, "Service: ", service.getName(), "SERVICE");
+ body.title(3, "Overview");
+ body.comment(service.getComment());
+ writeServiceTable(body, area, service);
+ body.title(3, "Service-level Requirements");
+ writeRequirements(body, service.getDocumentation().getSections());
+ writeComUsage(body, document, area, service);
+
+ for (CapabilitySet set : service.getCapabilitySets()) {
+ for (Operation operation : set.getOperations()) {
+ body.pageBreak();
+ // The bookmark is named after the service number rather than its name: a
+ // long bookmark name is cut short and the link stops working.
+ body.title(3, "Operation: ", operation.getName(),
+ "OPERATION_" + service.getNumber());
+ body.title(4, "Overview");
+ body.comment(operation.getComment());
+ writeOperationTable(body, area, service, operation);
+ writeSignatureDetails(body, operation);
+ body.title(4, "Requirements");
+ writeRequirements(body, operation.getDocumentation().getSections());
+ writeOperationErrors(body, model, area, service, operation);
+ }
+ }
+ }
+
+ /**
+ * What the service is numbered, and every operation it offers.
+ */
+ private void writeServiceTable(DocxBody body, Area area, Service service) {
+ DocxTable table = body.table(SERVICE_OVERVIEW_WIDTHS,
+ service.getName() + " Service Operations");
+ table.row()
+ .cell("Area Identifier").shaded(HEADER_COLOUR).centered().next()
+ .cell("Service Identifier").shaded(HEADER_COLOUR).centered().next()
+ .cell("Area Number").shaded(HEADER_COLOUR).centered().next()
+ .cell("Service Number").shaded(HEADER_COLOUR).centered().next()
+ .cell("Area Version").shaded(HEADER_COLOUR).centered().endRow();
+ table.row()
+ .cell(area.getName()).centered().next()
+ .cell(service.getName()).centered().next()
+ .cell(String.valueOf(area.getNumber())).centered().next()
+ .cell(String.valueOf(service.getNumber())).centered().next()
+ .cell(String.valueOf(area.getVersion())).centered().endRow();
+ table.row()
+ .cell("Interaction Pattern").shaded(HEADER_COLOUR).centered().next()
+ .cell("Operation Identifier").shaded(HEADER_COLOUR).centered().spanning(2).next()
+ .cell("Operation Number").shaded(HEADER_COLOUR).centered().next()
+ .cell("Capability Set").shaded(HEADER_COLOUR).centered().endRow();
+
+ for (CapabilitySet set : service.getCapabilitySets()) {
+ // The capability set number is written once for the run of operations that
+ // belong to it, so the cell of the first operation is merged over the rest.
+ boolean first = true;
+ for (Operation operation : set.getOperations()) {
+ String linkTo = "OPERATION_" + service.getNumber() + "_" + operation.getName();
+ DocxRow row = table.row();
+ row.cell(shortPatternNameOf(operation)).centered().next()
+ .markedUp(DocxTypeLink.hyperlink("", operation.getName(), "", linkTo, true))
+ .centered().spanning(2).next()
+ .cell(String.valueOf(operation.getNumber())).centered().next();
+ DocxCell capability = row.cell(String.valueOf(set.getNumber())).centered();
+ if (first) {
+ capability.mergeStart();
+ } else {
+ capability.mergeContinue();
+ }
+ capability.endRow();
+ first = false;
+ }
+ }
+ table.end();
+ }
+
+ /**
+ * What the service adds to the COM: the objects it stores, the events it raises, and
+ * how it uses the archive and the activity tracking.
+ */
+ private void writeComUsage(DocxBody body, DocxDocument document, Area area, Service service)
+ throws IOException {
+ COMFeatures com = service.getCom();
+ if (com == null) {
+ return;
+ }
+
+ // An objects section counts as saying something only when it lists something; an
+ // events section counts as soon as it is written at all. The difference is in the
+ // existing generator and decides which relationships the figure is said to show.
+ boolean hasObjects = !com.getObjects().isEmpty();
+ boolean hasEvents = com.declaresEvents();
+
+ if (com.declaresObjects()) {
+ body.title(3, "COM usage");
+ body.numberedComment(DocxText.split(com.getObjectsComment()));
+ if (hasObjects) {
+ writeComObjects(body, area, service, com.getObjects(),
+ service.getName() + " Service Object Types", "Object Name");
+ }
+ }
+ if (hasEvents) {
+ body.title(3, "COM Event Service usage");
+ body.numberedComment(DocxText.split(com.getEventsComment()));
+ writeComObjects(body, area, service, com.getEvents(),
+ service.getName() + " Service Events", "Event Name");
+ }
+
+ if (hasObjects || hasEvents) {
+ String what = "COM" + (hasObjects ? " object" : "")
+ + (hasEvents ? (hasObjects ? " and event" : " event") : "") + " relationships";
+ body.title(3, "COM Object Relationships");
+ body.comment("The Figure below shows the " + what + " for this service:");
+ body.figureCaption(service.getName() + " Service " + what);
+ }
+
+ if (com.getArchiveUsage() != null) {
+ body.title(3, "COM Archive Service usage");
+ body.numberedComment(DocxText.split(com.getArchiveUsage()));
+ }
+ if (com.getActivityUsage() != null) {
+ body.title(3, "COM Activity Service usage");
+ body.numberedComment(DocxText.split(com.getActivityUsage()));
+ }
+ }
+
+ /**
+ * The objects or the events of a service, which are described the same way.
+ */
+ private void writeComObjects(DocxBody body, Area area, Service service,
+ List<COMObject> objects, String caption, String nameColumn) {
+ DocxTable table = body.table(COM_TYPES_WIDTHS, caption);
+ table.row()
+ .cell("Object Number").shaded(HEADER_COLOUR).centered().next()
+ .cell(nameColumn).shaded(HEADER_COLOUR).centered().next()
+ .cell("Object Body Type").shaded(HEADER_COLOUR).centered().next()
+ .cell("Related link").shaded(HEADER_COLOUR).centered().next()
+ .cell("Source link").shaded(HEADER_COLOUR).centered().endRow();
+
+ for (COMObject object : objects) {
+ DocxRow row = table.row();
+ row.cell(String.valueOf(object.getNumber())).centered().next()
+ .cell(object.getName()).centered().next();
+ if (object.getBodyType() == null) {
+ row.cell("No body").centered().next();
+ } else {
+ row.markedUp(DocxTypeLink.forType(area, service, object.getBodyType()))
+ .centered().next();
+ }
+ row.cell(linkText(area, service, object.getRelated())).centered().next()
+ .cell(linkText(area, service, object.getSource())).centered().endRow();
+ }
+ table.end();
+ }
+
+ /**
+ * What a link to another object says: the object it points at, whatever the
+ * specification said instead, or that there is nothing there.
+ */
+ private static String linkText(Area area, Service service, ObjectLink link) {
+ if (link == null) {
+ return "Set to NULL";
+ }
+ if (link.getTarget() != null) {
+ ObjectReference target = link.getTarget();
+ StringBuilder buf = new StringBuilder();
+ if (!area.getName().equalsIgnoreCase(target.getArea())) {
+ buf.append(target.getArea()).append("::");
+ }
+ String owning = service == null ? "" : service.getName();
+ if (target.getService() != null && !target.getService().isEmpty()
+ && !target.getService().equalsIgnoreCase(owning)) {
+ buf.append(target.getService()).append("::");
+ }
+ return buf.append(target.getNumber()).toString();
+ }
+ return link.getComment() != null ? link.getComment() : "Not specified";
+ }
+
+ /**
+ * What one operation exchanges: the pattern it follows, and a row per message with the
+ * fields it carries.
+ */
+ private void writeOperationTable(DocxBody body, Area area, Service service,
+ Operation operation) {
+ DocxTable table = body.table(OPERATION_OVERVIEW_WIDTHS);
+ table.row()
+ .cell("Operation Identifier").shaded(HEADER_COLOUR).centered().next()
+ .cell(operation.getName()).centered().spanning(3).endRow();
+
+ table.row()
+ .cell("Interaction Pattern").shaded(HEADER_COLOUR).centered().next()
+ .cell(patternNameOf(operation)).shaded(FIXED_COLOUR).centered().spanning(3)
+ .endRow();
+
+ // Only where the operation says something about its keys: an operation that
+ // declares none at all is not the same as one that declares an empty set.
+ if (operation.getPattern() == InteractionPattern.PUBSUB
+ && operation.getMessage(InteractionStage.SUBSCRIPTION_KEYS) != null) {
+ writeSubscriptionKeys(table, area, service, operation);
+ }
+
+ table.row()
+ .cell("Pattern Sequence").shaded(HEADER_COLOUR).centered().next()
+ .cell("Message").shaded(HEADER_COLOUR).centered().next()
+ .cell("Nullable").shaded(HEADER_COLOUR).centered().next()
+ .cell("Type Signature").shaded(HEADER_COLOUR).centered().endRow();
+
+ for (Message message : messagesOf(operation)) {
+ writeMessage(table, area, service, message);
+ }
+ table.end();
+ }
+
+ /**
+ * The names a subscription is keyed by, which a publish-subscribe operation states
+ * before the messages themselves.
+ */
+ private void writeSubscriptionKeys(DocxTable table, Area area, Service service,
+ Operation operation) {
+ List<Field> keys = fieldsOf(operation, InteractionStage.SUBSCRIPTION_KEYS);
+ DocxRow row = table.row();
+ row.cell("Subscription Keys").shaded(HEADER_COLOUR).centered().next();
+ if (keys.isEmpty()) {
+ row.cell("Empty").shaded(FIXED_COLOUR).centered().spanning(3).endRow();
+ } else {
+ row.markedUp(signature(area, service, keys)).centered().spanning(3).endRow();
+ }
+ }
+
+ /**
+ * One message of an interaction: which way it goes, what it is called, and what it
+ * carries.
+ */
+ private void writeMessage(DocxTable table, Area area, Service service, Message message) {
+ DocxRow row = table.row();
+ row.cell(message.incoming ? "IN" : "OUT").shaded(FIXED_COLOUR).centered().next()
+ .cell(message.name).shaded(FIXED_COLOUR).centered().next();
+ if (message.fields.isEmpty()) {
+ row.cell("-").shaded(FIXED_COLOUR).centered().next()
+ .cell("-").shaded(FIXED_COLOUR).centered().endRow();
+ } else {
+ row.markedUp(DocxTypeLink.nullability(message.fields)).centered().next()
+ .markedUp(signature(area, service, message.fields)).centered().endRow();
+ }
+ }
+
+ /**
+ * @return the fields of a message, each named and linked to its type.
+ */
+ private static String signature(Area area, Service service, List<Field> fields) {
+ List<String> parts = new ArrayList<String>();
+ for (Field field : fields) {
+ parts.add(DocxTypeLink.forField(area, service, field));
+ }
+ return DocxTypeLink.join(parts);
+ }
+
+ /**
+ * The messages of an interaction, in the order they are exchanged, each knowing which
+ * way it travels and what the document calls it.
+ */
+ private static List<Message> messagesOf(Operation operation) {
+ List<Message> messages = new ArrayList<Message>();
+ switch (operation.getPattern()) {
+ case SEND:
+ messages.add(new Message(true, "SEND", InteractionStage.SEND,
+ fieldsOf(operation, InteractionStage.SEND)));
+ break;
+ case SUBMIT:
+ messages.add(new Message(true, "SUBMIT", InteractionStage.SUBMIT,
+ fieldsOf(operation, InteractionStage.SUBMIT)));
+ break;
+ case REQUEST:
+ messages.add(new Message(true, "REQUEST", InteractionStage.REQUEST,
+ fieldsOf(operation, InteractionStage.REQUEST)));
+ messages.add(new Message(false, "RESPONSE", InteractionStage.RESPONSE,
+ fieldsOf(operation, InteractionStage.RESPONSE)));
+ break;
+ case INVOKE:
+ messages.add(new Message(true, "INVOKE", InteractionStage.INVOKE,
+ fieldsOf(operation, InteractionStage.INVOKE)));
+ messages.add(new Message(false, "ACK", InteractionStage.ACK,
+ fieldsOf(operation, InteractionStage.ACK)));
+ messages.add(new Message(false, "RESPONSE", InteractionStage.RESPONSE,
+ fieldsOf(operation, InteractionStage.RESPONSE)));
+ break;
+ case PROGRESS:
+ messages.add(new Message(true, "PROGRESS", InteractionStage.PROGRESS,
+ fieldsOf(operation, InteractionStage.PROGRESS)));
+ messages.add(new Message(false, "ACK", InteractionStage.ACK,
+ fieldsOf(operation, InteractionStage.ACK)));
+ messages.add(new Message(false, "UPDATE", InteractionStage.UPDATE,
+ fieldsOf(operation, InteractionStage.UPDATE)));
+ messages.add(new Message(false, "RESPONSE", InteractionStage.RESPONSE,
+ fieldsOf(operation, InteractionStage.RESPONSE)));
+ break;
+ case PUBSUB:
+ messages.add(new Message(false, "PUBLISH", InteractionStage.PUBLISH_NOTIFY,
+ fieldsOf(operation, InteractionStage.PUBLISH_NOTIFY)));
+ break;
+ default:
+ break;
+ }
+ return messages;
+ }
+
+ /**
+ * @return what the operation's own table calls this interaction pattern.
+ */
+ private static String patternNameOf(Operation operation) {
+ return operation.getPattern() == InteractionPattern.PUBSUB
+ ? "PUBLISH-SUBSCRIBE" : operation.getPattern().name();
+ }
+
+ /**
+ * @return what the service overview table calls this interaction pattern, which is the
+ * same as above except that the column is narrow enough to want it shortened.
+ */
+ private static String shortPatternNameOf(Operation operation) {
+ return operation.getPattern() == InteractionPattern.PUBSUB
+ ? "PUB-SUB" : operation.getPattern().name();
+ }
+
+ private static List<Field> fieldsOf(Operation operation, InteractionStage stage) {
+ MessageBody body = operation.getMessage(stage);
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ /**
+ * One error an operation may answer with, gathered from the reference that names it.
+ * <p>
+ * The specifications only ever reference an error from an operation, never define one
+ * there, so the definition is looked up to find its number - and an error of another
+ * area is named rather than numbered, since its number is that area's business.
+ */
+ private static final class OperationError implements Comparable<OperationError> {
+
+ private final String name;
+ private final String number;
+
+ /**
+ * What the error sorts on. Usually its number, but an error of another area sorts
+ * as zero and one whose number could not be found sorts under the text that says
+ * so - which is how the reference output orders them.
+ */
+ private final String order;
+ private final List<String> comments;
+ private final String extraType;
+ private final String extraDescription;
+
+ private OperationError(String name, String number, String order, List<String> comments,
+ String extraType, String extraDescription) {
+ this.name = name;
+ this.number = number;
+ this.order = order;
+ this.comments = comments;
+ this.extraType = extraType;
+ this.extraDescription = extraDescription;
+ }
+
+ private static OperationError of(MOModel model, Area area, Service service,
+ ErrorReference reference) {
+ String name = reference.getError().getName();
+ String number = "UNKNOWN ERROR NUMBER!";
+ String order;
+
+ String declaredIn = reference.getError().getArea();
+ if (declaredIn == null || declaredIn.equals(area.getName())) {
+ ErrorDefinition definition = model.resolveError(reference.getError());
+ if (definition != null) {
+ number = String.valueOf(definition.getNumber());
+ }
+ order = number;
+ } else {
+ number = "Defined in " + declaredIn;
+ order = "0";
+ }
+
+ String extraType = NOT_USED;
+ String extraDescription = "-";
+ Field extra = reference.getExtraInformation();
+ if (extra != null) {
+ extraType = qualify(area, service, extra.getType());
+ if (extra.getComment() != null) {
+ extraDescription = extra.getComment();
+ }
+ }
+ return new OperationError(name, number, order,
+ DocxText.split(reference.getComment()), extraType, extraDescription);
+ }
+
+ /**
+ * @return the error named and described, a line per thing said about it.
+ */
+ private List<String> describe() {
+ List<String> lines = new ArrayList<String>();
+ if (comments.isEmpty()) {
+ lines.add(name + ": Not described");
+ return lines;
+ }
+ for (String comment : comments) {
+ lines.add(name + ": " + comment);
+ }
+ return lines;
+ }
+
+ @Override
+ public int compareTo(OperationError other) {
+ try {
+ return Long.valueOf(order).compareTo(Long.valueOf(other.order));
+ } catch (NumberFormatException ex) {
+ // One of them is not a number at all, so they are ordered as text.
+ return order.compareTo(other.order);
+ }
+ }
+ }
+
+ /**
+ * Names a type from where it is mentioned, leaving off the area and service that are
+ * being written about.
+ */
+ private static String qualify(Area area, Service service, esa.mo.apigen.model.types.TypeRef type) {
+ StringBuilder buf = new StringBuilder();
+ if (!area.getName().equalsIgnoreCase(type.getArea())) {
+ buf.append(type.getArea()).append("::");
+ }
+ String owning = service == null ? "" : service.getName();
+ if (type.getService() != null && !type.getService().isEmpty()
+ && !type.getService().equalsIgnoreCase(owning)) {
+ buf.append(type.getService()).append("::");
+ }
+ buf.append(type.getName());
+ // The extra information of an error is named in full, list wrapper and all: unlike
+ // a message field, there is no separate column to put it in.
+ return type.isList() ? "List<" + buf + ">" : buf.toString();
+ }
+
+ /**
+ * One message of an interaction, as the table describes it.
+ */
+ private static final class Message {
+
+ private final boolean incoming;
+ private final String name;
+ private final InteractionStage stage;
+ private final List<Field> fields;
+
+ private Message(boolean incoming, String name, InteractionStage stage,
+ List<Field> fields) {
+ this.incoming = incoming;
+ this.name = name;
+ this.stage = stage;
+ this.fields = fields;
+ }
+ }
+
+ /**
+ * The errors an operation may answer with: named and described, then tabulated with
+ * whatever extra information each one carries.
+ */
+ private void writeOperationErrors(DocxBody body, MOModel model, Area area, Service service,
+ Operation operation) throws IOException {
+ body.title(4, "MO Errors");
+
+ if (operation.getPattern() == InteractionPattern.SEND) {
+ // A send is not answered at all, so there is nowhere to put an error.
+ body.comment("The operation cannot return any errors.");
+ return;
+ }
+ if (operation.getErrors().isEmpty()) {
+ body.comment("The operation does not return any errors.");
+ return;
+ }
+
+ body.comment(operation.getErrors().size() == 1
+ ? "The operation may return the following error:"
+ : "The operation may return one of the following errors:");
+
+ List<OperationError> errors = new ArrayList<OperationError>();
+ for (ErrorReference reference : operation.getErrors()) {
+ errors.add(OperationError.of(model, area, service, reference));
+ }
+ java.util.Collections.sort(errors);
+
+ List<String> described = new ArrayList<String>();
+ for (OperationError error : errors) {
+ described.addAll(error.describe());
+ }
+ body.numberedComment(described);
+
+ DocxTable table = body.table(OPERATION_ERROR_WIDTHS);
+ table.row()
+ .cell("Error").shaded(HEADER_COLOUR).centered().next()
+ .cell("Error #").shaded(HEADER_COLOUR).centered().next()
+ .cell("ExtraInfo Type").shaded(HEADER_COLOUR).centered().next()
+ .cell("ExtraInfo description").shaded(HEADER_COLOUR).centered().endRow();
+
+ for (OperationError error : errors) {
+ DocxRow row = table.row();
+ row.cell(error.name).centered().next()
+ .cell(error.number).centered().next();
+ // A type of this area is linked to where it is defined; one that names its own
+ // area, or none at all, is only shown.
+ if (error.extraType.contains("::") || NOT_USED.equals(error.extraType)) {
+ row.cell(error.extraType.replace("MAL::", "")).centered().next();
+ } else {
+ row.markedUp(DocxTypeLink.hyperlink("", error.extraType, "",
+ "DATATYPE_" + error.extraType, true)).centered().next();
+ }
+ row.cell(error.extraDescription).centered().endRow();
+ }
+ table.end();
+ }
+
+ /**
+ * Describes every field of every message, so that the table above can stay to the
+ * types and the names.
+ */
+ private void writeSignatureDetails(DocxBody body, Operation operation) {
+ body.title(4, "Type Signature Details");
+ for (InteractionStage stage : detailedStagesOf(operation)) {
+ for (Field field : fieldsOf(operation, stage)) {
+ body.singleTypeSignature(field.getName(), field.getComment());
+ }
+ }
+ }
+
+ /**
+ * The stages whose fields are described one by one. A publish-subscribe operation
+ * describes its subscription keys here as well, which the table above only lists.
+ */
+ private static List<InteractionStage> detailedStagesOf(Operation operation) {
+ List<InteractionStage> stages = new ArrayList<InteractionStage>();
+ if (operation.getPattern() == InteractionPattern.PUBSUB) {
+ stages.add(InteractionStage.SUBSCRIPTION_KEYS);
+ stages.add(InteractionStage.PUBLISH_NOTIFY);
+ return stages;
+ }
+ for (Message message : messagesOf(operation)) {
+ stages.add(message.stage);
+ }
+ return stages;
+ }
+
+ /**
+ * The requirements a service states, numbered as one list however many sections they
+ * are written in: they are the requirements of the service, not of its sections.
+ */
+ private void writeRequirements(DocxBody body, List<DocSection> sections) throws IOException {
+ List<String> requirements = new ArrayList<String>();
+ for (DocSection section : sections) {
+ requirements.addAll(DocxText.split(section.getContent()));
+ }
+ body.numberedComment(requirements);
+ }
+
+ /**
+ * Every type the specification declares, area level first and then service by service.
+ */
+ private void writeDataTypes(DocxBody types, MOModel model, Area area) throws IOException {
+ types.pageBreak();
+ types.title(1, "Data types");
+ boolean any = !area.getDataTypes().isEmpty();
+
+ if (any) {
+ types.title(2, "Area data types: " + area.getName());
+ for (TypeDefinition type : area.getDataTypes()) {
+ writeDataType(types, model, area, null, type);
+ }
+ }
+ for (Service service : area.getServices()) {
+ if (!service.getDataTypes().isEmpty()) {
+ any = true;
+ types.title(2, "Service data types: " + service.getName());
+ for (TypeDefinition type : service.getDataTypes()) {
+ writeDataType(types, model, area, service, type);
+ }
+ }
+ }
+ if (!any) {
+ types.comment("No data types are defined in this specification.");
+ }
+ }
+
+ /**
+ * One declared type, described according to what kind of thing it is.
+ */
+ private void writeDataType(DocxBody types, MOModel model, Area area, Service service,
+ TypeDefinition type) {
+ if (type instanceof FundamentalType) {
+ types.title(3, "Fundamental: ", type.getName(), "DATATYPE");
+ if (type.getComment() != null && !type.getComment().isEmpty()) {
+ types.comment(type.getComment());
+ }
+ } else if (type instanceof AttributeType) {
+ writeAttribute(types, (AttributeType) type);
+ } else if (type instanceof EnumerationType) {
+ writeEnumeration(types, (EnumerationType) type);
+ } else if (type instanceof CompositeType) {
+ writeComposite(types, model, area, service, (CompositeType) type);
+ }
+ }
+
+ /**
+ * An attribute is one of the types everything else is built from, so there is little to
+ * say beyond what it is called and numbered.
+ */
+ private void writeAttribute(DocxBody types, AttributeType attribute) {
+ types.title(3, "Attribute: ", attribute.getName(), "DATATYPE");
+ if (attribute.getComment() != null && !attribute.getComment().isEmpty()) {
+ types.comment(attribute.getComment());
+ }
+
+ DocxTable table = types.table(LIST_WIDTHS);
+ table.row().cell("Name").shaded(HEADER_COLOUR).centered().next()
+ .cell(attribute.getName()).centered().endRow();
+ table.row().cell("Extends").shaded(HEADER_COLOUR).centered().next()
+ .cell("Attribute").centered().endRow();
+ table.row().cell("Short Form Part").shaded(HEADER_COLOUR).centered().next()
+ .cell(String.valueOf(attribute.getShortFormPart())).centered().endRow();
+ table.end();
+ types.sectionBreak();
+ }
+
+ /**
+ * An enumeration is its values, each with the number it travels as.
+ */
+ private void writeEnumeration(DocxBody types, EnumerationType enumeration) {
+ types.title(3, "Enumeration: ", enumeration.getName(), "DATATYPE");
+ if (enumeration.getComment() != null && !enumeration.getComment().isEmpty()) {
+ types.comment(enumeration.getComment());
+ }
+
+ DocxTable table = types.table(ENUM_WIDTHS);
+ table.row().cell("Name").shaded(HEADER_COLOUR).centered().next()
+ .cell(enumeration.getName()).centered().spanning(2).endRow();
+ table.row().cell("Short Form Part").shaded(HEADER_COLOUR).centered().next()
+ .cell(String.valueOf(enumeration.getShortFormPart())).centered().spanning(2)
+ .endRow();
+ table.row()
+ .cell("Enumeration Value").shaded(HEADER_COLOUR).centered().next()
+ .cell("Numerical Value").shaded(HEADER_COLOUR).centered().next()
+ .cell("Comment").shaded(HEADER_COLOUR).centered().endRow();
+
+ for (EnumerationItem item : enumeration.getItems()) {
+ table.row()
+ .cell(item.getValue()).centered().next()
+ .cell(String.valueOf(item.getNumericValue())).centered().next()
+ .cell(item.getComment()).endRow();
+ }
+ table.end();
+ types.sectionBreak();
+ }
+
+ /**
+ * A composite is its fields, and the fields of whatever it extends before them.
+ */
+ private void writeComposite(DocxBody types, MOModel model, Area area, Service service,
+ CompositeType composite) {
+ TypeRef parent = composite.getSuperType() != null ? composite.getSuperType()
+ : new TypeRef("MAL", area.getVersion(), null, "Composite", false, false);
+ // A composite extending the MAL Object is an object in the COM sense: something
+ // that is stored and referred to, rather than only carried in a message.
+ boolean isObject = "Object".equals(parent.getName());
+
+ types.title(3, isObject ? "MO Object: " : "Composite: ", composite.getName(), "DATATYPE");
+ if (composite.getComment() != null && !composite.getComment().isEmpty()) {
+ types.comment(composite.getComment());
+ }
+
+ DocxTable table = types.table(COMPOSITE_WIDTHS);
+ table.row().cell("Name").shaded(HEADER_COLOUR).centered().next()
+ .cell(composite.getName()).centered().spanning(3).endRow();
+ table.row().cell("Extends").shaded(HEADER_COLOUR).centered().next()
+ .markedUp(DocxTypeLink.forType(area, service, parent)).centered().spanning(3)
+ .endRow();
+
+ if (composite.getShortFormPart() == null) {
+ table.row().cell("Abstract").shaded(HEADER_COLOUR).centered().spanning(4).endRow();
+ } else {
+ table.row().cell("Short Form Part").shaded(HEADER_COLOUR).centered().next()
+ .cell(String.valueOf(composite.getShortFormPart())).centered().spanning(3)
+ .endRow();
+ }
+
+ List<Field> inherited = model.inheritedFields(composite);
+ List<Field> own = composite.getFields();
+
+ if (!own.isEmpty()) {
+ table.row()
+ .cell("Field").shaded(HEADER_COLOUR).centered().next()
+ .cell("Type").shaded(HEADER_COLOUR).centered().next()
+ .cell("Nullable").shaded(HEADER_COLOUR).centered().next()
+ .cell("Comment").shaded(HEADER_COLOUR).centered().endRow();
+
+ for (Field field : inherited) {
+ writeCompositeField(table, area, service, field, FIXED_COLOUR);
+ }
+ for (Field field : own) {
+ writeCompositeField(table, area, service, field, null);
+ }
+ }
+ table.end();
+ types.sectionBreak();
+ }
+
+ /**
+ * One field of a composite. A field it inherits is filled in, to set it apart from the
+ * ones the composite declares itself.
+ */
+ private void writeCompositeField(DocxTable table, Area area, Service service, Field field,
+ String shade) {
+ DocxRow row = table.row();
+ row.cell(field.getName()).shaded(shade).centered().next()
+ .markedUp(DocxTypeLink.forType(area, service, field.getType())).shaded(shade)
+ .centered().next()
+ .cell(field.isCanBeNull() ? "Yes" : "No").shaded(shade).centered().next()
+ .cell(field.getComment()).shaded(shade).endRow();
+ }
+
+ /**
+ * Every error the specification declares, wherever it declares it.
+ */
+ private void writeErrors(DocxBody types, Area area) throws IOException {
+ types.title(1, "MO Errors");
+ List<ErrorDefinition> errors = new ArrayList<ErrorDefinition>(area.getErrors());
+ for (Service service : area.getServices()) {
+ errors.addAll(service.getErrors());
+ }
+
+ if (errors.isEmpty()) {
+ types.comment("No errors are defined in this specification.");
+ return;
+ }
+
+ types.comment("The following table lists the errors defined in this specification:");
+ DocxTable table = types.table(ERROR_TABLE_WIDTHS, area.getName() + " MO Errors");
+ table.row()
+ .cell("Error").shaded(HEADER_COLOUR).centered().next()
+ .cell("Error #").shaded(HEADER_COLOUR).centered().next()
+ .cell("Comment").shaded(HEADER_COLOUR).centered().endRow();
+ for (ErrorDefinition error : errors) {
+ table.row()
+ .cell(error.getName()).centered().next()
+ .cell(String.valueOf(error.getNumber())).centered().next()
+ .cell(error.getComment()).endRow();
+ }
+ table.end();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxNumbering.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxNumbering.java
new file mode 100644
index 00000000..2dc40e48
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxNumbering.java
@@ -0,0 +1,80 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+import java.io.IOException;
+
+/**
+ * The numbering definitions of one document.
+ * <p>
+ * A Word document keeps its list numbering apart from its body: the body says which
+ * numbering an item belongs to, and the numbering part says what that looks like. Two are
+ * defined up front - a dash bullet and a symbol bullet - and a further one is defined each
+ * time a numbered list is started, so that lists number from the top rather than continuing
+ * one another. That is why this is not a fixed resource like the style sheet, and why every
+ * document ends up with a numbering part of its own.
+ */
+public final class DocxNumbering {
+
+ private final StringBuilder definitions = new StringBuilder();
+
+ private final StringBuilder instances = new StringBuilder();
+
+ /**
+ * Counts the numberings handed out. The preamble defines 0 and 1, so the first one
+ * asked for is 2.
+ */
+ private int lastInstance = 1;
+
+ /**
+ * @throws IOException if the fixed part of the numbering is missing from the build.
+ */
+ public DocxNumbering() throws IOException {
+ definitions.append(DocxResources.read(DocxResources.NUMBERING_PREAMBLE))
+ .append(DocxText.SEPARATOR);
+ instances.append(DocxText.line(2,
+ "<w:num w:numId=\"1\"><w:abstractNumId w:val=\"1\"/></w:num>", DocxText.SEPARATOR));
+ }
+
+ /**
+ * Defines a numbering for a list that is about to start.
+ *
+ * @return the identifier the body refers to it by.
+ * @throws IOException if the template is missing from the build.
+ */
+ public int nextInstance() throws IOException {
+ int instance = ++lastInstance;
+ String id = String.valueOf(instance);
+ definitions.append(DocxResources.read(DocxResources.NUMBERING_INSTANCE)
+ .replace("${id}", id)).append(DocxText.SEPARATOR);
+ instances.append(DocxText.line(2, "<w:num w:numId=\"" + id
+ + "\"><w:abstractNumId w:val=\"" + id + "\"/></w:num>", DocxText.SEPARATOR));
+ return instance;
+ }
+
+ /**
+ * @return the numbering part of the document: every definition, then every instance
+ * that refers to one.
+ */
+ public String toXml() {
+ return definitions.toString() + instances + "</w:numbering>" + DocxText.SEPARATOR;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxResources.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxResources.java
new file mode 100644
index 00000000..8f48214a
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxResources.java
@@ -0,0 +1,84 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.Charset;
+
+/**
+ * Reads the fixed parts of a Word document out of the module's resources.
+ * <p>
+ * A .docx carries a good deal of XML that says nothing about the specification being
+ * documented - the style sheet, the content types, the package relationships, the numbering
+ * definitions. It was 270 000 characters of escaped string literal in the generator this
+ * replaces; here it is the files it actually is, so that a style can be read, diffed and
+ * edited as XML.
+ */
+public final class DocxResources {
+
+ private static final Charset UTF8 = Charset.forName("UTF-8");
+
+ /**
+ * The style sheet in use: Times New Roman at 12 point, with the MO table style. Four
+ * others are kept beside it - Calibri, plain Times, Times with the MO table style, and
+ * the CCSDS sheet - none of them selected by anything. They are carried because they
+ * were carried before, not because anything reaches them.
+ */
+ public static final String STYLES = "styles.xml";
+
+ public static final String CONTENT_TYPES = "content-types.xml";
+
+ public static final String PACKAGE_RELS = "package.rels";
+
+ public static final String NUMBERING_PREAMBLE = "numbering-preamble.xml";
+
+ public static final String NUMBERING_INSTANCE = "numbering-instance.xml";
+
+ private DocxResources() {
+ }
+
+ /**
+ * Reads one of the fixed parts.
+ *
+ * @param name The resource name, one of the constants here.
+ * @return the contents.
+ * @throws IOException if the resource is missing from the build.
+ */
+ public static String read(String name) throws IOException {
+ InputStream in = DocxResources.class.getResourceAsStream("/docx/" + name);
+ if (in == null) {
+ throw new IOException("The docx resource '" + name + "' is not on the classpath");
+ }
+ try {
+ ByteArrayOutputStream buf = new ByteArrayOutputStream();
+ byte[] chunk = new byte[8192];
+ int read;
+ while ((read = in.read(chunk)) != -1) {
+ buf.write(chunk, 0, read);
+ }
+ return new String(buf.toByteArray(), UTF8);
+ } finally {
+ in.close();
+ }
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxRow.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxRow.java
new file mode 100644
index 00000000..19b377d6
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxRow.java
@@ -0,0 +1,74 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+/**
+ * One row of a table, which knows where it has got to across the columns.
+ * <p>
+ * A cell is as wide as the column it sits in, and a cell that spans is as wide as the
+ * columns it covers together. The row keeps the count, so that nothing has to be told its
+ * own position.
+ */
+public final class DocxRow {
+
+ private final DocxTable table;
+
+ private int column = 0;
+
+ DocxRow(DocxTable table) {
+ this.table = table;
+ table.append(3, "<w:tr>");
+ }
+
+ /**
+ * Adds a cell holding text, in the table's own style.
+ *
+ * @param text The text, which is escaped.
+ * @return the cell, for saying anything else about it.
+ */
+ public DocxCell cell(String text) {
+ return new DocxCell(this, "<w:pPr><w:pStyle w:val=\"MOTable\"/></w:pPr><w:r><w:t>"
+ + DocxText.escape(text) + "</w:t></w:r>");
+ }
+
+ /**
+ * Adds a cell holding content that is already marked up - a hyperlink, or a signature
+ * built out of several runs.
+ *
+ * @param xml The content of the cell, inside its paragraph.
+ * @return the cell, for saying anything else about it.
+ */
+ public DocxCell markedUp(String xml) {
+ return new DocxCell(this, xml);
+ }
+
+ /**
+ * Ends the row.
+ */
+ public void end() {
+ table.append(3, "</w:tr>");
+ }
+
+ void write(DocxCell cell) {
+ table.append(4, cell.toXml(table.widthOf(column, cell.getSpan())));
+ column += cell.getSpan();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxTable.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxTable.java
new file mode 100644
index 00000000..c5cdfc90
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxTable.java
@@ -0,0 +1,99 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+/**
+ * One table: the widths of its columns, and the rows written into it.
+ * <p>
+ * The borders and the sizing are the same for every table in these documents, so they are
+ * not something a caller says anything about.
+ */
+public final class DocxTable {
+
+ /**
+ * The borders every table in these documents has. Written through the same indent
+ * helper as everything else rather than as a block of pre-indented text, so that one
+ * place decides what a level of indentation is.
+ */
+ private static final String[] BORDERS = {"top", "left", "bottom", "right", "insideH", "insideV"};
+
+ private final DocxBody body;
+
+ private final int[] widths;
+
+ DocxTable(DocxBody body, int[] widths) {
+ this.body = body;
+ this.widths = widths;
+ body.append(2, "<w:tbl>");
+ body.append(3, "<w:tblPr>");
+ body.append(4, "<w:tblW w:w=\"00\" w:type=\"auto\"/>");
+ body.append(4, "<w:tblBorders>");
+ for (String edge : BORDERS) {
+ body.append(5, "<w:" + edge + " w:val=\"single\" w:sz=\"4\" w:space=\"0\""
+ + " w:color=\"000000\"/>");
+ }
+ body.append(4, "</w:tblBorders>");
+ body.append(3, "</w:tblPr>");
+ if (widths != null) {
+ body.append(3, "<w:tblGrid>");
+ for (int width : widths) {
+ body.append(4, "<w:gridCol w:w=\"" + width + "\"/>");
+ }
+ body.append(3, "</w:tblGrid>");
+ }
+ }
+
+ /**
+ * Starts a row.
+ *
+ * @return the row, to add cells to.
+ */
+ public DocxRow row() {
+ return new DocxRow(this);
+ }
+
+ /**
+ * Ends the table.
+ */
+ public void end() {
+ body.append(2, "</w:tbl>");
+ }
+
+ /**
+ * @param column The column the cell starts in.
+ * @param span How many columns it covers.
+ * @return how wide the cell is, which is the columns it covers taken together.
+ */
+ int widthOf(int column, int span) {
+ if (widths == null) {
+ return 0;
+ }
+ int width = 0;
+ for (int i = column; i < column + span && i < widths.length; i++) {
+ width += widths[i];
+ }
+ return width;
+ }
+
+ void append(int indent, String text) {
+ body.append(indent, text);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxText.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxText.java
new file mode 100644
index 00000000..42647c3f
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxText.java
@@ -0,0 +1,90 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+/**
+ * The text side of a document: what has to be escaped, and how a line is indented.
+ */
+public final class DocxText {
+
+ private DocxText() {
+ }
+
+ /**
+ * Prepares text written by a specification for a document.
+ * <p>
+ * The list item markup a few comments carry is dropped rather than escaped: the
+ * documents show those comments as running text, so a literal {@code _li_} in the middle
+ * of a sentence would be worse than nothing. Everything else XML reserves is escaped,
+ * and the order matters - the ampersands have to go first, or the escapes escape
+ * themselves.
+ *
+ * @param text The text to put in the document, may be null.
+ * @return the text, ready to sit inside an element.
+ */
+ public static String escape(String text) {
+ if (text == null) {
+ return "";
+ }
+ return text.replace("<li>", "").replace("</li>", "")
+ .replace("&", "&").replace("<", "<").replace(">", ">");
+ }
+
+ /**
+ * The body of a document ends its lines the way Word does, and the numbering part ends
+ * them the way everything else here does. That is not a decision anyone took - the two
+ * writers of the existing generator were built with different separators, one passing
+ * "\r\n" and the other taking the default - but the documents are compared byte for
+ * byte, so both are reproduced as they are.
+ */
+ public static final String BODY_SEPARATOR = "\r\n";
+
+ public static final String SEPARATOR = "\n";
+
+ /**
+ * Splits a comment where a document starts a new paragraph: at a line break, or at the
+ * double space the specifications use to mean one.
+ *
+ * @param text The comment, may be null.
+ * @return the paragraphs, empty if there is no text.
+ */
+ public static java.util.List<String> split(String text) {
+ java.util.List<String> parts = new java.util.ArrayList<String>();
+ if (text != null) {
+ parts.addAll(java.util.Arrays.asList(text.split("( |\n)")));
+ }
+ return parts;
+ }
+
+ /**
+ * @param indent How many steps in, at four spaces a step.
+ * @param text The line.
+ * @param separator How the line ends.
+ * @return the line, indented and ended.
+ */
+ public static String line(int indent, String text, String separator) {
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < indent; i++) {
+ buf.append(" ");
+ }
+ return buf.append(text).append(separator).toString();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxTypeLink.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxTypeLink.java
new file mode 100644
index 00000000..2c3325c7
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/docx/DocxTypeLink.java
@@ -0,0 +1,206 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.docx;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.TypeRef;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Names a type inside a table cell, linking to where it is defined when the document that
+ * mentions it is also the document that defines it.
+ * <p>
+ * The generator this replaces took two flags through every call - whether to show the name
+ * of the field and whether to use the older layout - and branched on them here. Neither has
+ * ever been set to anything but its default, so neither is carried over: a field is always
+ * shown as {@code List_Type_ name}, never as {@code name : (List_Type_)}.
+ */
+public final class DocxTypeLink {
+
+ /**
+ * Separates two type names sharing a cell: the cell holds a paragraph each.
+ */
+ private static final String NEXT_LINE
+ = "</w:p><w:p><w:pPr><w:jc w:val=\"center\"/></w:pPr>";
+
+ private DocxTypeLink() {
+ }
+
+ /**
+ * Names the type of a field, with the field's own name after it.
+ *
+ * @param area The area of the document being written.
+ * @param service The service being written, or null at area level.
+ * @param field The field to name.
+ * @return the content of a cell.
+ */
+ public static String forField(Area area, Service service, Field field) {
+ TypeRef type = field.getType();
+ String prefix = type.isList() ? "List<" : "";
+ String postfix = (type.isList() ? "> " : " ") + field.getName();
+ return link(area, service, type, prefix, postfix);
+ }
+
+ /**
+ * Names a type on its own.
+ *
+ * @param area The area of the document being written.
+ * @param service The service being written, or null at area level.
+ * @param type The type to name.
+ * @return the content of a cell.
+ */
+ public static String forType(Area area, Service service, TypeRef type) {
+ String prefix = type.isList() ? "List<" : "";
+ String postfix = type.isList() ? ">" : "";
+ return link(area, service, type, prefix, postfix);
+ }
+
+ /**
+ * Says of each field whether it may be left out.
+ *
+ * @param fields The fields of a message.
+ * @return the content of a cell, one answer per line.
+ */
+ public static String nullability(List<Field> fields) {
+ List<String> answers = new ArrayList<String>();
+ for (Field field : fields) {
+ answers.add("<w:pPr><w:pStyle w:val=\"MOTable\"/></w:pPr><w:r><w:t>"
+ + (field.isCanBeNull() ? "Yes" : "No") + "</w:t></w:r>");
+ }
+ return join(answers);
+ }
+
+ /**
+ * @param fragments What each line of the cell holds.
+ * @return the fragments as the lines of one cell.
+ */
+ public static String join(List<String> fragments) {
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < fragments.size(); i++) {
+ buf.append(fragments.get(i));
+ if (i != fragments.size() - 1) {
+ buf.append(NEXT_LINE);
+ }
+ }
+ return buf.toString();
+ }
+
+ /**
+ * Writes the name, linked to its definition when that definition is in this document.
+ */
+ private static String link(Area area, Service service, TypeRef type,
+ String prefix, String postfix) {
+ String name = qualify(area, service, type);
+ // The MAL types are mentioned everywhere and defined in a document of their own, so
+ // naming their area every time would say nothing.
+ if (name.startsWith("MAL::")) {
+ name = name.substring("MAL::".length());
+ }
+ boolean sameArea = area.getName().equalsIgnoreCase(type.getArea());
+ return hyperlink(prefix, name, postfix, "DATATYPE_" + name, sameArea);
+ }
+
+ /**
+ * Names a type from where it is being mentioned: the area is left off when it is the
+ * area being written, and so is the service.
+ */
+ private static String qualify(Area area, Service service, TypeRef reference) {
+ // The older spelling of an object reference, ObjectRef(Product), means the same as
+ // the newer one; unwrapping lets both be named the same way.
+ TypeRef type = reference.unwrapped();
+ StringBuilder buf = new StringBuilder();
+ if (!area.getName().equalsIgnoreCase(type.getArea())) {
+ buf.append(type.getArea()).append("::");
+ }
+ String owning = service == null ? "" : service.getName();
+ if (type.getService() != null && !type.getService().isEmpty()
+ && !type.getService().equalsIgnoreCase(owning)) {
+ buf.append(type.getService()).append("::");
+ }
+ return buf.append(type.isObjectRef()
+ ? "ObjectRef<" + type.getName() + ">" : type.getName()).toString();
+ }
+
+ /**
+ * Writes a name, as a link to a bookmark where there is one to link to.
+ *
+ * @param prefix What comes before the name.
+ * @param typeName The name shown.
+ * @param postfix What comes after the name.
+ * @param linkTo The bookmark to link to.
+ * @param withHyperlink Whether to link at all.
+ * @return the content of a cell.
+ */
+ public static String hyperlink(String prefix, String typeName, String postfix,
+ String linkTo, boolean withHyperlink) {
+ // An object reference is shown as ObjectRef_Product_, but what is linked to is
+ // Product: the reference is not a type anyone documents.
+ boolean isObjectRef = typeName.startsWith("ObjectRef");
+ String target = linkTo.replace("ObjectRef<", "").replace(">", "")
+ .replace("ObjectRef(", "").replace(")", "");
+ String shown = isObjectRef ? insideObjectRef(typeName) : typeName;
+
+ StringBuilder buf = new StringBuilder();
+ buf.append("<w:pPr><w:pStyle w:val=\"MOTable\"/></w:pPr><w:r><w:t>");
+ buf.append(DocxText.escape(prefix));
+ if (isObjectRef) {
+ buf.append(DocxText.escape("ObjectRef<"));
+ }
+ buf.append("</w:t></w:r>");
+
+ if (withHyperlink) {
+ buf.append("<w:r><w:fldChar w:fldCharType=\"begin\"/></w:r>");
+ buf.append("<w:r><w:instrText xml:space=\"preserve\"> HYPERLINK \\l \"");
+ buf.append(DocxText.escape(isObjectRef ? target : linkTo));
+ buf.append("\" </w:instrText></w:r>");
+ buf.append("<w:r><w:fldChar w:fldCharType=\"separate\"/></w:r>");
+ }
+
+ buf.append("<w:r>");
+ if (withHyperlink) {
+ buf.append("<w:rPr><w:rStyle w:val=\"Hyperlink\"/></w:rPr>");
+ }
+ buf.append("<w:t>").append(DocxText.escape(shown)).append("</w:t></w:r>");
+
+ if (withHyperlink) {
+ buf.append("<w:r><w:fldChar w:fldCharType=\"end\"/></w:r>");
+ }
+
+ buf.append("<w:r><w:t xml:space=\"preserve\">");
+ if (isObjectRef) {
+ buf.append(DocxText.escape(">"));
+ }
+ return buf.append(DocxText.escape(postfix)).append("</w:t></w:r>").toString();
+ }
+
+ /**
+ * @param typeName A name of the form ObjectRef_Something_.
+ * @return what the reference points at.
+ */
+ private static String insideObjectRef(String typeName) {
+ int open = typeName.indexOf('<');
+ int close = typeName.lastIndexOf('>');
+ return open >= 0 && close > open ? typeName.substring(open + 1, close) : typeName;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaClassBuilder.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaClassBuilder.java
new file mode 100644
index 00000000..c9d96950
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaClassBuilder.java
@@ -0,0 +1,196 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * One Java class, from its package statement to its closing brace.
+ * <p>
+ * The outermost of the three builders. {@link #open} writes the package statement, the
+ * javadoc and the declaration and hands back the source to write the members into;
+ * {@link #close} writes the brace that ends the class and returns the finished text. The
+ * members in between are written with {@link JavaFieldBuilder} and
+ * {@link JavaMethodBuilder}, which is why the class does not hold them itself: a writer
+ * decides what goes in and in what order, and this decides how the class around them reads.
+ * <p>
+ * Every class this generator writes is public, so there is nothing to say about scope.
+ */
+public final class JavaClassBuilder {
+
+ private final String name;
+
+ private final List<String> interfaces = new ArrayList<String>();
+
+ private final JavaSource out = new JavaSource();
+
+ private String packageName = null;
+
+ private String comment = null;
+
+ private String superClass = null;
+
+ private boolean isFinal = false;
+
+ private boolean isAbstract = false;
+
+ private boolean isInterface = false;
+
+ private JavaClassBuilder(String name) {
+ this.name = name;
+ }
+
+ /**
+ * @param name The name of the class.
+ * @return a public class, extending nothing and implementing nothing.
+ */
+ public static JavaClassBuilder named(String name) {
+ return new JavaClassBuilder(name);
+ }
+
+ /**
+ * Sets the package the class belongs to.
+ *
+ * @param name The package name.
+ * @return this class.
+ */
+ public JavaClassBuilder inPackage(String name) {
+ this.packageName = name;
+ return this;
+ }
+
+ /**
+ * Sets the comment of the class.
+ *
+ * @param text The comment, may be null.
+ * @return this class.
+ */
+ public JavaClassBuilder comment(String text) {
+ this.comment = text;
+ return this;
+ }
+
+ /**
+ * Sets the class this one extends.
+ *
+ * @param type The super class.
+ * @return this class.
+ */
+ public JavaClassBuilder extending(String type) {
+ this.superClass = type;
+ return this;
+ }
+
+ /**
+ * Adds an interface the class implements, in order.
+ *
+ * @param type The interface.
+ * @return this class.
+ */
+ public JavaClassBuilder implementing(String type) {
+ interfaces.add(type);
+ return this;
+ }
+
+ /**
+ * @return this class, marked final.
+ */
+ public JavaClassBuilder asFinal() {
+ this.isFinal = true;
+ return this;
+ }
+
+ /**
+ * @return this class, marked abstract.
+ */
+ public JavaClassBuilder asAbstract() {
+ this.isAbstract = true;
+ return this;
+ }
+
+ /**
+ * Marks this as an interface rather than a class. Its members are declarations, so they
+ * are written packed together rather than a blank line apart, and the blank line that
+ * separates them from the declaration is written here instead.
+ *
+ * @return this class.
+ */
+ public JavaClassBuilder asInterface() {
+ this.isInterface = true;
+ return this;
+ }
+
+ /**
+ * Writes everything down to the brace that opens the class.
+ *
+ * @return the source to write the members into.
+ */
+ public JavaSource open() {
+ out.line("package " + packageName + ";");
+ out.blank();
+
+ List<String> lines = JavaComment.normaliseInClass(comment);
+ if (!lines.isEmpty()) {
+ out.line("/**");
+ for (String line : lines) {
+ out.line(" * " + line);
+ }
+ out.line(" */");
+ }
+
+ StringBuilder buf = new StringBuilder("public ");
+ if (isFinal) {
+ buf.append("final ");
+ }
+ if (isAbstract) {
+ buf.append("abstract ");
+ }
+ buf.append(isInterface ? "interface " : "class ").append(name);
+ if (superClass != null) {
+ buf.append(" extends ").append(superClass);
+ }
+ for (int i = 0; i < interfaces.size(); i++) {
+ // An interface extends what a class implements.
+ buf.append(i == 0 ? (isInterface ? " extends " : " implements ") : ", ")
+ .append(interfaces.get(i));
+ }
+ out.line(buf.append(" {").toString());
+ if (isInterface) {
+ out.blank();
+ }
+ return out;
+ }
+
+ /**
+ * Writes the brace that ends the class, under the blank line that separates it from the
+ * last member. An interface has no such line: its declarations are packed.
+ *
+ * @return the finished source.
+ */
+ public String close() {
+ if (!isInterface) {
+ out.blank();
+ }
+ out.line("}");
+ return out.toString();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaComment.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaComment.java
new file mode 100644
index 00000000..6fb5bb73
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaComment.java
@@ -0,0 +1,124 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Turns a specification comment into javadoc lines.
+ * <p>
+ * This reproduces the existing generator's behaviour exactly, including where that
+ * behaviour is odd, because the generated API is compiled against by every api module and
+ * its javadoc is part of what people read. Two quirks are deliberate:
+ * <ul>
+ * <li>an apostrophe becomes {@code "} rather than {@code '};</li>
+ * <li>an angle bracket becomes an underscore, so a comment mentioning {@code >=} reads
+ * {@code _=};</li>
+ * <li>the line-length check happens before a word is added rather than after, so lines
+ * routinely run past the threshold - up to 92 characters in the current output.</li>
+ * </ul>
+ * Changing either would be an improvement, and would show up in the golden tree as a
+ * deliberate difference to be agreed rather than something to slip in here.
+ */
+public final class JavaComment {
+
+ private static final int LENGTH_THRESHOLD = 70;
+
+ private JavaComment() {
+ }
+
+ /**
+ * Normalises a comment into the lines of a javadoc block.
+ *
+ * @param comment The comment, may be null.
+ * @return the lines, empty if there is no comment.
+ */
+ public static List<String> normalise(String comment) {
+ List<String> output = new ArrayList<String>();
+ if (comment == null || comment.isEmpty()) {
+ return output;
+ }
+ String text = comment;
+ if (!text.endsWith(".")) {
+ text += ".";
+ }
+ text = text.replace("&", "&");
+ text = text.replace("'", """);
+ output.addAll(wrap(text));
+ return output;
+ }
+
+ /**
+ * Normalises a comment for a javadoc block inside a class, where angle brackets would
+ * be read as markup. Package documentation goes through {@link #normalise} instead and
+ * keeps its {@code <ul>} and {@code <li>} tags.
+ *
+ * @param comment The comment, may be null.
+ * @return the lines, empty if there is no comment.
+ */
+ public static List<String> normaliseInClass(String comment) {
+ List<String> output = new ArrayList<String>();
+ for (String line : normalise(comment)) {
+ output.add(escape(line));
+ }
+ return output;
+ }
+
+ /**
+ * Removes the angle brackets that would otherwise be read as javadoc markup.
+ *
+ * @param text The comment text.
+ * @return the text with angle brackets replaced by underscores.
+ */
+ public static String escape(String text) {
+ return text == null ? null : text.replace("<", "_").replace(">", "_");
+ }
+
+ /**
+ * Breaks text into lines at roughly the threshold, paragraph by paragraph.
+ *
+ * @param text The text to wrap.
+ * @return the lines.
+ */
+ public static List<String> wrap(String text) {
+ List<String> output = new ArrayList<String>();
+ if (text.length() < LENGTH_THRESHOLD) {
+ output.add(text);
+ return output;
+ }
+ for (String paragraph : text.split("\n")) {
+ StringBuilder line = new StringBuilder();
+ int counter = 0;
+ for (String word : paragraph.split(" ")) {
+ if (counter > LENGTH_THRESHOLD) {
+ output.add(line.toString().trim());
+ line.setLength(0);
+ counter = 0;
+ }
+ line.append(word).append(' ');
+ counter += 1 + word.length();
+ }
+ output.add(line.toString().trim());
+ }
+ return output;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaFieldBuilder.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaFieldBuilder.java
new file mode 100644
index 00000000..131074d8
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaFieldBuilder.java
@@ -0,0 +1,190 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import java.util.List;
+
+/**
+ * One Java field, from its javadoc to its semicolon.
+ * <p>
+ * The counterpart of {@link JavaMethodBuilder}, and built the same way: the comment is held
+ * with the declaration it documents, and {@code write} is the only thing that produces
+ * text. A value spanning more than one line is written as it is given, so the caller that
+ * lays out an array lays out its own continuation, as it does for the body of a method.
+ */
+public final class JavaFieldBuilder {
+
+ /**
+ * The step a field takes past the class.
+ */
+ private static final String INDENT = " ";
+
+ private final String name;
+
+ private String scope = "public";
+
+ private String type = null;
+
+ private String value = null;
+
+ private String comment = null;
+
+ private boolean isStatic = false;
+
+ private boolean isFinal = false;
+
+ private boolean isDeprecated = false;
+
+ private boolean joined = false;
+
+ private JavaFieldBuilder(String name) {
+ this.name = name;
+ }
+
+ /**
+ * @param name The name of the field.
+ * @return a public field, with no type yet and no value.
+ */
+ public static JavaFieldBuilder named(String name) {
+ return new JavaFieldBuilder(name);
+ }
+
+ /**
+ * Sets the scope. Public unless said otherwise.
+ *
+ * @param scope The scope keyword.
+ * @return this field.
+ */
+ public JavaFieldBuilder scope(String scope) {
+ this.scope = scope;
+ return this;
+ }
+
+ /**
+ * Sets the declared type.
+ *
+ * @param typeName The type of the field.
+ * @return this field.
+ */
+ public JavaFieldBuilder ofType(String typeName) {
+ this.type = typeName;
+ return this;
+ }
+
+ /**
+ * Sets what the field is initialised to. A field with no value is declared and left
+ * unset.
+ *
+ * @param expression The initialiser, which may span several lines.
+ * @return this field.
+ */
+ public JavaFieldBuilder value(String expression) {
+ this.value = expression;
+ return this;
+ }
+
+ /**
+ * Sets the comment of the field.
+ *
+ * @param text The comment, may be null.
+ * @return this field.
+ */
+ public JavaFieldBuilder comment(String text) {
+ this.comment = text;
+ return this;
+ }
+
+ /**
+ * @return this field, marked static.
+ */
+ public JavaFieldBuilder asStatic() {
+ this.isStatic = true;
+ return this;
+ }
+
+ /**
+ * @return this field, marked final.
+ */
+ public JavaFieldBuilder asFinal() {
+ this.isFinal = true;
+ return this;
+ }
+
+ /**
+ * @return this field, marked deprecated.
+ */
+ public JavaFieldBuilder asDeprecated() {
+ this.isDeprecated = true;
+ return this;
+ }
+
+ /**
+ * Writes the field directly under the one before it, with no blank line between them.
+ * The reference output keeps the fields that carry a type's identity together as one
+ * block, and separates everything else.
+ *
+ * @return this field.
+ */
+ public JavaFieldBuilder joinedToPrevious() {
+ this.joined = true;
+ return this;
+ }
+
+ /**
+ * Writes the field, preceded by the blank line that separates it from what came before
+ * it unless it was asked to stay with it.
+ *
+ * @param out The source to write to.
+ */
+ public void write(JavaSource out) {
+ if (!joined) {
+ out.blank();
+ }
+
+ List<String> lines = JavaComment.normaliseInClass(comment);
+ if (!lines.isEmpty()) {
+ out.line(INDENT + "/**");
+ for (String line : lines) {
+ out.line(INDENT + " * " + line);
+ }
+ out.line(INDENT + " */");
+ }
+
+ if (isDeprecated) {
+ out.line(INDENT + "@Deprecated");
+ }
+
+ StringBuilder buf = new StringBuilder(INDENT);
+ buf.append(scope).append(' ');
+ if (isStatic) {
+ buf.append("static ");
+ }
+ if (isFinal) {
+ buf.append("final ");
+ }
+ buf.append(type).append(' ').append(name);
+ if (value != null) {
+ buf.append(" = ").append(value);
+ }
+ buf.append(';');
+ out.line(buf.toString());
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaGenerator.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaGenerator.java
new file mode 100644
index 00000000..19ffe2fb
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaGenerator.java
@@ -0,0 +1,315 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import esa.mo.apigen.generators.Generator;
+import esa.mo.apigen.generators.java.writers.CompositeWriter;
+import esa.mo.apigen.generators.java.writers.ConsumerAdapterWriter;
+import esa.mo.apigen.generators.java.writers.ConsumerStubWriter;
+import esa.mo.apigen.generators.java.writers.ElementFactoryWriter;
+import esa.mo.apigen.generators.java.writers.EnumerationWriter;
+import esa.mo.apigen.generators.java.writers.ExceptionWriter;
+import esa.mo.apigen.generators.java.writers.HelperWriter;
+import esa.mo.apigen.generators.java.writers.ListWriter;
+import esa.mo.apigen.generators.java.writers.MultiReturnBodyWriter;
+import esa.mo.apigen.generators.java.writers.ProviderHandlerWriter;
+import esa.mo.apigen.generators.java.writers.ProviderInheritanceSkeletonWriter;
+import esa.mo.apigen.generators.java.writers.ProviderInteractionWriter;
+import esa.mo.apigen.generators.java.writers.ProviderPublisherWriter;
+import esa.mo.apigen.generators.java.writers.ProviderSkeletonWriter;
+import esa.mo.apigen.generators.java.writers.ServiceInfoWriter;
+import esa.mo.apigen.generators.java.writers.SubscriptionKeysWriter;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import java.io.IOException;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * Generates the Java API.
+ * <p>
+ * Written against the model directly. The old generator is the reference for what comes
+ * out - the generated API is compiled against by every api module and by user code, so
+ * its shape is a compatibility surface - but not for how it is produced.
+ * <p>
+ * Incomplete: it writes the structures, the exceptions, the helpers, the element factories
+ * and the package documentation - verified byte for byte against the reference output. The
+ * provider skeletons, the consumer stubs, the {@code ServiceInfo} classes and the
+ * multiple-return bodies are still to come; the last of those also brings the two
+ * {@code package-info.java} files that the old generator writes as a side effect of it.
+ */
+public final class JavaGenerator implements Generator {
+
+ private static final Charset UTF8 = Charset.forName("UTF-8");
+
+ @Override
+ public String getShortName() {
+ return "Java";
+ }
+
+ @Override
+ public String getDescription() {
+ return "Generates the Java API for a set of MO service specifications";
+ }
+
+ @Override
+ public void generate(MOModel model, List<Area> targets, Path outputDir) throws IOException {
+ for (Area area : targets) {
+ generateArea(model, area, outputDir);
+ }
+ }
+
+ private void generateArea(MOModel model, Area area, Path outputDir) throws IOException {
+ PackageInfoWriter packages = new PackageInfoWriter(outputDir);
+ // An area without a comment still gets one: the package documentation would
+ // otherwise be an empty javadoc block.
+ String areaComment = area.getComment() != null && !area.getComment().isEmpty()
+ ? area.getComment() : "The " + area.getName() + " area";
+ packages.write(JavaNaming.packageOf(area), areaComment);
+ if (!area.getDataTypes().isEmpty()) {
+ packages.write(JavaNaming.packageOf(area, JavaNaming.STRUCTURES),
+ "Package containing types defined in the " + area.getName() + " area");
+ }
+ writeTypes(model, area, null, area.getDataTypes(), outputDir);
+ writeExceptions(area, outputDir);
+ writeHelpers(area, outputDir);
+ writeElementFactory(area, outputDir);
+ for (Service service : area.getServices()) {
+ writeTypes(model, area, service, service.getDataTypes(), outputDir);
+ writeServiceInfo(model, area, service, outputDir);
+ writeSubscriptionKeys(model, service, outputDir);
+ writeConsumer(model, area, service, outputDir);
+ writeProvider(model, service, outputDir);
+ writeMultiReturnBodies(model, service, packages, outputDir);
+ packages.write(JavaNaming.packageOf(service), service.getComment());
+ packages.write(JavaNaming.packageOf(service, JavaNaming.CONSUMER),
+ "Package containing the consumer stubs for the "
+ + service.getName() + " service");
+ packages.write(JavaNaming.packageOf(service, JavaNaming.PROVIDER),
+ "Package containing the provider skeletons for the "
+ + service.getName() + " service");
+ if (!service.getDataTypes().isEmpty()) {
+ packages.write(JavaNaming.packageOf(service, JavaNaming.STRUCTURES),
+ "Package containing types defined in the "
+ + service.getName() + " service");
+ }
+ }
+ }
+
+ /**
+ * Every error the area declares becomes an exception in the area's own package,
+ * whether it was declared by the area or by one of its services.
+ */
+ private void writeExceptions(Area area, Path outputDir) throws IOException {
+ java.util.List<esa.mo.apigen.model.ErrorDefinition> errors
+ = new java.util.ArrayList<esa.mo.apigen.model.ErrorDefinition>(area.getErrors());
+ for (Service service : area.getServices()) {
+ errors.addAll(service.getErrors());
+ }
+ if (errors.isEmpty()) {
+ return;
+ }
+ Path dir = outputDir.resolve(JavaNaming.directoryOf(JavaNaming.packageOf(area)));
+ Files.createDirectories(dir);
+ for (esa.mo.apigen.model.ErrorDefinition error : errors) {
+ Files.write(dir.resolve(ExceptionWriter.classNameOf(error.getName()) + ".java"),
+ ExceptionWriter.write(area, error).getBytes(UTF8));
+ }
+ }
+
+ /**
+ * The area's helper, and one for each of its services.
+ */
+ private void writeHelpers(Area area, Path outputDir) throws IOException {
+ Path areaDir = outputDir.resolve(JavaNaming.directoryOf(JavaNaming.packageOf(area)));
+ Files.createDirectories(areaDir);
+ Files.write(areaDir.resolve(area.getName() + "Helper.java"),
+ HelperWriter.writeArea(area).getBytes(UTF8));
+ for (Service service : area.getServices()) {
+ Path dir = outputDir.resolve(JavaNaming.directoryOf(JavaNaming.packageOf(service)));
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(service.getName() + "Helper.java"),
+ HelperWriter.writeService(service).getBytes(UTF8));
+ }
+ }
+
+ /**
+ * The factory that creates the Elements of the area, one per area.
+ */
+ private void writeElementFactory(Area area, Path outputDir) throws IOException {
+ Path dir = outputDir.resolve(JavaNaming.directoryOf(JavaNaming.packageOf(area)));
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(area.getName() + "ElementFactory.java"),
+ ElementFactoryWriter.write(area).getBytes(UTF8));
+ }
+
+ /**
+ * The ServiceInfo of a service, which is what its stubs and skeletons name their
+ * operations through.
+ */
+ private void writeServiceInfo(MOModel model, Area area, Service service, Path outputDir)
+ throws IOException {
+ Path dir = outputDir.resolve(JavaNaming.directoryOf(JavaNaming.packageOf(service)));
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(service.getName() + "ServiceInfo.java"),
+ ServiceInfoWriter.write(model, area, service).getBytes(UTF8));
+ }
+
+ /**
+ * One class per publish-subscribe operation, for reading the keys of a notify message.
+ */
+ private void writeSubscriptionKeys(MOModel model, Service service, Path outputDir)
+ throws IOException {
+ Path dir = outputDir.resolve(
+ JavaNaming.directoryOf(JavaNaming.packageOf(service, JavaNaming.CONSUMER)));
+ for (esa.mo.apigen.model.Operation operation : service.getOperations()) {
+ if (operation.getPattern() != esa.mo.apigen.model.InteractionPattern.PUBSUB) {
+ continue;
+ }
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(SubscriptionKeysWriter.classNameOf(operation) + ".java"),
+ SubscriptionKeysWriter.write(model, service, operation).getBytes(UTF8));
+ }
+ }
+
+ /**
+ * The consumer stub of a service, and the adapter its answers arrive through.
+ */
+ private void writeConsumer(MOModel model, Area area, Service service, Path outputDir)
+ throws IOException {
+ Path dir = outputDir.resolve(
+ JavaNaming.directoryOf(JavaNaming.packageOf(service, JavaNaming.CONSUMER)));
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(service.getName() + "Stub.java"),
+ ConsumerStubWriter.write(model, service).getBytes(UTF8));
+ Files.write(dir.resolve(service.getName() + "Adapter.java"),
+ ConsumerAdapterWriter.write(model, area, service).getBytes(UTF8));
+ }
+
+ /**
+ * The provider side of a service: what a provider implements, and how it reaches its
+ * publishers.
+ */
+ private void writeProvider(MOModel model, Service service, Path outputDir)
+ throws IOException {
+ Path dir = outputDir.resolve(
+ JavaNaming.directoryOf(JavaNaming.packageOf(service, JavaNaming.PROVIDER)));
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(service.getName() + "Handler.java"),
+ ProviderHandlerWriter.write(model, service).getBytes(UTF8));
+ Files.write(dir.resolve(service.getName() + "Skeleton.java"),
+ ProviderSkeletonWriter.write(service).getBytes(UTF8));
+ Files.write(dir.resolve(service.getName() + "InheritanceSkeleton.java"),
+ ProviderInheritanceSkeletonWriter.write(model, service).getBytes(UTF8));
+ // An operation that reports back over time is answered through an object of its
+ // own, so that what it can send is named and typed.
+ for (esa.mo.apigen.model.Operation operation : service.getOperations()) {
+ if (operation.getPattern() == esa.mo.apigen.model.InteractionPattern.INVOKE
+ || operation.getPattern() == esa.mo.apigen.model.InteractionPattern.PROGRESS) {
+ Files.write(dir.resolve(ProviderInteractionWriter.classNameOf(operation) + ".java"),
+ ProviderInteractionWriter.write(model, service, operation).getBytes(UTF8));
+ }
+ if (operation.getPattern() == esa.mo.apigen.model.InteractionPattern.PUBSUB) {
+ Files.write(dir.resolve(ProviderPublisherWriter.classNameOf(operation) + ".java"),
+ ProviderPublisherWriter.write(model, service, operation).getBytes(UTF8));
+ }
+ }
+ }
+
+ /**
+ * An operation that answers with more than one field needs a class to hold the answer,
+ * since a Java method can only return one thing.
+ */
+ private void writeMultiReturnBodies(MOModel model, Service service,
+ PackageInfoWriter packages, Path outputDir) throws IOException {
+ java.util.List<esa.mo.apigen.model.Operation> operations
+ = MultiReturnBodyWriter.operationsOf(service);
+ if (operations.isEmpty()) {
+ return;
+ }
+ String pkg = JavaNaming.packageOf(service, MultiReturnBodyWriter.BODY);
+ packages.write(pkg, "Package containing the types for holding compound messages");
+ Path dir = outputDir.resolve(JavaNaming.directoryOf(pkg));
+ Files.createDirectories(dir);
+ for (esa.mo.apigen.model.Operation operation : operations) {
+ Files.write(dir.resolve(MultiReturnBodyWriter.classNameOf(operation) + ".java"),
+ MultiReturnBodyWriter.write(model, service, operation).getBytes(UTF8));
+ }
+ }
+
+ private void writeTypes(MOModel model, Area area, Service service,
+ java.util.List<TypeDefinition> types, Path outputDir) throws IOException {
+ String pkg = service == null
+ ? JavaNaming.packageOf(area, JavaNaming.STRUCTURES)
+ : JavaNaming.packageOf(service, JavaNaming.STRUCTURES);
+ Path dir = outputDir.resolve(JavaNaming.directoryOf(pkg));
+ for (TypeDefinition type : types) {
+ if (type instanceof EnumerationType) {
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(type.getName() + ".java"),
+ EnumerationWriter.write(area, service, (EnumerationType) type)
+ .getBytes(UTF8));
+ }
+ if (type instanceof CompositeType) {
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(type.getName() + ".java"),
+ CompositeWriter.write(model, area, service, (CompositeType) type)
+ .getBytes(UTF8));
+ }
+ String list = ListWriter.write(area, service, type);
+ if (list != null) {
+ Files.createDirectories(dir);
+ Files.write(dir.resolve(type.getName() + "List.java"), list.getBytes(UTF8));
+ }
+ }
+ }
+
+ /**
+ * Writes the package-info.java files.
+ */
+ private static final class PackageInfoWriter {
+
+ private final Path root;
+
+ private PackageInfoWriter(Path root) {
+ this.root = root;
+ }
+
+ private void write(String packageName, String comment) throws IOException {
+ Path dir = root.resolve(JavaNaming.directoryOf(packageName));
+ Files.createDirectories(dir);
+ StringBuilder buf = new StringBuilder();
+ buf.append("/**\n");
+ for (String line : JavaComment.normalise(comment)) {
+ buf.append(" * ").append(line).append('\n');
+ }
+ buf.append("*/\n");
+ buf.append("package ").append(packageName).append(";\n");
+ Files.write(dir.resolve("package-info.java"), buf.toString().getBytes(UTF8));
+ }
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaMethodBuilder.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaMethodBuilder.java
new file mode 100644
index 00000000..121311d3
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaMethodBuilder.java
@@ -0,0 +1,378 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * One Java method, from its javadoc to its closing brace.
+ * <p>
+ * Written out in the order the pieces are declared here rather than in the order they end
+ * up on the page: an argument is given with the description that documents it, so the
+ * {@code @param} block and the signature cannot drift apart, and the body is held with the
+ * signature so that a method is one expression from end to end.
+ * <p>
+ * Everything a method can be is set through the same object, so a writer never has to
+ * decide between "the one with the comment" and "the one that overrides". A method the
+ * language has no word for - a static override, say - is simply never asked for.
+ */
+public final class JavaMethodBuilder {
+
+ /**
+ * The step a method takes past the class, and the step its body takes past it.
+ */
+ private static final String INDENT = " ";
+
+ private static final String BODY_INDENT = INDENT + INDENT;
+
+ /**
+ * Arguments past the first are carried onto their own line, at the step the reference
+ * output uses regardless of how long the signature is.
+ */
+ private static final String ARGUMENT_INDENT = " ";
+
+ private final String name;
+
+ private final List<Argument> arguments = new ArrayList<Argument>();
+
+ private final List<Thrown> thrown = new ArrayList<Thrown>();
+
+ private final List<String> body = new ArrayList<String>();
+
+ private String scope = "public";
+
+ private String returnType = null;
+
+ private String returnComment = null;
+
+ private String comment = null;
+
+ private boolean constructor = false;
+
+ private boolean isStatic = false;
+
+ private boolean isFinal = false;
+
+ private boolean isOverride = false;
+
+ private boolean isDeprecated = false;
+
+ private boolean declarationOnly = false;
+
+ private JavaMethodBuilder(String name) {
+ this.name = name;
+ }
+
+ /**
+ * @param name The name of the method.
+ * @return a method that returns nothing, is public, and has no arguments.
+ */
+ public static JavaMethodBuilder named(String name) {
+ return new JavaMethodBuilder(name);
+ }
+
+ /**
+ * @param className The name of the class being constructed.
+ * @return a constructor, which is written without a return type.
+ */
+ public static JavaMethodBuilder constructor(String className) {
+ JavaMethodBuilder method = new JavaMethodBuilder(className);
+ method.constructor = true;
+ return method;
+ }
+
+ /**
+ * Sets the scope. Public unless said otherwise.
+ *
+ * @param scope The scope keyword.
+ * @return this method.
+ */
+ public JavaMethodBuilder scope(String scope) {
+ this.scope = scope;
+ return this;
+ }
+
+ /**
+ * Sets what the method returns. Void unless said otherwise.
+ *
+ * @param type The returned type.
+ * @param description What is returned, or null to leave it undocumented.
+ * @return this method.
+ */
+ public JavaMethodBuilder returns(String type, String description) {
+ this.returnType = type;
+ this.returnComment = description;
+ return this;
+ }
+
+ /**
+ * Adds an argument, in declaration order, with the description that documents it.
+ *
+ * @param type The type of the argument.
+ * @param argumentName The name of the argument.
+ * @param description What the argument is, or null for a plain description of it.
+ * @return this method.
+ */
+ public JavaMethodBuilder argument(String type, String argumentName,
+ String description) {
+ arguments.add(new Argument(type, argumentName, description));
+ return this;
+ }
+
+ /**
+ * Adds a thrown type, in order, with the description that documents it.
+ *
+ * @param type The thrown type.
+ * @param description When it is thrown, or null to leave it undocumented.
+ * @return this method.
+ */
+ public JavaMethodBuilder throwing(String type, String description) {
+ thrown.add(new Thrown(type, description));
+ return this;
+ }
+
+ /**
+ * Sets the comment of the method.
+ *
+ * @param text The comment, may be null.
+ * @return this method.
+ */
+ public JavaMethodBuilder comment(String text) {
+ this.comment = text;
+ return this;
+ }
+
+ /**
+ * @return this method, marked static.
+ */
+ public JavaMethodBuilder asStatic() {
+ this.isStatic = true;
+ return this;
+ }
+
+ /**
+ * @return this method, marked final.
+ */
+ public JavaMethodBuilder asFinal() {
+ this.isFinal = true;
+ return this;
+ }
+
+ /**
+ * Marks the method as overriding another, which carries the annotation.
+ *
+ * @return this method.
+ */
+ public JavaMethodBuilder asOverride() {
+ this.isOverride = true;
+ return this;
+ }
+
+ /**
+ * @return this method, marked deprecated.
+ */
+ public JavaMethodBuilder asDeprecated() {
+ this.isDeprecated = true;
+ return this;
+ }
+
+ /**
+ * Marks the method as a declaration without a body, for an interface. The scope goes
+ * unwritten: an interface method has no keyword in front of it.
+ *
+ * @return this method.
+ */
+ public JavaMethodBuilder asDeclaration() {
+ this.declarationOnly = true;
+ return this;
+ }
+
+ /**
+ * Adds a line to the body, indented past the method. A line that steps further in says
+ * so itself, as the reference output does.
+ *
+ * @param text The line, without the indentation of the body.
+ * @return this method.
+ */
+ public JavaMethodBuilder line(String text) {
+ body.add(text);
+ return this;
+ }
+
+ /**
+ * Adds the lines of the body, in order.
+ *
+ * @param lines The lines, without the indentation of the body.
+ * @return this method.
+ */
+ public JavaMethodBuilder lines(List<String> lines) {
+ body.addAll(lines);
+ return this;
+ }
+
+ /**
+ * Writes the method, preceded by the blank line that separates it from what came
+ * before it. A declaration has no such line.
+ *
+ * @param out The source to write to.
+ */
+ public void write(JavaSource out) {
+ // A declaration follows the one before it without a gap, the way an interface reads
+ // in the reference output.
+ if (!declarationOnly) {
+ out.blank();
+ }
+ writeComment(out);
+ if (isDeprecated) {
+ out.line(INDENT + "@Deprecated");
+ }
+ if (isOverride) {
+ out.line(INDENT + "@Override");
+ }
+ out.line(INDENT + signature());
+ if (declarationOnly) {
+ return;
+ }
+ for (String line : body) {
+ out.line(line.isEmpty() ? "" : BODY_INDENT + line);
+ }
+ out.line(INDENT + "}");
+ }
+
+ /**
+ * Writes the javadoc, which is left out entirely when there would be nothing in it.
+ * <p>
+ * An override is never documented: it says the same thing as the method it overrides,
+ * and javadoc carries that documentation down on its own.
+ */
+ private void writeComment(JavaSource out) {
+ if (isOverride) {
+ return;
+ }
+
+ List<String> lines = JavaComment.normaliseInClass(comment);
+ List<String> tags = new ArrayList<String>();
+
+ for (Argument argument : arguments) {
+ tags.add("@param " + argument.name + " " + argument.describe());
+ }
+ if (returnComment != null && !returnComment.isEmpty()) {
+ tags.add("@return " + returnComment);
+ }
+ for (Thrown item : thrown) {
+ if (item.description != null && !item.description.isEmpty()) {
+ tags.add("@throws " + item.type + " " + item.description);
+ }
+ }
+ if (lines.isEmpty() && tags.isEmpty()) {
+ return;
+ }
+
+ out.line(INDENT + "/**");
+ for (String line : lines) {
+ out.line(INDENT + " * " + line);
+ }
+ // The blank line stands between the description and the tags whether or not there
+ // is a description above it, which is what the reference output does.
+ out.line(INDENT + " * ");
+ for (String tag : tags) {
+ out.line(INDENT + " * " + JavaComment.escape(tag));
+ }
+ out.line(INDENT + " */");
+ }
+
+ /**
+ * @return the signature, from the scope to the brace that opens the body.
+ */
+ private String signature() {
+ StringBuilder buf = new StringBuilder();
+
+ if (!declarationOnly) {
+ // An override is public whatever else it is: so is the method it overrides
+ buf.append(isOverride ? "public" : scope).append(' ');
+ }
+ if (isStatic) {
+ buf.append("static ");
+ }
+ if (isFinal) {
+ buf.append("final ");
+ }
+ if (!constructor) {
+ buf.append(returnType == null ? "void" : returnType).append(' ');
+ }
+
+ buf.append(name).append('(');
+ for (int i = 0; i < arguments.size(); i++) {
+ if (i != 0) {
+ buf.append(",\n").append(ARGUMENT_INDENT);
+ }
+ Argument argument = arguments.get(i);
+ buf.append(argument.type).append(' ').append(argument.name);
+ }
+ buf.append(')');
+
+ for (int i = 0; i < thrown.size(); i++) {
+ buf.append(i == 0 ? " throws " : ", ").append(thrown.get(i).type);
+ }
+
+ buf.append(declarationOnly ? ";" : " {");
+ return buf.toString();
+ }
+
+ /**
+ * One argument, held with the description that documents it.
+ */
+ private static final class Argument {
+
+ private final String type;
+ private final String name;
+ private final String description;
+
+ private Argument(String type, String name, String description) {
+ this.type = type;
+ this.name = name;
+ this.description = description;
+ }
+
+ /**
+ * @return the description, or a plain one naming the argument.
+ */
+ private String describe() {
+ return (description == null || description.isEmpty())
+ ? "The " + name + " field." : description;
+ }
+ }
+
+ /**
+ * One thrown type, held with the description that documents it.
+ */
+ private static final class Thrown {
+
+ private final String type;
+ private final String description;
+
+ private Thrown(String type, String description) {
+ this.type = type;
+ this.description = description;
+ }
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaNaming.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaNaming.java
new file mode 100644
index 00000000..270de2a6
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaNaming.java
@@ -0,0 +1,85 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Service;
+
+/**
+ * Where generated Java lands: package names and their directories.
+ */
+public final class JavaNaming {
+
+ /**
+ * The root package of every generated API.
+ */
+ public static final String ROOT = "org.ccsds.moims.mo.";
+ /**
+ * The folder that holds an area's or a service's data types.
+ */
+ public static final String STRUCTURES = "structures";
+ /**
+ * The MAL area's package. Generated code refers to it constantly - every element,
+ * encoder and type id lives there - so it is named once here.
+ */
+ public static final String MAL = ROOT + "mal.";
+ /**
+ * The package holding the MAL's own data types.
+ */
+ public static final String MAL_STRUCTURES = MAL + STRUCTURES + ".";
+ /**
+ * The folder that holds a service's consumer stubs.
+ */
+ public static final String CONSUMER = "consumer";
+ /**
+ * The folder that holds a service's provider skeletons.
+ */
+ public static final String PROVIDER = "provider";
+
+ private JavaNaming() {
+ }
+
+ public static String packageOf(Area area) {
+ return ROOT + area.getName().toLowerCase();
+ }
+
+ public static String packageOf(Area area, String folder) {
+ return packageOf(area) + "." + folder;
+ }
+
+ public static String packageOf(Service service) {
+ return packageOf(service.getArea()) + "." + service.getName().toLowerCase();
+ }
+
+ public static String packageOf(Service service, String folder) {
+ return packageOf(service) + "." + folder;
+ }
+
+ /**
+ * Returns the directory a package maps to, relative to the output root.
+ *
+ * @param packageName The package.
+ * @return the relative path, using '/' as separator.
+ */
+ public static String directoryOf(String packageName) {
+ return packageName.replace('.', '/');
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaSource.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaSource.java
new file mode 100644
index 00000000..17d473e8
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaSource.java
@@ -0,0 +1,85 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+/**
+ * Accumulates the text of a Java source file.
+ */
+public final class JavaSource {
+
+ private final StringBuilder buf = new StringBuilder();
+
+ public void line(String text) {
+ buf.append(text).append('\n');
+ }
+
+ public void blank() {
+ buf.append('\n');
+ }
+
+ /**
+ * Writes a single-line javadoc block at the given indentation.
+ *
+ * @param indent Number of four-space levels.
+ * @param text The comment, already normalised.
+ */
+ public void javadoc(int indent, String text) {
+ String pad = pad(indent);
+ line(pad + "/**");
+ line(pad + " * " + JavaComment.escape(text));
+ line(pad + " */");
+ }
+
+ private static String pad(int indent) {
+ StringBuilder p = new StringBuilder();
+ for (int i = 0; i < indent; i++) {
+ p.append(" ");
+ }
+ return p.toString();
+ }
+
+ /**
+ * @return the last line written, without its line separator.
+ */
+ public String lastLine() {
+ int end = buf.length() - 1;
+ int start = buf.lastIndexOf("\n", end - 1) + 1;
+ return buf.substring(start, end);
+ }
+
+ /**
+ * Replaces the last line written, for the rare case where a line can only be finished
+ * once the next is known - a list that closes on the line of its last entry.
+ *
+ * @param text The replacement line.
+ */
+ public void replaceLast(String text) {
+ int end = buf.length() - 1;
+ int start = buf.lastIndexOf("\n", end - 1) + 1;
+ buf.setLength(start);
+ line(text);
+ }
+
+ @Override
+ public String toString() {
+ return buf.toString();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaTypeName.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaTypeName.java
new file mode 100644
index 00000000..4b819904
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaTypeName.java
@@ -0,0 +1,210 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.types.AttributeType;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+
+/**
+ * Renders a type reference as the Java type that represents it.
+ */
+public final class JavaTypeName {
+
+ private JavaTypeName() {
+ }
+
+ /**
+ * @return the Java type for a field or parameter of this type.
+ */
+ public static String of(MOModel model, TypeRef reference) {
+ if (reference == null) {
+ return "java.lang.Object";
+ }
+ // The older spelling of an object reference, ObjectRef(Product), means the same as
+ // objectRef="true"; unwrapping here lets everything below see just the one form.
+ TypeRef ref = reference.unwrapped();
+ if (ref.isList()) {
+ // A list of object references is a list of references, not of the target type.
+ return ref.isObjectRef()
+ ? JavaNaming.MAL_STRUCTURES + "ObjectRefList" : qualifiedList(ref);
+ }
+ if (ref.isObjectRef()) {
+ return JavaNaming.MAL_STRUCTURES + "ObjectRef<" + qualified(ref) + ">";
+ }
+ if (isNativeAttribute(model, ref)) {
+ return JavaTypes.nativeName(ref.getName());
+ }
+ return qualified(ref);
+ }
+
+ /**
+ * @return the expression that creates an empty instance, for decoding.
+ */
+ public static String newInstance(MOModel model, TypeRef ref) {
+ // An enumeration cannot be constructed empty, so its first singleton stands in.
+ if (ref != null && !ref.isList() && !ref.isObjectRef()) {
+ TypeDefinition definition = model.resolve(ref);
+ if (definition instanceof EnumerationType) {
+ EnumerationType enumeration = (EnumerationType) definition;
+ if (!enumeration.getItems().isEmpty()) {
+ return qualified(ref) + "." + enumeration.getItems().get(0).getValue();
+ }
+ }
+ }
+ return "new " + of(model, ref) + "()";
+ }
+
+ /**
+ * @return the fully qualified name of the type itself, ignoring list and reference
+ * wrapping.
+ */
+ public static String qualified(TypeRef ref) {
+ StringBuilder pkg = new StringBuilder("org.ccsds.moims.mo.");
+ pkg.append(ref.getArea().toLowerCase());
+ if (ref.getService() != null) {
+ pkg.append('.').append(ref.getService().toLowerCase());
+ }
+ pkg.append('.').append(JavaNaming.STRUCTURES).append('.')
+ .append(JavaTypes.className(ref.getArea(), ref.getName()));
+ return pkg.toString();
+ }
+
+ /**
+ * Returns the Java type of a list of this type. Usually the element's name with
+ * "List" appended, but a list of MAL Elements is the hand-written HeterogeneousList
+ * rather than a generated ElementList.
+ */
+ private static String qualifiedList(TypeRef ref) {
+ String listName = JavaTypes.className(ref.getArea(), ref.getName() + "List");
+ int lastDot = qualified(ref).lastIndexOf('.');
+ return qualified(ref).substring(0, lastDot + 1) + listName;
+ }
+
+ /**
+ * Returns true if the reference names a MAL attribute type that is represented by a
+ * plain Java type.
+ */
+ public static boolean isNativeAttribute(MOModel model, TypeRef ref) {
+ return !ref.isList() && !ref.isObjectRef()
+ && JavaTypes.isNative(ref.getArea(), ref.getName())
+ && isAttribute(model, ref);
+ }
+
+ /**
+ * Returns the MAL attribute type this reference names, or null if it names something
+ * else. Attributes have their own encoder methods; everything else is encoded as an
+ * element.
+ */
+ public static String attributeName(MOModel model, TypeRef ref) {
+ if (ref == null || ref.isList() || ref.isObjectRef()) {
+ return null;
+ }
+ // The abstract Attribute type has its own encoder method, like the concrete ones.
+ if ("MAL".equals(ref.getArea()) && "Attribute".equals(ref.getName())) {
+ return "Attribute";
+ }
+ return isAttribute(model, ref) ? ref.getName() : null;
+ }
+
+ /**
+ * Returns true if the reference names a type that cannot be instantiated, so the
+ * encoder has to record which concrete type it is writing.
+ */
+ public static boolean isAbstractElement(MOModel model, TypeRef ref) {
+ if (ref == null || ref.isList()) {
+ return false;
+ }
+ // A reference to an abstract type is itself abstract: ObjectRef<Element> can hold
+ // a reference to anything, so the encoder has to record what it wrote.
+ TypeDefinition definition = model.resolve(ref);
+ return definition != null && definition.isAbstract();
+ }
+
+ /**
+ * Returns the expression that names the short form of a type, as a message body needs
+ * it to say what it carries. An abstract type has none - what is on the wire is decided
+ * per message - and neither has the base Element.
+ *
+ * @param model The model the reference is resolved against.
+ * @param reference The type, may be null.
+ * @return the short form expression, or the literal null.
+ */
+ public static String shortFormOf(MOModel model, TypeRef reference) {
+ if (reference == null) {
+ return "null";
+ }
+ TypeRef ref = reference.unwrapped();
+ // What is on the wire is decided per message, whether the field holds one of them
+ // or a list of them.
+ TypeDefinition definition = model.resolve(ref);
+ if (definition != null && definition.isAbstract()) {
+ return "null";
+ }
+ // An attribute carries the short form of the attribute type, not of a class: the
+ // concrete ones are constants on Attribute itself.
+ if (!ref.isList() && isAttribute(model, ref)) {
+ return JavaNaming.MAL_STRUCTURES + "Attribute."
+ + ref.getName().toUpperCase() + "_SHORT_FORM";
+ }
+ if (ref.isObjectRef()) {
+ return ref.isList()
+ ? JavaNaming.MAL_STRUCTURES + "ObjectRefList.SHORT_FORM"
+ : JavaNaming.MAL_STRUCTURES + "ObjectRef.OBJECTREF_SHORT_FORM";
+ }
+ String java = of(model, ref);
+ return (JavaNaming.MAL_STRUCTURES + "Element").equals(java) ? "null" : java + ".SHORT_FORM";
+ }
+
+ /**
+ * Returns what a decoder is handed so it knows what to build. An abstract type carries
+ * its own identity on the wire, so nothing is handed over for it - except a list of
+ * abstract things, which is still a list and can be built empty. A list of the base
+ * Element is the one exception to that exception: the reference output leaves it
+ * undecided, because before the Java mapping renames it the type is called ElementList
+ * and the rule matches on the name.
+ *
+ * @param model The model the reference is resolved against.
+ * @param reference The type of the field being decoded.
+ * @return the expression handed to the decoder, or the literal null.
+ */
+ public static String expectedTypeOf(MOModel model, TypeRef reference) {
+ TypeRef ref = reference.unwrapped();
+ String raw = qualified(ref) + (ref.isList() ? "List" : "");
+ if (raw.contains(".MOObject")) {
+ return "null";
+ }
+ TypeDefinition definition = model.resolve(ref);
+ boolean isAbstract = definition != null && definition.isAbstract();
+ if (isAbstract) {
+ return raw.contains("List") && !raw.contains(".Element")
+ ? "new " + of(model, reference) + "()" : "null";
+ }
+ return newInstance(model, reference);
+ }
+
+ private static boolean isAttribute(MOModel model, TypeRef ref) {
+ TypeDefinition definition = model.resolve(ref);
+ return definition instanceof AttributeType;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaTypes.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaTypes.java
new file mode 100644
index 00000000..9d833a9f
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JavaTypes.java
@@ -0,0 +1,127 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * How the MAL's attribute types are represented in Java.
+ * <p>
+ * The model takes the attribute types themselves from the MAL specification; this holds
+ * only the Java side of the mapping, which belongs to this generator and nowhere else.
+ * <p>
+ * Seven of them are plain Java types rather than generated classes, and the name is not
+ * always the MAL one - an Octet is a {@code Byte}.
+ */
+public final class JavaTypes {
+
+ private static final Map<String, String> NATIVE = new HashMap<String, String>();
+
+ static {
+ NATIVE.put("Boolean", "Boolean");
+ NATIVE.put("Double", "Double");
+ NATIVE.put("Float", "Float");
+ NATIVE.put("Integer", "Integer");
+ NATIVE.put("Long", "Long");
+ NATIVE.put("Octet", "Byte");
+ NATIVE.put("Short", "Short");
+ NATIVE.put("String", "String");
+ }
+
+ /**
+ * The value a native attribute is created with where one has to be created without
+ * knowing anything about it - the Union that carries it has no empty constructor.
+ */
+ private static final Map<String, String> NATIVE_DEFAULT = new HashMap<String, String>();
+
+ static {
+ NATIVE_DEFAULT.put("Boolean", "Boolean.FALSE");
+ NATIVE_DEFAULT.put("Double", "Double.MAX_VALUE");
+ NATIVE_DEFAULT.put("Float", "Float.MAX_VALUE");
+ NATIVE_DEFAULT.put("Integer", "Integer.MAX_VALUE");
+ NATIVE_DEFAULT.put("Long", "Long.MAX_VALUE");
+ NATIVE_DEFAULT.put("Octet", "Byte.MAX_VALUE");
+ NATIVE_DEFAULT.put("Short", "Short.MAX_VALUE");
+ NATIVE_DEFAULT.put("String", "\"\"");
+ }
+
+ /**
+ * MAL types whose Java class is named differently, to avoid colliding with a Java
+ * built-in: MAL's Object would otherwise shadow java.lang.Object.
+ */
+ private static final Map<String, String> RENAMED = new HashMap<String, String>();
+
+ static {
+ RENAMED.put("Object", "MOObject");
+ RENAMED.put("ElementList", "HeterogeneousList");
+ }
+
+ private JavaTypes() {
+ }
+
+ /**
+ * Returns the Java class name for a MAL type, which is usually its own name.
+ *
+ * @param malArea The area the type belongs to.
+ * @param typeName The MAL type name.
+ * @return the Java class name.
+ */
+ public static String className(String malArea, String typeName) {
+ if ("MAL".equals(malArea) && RENAMED.containsKey(typeName)) {
+ return RENAMED.get(typeName);
+ }
+ return typeName;
+ }
+
+ /**
+ * Returns true if the MAL attribute type is a plain Java type rather than a class this
+ * generator produces.
+ *
+ * @param malArea The area the type belongs to.
+ * @param typeName The MAL type name.
+ * @return true if it maps to a Java built-in.
+ */
+ public static boolean isNative(String malArea, String typeName) {
+ return "MAL".equals(malArea) && NATIVE.containsKey(typeName);
+ }
+
+ /**
+ * Returns the Java name of a native MAL attribute type.
+ *
+ * @param typeName The MAL type name.
+ * @return the Java type name.
+ */
+ public static String nativeName(String typeName) {
+ return NATIVE.get(typeName);
+ }
+
+ /**
+ * Returns the value a native MAL attribute type is created with when nothing is known
+ * about the value it is going to carry.
+ *
+ * @param typeName The MAL type name.
+ * @return the Java expression of the default value.
+ */
+ public static String nativeDefault(String typeName) {
+ return NATIVE_DEFAULT.get(typeName);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JumpTable.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JumpTable.java
new file mode 100644
index 00000000..480de6f2
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/JumpTable.java
@@ -0,0 +1,177 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import java.util.Collection;
+import java.util.Map;
+import java.util.SortedSet;
+import java.util.TreeMap;
+import java.util.TreeSet;
+
+/**
+ * Decides how the type numbers of an element factory are laid out, so that a lookup
+ * compiles to a jump rather than to a binary search.
+ * <p>
+ * Carried over from the generator this replaces, rule for rule. A type and the list that
+ * holds it share a number save for the sign, so numbers far from zero leave the whole
+ * distance across zero empty between them, and a switch spanning that emptiness falls back
+ * to a binary search. Two things follow: numbers that lie past the widest table worth
+ * building are answered by a second method, and where each side of zero would answer with
+ * a table of its own but the two together would not, the sides are switched apart.
+ */
+public final class JumpTable {
+
+ private JumpTable() {
+ }
+
+ /**
+ * Returns true when a switch over this many numbers, spanning this far, is worth
+ * compiling to a jump table rather than to a binary search.
+ *
+ * @param count How many numbers the switch answers for.
+ * @param span The distance from the lowest number to the highest, inclusive.
+ * @return true if a jump table pays.
+ */
+ public static boolean compilesToJumpTable(int count, long span) {
+ return (4 + span) + 3L * 3L <= (3 + 2L * count) + 3L * count;
+ }
+
+ /**
+ * Returns the widest distance from zero within which the numbers still pay for a jump
+ * table. A type and its list share a number save for the sign, so the band widens by
+ * the same step on both sides at once.
+ *
+ * @param numbers The type numbers.
+ * @return the widest band, or zero if no table pays.
+ */
+ public static int widestJumpTableBand(Collection<Integer> numbers) {
+ SortedSet<Integer> magnitudes = new TreeSet<Integer>();
+ for (Integer number : numbers) {
+ magnitudes.add(Math.abs(number));
+ }
+
+ int widest = 0;
+ for (Integer magnitude : magnitudes) {
+ int count = 0;
+ for (Integer number : numbers) {
+ if (Math.abs(number) <= magnitude) {
+ count++;
+ }
+ }
+ if (compilesToJumpTable(count, 2L * magnitude + 1L)) {
+ widest = magnitude;
+ }
+ }
+ return widest;
+ }
+
+ /**
+ * Returns true when the numbers are better switched on one side of zero at a time than
+ * all together: neither side is worth it unless both sides answer with a table of
+ * their own and the two together would not.
+ *
+ * @param numbers The type numbers of the switch.
+ * @return true if each side of zero should be switched on its own.
+ */
+ public static boolean shouldSplitOnSign(Collection<Integer> numbers) {
+ int positives = 0;
+ int negatives = 0;
+ int highest = Integer.MIN_VALUE;
+ int lowest = Integer.MAX_VALUE;
+ int highestPositive = Integer.MIN_VALUE;
+ int lowestPositive = Integer.MAX_VALUE;
+ int highestNegative = Integer.MIN_VALUE;
+ int lowestNegative = Integer.MAX_VALUE;
+
+ for (Integer number : numbers) {
+ highest = Math.max(highest, number);
+ lowest = Math.min(lowest, number);
+ if (number > 0) {
+ positives++;
+ highestPositive = Math.max(highestPositive, number);
+ lowestPositive = Math.min(lowestPositive, number);
+ } else {
+ negatives++;
+ highestNegative = Math.max(highestNegative, number);
+ lowestNegative = Math.min(lowestNegative, number);
+ }
+ }
+
+ if (positives == 0 || negatives == 0) {
+ return false; // There is only one side to switch on
+ }
+
+ return !compilesToJumpTable(numbers.size(), (long) highest - lowest + 1L)
+ && compilesToJumpTable(positives, (long) highestPositive - lowestPositive + 1L)
+ && compilesToJumpTable(negatives, (long) highestNegative - lowestNegative + 1L);
+ }
+
+ /**
+ * The types of one switch, split into the ones a jump table can hold and the ones
+ * whose numbers lie too far out for it.
+ */
+ public static final class Split {
+
+ private final Map<Integer, String> inBand = new TreeMap<Integer, String>();
+ private final Map<Integer, String> outOfBand = new TreeMap<Integer, String>();
+
+ /**
+ * @return true if the types have to be reached by two switches.
+ */
+ public boolean isSplit() {
+ return !inBand.isEmpty() && !outOfBand.isEmpty();
+ }
+
+ public Map<Integer, String> getInBand() {
+ return inBand;
+ }
+
+ public Map<Integer, String> getOutOfBand() {
+ return outOfBand;
+ }
+
+ /**
+ * @return every type, whether or not the jump table can hold it.
+ */
+ public Map<Integer, String> all() {
+ Map<Integer, String> every = new TreeMap<Integer, String>(inBand);
+ every.putAll(outOfBand);
+ return every;
+ }
+ }
+
+ /**
+ * Splits the types into the ones the widest jump table can hold and the ones past it.
+ *
+ * @param types The types, by number, in declaration order.
+ * @return the split.
+ */
+ public static Split splitTypes(Map<Integer, String> types) {
+ Map<Integer, String> byNumber = new TreeMap<Integer, String>(types);
+ int band = widestJumpTableBand(byNumber.keySet());
+ Split split = new Split();
+ for (Map.Entry<Integer, String> entry : byNumber.entrySet()) {
+ boolean fits = Math.abs(entry.getKey()) <= band;
+ (fits ? split.inBand : split.outOfBand).put(entry.getKey(), entry.getValue());
+ }
+ return split;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/ShortForm.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/ShortForm.java
new file mode 100644
index 00000000..bca55708
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/ShortForm.java
@@ -0,0 +1,76 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Service;
+
+/**
+ * The absolute short form of a type: the number that identifies it on the wire.
+ * <p>
+ * Area number, service number, area version and the type's own short form part, packed
+ * into one long.
+ */
+public final class ShortForm {
+
+ private ShortForm() {
+ }
+
+ /**
+ * Computes the absolute short form.
+ *
+ * @param area The area defining the type.
+ * @param service The service defining it, or null for an area-level type.
+ * @param shortFormPart The type's short form part.
+ * @return the absolute short form.
+ */
+ public static long of(Area area, Service service, long shortFormPart) {
+ long serviceNumber = service == null ? 0 : service.getNumber();
+ return ((long) area.getNumber() << 48)
+ + (serviceNumber << 32)
+ + ((long) area.getVersion() << 24)
+ + shortFormPart;
+ }
+
+ /**
+ * Writes the three fields that carry a type's identity: the version the class was
+ * serialised under, the short form as a Long, and the TypeId built from it. Composites,
+ * enumerations and lists all open with them, written as one block with no blank line
+ * between them.
+ *
+ * @param out The source to write to.
+ * @param shortForm The absolute short form of the type.
+ */
+ public static void writeIdentity(JavaSource out, long shortForm) {
+ JavaFieldBuilder.named("serialVersionUID").scope("private").asStatic().asFinal()
+ .ofType("long").value(shortForm + "L")
+ .write(out);
+ JavaFieldBuilder.named("SHORT_FORM").asStatic().asFinal()
+ .ofType("Long").value(shortForm + "L")
+ .comment("The TypeId of this Element as a long.")
+ .joinedToPrevious().write(out);
+ JavaFieldBuilder.named("TYPE_ID").asStatic().asFinal()
+ .ofType(JavaNaming.MAL + "TypeId")
+ .value("new " + JavaNaming.MAL + "TypeId(SHORT_FORM)")
+ .comment("The TypeId of this Element.")
+ .joinedToPrevious().write(out);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/CompositeWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/CompositeWriter.java
new file mode 100644
index 00000000..82488bfc
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/CompositeWriter.java
@@ -0,0 +1,375 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.generators.java.ShortForm;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.TypeRef;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the Java class for a composite.
+ */
+public final class CompositeWriter {
+
+ private static final String COMPOSITE = JavaNaming.MAL_STRUCTURES + "Composite";
+
+ private CompositeWriter() {
+ }
+
+ public static String write(MOModel model, Area area, Service service, CompositeType type) {
+ String name = type.getName();
+ String pkg = service == null
+ ? JavaNaming.packageOf(area, JavaNaming.STRUCTURES)
+ : JavaNaming.packageOf(service, JavaNaming.STRUCTURES);
+ String fq = pkg + "." + name;
+ List<Field> own = type.getFields();
+ List<Field> inherited = model.inheritedFields(type);
+ List<Field> all = new ArrayList<Field>(inherited);
+ all.addAll(own);
+
+ String superFq = superClassOf(type);
+ boolean isAbstract = type.isAbstract();
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(name).inPackage(pkg)
+ .comment(isBlank(type.getComment())
+ ? "The " + name + " structure." : type.getComment());
+ if (isAbstract) {
+ clazz.asAbstract();
+ } else {
+ clazz.asFinal();
+ }
+ // A composite that extends the base Composite implements the interface instead;
+ // anything else extends its super type.
+ if (superFq == null) {
+ clazz.implementing(COMPOSITE);
+ } else {
+ clazz.extending(superFq);
+ }
+ JavaSource out = clazz.open();
+
+ if (type.getShortFormPart() != null) {
+ ShortForm.writeIdentity(out, ShortForm.of(area, service, type.getShortFormPart()));
+ }
+
+ for (Field field : own) {
+ JavaFieldBuilder.named(field.getName()).scope("private")
+ .ofType(JavaTypeName.of(model, field.getType()))
+ .comment(isBlank(field.getComment())
+ ? "The " + field.getName() + " field." : field.getComment())
+ .write(out);
+ }
+
+ JavaMethodBuilder.constructor(name).comment("Default constructor for " + name + ".")
+ .write(out);
+
+ if (!all.isEmpty()) {
+ writeConstructor(out, model, name, all, inherited, own,
+ "Constructor that initialises the values of the structure.");
+ // The second constructor is suppressed in two cases: with no non-nullable
+ // fields it would take no arguments and collide with the default constructor,
+ // and with nothing but non-nullable fields it would repeat the first one.
+ List<Field> required = requiredOf(all);
+ if (!required.isEmpty() && required.size() != all.size()) {
+ writeConstructor(out, model, name, required,
+ retain(inherited, required), own,
+ "Constructor that initialises the non-nullable values of the structure.",
+ omitted(own, required));
+ }
+ }
+
+ if (!isAbstract) {
+ JavaMethodBuilder.named("createElement").asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Element", null)
+ .line("return new " + fq + "();")
+ .write(out);
+ }
+
+ for (Field field : own) {
+ JavaMethodBuilder.named("get" + capitalise(field.getName()))
+ .comment("Returns the field " + field.getName() + ".")
+ .returns(JavaTypeName.of(model, field.getType()),
+ "The field " + field.getName())
+ .line("return " + field.getName() + ";")
+ .write(out);
+ }
+
+ writeEquals(out, name, own, superFq != null);
+ writeHashCode(out, own, superFq != null);
+ writeToString(out, name, own, superFq != null);
+ writeEncode(out, model, own, superFq != null);
+ writeDecode(out, model, own, superFq != null);
+
+ if (type.getShortFormPart() != null) {
+ JavaMethodBuilder.named("getTypeId").asOverride()
+ .returns(JavaNaming.MAL + "TypeId", null)
+ .line("return TYPE_ID;")
+ .write(out);
+ }
+
+ return clazz.close();
+ }
+
+ // --------------------------------------------------------- constructors
+
+ private static void writeConstructor(JavaSource out, MOModel model, String name,
+ List<Field> parameters, List<Field> superArgs, List<Field> ownArgs, String title) {
+ writeConstructor(out, model, name, parameters, superArgs, ownArgs, title,
+ new ArrayList<Field>());
+ }
+
+ private static void writeConstructor(JavaSource out, MOModel model, String name,
+ List<Field> parameters, List<Field> superArgs, List<Field> ownArgs, String title,
+ List<Field> nulled) {
+ JavaMethodBuilder constructor = JavaMethodBuilder.constructor(name).comment(title);
+
+ for (Field field : parameters) {
+ // A field with no comment still gets a parameter description.
+ constructor.argument(JavaTypeName.of(model, field.getType()), field.getName(),
+ field.getComment());
+ }
+ if (!superArgs.isEmpty()) {
+ StringBuilder call = new StringBuilder("super(");
+ for (int i = 0; i < superArgs.size(); i++) {
+ if (i > 0) {
+ call.append(",\n ");
+ }
+ call.append(superArgs.get(i).getName());
+ }
+ call.append(");");
+ constructor.line(call.toString());
+ }
+ // Assignments follow declaration order; a constructor that omits the nullable
+ // fields still sets them, in place, to null.
+ for (Field field : ownArgs) {
+ boolean omitted = nulled.contains(field);
+ constructor.line("this." + field.getName() + " = "
+ + (omitted ? "null" : field.getName()) + ";");
+ }
+ constructor.write(out);
+ }
+
+ // ------------------------------------------------------------- equality
+
+ private static void writeEquals(JavaSource out, String name, List<Field> fields,
+ boolean hasSuper) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("equals").asOverride()
+ .returns("boolean", null)
+ .argument("Object", "obj", null);
+
+ method.line("if (obj instanceof " + name + ") {");
+ if (hasSuper) {
+ // A subclass compares its own fields only after the inherited ones agree.
+ method.line(" if (! super.equals(obj)) {");
+ method.line(" return false;");
+ method.line(" }");
+ }
+ if (!fields.isEmpty()) {
+ method.line(" " + name + " other = (" + name + ") obj;");
+ }
+ for (Field field : fields) {
+ String f = field.getName();
+ method.line(" if (" + f + " == null) {");
+ method.line(" if (other." + f + " != null) {");
+ method.line(" return false;");
+ method.line(" }");
+ method.line(" } else {");
+ method.line(" if (! " + f + ".equals(other." + f + ")) {");
+ method.line(" return false;");
+ method.line(" }");
+ method.line(" }");
+ }
+ method.line(" return true;");
+ method.line("}");
+ method.line("return false;");
+ method.write(out);
+ }
+
+ private static void writeHashCode(JavaSource out, List<Field> fields,
+ boolean hasSuper) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("hashCode").asOverride()
+ .returns("int", null);
+
+ method.line("int hash = " + (hasSuper ? "super.hashCode()" : "7") + ";");
+ for (Field field : fields) {
+ method.line("hash = 83 * hash + (" + field.getName() + " != null ? "
+ + field.getName() + ".hashCode() : 0);");
+ }
+ method.line("return hash;");
+ method.write(out);
+ }
+
+ private static void writeToString(JavaSource out, String name, List<Field> fields,
+ boolean hasSuper) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("toString").asOverride()
+ .returns("String", null);
+
+ method.line("StringBuilder buf = new StringBuilder();");
+ method.line("buf.append(\"(" + name + ": \");");
+ if (hasSuper) {
+ method.line("buf.append(super.toString());");
+ }
+ for (int i = 0; i < fields.size(); i++) {
+ String f = fields.get(i).getName();
+ String separator = (i == 0 && !hasSuper) ? "" : ", ";
+ method.line("buf.append(\"" + separator + f + "=\").append(" + f + ");");
+ }
+ method.line("buf.append(')');");
+ method.line("return buf.toString();");
+ method.write(out);
+ }
+
+ // ------------------------------------------------------ encode / decode
+
+ private static void writeEncode(JavaSource out, MOModel model, List<Field> fields,
+ boolean hasSuper) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("encode").asOverride()
+ .argument(JavaNaming.MAL + "MALEncoder", "encoder", null)
+ .throwing(JavaNaming.MAL + "MALException", null);
+
+ if (hasSuper) {
+ // Inherited fields are written by the super type, before this one's.
+ method.line("super.encode(encoder);");
+ }
+ for (Field field : fields) {
+ if (!field.isCanBeNull()) {
+ method.line("if (" + field.getName() + " == null) {");
+ method.line(" throw new " + JavaNaming.MAL + "MALException(\"The field '"
+ + field.getName() + "' cannot be null!\");");
+ method.line("}");
+ }
+ }
+ for (Field field : fields) {
+ String nullable = field.isCanBeNull() ? "Nullable" : "";
+ String attribute = JavaTypeName.attributeName(model, field.getType());
+ String encoded = attribute == null
+ ? (JavaTypeName.isAbstractElement(model, field.getType())
+ ? "AbstractElement" : "Element")
+ : attribute;
+ method.line("encoder.encode" + nullable + encoded + "(" + field.getName() + ");");
+ }
+ method.write(out);
+ }
+
+ private static void writeDecode(JavaSource out, MOModel model, List<Field> fields,
+ boolean hasSuper) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("decode").asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Element", null)
+ .argument(JavaNaming.MAL + "MALDecoder", "decoder", null)
+ .throwing(JavaNaming.MAL + "MALException", null);
+
+ if (hasSuper) {
+ method.line("super.decode(decoder);");
+ }
+ for (Field field : fields) {
+ String nullable = field.isCanBeNull() ? "Nullable" : "";
+ String attribute = JavaTypeName.attributeName(model, field.getType());
+ if (attribute != null) {
+ // The abstract Attribute decodes to a general type and is cast back.
+ String cast = "Attribute".equals(attribute)
+ ? "(" + JavaNaming.MAL_STRUCTURES + "Attribute) " : "";
+ method.line(field.getName() + " = " + cast + "decoder.decode"
+ + nullable + attribute + "();");
+ } else if (JavaTypeName.isAbstractElement(model, field.getType())) {
+ // An abstract element carries its own type on the wire, so nothing needs
+ // to be handed to the decoder.
+ String java = JavaTypeName.of(model, field.getType());
+ method.line(field.getName() + " = (" + java + ") decoder.decode"
+ + nullable + "AbstractElement();");
+ } else {
+ String java = JavaTypeName.of(model, field.getType());
+ method.line(field.getName() + " = (" + java + ") decoder.decode"
+ + nullable + "Element("
+ + JavaTypeName.newInstance(model, field.getType()) + ");");
+ }
+ }
+ method.line("return this;");
+ method.write(out);
+ }
+
+ // ---------------------------------------------------------------- utils
+
+ /**
+ * A composite that extends the base Composite implements the interface; anything else
+ * extends its super type and inherits its fields.
+ */
+ /**
+ * A comment that was written empty says as little as one that was not written at all,
+ * so both are replaced by a plain description of what is being declared.
+ */
+ private static boolean isBlank(String comment) {
+ return comment == null || comment.isEmpty();
+ }
+
+ private static String superClassOf(CompositeType type) {
+ TypeRef superType = type.getSuperType();
+ if (superType == null
+ || ("MAL".equals(superType.getArea()) && "Composite".equals(superType.getName()))) {
+ return null;
+ }
+ return JavaTypeName.qualified(superType);
+ }
+
+ private static List<Field> requiredOf(List<Field> fields) {
+ List<Field> required = new ArrayList<Field>();
+ for (Field field : fields) {
+ if (!field.isCanBeNull()) {
+ required.add(field);
+ }
+ }
+ return required;
+ }
+
+ private static List<Field> omitted(List<Field> source, List<Field> keep) {
+ List<Field> result = new ArrayList<Field>();
+ for (Field field : source) {
+ if (!keep.contains(field)) {
+ result.add(field);
+ }
+ }
+ return result;
+ }
+
+ private static List<Field> retain(List<Field> source, List<Field> keep) {
+ List<Field> result = new ArrayList<Field>();
+ for (Field field : source) {
+ if (keep.contains(field)) {
+ result.add(field);
+ }
+ }
+ return result;
+ }
+
+ private static String capitalise(String name) {
+ return Character.toUpperCase(name.charAt(0)) + name.substring(1);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ConsumerAdapterWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ConsumerAdapterWriter.java
new file mode 100644
index 00000000..900d596f
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ConsumerAdapterWriter.java
@@ -0,0 +1,475 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.generators.java.JavaTypes;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the consumer adapter of a service: one empty method per message a consumer can
+ * receive, for the consumer to override, and one dispatch method per kind of message, which
+ * reads the operation number off the header and calls the right one.
+ * <p>
+ * The dispatch methods are final: what arrives is decided by the specification, so a
+ * consumer overrides what it wants to hear about, never how the message is routed.
+ */
+public final class ConsumerAdapterWriter {
+
+ private static final String HEADER = JavaNaming.MAL + "transport.MALMessageHeader";
+
+ private static final String BODY = JavaNaming.MAL + "transport.MALMessageBody";
+
+ private static final String NOTIFY_BODY = JavaNaming.MAL + "transport.MALNotifyBody";
+
+ private static final String ERROR_BODY = JavaNaming.MAL + "transport.MALErrorBody";
+
+ private static final String MAL_EXCEPTION = JavaNaming.MAL + "MALException";
+
+ private static final String HEADER_COMMENT = "msgHeader The header of the received message";
+
+ private static final String BODY_COMMENT = "body The body of the received message";
+
+ private static final String QOS_COMMENT =
+ "qosProperties The QoS properties associated with the message";
+
+ private static final String THROWN = "if an error is detected processing the message.";
+
+ /**
+ * The step an argument of a dispatched call takes past the line it starts on.
+ */
+ private static final String ARGUMENT = ",\n ";
+
+ private ConsumerAdapterWriter() {
+ }
+
+ /**
+ * Writes the adapter a consumer subclasses to receive what a provider sends back.
+ *
+ * @param model Every loaded specification.
+ * @param area The area the service belongs to.
+ * @param service The service to write the adapter of.
+ * @return the source of the service's consumer adapter.
+ */
+ public static String write(MOModel model, Area area, Service service) {
+ String name = service.getName();
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "Adapter").asAbstract()
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.CONSUMER))
+ .extending(JavaNaming.MAL + "consumer.MALInteractionAdapter")
+ .comment("Consumer adapter for " + name + " service.");
+ JavaSource out = clazz.open();
+
+ boolean submits = false;
+ boolean requests = false;
+ boolean invokes = false;
+ boolean progresses = false;
+ boolean pubsubs = false;
+
+ for (Operation operation : service.getOperations()) {
+ String opName = operation.getName();
+ switch (operation.getPattern()) {
+ case SUBMIT:
+ callback(out, opName + "AckReceived")
+ .comment("Called by the MAL when a SUBMIT acknowledgement is received"
+ + " from a provider for the operation " + opName)
+ .write(out);
+ error(out, opName + "ErrorReceived",
+ "Called by the MAL when a SUBMIT acknowledgement error is received"
+ + " from a provider for the operation " + opName);
+ submits = true;
+ break;
+ case REQUEST:
+ received(out, model, operation, "ResponseReceived", InteractionStage.RESPONSE,
+ "Called by the MAL when a REQUEST response is received from a"
+ + " provider for the operation " + opName);
+ error(out, opName + "ErrorReceived",
+ "Called by the MAL when a REQUEST response error is received from a"
+ + " provider for the operation " + opName);
+ requests = true;
+ break;
+ case INVOKE:
+ received(out, model, operation, "AckReceived", InteractionStage.ACK,
+ "Called by the MAL when an INVOKE acknowledgement is received from a"
+ + " provider for the operation " + opName);
+ received(out, model, operation, "ResponseReceived", InteractionStage.RESPONSE,
+ "Called by the MAL when an INVOKE response is received from a"
+ + " provider for the operation " + opName);
+ error(out, opName + "AckErrorReceived",
+ "Called by the MAL when an INVOKE acknowledgement error is received"
+ + " from a provider for the operation " + opName);
+ error(out, opName + "ResponseErrorReceived",
+ "Called by the MAL when an INVOKE response error is received from a"
+ + " provider for the operation " + opName);
+ invokes = true;
+ break;
+ case PROGRESS:
+ received(out, model, operation, "AckReceived", InteractionStage.ACK,
+ "Called by the MAL when a PROGRESS acknowledgement is received from a"
+ + " provider for the operation " + opName);
+ received(out, model, operation, "UpdateReceived", InteractionStage.UPDATE,
+ "Called by the MAL when a PROGRESS update is received from a provider"
+ + " for the operation " + opName);
+ received(out, model, operation, "ResponseReceived", InteractionStage.RESPONSE,
+ "Called by the MAL when a PROGRESS response is received from a"
+ + " provider for the operation " + opName);
+ error(out, opName + "AckErrorReceived",
+ "Called by the MAL when a PROGRESS acknowledgement error is received"
+ + " from a provider for the operation " + opName);
+ error(out, opName + "UpdateErrorReceived",
+ "Called by the MAL when a PROGRESS update error is received from a"
+ + " provider for the operation " + opName);
+ error(out, opName + "ResponseErrorReceived",
+ "Called by the MAL when a PROGRESS response error is received from a"
+ + " provider for the operation " + opName);
+ progresses = true;
+ break;
+ case PUBSUB:
+ callback(out, opName + "RegisterAckReceived")
+ .comment("Called by the MAL when a PubSub register acknowledgement is"
+ + " received from a broker for the operation " + opName)
+ .write(out);
+ error(out, opName + "RegisterErrorReceived",
+ "Called by the MAL when a PubSub register acknowledgement error is"
+ + " received from a broker for the operation " + opName);
+ callback(out, opName + "DeregisterAckReceived")
+ .comment("Called by the MAL when a PubSub deregister acknowledgement"
+ + " is received from a broker for the operation " + opName)
+ .write(out);
+ writeNotifyCallback(out, model, operation);
+ error(out, opName + "NotifyErrorReceived",
+ "Called by the MAL when a PubSub update error is received from a"
+ + " broker for the operation " + opName);
+ pubsubs = true;
+ break;
+ default:
+ break;
+ }
+ }
+
+ if (submits) {
+ dispatch(out, model, service, InteractionPattern.SUBMIT, "submitAck", "Ack", null, false,
+ "Called by the MAL when a SUBMIT acknowledgement is received from a provider.");
+ dispatchError(out, service, InteractionPattern.SUBMIT, "submit", "",
+ "Called by the MAL when a SUBMIT acknowledgement error is received from a provider.");
+ }
+ if (requests) {
+ dispatch(out, model, service, InteractionPattern.REQUEST, "requestResponse", "Response",
+ InteractionStage.RESPONSE, true,
+ "Called by the MAL when a REQUEST response is received from a provider.");
+ dispatchError(out, service, InteractionPattern.REQUEST, "request", "",
+ "Called by the MAL when a REQUEST response error is received from a provider.");
+ }
+ if (invokes) {
+ dispatch(out, model, service, InteractionPattern.INVOKE, "invokeAck", "Ack",
+ InteractionStage.ACK, true,
+ "Called by the MAL when an INVOKE acknowledgement is received from a provider.");
+ dispatchError(out, service, InteractionPattern.INVOKE, "invokeAck", "Ack",
+ "Called by the MAL when an INVOKE acknowledgement error is received from a provider.");
+ dispatch(out, model, service, InteractionPattern.INVOKE, "invokeResponse", "Response",
+ InteractionStage.RESPONSE, true,
+ "Called by the MAL when an INVOKE response is received from a provider.");
+ dispatchError(out, service, InteractionPattern.INVOKE, "invokeResponse", "Response",
+ "Called by the MAL when an INVOKE response error is received from a provider.");
+ }
+ if (progresses) {
+ dispatch(out, model, service, InteractionPattern.PROGRESS, "progressAck", "Ack",
+ InteractionStage.ACK, true,
+ "Called by the MAL when a PROGRESS acknowledgement is received from a provider.");
+ dispatchError(out, service, InteractionPattern.PROGRESS, "progressAck", "Ack",
+ "Called by the MAL when a PROGRESS acknowledgement error is received from a provider.");
+ dispatch(out, model, service, InteractionPattern.PROGRESS, "progressUpdate", "Update",
+ InteractionStage.UPDATE, true,
+ "Called by the MAL when a PROGRESS update is received from a provider.");
+ dispatchError(out, service, InteractionPattern.PROGRESS, "progressUpdate", "Update",
+ "Called by the MAL when a PROGRESS update error is received from a provider.");
+ dispatch(out, model, service, InteractionPattern.PROGRESS, "progressResponse", "Response",
+ InteractionStage.RESPONSE, true,
+ "Called by the MAL when a PROGRESS response is received from a provider.");
+ dispatchError(out, service, InteractionPattern.PROGRESS, "progressResponse", "Response",
+ "Called by the MAL when a PROGRESS response error is received from a provider.");
+ }
+ if (pubsubs) {
+ dispatch(out, model, service, InteractionPattern.PUBSUB, "registerAck", "RegisterAck",
+ InteractionStage.ACK, false,
+ "Called by the MAL when a PubSub register acknowledgement is received from a broker.");
+ dispatchError(out, service, InteractionPattern.PUBSUB, "register", "Register",
+ "Called by the MAL when a PubSub register acknowledgement error is received from a broker.");
+ writeNotifyDispatch(out, model, area, service);
+ dispatchError(out, service, InteractionPattern.PUBSUB, "notify", "Notify",
+ "Called by the MAL when a PubSub update error is received from a broker.");
+ dispatch(out, model, service, InteractionPattern.PUBSUB, "deregisterAck", "DeregisterAck",
+ InteractionStage.ACK, false,
+ "Called by the MAL when a PubSub deregister acknowledgement is received from a broker.");
+
+ JavaMethodBuilder.named("notifyReceivedFromOtherService")
+ .comment("Called by the MAL when a PubSub update from another service is"
+ + " received from a broker.")
+ .argument(HEADER, "msgHeader", HEADER_COMMENT)
+ .argument(NOTIFY_BODY, "body", BODY_COMMENT)
+ .argument("java.util.Map", "qosProperties", QOS_COMMENT)
+ .throwing(MAL_EXCEPTION, THROWN)
+ .write(out);
+ }
+
+ return clazz.close();
+ }
+
+ /**
+ * A callback that carries nothing but the header.
+ */
+ private static JavaMethodBuilder callback(JavaSource out, String name) {
+ return JavaMethodBuilder.named(name)
+ .argument(HEADER, "msgHeader", HEADER_COMMENT)
+ .argument("java.util.Map", "qosProperties", QOS_COMMENT);
+ }
+
+ /**
+ * A callback that carries the fields of one stage of the interaction.
+ */
+ private static void received(JavaSource out, MOModel model, Operation operation,
+ String suffix, InteractionStage stage, String comment) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(operation.getName() + suffix)
+ .comment(comment)
+ .argument(HEADER, "msgHeader", HEADER_COMMENT);
+ addFields(method, model, fieldsOf(operation.getMessage(stage)));
+ method.argument("java.util.Map", "qosProperties", QOS_COMMENT).write(out);
+ }
+
+ /**
+ * A callback that carries an error instead of a body.
+ */
+ private static void error(JavaSource out, String name, String comment) {
+ JavaMethodBuilder.named(name).comment(comment)
+ .argument(HEADER, "msgHeader", HEADER_COMMENT)
+ .argument(JavaNaming.MAL + "MOErrorException", "error",
+ "error The received error message")
+ .argument("java.util.Map", "qosProperties", QOS_COMMENT)
+ .write(out);
+ }
+
+ /**
+ * The notify callback carries what every update carries - which subscription it answers
+ * and the header of the update - then the typed keys, then the published fields.
+ */
+ private static void writeNotifyCallback(JavaSource out, MOModel model, Operation operation) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(operation.getName() + "NotifyReceived")
+ .comment("Called by the MAL when a PubSub update is received from a broker for"
+ + " the operation " + operation.getName())
+ .argument(HEADER, "msgHeader", HEADER_COMMENT)
+ .argument(JavaNaming.MAL_STRUCTURES + "Identifier", "subscriptionId",
+ "The subscriptionId of the subscription.")
+ .argument(JavaNaming.MAL_STRUCTURES + "UpdateHeader", "updateHeader",
+ "The Update header.")
+ .argument(SubscriptionKeysWriter.classNameOf(operation), "keys",
+ "The typed Subscription Key accessors for this update");
+ // The published fields are numbered after the two the MAL always sends first.
+ addFields(method, model,
+ fieldsOf(operation.getMessage(InteractionStage.PUBLISH_NOTIFY)), 2);
+ method.argument("java.util.Map", "qosProperties", QOS_COMMENT).write(out);
+ }
+
+ /**
+ * Writes one dispatch method: it reads the operation number off the header and calls the
+ * callback of that operation, unpacking the body as it goes.
+ */
+ private static void dispatch(JavaSource out, MOModel model, Service service,
+ InteractionPattern pattern, String name, String suffix, InteractionStage stage,
+ boolean carriesBody, String comment) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(name + "Received").asFinal().asOverride()
+ .comment(comment)
+ .argument(HEADER, "msgHeader", HEADER_COMMENT);
+ if (carriesBody) {
+ method.argument(BODY, "body", BODY_COMMENT);
+ }
+ method.argument("java.util.Map", "qosProperties", QOS_COMMENT)
+ .throwing(MAL_EXCEPTION, THROWN);
+
+ method.line("switch (msgHeader.getOperation().getValue()) {");
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() != pattern) {
+ continue;
+ }
+ method.line(" case " + operationNumberOf(service, operation) + ":");
+ String arguments = stage == null ? ""
+ : unpacked(model, fieldsOf(operation.getMessage(stage)), 0);
+ method.line(" " + operation.getName() + suffix + "Received(msgHeader"
+ + arguments + ", qosProperties);");
+ method.line(" break;");
+ }
+ method.line(" default:");
+ method.line(" throw new " + MAL_EXCEPTION + "(\"Consumer adapter was not expecting"
+ + " operation number \" + msgHeader.getOperation().getValue());");
+ method.line("}");
+ method.write(out);
+ }
+
+ /**
+ * Writes the dispatch method for errors, which have no body to unpack.
+ */
+ private static void dispatchError(JavaSource out, Service service, InteractionPattern pattern,
+ String name, String suffix, String comment) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(name + "ErrorReceived")
+ .asFinal().asOverride().comment(comment)
+ .argument(HEADER, "msgHeader", HEADER_COMMENT)
+ .argument(ERROR_BODY, "body", BODY_COMMENT)
+ .argument("java.util.Map", "qosProperties", QOS_COMMENT)
+ .throwing(MAL_EXCEPTION, THROWN);
+
+ method.line("switch (msgHeader.getOperation().getValue()) {");
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() != pattern) {
+ continue;
+ }
+ method.line(" case " + operationNumberOf(service, operation) + ":");
+ method.line(" " + operation.getName() + suffix
+ + "ErrorReceived(msgHeader, body.getError(), qosProperties);");
+ method.line(" break;");
+ }
+ method.line(" default:");
+ method.line(" throw new " + MAL_EXCEPTION + "(\"Consumer adapter was not expecting"
+ + " operation number \" + msgHeader.getOperation().getValue());");
+ method.line("}");
+ method.write(out);
+ }
+
+ /**
+ * The notify dispatch also checks the update belongs to this service: a broker may hold
+ * subscriptions of several, and an update of another one is handed on rather than
+ * misread.
+ */
+ private static void writeNotifyDispatch(JavaSource out, MOModel model, Area area,
+ Service service) {
+ String areaHelper = JavaNaming.packageOf(area) + "." + area.getName() + "Helper";
+ String serviceInfo = JavaNaming.packageOf(service) + "." + service.getName() + "ServiceInfo";
+
+ JavaMethodBuilder method = JavaMethodBuilder.named("notifyReceived").asFinal().asOverride()
+ .comment("Called by the MAL when a PubSub update is received from a broker.")
+ .argument(HEADER, "msgHeader", HEADER_COMMENT)
+ .argument(NOTIFY_BODY, "body", BODY_COMMENT)
+ .argument(JavaNaming.MAL_STRUCTURES + "IdentifierList", "selectedKeys",
+ "selectedKeys The selected Subscription Key names, or null if trimming"
+ + " was not enabled")
+ .argument("java.util.Map", "qosProperties", QOS_COMMENT)
+ .throwing(MAL_EXCEPTION, THROWN);
+
+ method.line("if ((" + areaHelper + "." + area.getName().toUpperCase()
+ + "_AREA_NUMBER.equals(msgHeader.getServiceArea())) && (" + serviceInfo + "."
+ + service.getName().toUpperCase()
+ + "_SERVICE_NUMBER.equals(msgHeader.getService()))) {");
+ method.line(" switch (msgHeader.getOperation().getValue()) {");
+
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() != InteractionPattern.PUBSUB) {
+ continue;
+ }
+ method.line(" case " + operationNumberOf(service, operation) + ":");
+ // The subscription identifier and the update header come first, then the keys
+ // built from that same header, then what was published.
+ String head = ARGUMENT + "(" + JavaNaming.MAL_STRUCTURES
+ + "Identifier) body.getBodyElement(0, new " + JavaNaming.MAL_STRUCTURES
+ + "Identifier())" + ARGUMENT + "(" + JavaNaming.MAL_STRUCTURES
+ + "UpdateHeader) body.getBodyElement(1, new " + JavaNaming.MAL_STRUCTURES
+ + "UpdateHeader())";
+ String keys = ARGUMENT + "new " + SubscriptionKeysWriter.classNameOf(operation)
+ + "((" + JavaNaming.MAL_STRUCTURES + "UpdateHeader) body.getBodyElement(1, new "
+ + JavaNaming.MAL_STRUCTURES + "UpdateHeader()), selectedKeys)";
+ String published = unpacked(model,
+ fieldsOf(operation.getMessage(InteractionStage.PUBLISH_NOTIFY)), 2);
+ method.line(" " + operation.getName() + "NotifyReceived(msgHeader"
+ + head + keys + published + ", qosProperties);");
+ method.line(" break;");
+ }
+ method.line(" default:");
+ method.line(" throw new " + MAL_EXCEPTION + "(\"Consumer adapter was not expecting"
+ + " operation number \" + msgHeader.getOperation().getValue());");
+ method.line(" }");
+ method.line("}");
+ method.line("else {");
+ method.line(" notifyReceivedFromOtherService(msgHeader, body, qosProperties);");
+ method.line("}");
+ method.write(out);
+ }
+
+ /**
+ * @return the fields taken out of the body, each on its own line, starting at the given
+ * position in it.
+ */
+ private static String unpacked(MOModel model, List<Field> fields, int first) {
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ int index = first + i;
+ buf.append(ARGUMENT);
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ String union = JavaNaming.MAL_STRUCTURES + "Union";
+ String element = "body.getBodyElement(" + index + ", new " + union + "("
+ + JavaTypes.nativeDefault(field.getType().getName()) + "))";
+ buf.append("(").append(element).append(" == null) ? null : ((").append(union)
+ .append(") ").append(element).append(").get")
+ .append(field.getType().getName()).append("Value()");
+ } else {
+ buf.append("(").append(JavaTypeName.of(model, field.getType()))
+ .append(") body.getBodyElement(").append(index).append(", ")
+ .append(JavaTypeName.expectedTypeOf(model, field.getType())).append(")");
+ }
+ }
+ return buf.toString();
+ }
+
+
+ private static void addFields(JavaMethodBuilder method, MOModel model, List<Field> fields) {
+ addFields(method, model, fields, 0);
+ }
+
+ private static void addFields(JavaMethodBuilder method, MOModel model, List<Field> fields,
+ int first) {
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ String comment = field.getComment() != null ? field.getComment()
+ : field.getName() + " Argument number " + (first + i)
+ + " as defined by the service operation";
+ method.argument(JavaTypeName.of(model, field.getType()), field.getName(), comment);
+ }
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ private static String operationNumberOf(Service service, Operation operation) {
+ return JavaNaming.packageOf(service) + "." + service.getName() + "ServiceInfo._"
+ + operation.getName().toUpperCase() + "_OP_NUMBER";
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ConsumerStubWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ConsumerStubWriter.java
new file mode 100644
index 00000000..a0a1f741
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ConsumerStubWriter.java
@@ -0,0 +1,435 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.generators.java.JavaTypes;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the consumer stub of a service: one method per operation, taking the fields the
+ * operation sends and answering with the ones it sends back.
+ * <p>
+ * The stub is a thin mapping onto the generic MAL consumer - it names the operation and
+ * hands over the arguments - so every method is a single call, plus the unpacking of
+ * whatever came back.
+ */
+public final class ConsumerStubWriter {
+
+ private static final String CONSUMER = JavaNaming.MAL + "consumer.MALConsumer";
+
+ private static final String MESSAGE = JavaNaming.MAL + "transport.MALMessage";
+
+ private static final String MESSAGE_BODY = JavaNaming.MAL + "transport.MALMessageBody";
+
+ private static final String INTERACTION_EXCEPTION = JavaNaming.MAL + "MALInteractionException";
+
+ private static final String MAL_EXCEPTION = JavaNaming.MAL + "MALException";
+
+ private static final String INTERACTION_THROWN =
+ "if there is a problem during the interaction as defined by the MAL specification.";
+
+ private static final String EXCEPTION_THROWN = "if there is an implementation exception";
+
+ private static final String SENT = "the MAL message sent to initiate the interaction";
+
+ private ConsumerStubWriter() {
+ }
+
+ /**
+ * Writes the stub a consumer calls to invoke the operations of a service.
+ *
+ * @param model Every loaded specification.
+ * @param service The service to write the stub of.
+ * @return the source of the service's consumer stub.
+ */
+ public static String write(MOModel model, Service service) {
+ String name = service.getName();
+ String adapterType = JavaNaming.packageOf(service, JavaNaming.CONSUMER) + "." + name + "Adapter";
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "Stub")
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.CONSUMER))
+ .comment("Consumer stub for " + name + " service.");
+ JavaSource out = clazz.open();
+
+ JavaFieldBuilder.named("consumer").scope("private").asFinal().ofType(CONSUMER)
+ .comment("The consumer field.").write(out);
+
+ JavaMethodBuilder.constructor(name + "Stub")
+ .comment("Wraps a MALconsumer connection with service specific methods that"
+ + " map from the high level service API to the generic MAL API.")
+ .argument(CONSUMER, "consumer", "consumer The MALConsumer to use in this stub.")
+ .line("this.consumer = consumer;")
+ .write(out);
+
+ JavaMethodBuilder.named("getConsumer").returns(CONSUMER, "The MAL consumer object.")
+ .comment("Returns the internal MAL consumer object used for sending of messages"
+ + " from this interface")
+ .line("return consumer;")
+ .write(out);
+
+ for (Operation operation : service.getOperations()) {
+ switch (operation.getPattern()) {
+ case SEND:
+ writeSend(out, model, service, operation);
+ break;
+ case SUBMIT:
+ case REQUEST:
+ writeRequest(out, model, service, operation, adapterType);
+ break;
+ case INVOKE:
+ case PROGRESS:
+ writeInvoke(out, model, service, operation, adapterType);
+ break;
+ case PUBSUB:
+ writePubSub(out, service, operation, adapterType);
+ break;
+ default:
+ break;
+ }
+ }
+
+ return clazz.close();
+ }
+
+ /**
+ * A send has nothing to wait for, so it answers with the message it sent.
+ */
+ private static void writeSend(JavaSource out, MOModel model, Service service,
+ Operation operation) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(operation.getName())
+ .returns(MESSAGE, SENT).comment(operation.getComment());
+ addArguments(method, model, requestBodyOf(operation));
+ addThrows(method);
+ method.line("return consumer.send(" + operationOf(service, operation) + ", "
+ + arguments(model, requestBodyOf(operation)) + ");");
+ method.write(out);
+ }
+
+ /**
+ * A submit or a request is answered in one go, so the stub waits for the answer and
+ * unpacks it. Both also get an asynchronous form and a way to pick an interaction back
+ * up.
+ */
+ private static void writeRequest(JavaSource out, MOModel model, Service service,
+ Operation operation, String adapterType) {
+ List<Field> sent = requestBodyOf(operation);
+ List<Field> received = fieldsOf(operation.getMessage(InteractionStage.RESPONSE));
+ String returnType = returnTypeOf(model, service, operation, received, "Response");
+
+ JavaMethodBuilder method = JavaMethodBuilder.named(operation.getName())
+ .comment(operation.getComment());
+ if (returnType != null) {
+ method.returns(returnType, "The return value of the interaction");
+ }
+ addArguments(method, model, sent);
+ addThrows(method);
+ method.line((returnType == null ? "" : MESSAGE_BODY + " body = ") + "consumer."
+ + patternCallOf(operation) + "(" + operationOf(service, operation) + ", "
+ + arguments(model, sent) + ");");
+ addReturn(method, model, service, operation, received, returnType);
+ method.write(out);
+
+ JavaMethodBuilder async = JavaMethodBuilder.named("async" + capitalise(operation.getName()))
+ .returns(MESSAGE, SENT)
+ .comment("Asynchronous version of method " + operation.getName());
+ addArguments(async, model, sent);
+ async.argument(adapterType, "adapter",
+ "adapter Listener in charge of receiving the messages from the service provider");
+ addThrows(async);
+ async.line("return consumer.async" + capitalise(patternCallOf(operation)) + "("
+ + operationOf(service, operation) + ", adapter, " + arguments(model, sent) + ");");
+ async.write(out);
+
+ writeContinue(out, service, operation, adapterType);
+ }
+
+ /**
+ * An invoke or a progress reports back over time, so the adapter is handed over with
+ * the call and the stub answers only with the acknowledgement.
+ */
+ private static void writeInvoke(JavaSource out, MOModel model, Service service,
+ Operation operation, String adapterType) {
+ List<Field> sent = requestBodyOf(operation);
+ List<Field> acknowledged = fieldsOf(operation.getMessage(InteractionStage.ACK));
+ String returnType = returnTypeOf(model, service, operation, acknowledged, "Ack");
+
+ JavaMethodBuilder method = JavaMethodBuilder.named(operation.getName())
+ .comment(operation.getComment());
+ if (returnType != null) {
+ method.returns(returnType, "The acknowledge value of the interaction");
+ }
+ addArguments(method, model, sent);
+ method.argument(adapterType, "adapter",
+ "adapter Listener in charge of receiving the messages from the service provider");
+ addThrows(method);
+ method.line((returnType == null ? "" : MESSAGE_BODY + " body = ") + "consumer."
+ + patternCallOf(operation) + "(" + operationOf(service, operation)
+ + ", adapter, " + arguments(model, sent) + ");");
+ addReturn(method, model, service, operation, acknowledged, returnType);
+ method.write(out);
+
+ JavaMethodBuilder async = JavaMethodBuilder.named("async" + capitalise(operation.getName()))
+ .returns(MESSAGE, SENT)
+ .comment("Asynchronous version of method " + operation.getName());
+ addArguments(async, model, sent);
+ async.argument(adapterType, "adapter",
+ "adapter Listener in charge of receiving the messages from the service provider");
+ addThrows(async);
+ async.line("return consumer.async" + capitalise(patternCallOf(operation)) + "("
+ + operationOf(service, operation) + ", adapter, " + arguments(model, sent) + ");");
+ async.write(out);
+
+ writeContinue(out, service, operation, adapterType);
+ }
+
+ /**
+ * Registering says what to listen for; deregistering says to stop.
+ */
+ private static void writePubSub(JavaSource out, Service service, Operation operation,
+ String adapterType) {
+ String name = operation.getName();
+ String subscription = JavaNaming.MAL_STRUCTURES + "Subscription";
+ String identifiers = JavaNaming.MAL_STRUCTURES + "IdentifierList";
+ String adapterComment =
+ "adapter Listener in charge of receiving the messages from the service provider";
+
+ JavaMethodBuilder register = JavaMethodBuilder.named(name + "Register")
+ .comment("Register method for the " + name + " PubSub interaction")
+ .argument(subscription, "subscription", "subscription the subscription to register for")
+ .argument(adapterType, "adapter", adapterComment);
+ addThrows(register);
+ register.line("consumer.register(" + operationOf(service, operation)
+ + ", subscription, adapter);");
+ register.write(out);
+
+ JavaMethodBuilder asyncRegister = JavaMethodBuilder.named("async" + capitalise(name) + "Register")
+ .returns(MESSAGE, SENT)
+ .comment("Asynchronous version of method " + name + "Register")
+ .argument(subscription, "subscription", "subscription the subscription to register for")
+ .argument(adapterType, "adapter", adapterComment);
+ addThrows(asyncRegister);
+ asyncRegister.line("return consumer.asyncRegister(" + operationOf(service, operation)
+ + ", subscription, adapter);");
+ asyncRegister.write(out);
+
+ JavaMethodBuilder deregister = JavaMethodBuilder.named(name + "Deregister")
+ .comment("Deregister method for the " + name + " PubSub interaction")
+ .argument(identifiers, "identifierList",
+ "identifierList the subscription identifiers to deregister");
+ addThrows(deregister);
+ deregister.line("consumer.deregister(" + operationOf(service, operation)
+ + ", identifierList);");
+ deregister.write(out);
+
+ JavaMethodBuilder asyncDeregister = JavaMethodBuilder.named("async" + capitalise(name) + "Deregister")
+ .returns(MESSAGE, SENT)
+ .comment("Asynchronous version of method " + name + "Deregister")
+ .argument(identifiers, "identifierList",
+ "identifierList the subscription identifiers to deregister")
+ .argument(adapterType, "adapter", adapterComment);
+ addThrows(asyncDeregister);
+ asyncDeregister.line("return consumer.asyncDeregister(" + operationOf(service, operation)
+ + ", identifierList, adapter);");
+ asyncDeregister.write(out);
+ }
+
+ /**
+ * Picks an interaction back up where it was left, which is how a consumer that was
+ * restarted carries on.
+ */
+ private static void writeContinue(JavaSource out, Service service, Operation operation,
+ String adapterType) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("continue" + capitalise(operation.getName()))
+ .comment("Continues a previously started interaction")
+ .argument(JavaNaming.MAL_STRUCTURES + "UOctet", "lastInteractionStage",
+ "lastInteractionStage The last stage of the interaction to continue")
+ .argument(JavaNaming.MAL_STRUCTURES + "Time", "initiationTimestamp",
+ "initiationTimestamp Timestamp of the interaction initiation message")
+ .argument("Long", "transactionId",
+ "transactionId Transaction identifier of the interaction to continue")
+ .argument(adapterType, "adapter",
+ "adapter Listener in charge of receiving the messages from the service provider");
+ addThrows(method);
+ method.line("consumer.continueInteraction(" + operationOf(service, operation)
+ + ", lastInteractionStage, initiationTimestamp, transactionId, adapter);");
+ method.write(out);
+ }
+
+ /**
+ * Unpacks what came back. Each field is taken out of the body under its own name before
+ * it is answered with, so that the cast reads next to the type it is casting to.
+ */
+ private static void addReturn(JavaMethodBuilder method, MOModel model, Service service,
+ Operation operation, List<Field> fields, String returnType) {
+ if (returnType == null || fields.isEmpty()) {
+ return;
+ }
+ List<String> answers = new ArrayList<String>();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ String union = JavaNaming.MAL_STRUCTURES + "Union";
+ method.line("Object body" + i + " = (Object) body.getBodyElement(" + i + ", new "
+ + union + "(" + JavaTypes.nativeDefault(field.getType().getName()) + "));");
+ answers.add("(body" + i + " == null) ? null : ((" + union + ") body" + i + ").get"
+ + field.getType().getName() + "Value()");
+ } else {
+ method.line("Object body" + i + " = (Object) body.getBodyElement(" + i + ", "
+ + JavaTypeName.expectedTypeOf(model, field.getType()) + ");");
+ answers.add("(" + JavaTypeName.of(model, field.getType()) + ") body" + i);
+ }
+ }
+ if (answers.size() == 1) {
+ method.line("return " + answers.get(0) + ";");
+ return;
+ }
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < answers.size(); i++) {
+ buf.append(i == 0 ? "" : ", ").append(answers.get(i));
+ }
+ method.line("return new " + returnType + "(" + buf + ");");
+ }
+
+
+ /**
+ * @return the type the stub answers with, or null when the operation answers with
+ * nothing. More than one field is answered with the class that holds them together.
+ */
+ private static String returnTypeOf(MOModel model, Service service, Operation operation,
+ List<Field> fields, String messageType) {
+ if (fields.isEmpty()) {
+ return null;
+ }
+ if (fields.size() == 1) {
+ return JavaTypeName.of(model, fields.get(0).getType());
+ }
+ return JavaNaming.packageOf(service, "body") + "."
+ + capitalise(operation.getName()) + messageType;
+ }
+
+ private static void addArguments(JavaMethodBuilder method, MOModel model, List<Field> fields) {
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ // A field the specification did not describe is documented by its place in the
+ // message, which is the only thing there is to say about it.
+ String comment = field.getComment() != null ? field.getComment()
+ : field.getName() + " Argument number " + i
+ + " as defined by the service operation";
+ method.argument(JavaTypeName.of(model, field.getType()), field.getName(), comment);
+ }
+ }
+
+ /**
+ * @return the arguments handed to the MAL, with a native attribute wrapped in the Union
+ * that carries it, or the literal null where there are none.
+ */
+ private static String arguments(MOModel model, List<Field> fields) {
+ if (fields.isEmpty()) {
+ // Cast so that the empty case picks the varargs overload rather than reading as
+ // a single null array.
+ return "(Object[]) null";
+ }
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ buf.append(i == 0 ? "" : ", ");
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ buf.append("(").append(field.getName()).append(" == null) ? null : new ")
+ .append(JavaNaming.MAL_STRUCTURES).append("Union(")
+ .append(field.getName()).append(")");
+ } else {
+ buf.append(field.getName());
+ }
+ }
+ return buf.toString();
+ }
+
+ private static void addThrows(JavaMethodBuilder method) {
+ method.throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN);
+ }
+
+ /**
+ * @return the fields the consumer sends to start the interaction.
+ */
+ private static List<Field> requestBodyOf(Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ return fieldsOf(operation.getMessage(InteractionStage.SEND));
+ case SUBMIT:
+ return fieldsOf(operation.getMessage(InteractionStage.SUBMIT));
+ case REQUEST:
+ return fieldsOf(operation.getMessage(InteractionStage.REQUEST));
+ case INVOKE:
+ return fieldsOf(operation.getMessage(InteractionStage.INVOKE));
+ case PROGRESS:
+ return fieldsOf(operation.getMessage(InteractionStage.PROGRESS));
+ default:
+ return new ArrayList<Field>();
+ }
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ private static String operationOf(Service service, Operation operation) {
+ return JavaNaming.packageOf(service) + "." + service.getName() + "ServiceInfo."
+ + operation.getName().toUpperCase() + "_OP";
+ }
+
+ /**
+ * @return the name of the MAL consumer method that starts this kind of interaction.
+ */
+ private static String patternCallOf(Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ return "send";
+ case SUBMIT:
+ return "submit";
+ case REQUEST:
+ return "request";
+ case INVOKE:
+ return "invoke";
+ case PROGRESS:
+ return "progress";
+ default:
+ return null;
+ }
+ }
+
+ private static String capitalise(String text) {
+ return Character.toUpperCase(text.charAt(0)) + text.substring(1);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ElementFactoryWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ElementFactoryWriter.java
new file mode 100644
index 00000000..11f0c147
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ElementFactoryWriter.java
@@ -0,0 +1,318 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypes;
+import esa.mo.apigen.generators.java.JumpTable;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.AttributeType;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Writes the factory that creates the Elements of an area.
+ * <p>
+ * A type is reached by its number: the type itself under its short form part, and its list
+ * under the negative of it. Nothing is held, so the class of a type is only loaded once a
+ * message carries that type.
+ * <p>
+ * The cases are laid out so that a lookup is a jump rather than a binary search, following
+ * the rules in {@link JumpTable}: the numbers close enough together to be spanned by one
+ * table are switched together, and the ones that lie past it are answered by a second
+ * method, so that they do not stretch the table over the gap in front of them.
+ */
+public final class ElementFactoryWriter {
+
+ /**
+ * The Element the factory answers with, and the one argument every switch takes.
+ */
+ private static final String ELEMENT = JavaNaming.MAL_STRUCTURES + "Element";
+
+ private static final String AREA_METHOD = "createAreaElement";
+
+ private ElementFactoryWriter() {
+ }
+
+ /**
+ * @return the source of the area's element factory.
+ */
+ public static String write(Area area) {
+ String name = area.getName();
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "ElementFactory")
+ .inPackage(JavaNaming.packageOf(area)).asFinal()
+ .implementing(JavaNaming.MAL + "AreaElementFactory")
+ .comment("Creates the Elements of the " + name + " area, without holding an"
+ + " instance of each of them, so that the class of a type is only"
+ + " loaded once a message carries that type.");
+ JavaSource out = clazz.open();
+
+ // The types declared by the area itself answer to service number 0
+ Map<Integer, String> areaTypes = collectTypes(area, null);
+ JumpTable.Split areaSplit = JumpTable.splitTypes(areaTypes);
+
+ // The types of each service, gathered up front: an Area whose services declare
+ // none of their own is reached without a switch over them.
+ Map<Service, Map<Integer, String>> typesByService
+ = new LinkedHashMap<Service, Map<Integer, String>>();
+ boolean anyServiceHasTypes = false;
+
+ for (Service service : area.getServices()) {
+ Map<Integer, String> serviceTypes = collectTypes(area, service);
+ typesByService.put(service, serviceTypes);
+ anyServiceHasTypes = anyServiceHasTypes || !serviceTypes.isEmpty();
+ }
+
+ JavaMethodBuilder createElement = JavaMethodBuilder.named("createElement")
+ .asOverride()
+ .returns(ELEMENT, null)
+ .argument("int", "serviceNumber", null)
+ .argument("int", "typeNumber", null);
+
+ if (anyServiceHasTypes) {
+ createElement.line("switch (serviceNumber) {");
+ createElement.line(" case 0: return " + AREA_METHOD + "(typeNumber);");
+ for (Service service : area.getServices()) {
+ createElement.line(" case " + service.getNumber() + ": return "
+ + methodNameOf(service) + "(typeNumber);");
+ }
+ createElement.line(" default: return null;");
+ createElement.line("}");
+ } else {
+ // Every type of this Area is declared by the Area itself, so the types are
+ // answered here rather than through a switch over services that would only
+ // ever lead back to the one branch.
+ createElement.line("if (serviceNumber != 0) {");
+ createElement.line(" return null; // This Area declares no types under a service");
+ createElement.line("}");
+ createElement.lines(switchBody(areaSplit.getInBand(),
+ areaSplit.isSplit() ? outOfBandNameOf(AREA_METHOD) : null));
+ }
+ createElement.write(out);
+
+ // The factory says which Area it belongs to, so that registering it cannot
+ // associate it with the wrong number or version.
+ JavaMethodBuilder.named("getAreaNumber").asOverride().returns("int", null)
+ .line("return " + area.getNumber() + ";").write(out);
+ JavaMethodBuilder.named("getAreaVersion").asOverride().returns("int", null)
+ .line("return " + area.getVersion() + ";").write(out);
+
+ if (anyServiceHasTypes) {
+ writeTypeSwitch(out, AREA_METHOD, areaTypes,
+ "Creates an Element declared by the area itself.");
+ for (Map.Entry<Service, Map<Integer, String>> entry : typesByService.entrySet()) {
+ writeTypeSwitch(out, methodNameOf(entry.getKey()), entry.getValue(),
+ "Creates an Element declared by the " + entry.getKey().getName()
+ + " service.");
+ }
+ } else if (areaSplit.isSplit()) {
+ // createElement() holds the jump table itself, so only the types that did not
+ // fit in it are left to write out
+ writeOutOfBandMethod(out, AREA_METHOD, areaSplit);
+ }
+
+ return clazz.close();
+ }
+
+ /**
+ * Collects the types of an area or of one of its services, as the expression that
+ * creates one, by type number. The list of a type takes the negative of its number.
+ *
+ * @param area The area the types belong to.
+ * @param service The service, or null for the types of the area itself.
+ * @return the expressions, by type number.
+ */
+ private static Map<Integer, String> collectTypes(Area area, Service service) {
+ Map<Integer, String> types = new TreeMap<Integer, String>();
+ String pkg = (service == null)
+ ? JavaNaming.packageOf(area, JavaNaming.STRUCTURES)
+ : JavaNaming.packageOf(service, JavaNaming.STRUCTURES);
+ List<TypeDefinition> declared = (service == null)
+ ? area.getDataTypes() : service.getDataTypes();
+
+ for (TypeDefinition type : declared) {
+ Integer number = shortFormPartOf(type);
+
+ if (number == null) {
+ continue; // Abstract, or a fundamental: it is never created
+ }
+
+ String name = type.getName();
+ String created;
+
+ if (type instanceof AttributeType && JavaTypes.isNative(area.getName(), name)) {
+ // A native attribute is carried by a Union rather than by a class of its own
+ created = "new " + JavaNaming.MAL_STRUCTURES + "Union("
+ + JavaTypes.nativeDefault(name) + ")";
+ } else {
+ created = "new " + pkg + "." + JavaTypes.className(area.getName(), name) + "()";
+ }
+
+ types.put(number, created);
+ types.put(-number, "new " + pkg + "."
+ + JavaTypes.className(area.getName(), name + "List") + "()");
+ }
+
+ return types;
+ }
+
+ /**
+ * Writes the method, or the pair of methods, that create the Element of a type number.
+ * The class of a type is named only inside its own branch, so it is loaded when a
+ * message first carries that type, and not before.
+ */
+ private static void writeTypeSwitch(JavaSource out, String methodName,
+ Map<Integer, String> types, String comment) {
+ JumpTable.Split split = JumpTable.splitTypes(types);
+
+ // Splitting the types over two methods only pays off when there is a jump table to
+ // keep and something that would otherwise stretch it.
+ if (!split.isSplit()) {
+ writeSwitchMethod(out, methodName, comment, split.all(), null);
+ return;
+ }
+
+ writeSwitchMethod(out, methodName, comment, split.getInBand(), outOfBandNameOf(methodName));
+ writeOutOfBandMethod(out, methodName, split);
+ }
+
+ /**
+ * Writes the method that answers for the types the jump table could not hold.
+ */
+ private static void writeOutOfBandMethod(JavaSource out, String methodName,
+ JumpTable.Split split) {
+ writeSwitchMethod(out, outOfBandNameOf(methodName),
+ "Creates an Element whose type number lies too far out to be held in the"
+ + " jump table that is asked first. This says nothing about how often the"
+ + " type is asked for: the numbers of an Area are not handed out in the"
+ + " order of use.", split.getOutOfBand(), null);
+ }
+
+ /**
+ * Writes one method holding a switch over type numbers.
+ *
+ * @param out The source to write the method to.
+ * @param methodName The name of the method.
+ * @param comment The comment of the method.
+ * @param types The types the switch answers for, by type number.
+ * @param fallback The method the switch falls back on for a type number it does not
+ * answer for, or null to answer with nothing.
+ */
+ private static void writeSwitchMethod(JavaSource out, String methodName, String comment,
+ Map<Integer, String> types, String fallback) {
+ JavaMethodBuilder.named(methodName).scope("private").asStatic()
+ .comment(comment)
+ .returns(ELEMENT, null)
+ .argument("int", "typeNumber", null)
+ .lines(switchBody(types, fallback))
+ .write(out);
+ }
+
+ /**
+ * Builds the body that answers a type number: one switch, or a switch for each side of
+ * zero where the numbers lie too far out to be held together.
+ *
+ * @param types The types the body answers for, by type number.
+ * @param fallback The method the body falls back on for a type number it does not
+ * answer for, or null to answer with nothing.
+ * @return the lines of the body, indented relative to it.
+ */
+ private static List<String> switchBody(Map<Integer, String> types, String fallback) {
+ String missing = (fallback == null) ? "null" : fallback + "(typeNumber)";
+ List<String> lines = new ArrayList<String>();
+
+ if (types.isEmpty()) {
+ lines.add("return " + missing + ";");
+ return lines;
+ }
+
+ if (JumpTable.shouldSplitOnSign(types.keySet())) {
+ Map<Integer, String> positives = new TreeMap<Integer, String>();
+ Map<Integer, String> negatives = new TreeMap<Integer, String>();
+
+ for (Map.Entry<Integer, String> entry : types.entrySet()) {
+ boolean positive = entry.getKey() > 0;
+ (positive ? positives : negatives).put(entry.getKey(), entry.getValue());
+ }
+
+ // These numbers lie far from zero, so the types and their lists are reached
+ // apart: together they would span the whole way across zero
+ lines.add("if (typeNumber > 0) {");
+ addSwitchLines(lines, positives, missing, " ");
+ lines.add("}");
+ addSwitchLines(lines, negatives, missing, "");
+ return lines;
+ }
+
+ addSwitchLines(lines, types, missing, "");
+ return lines;
+ }
+
+ /**
+ * Adds the lines of one switch over type numbers.
+ *
+ * @param lines The body being built.
+ * @param types The types the switch answers for, by type number.
+ * @param missing What the switch answers with for a type number it does not answer for.
+ * @param indent The step this switch takes past the body of the method.
+ */
+ private static void addSwitchLines(List<String> lines, Map<Integer, String> types,
+ String missing, String indent) {
+ lines.add(indent + "switch (typeNumber) {");
+ for (Map.Entry<Integer, String> entry : types.entrySet()) {
+ lines.add(indent + " case " + entry.getKey() + ": return "
+ + entry.getValue() + ";");
+ }
+ lines.add(indent + " default: return " + missing + ";");
+ lines.add(indent + "}");
+ }
+
+ private static String methodNameOf(Service service) {
+ return "create" + service.getName() + "Element";
+ }
+
+ private static String outOfBandNameOf(String methodName) {
+ return methodName + "OutOfBand";
+ }
+
+ private static Integer shortFormPartOf(TypeDefinition type) {
+ if (type instanceof EnumerationType) {
+ return ((EnumerationType) type).getShortFormPart();
+ }
+ if (type instanceof AttributeType) {
+ return ((AttributeType) type).getShortFormPart();
+ }
+ if (type instanceof CompositeType) {
+ return ((CompositeType) type).getShortFormPart();
+ }
+ return null;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/EnumerationWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/EnumerationWriter.java
new file mode 100644
index 00000000..6bf7d271
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/EnumerationWriter.java
@@ -0,0 +1,189 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaComment;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.ShortForm;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.EnumerationItem;
+import esa.mo.apigen.model.types.EnumerationType;
+import java.util.List;
+
+/**
+ * Writes the Java class for an enumeration.
+ */
+public final class EnumerationWriter {
+
+
+ private EnumerationWriter() {
+ }
+
+ /**
+ * Renders the class.
+ *
+ * @param area The area defining the enumeration.
+ * @param service The service defining it, or null for an area-level type.
+ * @param type The enumeration.
+ * @return the source of the class.
+ */
+ public static String write(Area area, Service service, EnumerationType type) {
+ String name = type.getName();
+ String pkg = service == null
+ ? JavaNaming.packageOf(area, JavaNaming.STRUCTURES)
+ : JavaNaming.packageOf(service, JavaNaming.STRUCTURES);
+ String fq = pkg + "." + name;
+ long shortForm = ShortForm.of(area, service, type.getShortFormPart());
+ List<EnumerationItem> items = type.getItems();
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(name).inPackage(pkg).asFinal()
+ .extending(JavaNaming.MAL + "structures.Enumeration")
+ .comment("Enumeration class for " + name + ".");
+ JavaSource out = clazz.open();
+ ShortForm.writeIdentity(out, shortForm);
+
+ for (EnumerationItem item : items) {
+ String value = item.getValue();
+ JavaFieldBuilder.named(value + "_VALUE").asStatic().asFinal()
+ .ofType("int").value(String.valueOf(item.getNumericValue()))
+ .comment("Enumeration value for " + value + ".")
+ .write(out);
+ JavaFieldBuilder.named(value).asStatic().asFinal()
+ .ofType(fq).value("new " + fq + "(" + fq + "." + value + "_VALUE)")
+ .comment("Enumeration singleton for value " + value + ".")
+ .write(out);
+ }
+
+ JavaFieldBuilder.named("_ENUMERATIONS").scope("private").asStatic().asFinal()
+ .ofType(fq + "[]").value(enumerationsOf(items))
+ .comment("Set of enumeration instances.")
+ .write(out);
+
+ // The no-argument constructor takes the comment verbatim - unwrapped, with no
+ // trailing period and no blank line under it - where every other method wraps it.
+ // The difference is in the existing generator and is reproduced here, which is why
+ // this one method is written out rather than built like the rest.
+ out.blank();
+ out.line(" /**");
+ out.line(" * " + type.getComment());
+ out.line(" */");
+ out.line(" public " + name + "() {");
+ out.line(" super(-1);");
+ out.line(" }");
+
+ String comment = type.getComment();
+ if (comment == null || comment.isEmpty()) {
+ comment = "Creates an instance of the " + name + " Enumeration.";
+ }
+ JavaMethodBuilder.constructor(name).comment(comment)
+ .argument("int", "value", "The value of the Enumeration.")
+ .line("super(value);")
+ .write(out);
+
+ JavaMethodBuilder toString = JavaMethodBuilder.named("toString").asOverride()
+ .returns("String", null);
+ toString.line("switch (getValue()) {");
+ for (EnumerationItem item : items) {
+ toString.line(" case " + item.getValue() + "_VALUE:");
+ toString.line(" return \"" + item.getValue() + "\";");
+ }
+ toString.line(" default:");
+ toString.line(" throw new RuntimeException(\"Unknown ordinal!\");");
+ toString.line("}");
+ toString.write(out);
+
+ JavaMethodBuilder fromString = JavaMethodBuilder.named("fromString").asStatic()
+ .comment("Returns the enumeration element represented by the supplied string,"
+ + " or null if not matched.")
+ .returns(fq, "The matched enumeration element, or null if not matched.")
+ .argument("String", "s", "s The string to search for.");
+ fromString.line("switch (s) {");
+ for (EnumerationItem item : items) {
+ fromString.line(" case \"" + item.getValue() + "\":");
+ fromString.line(" return " + name + "." + item.getValue() + ";");
+ }
+ fromString.line(" default:");
+ fromString.line(" throw new RuntimeException(\"Unknown Enumeration for the "
+ + "provided string: \" + s);");
+ fromString.line("}");
+ fromString.write(out);
+
+ JavaMethodBuilder fromValue = JavaMethodBuilder.named("fromValue").asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Enumeration", null)
+ .argument("Integer", "value", null);
+ fromValue.line("switch (value) {");
+ for (EnumerationItem item : items) {
+ fromValue.line(" case " + item.getValue() + "_VALUE:");
+ fromValue.line(" return " + name + "." + item.getValue() + ";");
+ }
+ fromValue.line(" default:");
+ fromValue.line(" throw new RuntimeException(\"Unknown Enumeration for the "
+ + "provided value: \" + value);");
+ fromValue.line("}");
+ fromValue.write(out);
+
+ JavaMethodBuilder.named("createElement").asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Element", null)
+ .line("return _ENUMERATIONS[0];")
+ .write(out);
+
+ JavaMethodBuilder.named("getEnumSize").asOverride().returns("int", null)
+ .line("return " + items.size() + ";")
+ .write(out);
+
+ JavaMethodBuilder.named("getTypeId").asOverride()
+ .returns(JavaNaming.MAL + "TypeId", null)
+ .line("return TYPE_ID;")
+ .write(out);
+
+ return clazz.close();
+ }
+ /**
+ * The instances are listed in one run that wraps at the same threshold as a comment,
+ * each line indented by eight spaces, and the array closes on the line of the last of
+ * them.
+ *
+ * @param items The items of the enumeration.
+ * @return the initialiser of the array of instances.
+ */
+ private static String enumerationsOf(List<EnumerationItem> items) {
+ StringBuilder values = new StringBuilder();
+ for (int i = 0; i < items.size(); i++) {
+ values.append(i == 0 ? "" : ", ").append(items.get(i).getValue());
+ }
+
+ StringBuilder buf = new StringBuilder("{");
+ List<String> lines = JavaComment.wrap(values.toString());
+ for (int i = 0; i < lines.size(); i++) {
+ buf.append("\n ").append(lines.get(i));
+ if (i == lines.size() - 1) {
+ buf.append('}');
+ }
+ }
+ return buf.toString();
+ }
+
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ExceptionWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ExceptionWriter.java
new file mode 100644
index 00000000..c9f72d06
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ExceptionWriter.java
@@ -0,0 +1,105 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.ErrorDefinition;
+
+/**
+ * Writes the Java exception class for an error an area declares.
+ * <p>
+ * Every error becomes an exception in the area's own package, whether the area or one of
+ * its services declared it. The name it was declared under is kept verbatim in the class,
+ * and the number is read from the area's helper, so an error renamed between MAL
+ * generations still says which name it was raised under.
+ */
+public final class ExceptionWriter {
+
+ private ExceptionWriter() {
+ }
+
+ /**
+ * @return the source of the exception class.
+ */
+ public static String write(Area area, ErrorDefinition error) {
+ String className = classNameOf(error.getName());
+ String pkg = JavaNaming.packageOf(area);
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(className).inPackage(pkg).asFinal()
+ .extending(JavaNaming.MAL + "MOErrorException")
+ .comment("The " + className + " exception."
+ + (error.getComment() == null || error.getComment().isEmpty()
+ ? "" : " " + error.getComment()));
+ JavaSource out = clazz.open();
+ JavaFieldBuilder.named("MO_ERROR_NAME").scope("private").asStatic().asFinal()
+ .ofType("String").value("\"" + error.getName() + "\"")
+ .write(out);
+
+ String number = area.getName() + "Helper." + constantOf(error.getName()) + "_ERROR_NUMBER";
+
+ JavaMethodBuilder.constructor(className)
+ .comment("Constructs a new " + className + " exception.")
+ .line("super(MO_ERROR_NAME, " + number + ", \"\");")
+ .write(out);
+
+ JavaMethodBuilder.constructor(className)
+ .comment("Constructs a new " + className + " exception.")
+ .argument("Object", "extraInformation", "The extraInformation of the exception.")
+ .line("super(MO_ERROR_NAME, " + number + ", extraInformation);")
+ .write(out);
+
+ return clazz.close();
+ }
+
+ /**
+ * Returns the class name for an error: the words of its name run together, however it
+ * was spelled. DUPLICATE and "Delivery Failed" give DuplicateException and
+ * DeliveryFailedException.
+ *
+ * @param errorName The declared name.
+ * @return the class name.
+ */
+ public static String classNameOf(String errorName) {
+ StringBuilder buf = new StringBuilder();
+ for (String word : errorName.split("[ _]")) {
+ if (!word.isEmpty()) {
+ buf.append(Character.toUpperCase(word.charAt(0)))
+ .append(word.substring(1).toLowerCase());
+ }
+ }
+ return buf + "Exception";
+ }
+
+ /**
+ * Returns the name of the helper constant holding the error's number.
+ *
+ * @param errorName The declared name.
+ * @return the constant name, without the trailing _ERROR_NUMBER.
+ */
+ public static String constantOf(String errorName) {
+ return errorName.replace(' ', '_').toUpperCase();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/HelperWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/HelperWriter.java
new file mode 100644
index 00000000..20113785
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/HelperWriter.java
@@ -0,0 +1,157 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.ErrorDefinition;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the helper classes: one for an area, holding its identity and the numbers of the
+ * errors it declares, and one for each service, holding the service singleton.
+ */
+public final class HelperWriter {
+
+ private static final String STRUCTURES = JavaNaming.MAL_STRUCTURES;
+
+ private HelperWriter() {
+ }
+
+ /**
+ * @return the source of the area helper.
+ */
+ public static String writeArea(Area area) {
+ String name = area.getName();
+ String upper = name.toUpperCase();
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "Helper")
+ .inPackage(JavaNaming.packageOf(area))
+ .comment("Helper class for " + name + " area.");
+ JavaSource out = clazz.open();
+
+ constant("_" + upper + "_AREA_NUMBER", "int", String.valueOf(area.getNumber()))
+ .comment("Area number literal.").write(out);
+ constant(upper + "_AREA_NUMBER", STRUCTURES + "UShort",
+ "new " + STRUCTURES + "UShort(_" + upper + "_AREA_NUMBER)")
+ .comment("Area number instance.").write(out);
+ constant(upper + "_AREA_NAME", STRUCTURES + "Identifier",
+ "new " + STRUCTURES + "Identifier(\"" + name + "\")")
+ .comment("Area name constant.").write(out);
+ constant("_" + upper + "_AREA_VERSION", "short", String.valueOf(area.getVersion()))
+ .comment("Area version literal.").write(out);
+ constant(upper + "_AREA_VERSION", STRUCTURES + "UOctet",
+ "new " + STRUCTURES + "UOctet(_" + upper + "_AREA_VERSION)")
+ .comment("Area version instance.").write(out);
+
+ // Always empty: the elements of an area are reached through its factory instead.
+ constant(upper + "_AREA_ELEMENTS", STRUCTURES + "Element[]", "{}")
+ .comment("Area Elements.").write(out);
+
+ constant(upper + "_AREA_SERVICES", JavaNaming.MAL + "ServiceInfo[]",
+ servicesOf(area)).comment("Services in this Area.").write(out);
+
+ constant(upper + "_AREA", JavaNaming.MAL + "MALArea",
+ "new " + JavaNaming.MAL + "MALArea(" + upper + "_AREA_NUMBER, " + upper
+ + "_AREA_NAME, " + upper + "_AREA_VERSION, " + upper + "_AREA_ELEMENTS, "
+ + upper + "_AREA_SERVICES, new " + name + "ElementFactory())")
+ .comment("Area singleton instance.").write(out);
+
+ for (ErrorDefinition error : errorsOf(area)) {
+ String constant = ExceptionWriter.constantOf(error.getName());
+ constant("_" + constant + "_ERROR_NUMBER", "long", String.valueOf(error.getNumber()))
+ .comment("Error literal for error " + constant + ".").write(out);
+ constant(constant + "_ERROR_NUMBER", STRUCTURES + "UInteger",
+ "new " + STRUCTURES + "UInteger(_" + constant + "_ERROR_NUMBER)")
+ .comment("Error instance for error " + constant + ".").write(out);
+ }
+
+ JavaMethodBuilder.constructor(name + "Helper").scope("private")
+ .line("// Utility class; not meant to be instantiated.")
+ .write(out);
+ return clazz.close();
+ }
+
+ /**
+ * @param fieldName The name of the constant.
+ * @param type The type of the constant.
+ * @param value What it is initialised to.
+ * @return a public static final field, which is all a helper holds.
+ */
+ private static JavaFieldBuilder constant(String fieldName, String type, String value) {
+ return JavaFieldBuilder.named(fieldName).asStatic().asFinal()
+ .ofType(type).value(value);
+ }
+
+ /**
+ * The services are laid out one per line, and the array closes on the line of the last
+ * of them, after its trailing comma.
+ *
+ * @param area The area being written.
+ * @return the initialiser of the array of services.
+ */
+ private static String servicesOf(Area area) {
+ if (area.getServices().isEmpty()) {
+ return "{}";
+ }
+ StringBuilder buf = new StringBuilder("{");
+ for (Service service : area.getServices()) {
+ buf.append("\n ").append(JavaNaming.packageOf(service)).append('.')
+ .append(service.getName()).append("Helper.")
+ .append(service.getName().toUpperCase()).append("_SERVICE,");
+ }
+ return buf.append('}').toString();
+ }
+
+ /**
+ * @return the source of a service helper.
+ */
+ public static String writeService(Service service) {
+ String name = service.getName();
+ String pkg = JavaNaming.packageOf(service);
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "Helper").inPackage(pkg)
+ .comment("Helper class for " + name + " service.");
+ JavaSource out = clazz.open();
+ constant(name.toUpperCase() + "_SERVICE", pkg + "." + name + "ServiceInfo",
+ "new " + pkg + "." + name + "ServiceInfo()")
+ .comment("Service singleton instance.").write(out);
+ JavaMethodBuilder.constructor(name + "Helper").scope("private")
+ .line("// Utility class; not meant to be instantiated.")
+ .write(out);
+ return clazz.close();
+ }
+
+ /**
+ * @return every error the area declares, its own and its services'.
+ */
+ public static List<ErrorDefinition> errorsOf(Area area) {
+ List<ErrorDefinition> errors = new ArrayList<ErrorDefinition>(area.getErrors());
+ for (Service service : area.getServices()) {
+ errors.addAll(service.getErrors());
+ }
+ return errors;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ListWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ListWriter.java
new file mode 100644
index 00000000..ee1da208
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ListWriter.java
@@ -0,0 +1,200 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypes;
+import esa.mo.apigen.generators.java.ShortForm;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.AttributeType;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+
+/**
+ * Writes the list class that accompanies every concrete type.
+ * <p>
+ * A list's short form part is the negation of its element's, in three bytes - so a type
+ * with part 12 has a list with part {@code 0xFFFFFF - 11}.
+ */
+public final class ListWriter {
+
+
+ private ListWriter() {
+ }
+
+ /**
+ * @return the source of the list class, or null if the type has no list.
+ */
+ public static String write(Area area, Service service, TypeDefinition type) {
+ Integer shortFormPart = shortFormPartOf(type);
+ if (shortFormPart == null) {
+ return type instanceof CompositeType
+ ? writeHeterogeneous(area, service, type) : null;
+ }
+ String name = type.getName();
+ String listName = name + "List";
+ String pkg = service == null
+ ? JavaNaming.packageOf(area, JavaNaming.STRUCTURES)
+ : JavaNaming.packageOf(service, JavaNaming.STRUCTURES);
+ boolean isNative = JavaTypes.isNative(area.getName(), name);
+ // A native attribute type is a plain Java type: the list holds Boolean, not a
+ // generated class.
+ String element = isNative ? JavaTypes.nativeName(name) : pkg + "." + name;
+ String fq = pkg + "." + name;
+ long shortForm = ShortForm.of(area, service, 0xFFFFFFL & -shortFormPart.longValue());
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(listName).inPackage(pkg).asFinal()
+ .extending("java.util.ArrayList<" + element + ">")
+ .implementing(JavaNaming.MAL_STRUCTURES + "HomogeneousList<" + element + ">")
+ .comment("List class for " + name + ".");
+ JavaSource out = clazz.open();
+ ShortForm.writeIdentity(out, shortForm);
+
+ JavaMethodBuilder.constructor(listName)
+ .comment("Default constructor for " + listName + ".")
+ .write(out);
+
+ JavaMethodBuilder.constructor(listName)
+ .comment("Constructor that initialises the capacity of the list.")
+ .argument("int", "initialCapacity", "The required initial capacity.")
+ .line("super(initialCapacity);")
+ .write(out);
+
+ JavaMethodBuilder.constructor(listName)
+ .comment("Constructor that uses an ArrayList for initialization.")
+ .argument("java.util.ArrayList<" + element + ">", "elementList",
+ "The ArrayList that is used for initialization.")
+ .line("for(" + element + " element : elementList) {")
+ .line(" this.add(element);")
+ .line("}")
+ .write(out);
+
+ JavaMethodBuilder.named("add").asOverride().returns("boolean", null)
+ .argument(element, "element", null)
+ .line("if (element == null) {")
+ .line(" throw new IllegalArgumentException(\"The added argument cannot "
+ + "be null!\");")
+ .line("}")
+ .line("return super.add(element);")
+ .write(out);
+
+ JavaMethodBuilder.named("createElement").asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Element", null)
+ .line("return new " + listName + "();")
+ .write(out);
+
+ JavaMethodBuilder createTyped = JavaMethodBuilder.named("createTypedElement")
+ .asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Element", null);
+ if (isNative) {
+ // Nothing can be instantiated for a Java built-in, so the list hands back a
+ // Union carrying its own type id instead.
+ createTyped.line(JavaNaming.MAL + "TypeId typeId = this.getTypeId();");
+ createTyped.line("return new Union(typeId.generateTypeIdPositive());");
+ } else {
+ createTyped.line("return " + typedElement(type, fq) + ";");
+ }
+ createTyped.write(out);
+
+ JavaMethodBuilder.named("encode").asOverride()
+ .argument(JavaNaming.MAL + "MALEncoder", "encoder", null)
+ .throwing(JavaNaming.MAL + "MALException", null)
+ .line("encoder.encodeHomogeneousList(this);")
+ .write(out);
+
+ JavaMethodBuilder.named("decode").asOverride()
+ .returns(JavaNaming.MAL_STRUCTURES + "Element", null)
+ .argument(JavaNaming.MAL + "MALDecoder", "decoder", null)
+ .throwing(JavaNaming.MAL + "MALException", null)
+ .line("decoder.decodeHomogeneousList(this);")
+ .line("return this;")
+ .write(out);
+
+ JavaMethodBuilder.named("getTypeId").asOverride()
+ .returns(JavaNaming.MAL + "TypeId", null)
+ .line("return TYPE_ID;")
+ .write(out);
+
+ return clazz.close();
+ }
+
+ /**
+ * An abstract composite has no short form and cannot be instantiated, so its list
+ * holds whatever extends it and checks the type on the way in.
+ */
+ private static String writeHeterogeneous(Area area, Service service, TypeDefinition type) {
+ String name = type.getName();
+ String listName = name + "List";
+ String pkg = service == null
+ ? JavaNaming.packageOf(area, JavaNaming.STRUCTURES)
+ : JavaNaming.packageOf(service, JavaNaming.STRUCTURES);
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(listName).inPackage(pkg).asFinal()
+ .extending(JavaNaming.MAL + "structures.HeterogeneousList")
+ .comment("List class for " + name + ".");
+ JavaSource out = clazz.open();
+ JavaMethodBuilder.constructor(listName)
+ .comment("Default constructor for " + listName + ".")
+ .write(out);
+
+ JavaMethodBuilder.named("add").asOverride().returns("boolean", null)
+ .argument(JavaNaming.MAL_STRUCTURES + "Element", "element", null)
+ .line("if (element != null && !(element instanceof " + name + ")) {")
+ .line(" throw new java.lang.ClassCastException(\"The added element does "
+ + "not extend the type: " + name + "\");")
+ .line("}")
+ .line("return super.add(element);")
+ .write(out);
+ return clazz.close();
+ }
+
+ /**
+ * An enumeration has no no-argument value to hand back, so the list offers its first
+ * singleton instead.
+ */
+ private static String typedElement(TypeDefinition type, String fq) {
+ if (type instanceof EnumerationType) {
+ EnumerationType enumeration = (EnumerationType) type;
+ if (!enumeration.getItems().isEmpty()) {
+ return fq + "." + enumeration.getItems().get(0).getValue();
+ }
+ }
+ return "new " + fq + "()";
+ }
+
+ private static Integer shortFormPartOf(TypeDefinition type) {
+ if (type instanceof EnumerationType) {
+ return ((EnumerationType) type).getShortFormPart();
+ }
+ if (type instanceof AttributeType) {
+ return ((AttributeType) type).getShortFormPart();
+ }
+ if (type instanceof CompositeType) {
+ return ((CompositeType) type).getShortFormPart();
+ }
+ return null;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/MultiReturnBodyWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/MultiReturnBodyWriter.java
new file mode 100644
index 00000000..aaceade4
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/MultiReturnBodyWriter.java
@@ -0,0 +1,143 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the class that holds the answer of an operation that answers with more than one
+ * field, since a Java method can only return one thing.
+ */
+public final class MultiReturnBodyWriter {
+
+ /**
+ * The package the classes live in, which is neither the consumer's nor the provider's:
+ * both sides of the interaction name them.
+ */
+ public static final String BODY = "body";
+
+ private MultiReturnBodyWriter() {
+ }
+
+ /**
+ * @return the operations of a service that answer with more than one field, and so need
+ * a class to hold the answer.
+ */
+ public static List<Operation> operationsOf(Service service) {
+ List<Operation> found = new ArrayList<Operation>();
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() == InteractionPattern.REQUEST
+ && fieldsOf(operation.getMessage(InteractionStage.RESPONSE)).size() > 1) {
+ found.add(operation);
+ }
+ }
+ return found;
+ }
+
+ /**
+ * @return the name of the class that holds the answer of this operation.
+ */
+ public static String classNameOf(Operation operation) {
+ String name = operation.getName();
+ return Character.toUpperCase(name.charAt(0)) + name.substring(1) + "Response";
+ }
+
+ /**
+ * @return the source of the class holding the answer.
+ */
+ public static String write(MOModel model, Service service, Operation operation) {
+ String className = classNameOf(operation);
+ List<Field> fields = fieldsOf(operation.getMessage(InteractionStage.RESPONSE));
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(className).asFinal()
+ .inPackage(JavaNaming.packageOf(service, BODY))
+ .comment("Multi body return class for " + className + ".");
+ JavaSource out = clazz.open();
+
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ // The field is documented by its name and then by what it holds, because a
+ // reader of this class has only the names to go by.
+ JavaFieldBuilder.named(field.getName()).scope("private")
+ .ofType(JavaTypeName.of(model, field.getType()))
+ .comment(field.getName() + ": " + describe(field, i))
+ .write(out);
+ }
+
+ JavaMethodBuilder.constructor(className)
+ .comment("Default constructor for " + className + ".")
+ .write(out);
+
+ JavaMethodBuilder constructor = JavaMethodBuilder.constructor(className)
+ .comment("Constructs an instance of this type using provided values.");
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ constructor.argument(JavaTypeName.of(model, field.getType()), field.getName(),
+ describe(field, i));
+ }
+ for (Field field : fields) {
+ constructor.line("this." + field.getName() + " = " + field.getName() + ";");
+ }
+ constructor.write(out);
+
+ for (Field field : fields) {
+ JavaMethodBuilder.named("get" + capitalise(field.getName()))
+ .comment("Returns the field " + field.getName() + ".")
+ .returns(JavaTypeName.of(model, field.getType()),
+ "The field " + field.getName())
+ .line("return " + field.getName() + ";")
+ .write(out);
+ }
+
+ return clazz.close();
+ }
+
+ /**
+ * @return what the field holds, or its place in the message where nothing was said.
+ */
+ private static String describe(Field field, int index) {
+ return field.getComment() != null ? field.getComment()
+ : field.getName() + " Argument number " + index
+ + " as defined by the service operation";
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ private static String capitalise(String text) {
+ return Character.toUpperCase(text.charAt(0)) + text.substring(1);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderHandlerWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderHandlerWriter.java
new file mode 100644
index 00000000..e5024acc
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderHandlerWriter.java
@@ -0,0 +1,194 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.model.ErrorDefinition;
+import esa.mo.apigen.model.ErrorReference;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the handler interface of a service: the one method a provider has to implement per
+ * operation, and nothing else.
+ * <p>
+ * The errors an operation declares are on the throws clause, so a provider raises them
+ * directly and the layer above wraps them into an interaction exception.
+ */
+public final class ProviderHandlerWriter {
+
+ private static final String INTERACTION_EXCEPTION = JavaNaming.MAL + "MALInteractionException";
+
+ private static final String MAL_EXCEPTION = JavaNaming.MAL + "MALException";
+
+ private static final String INTERACTION_COMMENT =
+ "The MAL object representing the interaction in the provider.";
+
+ private ProviderHandlerWriter() {
+ }
+
+ /**
+ * @return the source of the service's handler interface.
+ */
+ public static String write(MOModel model, Service service) {
+ String name = service.getName();
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "Handler").asInterface()
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.PROVIDER))
+ .comment("Interface that providers of the " + name + " service must implement"
+ + " to handle the operations of that service.");
+ JavaSource out = clazz.open();
+
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() == esa.mo.apigen.model.InteractionPattern.PUBSUB) {
+ continue; // A provider publishes rather than answers, so there is nothing to implement
+ }
+ writeOperation(out, model, service, operation);
+ }
+
+ JavaMethodBuilder.named("setSkeleton").asDeclaration()
+ .comment("Sets the skeleton to be used for creation of publishers.")
+ .argument(JavaNaming.packageOf(service, JavaNaming.PROVIDER) + "." + name
+ + "Skeleton", "skeleton", "The skeleton to be used.")
+ .write(out);
+
+ return clazz.close();
+ }
+
+ /**
+ * One operation, taking what the consumer sent and, where the interaction reports back
+ * over time, the object the provider reports through.
+ */
+ private static void writeOperation(JavaSource out, MOModel model, Service service,
+ Operation operation) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(operation.getName()).asDeclaration()
+ .comment("Implements the operation " + operation.getName());
+
+ List<Field> sent = fieldsOf(operation.getMessage(requestStageOf(operation)));
+ for (int i = 0; i < sent.size(); i++) {
+ Field field = sent.get(i);
+ String comment = field.getComment() != null ? field.getComment()
+ : field.getName() + " Argument number " + i
+ + " as defined by the service operation";
+ method.argument(JavaTypeName.of(model, field.getType()), field.getName(), comment);
+ }
+
+ if (operation.getPattern() == esa.mo.apigen.model.InteractionPattern.REQUEST) {
+ List<Field> answered = fieldsOf(operation.getMessage(InteractionStage.RESPONSE));
+ String returnType = returnTypeOf(model, service, operation, answered);
+ if (returnType != null) {
+ method.returns(returnType, "The return value of the operation");
+ }
+ }
+
+ method.argument(interactionTypeOf(service, operation), "interaction", INTERACTION_COMMENT);
+ addErrors(method, model, operation);
+ method.throwing(INTERACTION_EXCEPTION,
+ "if there is a problem during the interaction as defined by the MAL specification.")
+ .throwing(MAL_EXCEPTION, "if there is an implementation exception")
+ .write(out);
+ }
+
+ /**
+ * The errors of the operation, each with the description that says when it is raised.
+ * A reference rarely carries its own, so the definition it names answers for it.
+ */
+ private static void addErrors(JavaMethodBuilder method, MOModel model, Operation operation) {
+ for (ErrorReference reference : operation.getErrors()) {
+ String comment = reference.getComment();
+ if (comment == null || comment.isEmpty()) {
+ ErrorDefinition definition = model.resolveError(reference.getError());
+ comment = definition != null && definition.getComment() != null
+ && !definition.getComment().isEmpty()
+ ? definition.getComment() : "if the corresponding MO error occurs";
+ }
+ method.throwing(JavaNaming.ROOT + reference.getError().getArea().toLowerCase() + "."
+ + ExceptionWriter.classNameOf(reference.getError().getName()), comment);
+ }
+ }
+
+ /**
+ * @return the type of the interaction object: the plain one where the provider answers
+ * in one go, and the operation's own where it reports back over time.
+ */
+ private static String interactionTypeOf(Service service, Operation operation) {
+ switch (operation.getPattern()) {
+ case INVOKE:
+ case PROGRESS:
+ return JavaNaming.packageOf(service, JavaNaming.PROVIDER) + "."
+ + capitalise(operation.getName()) + "Interaction";
+ default:
+ return JavaNaming.MAL + "provider.MALInteraction";
+ }
+ }
+
+ /**
+ * @return the type the provider answers with, or null when it answers with nothing.
+ */
+ private static String returnTypeOf(MOModel model, Service service, Operation operation,
+ List<Field> fields) {
+ if (fields.isEmpty()) {
+ return null;
+ }
+ if (fields.size() == 1) {
+ return JavaTypeName.of(model, fields.get(0).getType());
+ }
+ return JavaNaming.packageOf(service, "body") + "."
+ + capitalise(operation.getName()) + "Response";
+ }
+
+ /**
+ * @return the stage that carries what the consumer sent to start the interaction.
+ */
+ private static InteractionStage requestStageOf(Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ return InteractionStage.SEND;
+ case SUBMIT:
+ return InteractionStage.SUBMIT;
+ case REQUEST:
+ return InteractionStage.REQUEST;
+ case INVOKE:
+ return InteractionStage.INVOKE;
+ case PROGRESS:
+ return InteractionStage.PROGRESS;
+ default:
+ return null;
+ }
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ private static String capitalise(String text) {
+ return Character.toUpperCase(text.charAt(0)) + text.substring(1);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderInheritanceSkeletonWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderInheritanceSkeletonWriter.java
new file mode 100644
index 00000000..63f56eed
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderInheritanceSkeletonWriter.java
@@ -0,0 +1,373 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.generators.java.JavaTypes;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the inheritance skeleton of a service: the class a provider extends, which turns
+ * an incoming message into a call on the handler method that answers for it.
+ * <p>
+ * One dispatch method per interaction pattern, each switching on the operation number. An
+ * operation that declares errors of its own is wrapped in a try, so that a provider can
+ * raise them directly and have them arrive at the consumer as an interaction exception.
+ */
+public final class ProviderInheritanceSkeletonWriter {
+
+ private static final String MAL_EXCEPTION = JavaNaming.MAL + "MALException";
+
+ private static final String INTERACTION_EXCEPTION = JavaNaming.MAL + "MALInteractionException";
+
+ private static final String BODY = JavaNaming.MAL + "transport.MALMessageBody";
+
+ private static final String HANDLE_COMMENT =
+ "Called by the provider MAL layer on reception of a message to handle the interaction";
+
+ /**
+ * The message of the error raised for an operation number the service does not have.
+ */
+ private static final String UNSUPPORTED = JavaNaming.MAL
+ + "provider.MALInteractionHandler.ERROR_MSG_UNSUPPORTED + opNumber";
+
+ /**
+ * The step the arguments of a dispatched call take past the line they start on.
+ */
+ private static final String ARGUMENT = ",\n ";
+
+ private ProviderInheritanceSkeletonWriter() {
+ }
+
+ /**
+ * @return the source of the service's inheritance skeleton.
+ */
+ public static String write(MOModel model, Service service) {
+ String name = service.getName();
+ String className = name + "InheritanceSkeleton";
+ String provider = JavaNaming.packageOf(service, JavaNaming.PROVIDER);
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(className).asAbstract()
+ .inPackage(provider)
+ .implementing(JavaNaming.MAL + "provider.MALInteractionHandler")
+ .implementing(provider + "." + name + "Skeleton")
+ .implementing(provider + "." + name + "Handler")
+ .comment("Provider Inheritance skeleton for " + className + " service.");
+ JavaSource out = clazz.open();
+
+ JavaFieldBuilder.named("providerSet").scope("private")
+ .ofType(JavaNaming.MAL + "provider.MALProviderSet")
+ .value("new " + JavaNaming.MAL + "provider.MALProviderSet("
+ + JavaNaming.packageOf(service) + "." + name + "Helper."
+ + name.toUpperCase() + "_SERVICE)")
+ .comment("The providerSet field.").write(out);
+
+ JavaMethodBuilder.named("getConnection")
+ .returns(JavaNaming.MAL + "helpertools.connections.ConnectionProvider",
+ "the connection object for this provider")
+ .comment("Returns the connection object for this provider.")
+ .throwing("java.io.IOException", "if the method was not implemented yet.")
+ .line("throw new java.io.IOException(\"This method needs to be overridden!\");")
+ .write(out);
+
+ JavaMethodBuilder.named("setSkeleton").asOverride()
+ .argument(provider + "." + name + "Skeleton", "skeleton", "The skeleton (not used)")
+ .line("// Not used in the inheritance pattern (the skeleton is 'this');")
+ .write(out);
+
+ JavaMethodBuilder.named("malInitialize").asOverride()
+ .argument(JavaNaming.MAL + "provider.MALProvider", "provider", "The provider to be added.")
+ .throwing(MAL_EXCEPTION, "If an error is detected.")
+ .line("providerSet.addProvider(provider);")
+ .write(out);
+
+ JavaMethodBuilder.named("malFinalize").asOverride()
+ .argument(JavaNaming.MAL + "provider.MALProvider", "provider", "The provider to be added.")
+ .throwing(MAL_EXCEPTION, "If an error is detected.")
+ .line("providerSet.removeProvider(provider);")
+ .write(out);
+
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() == InteractionPattern.PUBSUB) {
+ writeCreatePublisher(out, service, operation);
+ }
+ }
+
+ handle(out, model, service, InteractionPattern.SEND, "handleSend",
+ JavaNaming.MAL + "provider.MALInteraction", "The interaction object", false);
+ handle(out, model, service, InteractionPattern.SUBMIT, "handleSubmit",
+ JavaNaming.MAL + "provider.MALSubmit", "The interaction object", true);
+ handle(out, model, service, InteractionPattern.REQUEST, "handleRequest",
+ JavaNaming.MAL + "provider.MALRequest", "The interaction object", true);
+ handle(out, model, service, InteractionPattern.INVOKE, "handleInvoke",
+ JavaNaming.MAL + "provider.MALInvoke", "The interaction object", true);
+ handle(out, model, service, InteractionPattern.PROGRESS, "handleProgress",
+ JavaNaming.MAL + "provider.MALProgress", "The interaction object", true);
+
+ return clazz.close();
+ }
+
+ /**
+ * How a provider reaches the publisher of one of its publish-subscribe operations.
+ */
+ private static void writeCreatePublisher(JavaSource out, Service service, Operation operation) {
+ String publisher = JavaNaming.packageOf(service, JavaNaming.PROVIDER) + "."
+ + ProviderPublisherWriter.classNameOf(operation);
+ JavaMethodBuilder.named("create" + capitalise(operation.getName()) + "Publisher")
+ .asOverride().returns(publisher, "The new publisher object.")
+ .comment("Creates a publisher object using the current registered provider set"
+ + " for the PubSub operation " + operation.getName())
+ .argument(JavaNaming.MAL_STRUCTURES + "IdentifierList", "domain",
+ "The domain used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "Identifier", "networkZone",
+ "The network zone used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "SessionType", "sessionType",
+ "The session used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "Identifier", "sessionName",
+ "The session name used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "QoSLevel", "qos",
+ "The QoS used for publishing")
+ .argument("java.util.Map", "qosProps", "The QoS properties used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "UInteger", "priority",
+ "The priority used for publishing")
+ .throwing(MAL_EXCEPTION, "if a problem is detected during creation of the publisher")
+ .line("return new " + publisher + "(providerSet.createPublisherSet("
+ + JavaNaming.packageOf(service) + "." + service.getName() + "ServiceInfo."
+ + operation.getName().toUpperCase()
+ + "_OP, domain, sessionType, sessionName, qos, qosProps, null));")
+ .write(out);
+ }
+
+ /**
+ * One dispatch method: it reads the operation number off the interaction and calls the
+ * handler method of that operation, unpacking the body as it goes.
+ *
+ * @param answers True where the interaction can be told about an operation it does not
+ * have. A send has nobody to tell.
+ */
+ private static void handle(JavaSource out, MOModel model, Service service,
+ InteractionPattern pattern, String name, String interactionType,
+ String interactionComment, boolean answers) {
+ JavaMethodBuilder method = JavaMethodBuilder.named(name).asOverride()
+ .comment(HANDLE_COMMENT)
+ .argument(interactionType, "interaction", interactionComment)
+ .argument(BODY, "body", "The message body")
+ .throwing(MAL_EXCEPTION, "if there is a internal error")
+ .throwing(INTERACTION_EXCEPTION, "if there is a operation interaction error");
+
+ // An operation that declares errors of its own is wrapped, so that the provider can
+ // raise them directly rather than wrapping each one itself.
+ boolean wrapErrors = declaresErrors(service, pattern);
+
+ method.line("int opNumber = interaction.getOperation().getNumber().getValue();");
+ if (wrapErrors) {
+ method.line("try {");
+ }
+ method.line("switch (opNumber) {");
+
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() != pattern) {
+ continue;
+ }
+ method.line(" case " + JavaNaming.packageOf(service) + "." + service.getName()
+ + "ServiceInfo._" + operation.getName().toUpperCase() + "_OP_NUMBER:");
+ writeCase(method, model, service, operation);
+ method.line(" break;");
+ }
+
+ method.line(" default:");
+ if (answers) {
+ method.line(" interaction.sendError(new " + JavaNaming.MAL
+ + "UnsupportedOperationException(\n " + UNSUPPORTED + "));");
+ }
+ method.line(" throw new " + INTERACTION_EXCEPTION + "(new " + JavaNaming.MAL
+ + "UnsupportedOperationException(\n " + UNSUPPORTED + "));");
+ method.line("}");
+ if (wrapErrors) {
+ method.line("} catch (" + JavaNaming.MAL + "MOErrorException error) {");
+ method.line(" throw new " + INTERACTION_EXCEPTION + "(error);");
+ method.line("}");
+ }
+ method.write(out);
+ }
+
+ /**
+ * The body of one case: the call on the handler, and whatever has to happen around it
+ * for the interaction to be answered.
+ */
+ private static void writeCase(JavaMethodBuilder method, MOModel model, Service service,
+ Operation operation) {
+ String arguments = unpacked(model, fieldsOf(operation.getMessage(requestStageOf(operation))));
+
+ switch (operation.getPattern()) {
+ case SEND:
+ method.line(" " + operation.getName() + "(" + arguments + "interaction);");
+ break;
+ case SUBMIT:
+ method.line(" " + operation.getName() + "(" + arguments + "interaction);");
+ method.line(" interaction.sendAcknowledgement();");
+ break;
+ case REQUEST:
+ writeRequestCase(method, model, service, operation, arguments);
+ break;
+ case INVOKE:
+ case PROGRESS:
+ method.line(" " + operation.getName() + "(" + arguments + "new "
+ + ProviderInteractionWriter.classNameOf(operation) + "(interaction));");
+ break;
+ default:
+ break;
+ }
+ }
+
+ /**
+ * A request is answered on the spot, so what the handler returns is taken apart and
+ * handed straight back.
+ */
+ private static void writeRequestCase(JavaMethodBuilder method, MOModel model, Service service,
+ Operation operation, String arguments) {
+ List<Field> answered = fieldsOf(operation.getMessage(InteractionStage.RESPONSE));
+ String call = operation.getName() + "(" + arguments + "interaction)";
+
+ if (answered.isEmpty()) {
+ method.line(" " + call + ";");
+ method.line(" interaction.sendResponse();");
+ return;
+ }
+
+ if (answered.size() == 1) {
+ Field field = answered.get(0);
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ // A native attribute has to be wrapped before it can be sent, so it is named
+ // first rather than wrapped inside the call.
+ String variable = operation.getName() + "Rt";
+ method.line(" " + JavaTypeName.of(model, field.getType()) + " " + variable
+ + " = " + call + ";");
+ method.line(" interaction.sendResponse((" + variable + " == null) ? null : new "
+ + JavaNaming.MAL_STRUCTURES + "Union(" + variable + "));");
+ } else {
+ method.line(" interaction.sendResponse(" + call + ");");
+ }
+ return;
+ }
+
+ String variable = operation.getName() + "Rt";
+ String returnType = JavaNaming.packageOf(service, "body") + "."
+ + capitalise(operation.getName()) + "Response";
+ method.line(" " + returnType + " " + variable + " = " + call + ";");
+ StringBuilder buf = new StringBuilder("\n ");
+ for (int i = 0; i < answered.size(); i++) {
+ Field field = answered.get(i);
+ String getter = variable + ".get" + capitalise(field.getName()) + "()";
+ if (i > 0) {
+ buf.append(",\n ");
+ }
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ buf.append("(").append(getter).append(" == null) ? null : new ")
+ .append(JavaNaming.MAL_STRUCTURES).append("Union(").append(getter).append(")");
+ } else {
+ buf.append(getter);
+ }
+ }
+ method.line(" interaction.sendResponse(" + buf);
+ method.line(" );");
+ }
+
+ /**
+ * @return the fields taken out of the body, each on its own line, and each followed by
+ * the comma that separates it from the interaction that comes last.
+ */
+ private static String unpacked(MOModel model, List<Field> fields) {
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ if (i != 0) {
+ buf.append(ARGUMENT);
+ }
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ String union = JavaNaming.MAL_STRUCTURES + "Union";
+ String element = "body.getBodyElement(" + i + ", new " + union + "("
+ + JavaTypes.nativeDefault(field.getType().getName()) + "))";
+ buf.append("(").append(element).append(" == null) ? null : ((").append(union)
+ .append(") ").append(element).append(").get")
+ .append(field.getType().getName()).append("Value()");
+ } else {
+ buf.append("(").append(JavaTypeName.of(model, field.getType()))
+ .append(") body.getBodyElement(").append(i).append(", ")
+ .append(JavaTypeName.expectedTypeOf(model, field.getType())).append(")");
+ }
+ }
+ return fields.isEmpty() ? "" : buf.append(ARGUMENT).toString();
+ }
+
+ /**
+ * @return true if any operation of this pattern declares an error of its own.
+ */
+ private static boolean declaresErrors(Service service, InteractionPattern pattern) {
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() == pattern && !operation.getErrors().isEmpty()) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * @return the stage that carries what the consumer sent to start the interaction.
+ */
+ private static InteractionStage requestStageOf(Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ return InteractionStage.SEND;
+ case SUBMIT:
+ return InteractionStage.SUBMIT;
+ case REQUEST:
+ return InteractionStage.REQUEST;
+ case INVOKE:
+ return InteractionStage.INVOKE;
+ case PROGRESS:
+ return InteractionStage.PROGRESS;
+ default:
+ return null;
+ }
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+
+ private static String capitalise(String text) {
+ return Character.toUpperCase(text.charAt(0)) + text.substring(1);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderInteractionWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderInteractionWriter.java
new file mode 100644
index 00000000..a2c3b6b3
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderInteractionWriter.java
@@ -0,0 +1,192 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the interaction class of an operation that reports back over time.
+ * <p>
+ * A provider handling an invoke or a progress is handed one of these instead of the plain
+ * MAL interaction, so that the messages it can send back are named and typed: it sends an
+ * acknowledgement, then updates, then a response, and the fields of each are the ones the
+ * operation declared.
+ */
+public final class ProviderInteractionWriter {
+
+ private static final String MESSAGE = JavaNaming.MAL + "transport.MALMessage";
+
+ private static final String INTERACTION_EXCEPTION = JavaNaming.MAL + "MALInteractionException";
+
+ private static final String MAL_EXCEPTION = JavaNaming.MAL + "MALException";
+
+ private static final String INTERACTION_THROWN =
+ "if there is a problem during the interaction as defined by the MAL specification.";
+
+ private static final String EXCEPTION_THROWN = "if there is an implementation exception";
+
+ private ProviderInteractionWriter() {
+ }
+
+ /**
+ * @return the name of the class, which is the operation's with the kind appended.
+ */
+ public static String classNameOf(Operation operation) {
+ String name = operation.getName();
+ return Character.toUpperCase(name.charAt(0)) + name.substring(1) + "Interaction";
+ }
+
+ /**
+ * @return the source of the operation's interaction class.
+ */
+ public static String write(MOModel model, Service service, Operation operation) {
+ boolean isProgress = operation.getPattern() == InteractionPattern.PROGRESS;
+ String pattern = isProgress ? "PROGRESS" : "INVOKE";
+ String malType = JavaNaming.MAL + "provider." + (isProgress ? "MALProgress" : "MALInvoke");
+ String className = classNameOf(operation);
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(className)
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.PROVIDER))
+ .comment("Provider " + pattern + " interaction class for " + service.getName()
+ + "::" + operation.getName() + " operation.");
+ JavaSource out = clazz.open();
+
+ JavaFieldBuilder.named("interaction").scope("private").ofType(malType)
+ .comment("The interaction field.").write(out);
+
+ JavaMethodBuilder.constructor(className)
+ .comment("Wraps the provided MAL interaction object with methods for sending"
+ + " responses to an " + pattern + " interaction from a provider.")
+ .argument(malType, "interaction", "The MAL interaction action object to use.")
+ .line("this.interaction = interaction;")
+ .write(out);
+
+ JavaMethodBuilder.named("getInteraction")
+ .returns(malType, "The MAL interaction object provided in the constructor")
+ .comment("Returns the MAL interaction object used for returning messages from"
+ + " the provider.")
+ .line("return interaction;")
+ .write(out);
+
+ send(out, model, operation, "sendAcknowledgement", InteractionStage.ACK,
+ "Sends a " + pattern + " acknowledge to the consumer",
+ "Returns the MAL message created by the acknowledge");
+ if (isProgress) {
+ send(out, model, operation, "sendUpdate", InteractionStage.UPDATE,
+ "Sends a " + pattern + " update to the consumer",
+ "Returns the MAL message created by the update");
+ }
+ send(out, model, operation, "sendResponse", InteractionStage.RESPONSE,
+ "Sends a " + pattern + " response to the consumer",
+ "Returns the MAL message created by the response");
+
+ // The invoke class describes the error it is handed, the progress class repeats the
+ // name in front of it. The difference is in the existing generator and is kept.
+ String errorComment = isProgress ? "error The MAL error to send to the consumer."
+ : "The MAL error to send to the consumer.";
+ sendError(out, "sendError", "Sends an error to the consumer", errorComment);
+ if (isProgress) {
+ sendError(out, "sendUpdateError", "Sends an update error to the consumer",
+ errorComment);
+ }
+
+ return clazz.close();
+ }
+
+ /**
+ * One of the messages a provider can send back, carrying the fields of that stage.
+ */
+ private static void send(JavaSource out, MOModel model, Operation operation, String name,
+ InteractionStage stage, String comment, String returnComment) {
+ List<Field> fields = fieldsOf(operation.getMessage(stage));
+ JavaMethodBuilder method = JavaMethodBuilder.named(name)
+ .returns(MESSAGE, returnComment).comment(comment);
+
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ String fieldComment = field.getComment() != null ? field.getComment()
+ : field.getName() + " Argument number " + i
+ + " as defined by the service operation";
+ method.argument(JavaTypeName.of(model, field.getType()), field.getName(), fieldComment);
+ }
+
+ method.throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line("return interaction." + name + "(" + arguments(model, fields) + ");")
+ .write(out);
+ }
+
+ /**
+ * The error a provider sends when it cannot go on.
+ */
+ private static void sendError(JavaSource out, String name, String comment,
+ String errorComment) {
+ JavaMethodBuilder.named(name)
+ .returns(MESSAGE, "Returns the MAL message created by the error")
+ .comment(comment)
+ .argument(JavaNaming.MAL + "MOErrorException", "error", errorComment)
+ .throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line("return interaction." + name + "(error);")
+ .write(out);
+ }
+
+ /**
+ * @return the arguments handed to the MAL, with a native attribute wrapped in the Union
+ * that carries it, or a cast null where there are none.
+ */
+ private static String arguments(MOModel model, List<Field> fields) {
+ if (fields.isEmpty()) {
+ return "(Object[]) null";
+ }
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ buf.append(i == 0 ? "" : ", ");
+ if (JavaTypeName.isNativeAttribute(model, field.getType())) {
+ buf.append("(").append(field.getName()).append(" == null) ? null : new ")
+ .append(JavaNaming.MAL_STRUCTURES).append("Union(")
+ .append(field.getName()).append(")");
+ } else {
+ buf.append(field.getName());
+ }
+ }
+ return buf.toString();
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderPublisherWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderPublisherWriter.java
new file mode 100644
index 00000000..d4f7779e
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderPublisherWriter.java
@@ -0,0 +1,216 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the publisher of a publish-subscribe operation: how a provider registers with the
+ * brokers it publishes through, and what one update looks like.
+ */
+public final class ProviderPublisherWriter {
+
+ private static final String PUBLISHER_SET = JavaNaming.MAL + "provider.MALPublisherSet";
+
+ private static final String LISTENER = JavaNaming.MAL + "provider.MALPublishInteractionListener";
+
+ private static final String INTERACTION_EXCEPTION = JavaNaming.MAL + "MALInteractionException";
+
+ private static final String MAL_EXCEPTION = JavaNaming.MAL + "MALException";
+
+ private static final String INTERACTION_THROWN =
+ "if there is a problem during the interaction as defined by the MAL specification.";
+
+ private static final String EXCEPTION_THROWN = "if there is an implementation exception";
+
+ private static final String ARGUMENT_THROWN = "If any supplied argument is invalid";
+
+ private static final String LISTENER_COMMENT =
+ "The listener object to use for callback from the publisher";
+
+ private ProviderPublisherWriter() {
+ }
+
+ /**
+ * @return the name of the class, which is the operation's with the kind appended.
+ */
+ public static String classNameOf(Operation operation) {
+ String name = operation.getName();
+ return Character.toUpperCase(name.charAt(0)) + name.substring(1) + "Publisher";
+ }
+
+ /**
+ * @return the source of the operation's publisher.
+ */
+ public static String write(MOModel model, Service service, Operation operation) {
+ String className = classNameOf(operation);
+ JavaClassBuilder clazz = JavaClassBuilder.named(className).asFinal()
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.PROVIDER))
+ .comment("Publisher class for the " + operation.getName() + " operation.");
+ JavaSource out = clazz.open();
+
+ JavaFieldBuilder.named("publisherSet").scope("private").ofType(PUBLISHER_SET)
+ .comment("The publisherSet field.").write(out);
+
+ JavaMethodBuilder.constructor(className)
+ .comment("Creates an instance of this class using the supplied publisher set.")
+ .argument(PUBLISHER_SET, "publisherSet",
+ "The set of broker connections to use when registering and publishing.")
+ .line("this.publisherSet = publisherSet;")
+ .write(out);
+
+ register(out, "register", "Registers this provider implementation to the set of broker"
+ + " connections", "publisherSet.register(keyNames, keyTypes, listener);");
+
+ writeRegisterWithDefaultKeys(out, model, operation);
+
+ register(out, "asyncRegister", "Asynchronously registers this provider implementation to"
+ + " the set of broker connections",
+ "publisherSet.asyncRegister(keyNames, keyTypes, listener);");
+
+ writePublish(out, model, operation);
+
+ JavaMethodBuilder.named("deregister")
+ .comment("Deregisters this provider implementation from the set of broker"
+ + " connections")
+ .throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line("publisherSet.deregister();")
+ .write(out);
+
+ JavaMethodBuilder.named("asyncDeregister")
+ .comment("Asynchronously deregisters this provider implementation from the set"
+ + " of broker connections")
+ .argument(LISTENER, "listener", LISTENER_COMMENT)
+ .throwing("java.lang.IllegalArgumentException", ARGUMENT_THROWN)
+ .throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line("publisherSet.asyncDeregister(listener);")
+ .write(out);
+
+ JavaMethodBuilder.named("close").comment("Closes this publisher")
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line("publisherSet.close();")
+ .write(out);
+
+ return clazz.close();
+ }
+
+ /**
+ * Registering says which keys the updates of this provider will be identified by.
+ */
+ private static void register(JavaSource out, String name, String comment, String body) {
+ JavaMethodBuilder.named(name).comment(comment)
+ .argument(JavaNaming.MAL_STRUCTURES + "IdentifierList", "keyNames",
+ "The key names to use in the method")
+ .argument(JavaNaming.MAL_STRUCTURES + "AttributeTypeList", "keyTypes",
+ "The key types to use in the method")
+ .argument(LISTENER, "listener", LISTENER_COMMENT)
+ .throwing("java.lang.IllegalArgumentException", ARGUMENT_THROWN)
+ .throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line(body)
+ .write(out);
+ }
+
+ /**
+ * Registering with the keys the operation itself declared, which is what a provider that
+ * has nothing of its own to add does.
+ */
+ private static void writeRegisterWithDefaultKeys(JavaSource out, MOModel model,
+ Operation operation) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("registerWithDefaultKeys")
+ .comment("Registers this provider implementation to the set of broker"
+ + " connections with the default subscription keys")
+ .argument(LISTENER, "listener", LISTENER_COMMENT)
+ .throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN);
+
+ method.line(JavaNaming.MAL_STRUCTURES + "IdentifierList keyNames = new "
+ + JavaNaming.MAL_STRUCTURES + "IdentifierList();");
+ method.line(JavaNaming.MAL_STRUCTURES + "AttributeTypeList keyTypes = new "
+ + JavaNaming.MAL_STRUCTURES + "AttributeTypeList();");
+ for (Field key : fieldsOf(operation.getMessage(InteractionStage.SUBSCRIPTION_KEYS))) {
+ method.line("keyNames.add(new " + JavaNaming.MAL_STRUCTURES + "Identifier(\""
+ + key.getName() + "\"));");
+ method.line("keyTypes.add(" + JavaNaming.MAL_STRUCTURES + "AttributeType."
+ + attributeTypeOf(model, key) + ");");
+ }
+ method.line("publisherSet.register(keyNames, keyTypes, listener);");
+ method.write(out);
+ }
+
+ /**
+ * One update: the header that identifies it, then the fields the operation publishes.
+ */
+ private static void writePublish(JavaSource out, MOModel model, Operation operation) {
+ List<Field> published = fieldsOf(operation.getMessage(InteractionStage.PUBLISH_NOTIFY));
+ JavaMethodBuilder method = JavaMethodBuilder.named("publish")
+ .comment("Publishes updates to the set of registered broker connections")
+ .argument(JavaNaming.MAL_STRUCTURES + "UpdateHeader", "updateHeader",
+ "The headers of the updates being added");
+
+ StringBuilder arguments = new StringBuilder("updateHeader");
+ for (int i = 0; i < published.size(); i++) {
+ Field field = published.get(i);
+ String comment = field.getComment() != null ? field.getComment()
+ : field.getName() + " Argument number " + i
+ + " as defined by the service operation";
+ method.argument(JavaTypeName.of(model, field.getType()), field.getName(), comment);
+ arguments.append(", ").append(field.getName());
+ }
+
+ method.throwing("java.lang.IllegalArgumentException", ARGUMENT_THROWN)
+ .throwing(INTERACTION_EXCEPTION, INTERACTION_THROWN)
+ .throwing(MAL_EXCEPTION, EXCEPTION_THROWN)
+ .line("publisherSet.publish(" + arguments + ");")
+ .write(out);
+ }
+
+ /**
+ * @return the attribute type a key is carried as. An enumeration travels as the number
+ * that stands for it, so it is keyed as a UShort.
+ */
+ private static String attributeTypeOf(MOModel model, Field key) {
+ TypeDefinition definition = model.resolve(key.getType());
+ return definition instanceof EnumerationType
+ ? "USHORT" : key.getType().getName().toUpperCase();
+ }
+
+ private static List<Field> fieldsOf(MessageBody body) {
+ return body == null ? new ArrayList<Field>() : body.getFields();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderSkeletonWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderSkeletonWriter.java
new file mode 100644
index 00000000..017b5854
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ProviderSkeletonWriter.java
@@ -0,0 +1,87 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+
+/**
+ * Writes the skeleton interface of a service: how a provider reaches the publishers of its
+ * publish-subscribe operations, and nothing else. A service that publishes nothing has an
+ * empty one.
+ */
+public final class ProviderSkeletonWriter {
+
+ private ProviderSkeletonWriter() {
+ }
+
+ /**
+ * @return the source of the service's skeleton interface.
+ */
+ public static String write(Service service) {
+ String name = service.getName();
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "Skeleton").asInterface()
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.PROVIDER))
+ .comment("The skeleton interface for the " + name + " service.");
+ JavaSource out = clazz.open();
+
+ for (Operation operation : service.getOperations()) {
+ if (operation.getPattern() != InteractionPattern.PUBSUB) {
+ continue;
+ }
+ String publisher = JavaNaming.packageOf(service, JavaNaming.PROVIDER) + "."
+ + capitalise(operation.getName()) + "Publisher";
+ JavaMethodBuilder.named("create" + capitalise(operation.getName()) + "Publisher")
+ .asDeclaration()
+ .comment("Creates a publisher object using the current registered provider"
+ + " set for the PubSub operation " + operation.getName())
+ .returns(publisher, "The new publisher object.")
+ .argument(JavaNaming.MAL_STRUCTURES + "IdentifierList", "domain",
+ "The domain used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "Identifier", "networkZone",
+ "~The network zone used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "SessionType", "sessionType",
+ "The session used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "Identifier", "sessionName",
+ "The session name used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "QoSLevel", "qos",
+ "The QoS used for publishing")
+ .argument("java.util.Map", "qosProps",
+ "The QoS properties used for publishing")
+ .argument(JavaNaming.MAL_STRUCTURES + "UInteger", "priority",
+ "The priority used for publishing")
+ .throwing(JavaNaming.MAL + "MALException",
+ "if a problem is detected during creation of the publisher")
+ .write(out);
+ }
+
+ return clazz.close();
+ }
+
+ private static String capitalise(String text) {
+ return Character.toUpperCase(text.charAt(0)) + text.substring(1);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ServiceInfoWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ServiceInfoWriter.java
new file mode 100644
index 00000000..b16bafe7
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/ServiceInfoWriter.java
@@ -0,0 +1,432 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.ErrorDefinition;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.com.COMObject;
+import esa.mo.apigen.model.com.ObjectLink;
+import esa.mo.apigen.model.com.ObjectReference;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the ServiceInfo class of a service: what the service is called and numbered, one
+ * constant per operation describing the messages it exchanges, and the errors it can raise.
+ * <p>
+ * This is what the consumer stubs and provider skeletons name their operations through, so
+ * it is written before either of them.
+ */
+public final class ServiceInfoWriter {
+
+ private static final String OPERATION_FIELD = JavaNaming.MAL + "OperationField";
+
+ /**
+ * The step the arguments of an operation take, and the step the fields of a message
+ * take past them.
+ */
+ private static final String ARGUMENT = "\n ";
+
+ private static final String FIELD = "\n ";
+
+ private ServiceInfoWriter() {
+ }
+
+ /**
+ * @return the source of the service's ServiceInfo class.
+ */
+ public static String write(MOModel model, Area area, Service service) {
+ String name = service.getName();
+ String upper = name.toUpperCase();
+ boolean isCom = service.isExtended();
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(name + "ServiceInfo")
+ .inPackage(JavaNaming.packageOf(service))
+ .extending(isCom ? JavaNaming.ROOT + "com.COMService" : JavaNaming.MAL + "ServiceInfo")
+ .comment("Helper class for " + name + " service.");
+ JavaSource out = clazz.open();
+
+ constant("_" + upper + "_SERVICE_NUMBER", "int", String.valueOf(service.getNumber()))
+ .comment("Service number literal.").write(out);
+ constant(upper + "_SERVICE_NUMBER", JavaNaming.MAL_STRUCTURES + "UShort",
+ "new " + JavaNaming.MAL_STRUCTURES + "UShort(_" + upper + "_SERVICE_NUMBER)")
+ .comment("Service number instance.").write(out);
+ constant(upper + "_SERVICE_NAME", JavaNaming.MAL_STRUCTURES + "Identifier",
+ "new " + JavaNaming.MAL_STRUCTURES + "Identifier(\"" + name + "\")")
+ .comment("Service name constant.").write(out);
+
+ // The key is what a message is addressed by, so it is built from the numbers rather
+ // than from the names.
+ constant("SERVICE_KEY", JavaNaming.MAL + "ServiceKey",
+ "new " + JavaNaming.MAL + "ServiceKey(" + ARGUMENT + area.getNumber() + ", "
+ + area.getVersion() + ", " + upper + "_SERVICE_NUMBER)")
+ .scope("private").comment("The service key of this service.").write(out);
+
+ List<Operation> operations = service.getOperations();
+ for (Operation operation : operations) {
+ writeOperation(out, model, operation);
+ }
+
+ // Left empty on purpose: the Area factory creates the elements on demand, so that
+ // the class of a type is only loaded once a message carries it.
+ constant(upper + "_SERVICE_ELEMENTS", JavaNaming.MAL_STRUCTURES + "Element[]", "{}")
+ .comment("Area elements.").write(out);
+
+ constant("OPERATIONS", JavaNaming.MAL + "MALOperation[]",
+ "new " + JavaNaming.MAL + "MALOperation[]{" + operationList(operations) + "}")
+ .comment("The set of operations for this service.").write(out);
+
+ List<String> comObjects = writeComObjects(out, model, area, service);
+ boolean hasComObjects = !comObjects.isEmpty();
+
+ if (hasComObjects) {
+ StringBuilder buf = new StringBuilder("{");
+ for (String object : comObjects) {
+ buf.append("\n ").append(object).append("_OBJECT,");
+ }
+ constant("COM_OBJECTS", JavaNaming.ROOT + "com.COMObject[]", buf.append('}').toString())
+ .comment("Object instance.").write(out);
+ }
+
+ JavaMethodBuilder.constructor(name + "ServiceInfo")
+ .comment("Creates an instance of the " + name + " ServiceInfo.")
+ .line("super(SERVICE_KEY, " + upper + "_SERVICE_NAME, " + upper
+ + "_SERVICE_ELEMENTS, OPERATIONS" + (hasComObjects ? ", COM_OBJECTS" : "")
+ + ");")
+ .write(out);
+
+ JavaMethodBuilder.named("getArea").asOverride().returns(JavaNaming.MAL + "MALArea", null)
+ .line("return " + JavaNaming.packageOf(area) + "." + area.getName() + "Helper."
+ + area.getName().toUpperCase() + "_AREA;")
+ .write(out);
+
+ writeGenerateMOError(out, area);
+ return clazz.close();
+ }
+
+ /**
+ * Writes the three constants that describe one operation: its number as a literal, its
+ * number as a UShort, and the operation itself with every message it exchanges.
+ */
+ private static void writeOperation(JavaSource out, MOModel model, Operation operation) {
+ String upper = operation.getName().toUpperCase();
+
+ constant("_" + upper + "_OP_NUMBER", "int", String.valueOf(operation.getNumber()))
+ .comment("Operation number literal for operation " + upper).write(out);
+ constant(upper + "_OP_NUMBER", JavaNaming.MAL_STRUCTURES + "UShort",
+ "new " + JavaNaming.MAL_STRUCTURES + "UShort(_" + upper + "_OP_NUMBER)")
+ .scope("private").comment("Operation number instance for operation " + upper)
+ .write(out);
+
+ constant(upper + "_OP", JavaNaming.MAL + operationTypeOf(operation),
+ operationValue(model, operation))
+ .comment("Operation instance for operation " + upper).write(out);
+
+ if (operation.getPattern() == esa.mo.apigen.model.InteractionPattern.PUBSUB) {
+ writeSubscriptionKeys(out, operation, upper);
+ }
+ }
+
+ /**
+ * The names a subscription is keyed by, as an array and as the list built from it.
+ */
+ private static void writeSubscriptionKeys(JavaSource out, Operation operation, String upper) {
+ String comment = "Key names instance for " + upper
+ + " operation of pubsub interaction pattern";
+ MessageBody keys = operation.getMessage(InteractionStage.SUBSCRIPTION_KEYS);
+ StringBuilder buf = new StringBuilder("{");
+ String separator = "";
+
+ if (keys != null) {
+ for (Field field : keys.getFields()) {
+ buf.append(separator).append("new ").append(JavaNaming.MAL_STRUCTURES)
+ .append("Identifier(\"").append(field.getName()).append("\")");
+ separator = ",\n ";
+ }
+ }
+
+ constant("_" + upper + "_OP_KEY_NAMES", JavaNaming.MAL_STRUCTURES + "Identifier []",
+ buf.append('}').toString()).scope("private").comment(comment).write(out);
+ constant(upper + "_OP_KEY_NAMES", JavaNaming.MAL_STRUCTURES + "IdentifierList",
+ "new " + JavaNaming.MAL_STRUCTURES + "IdentifierList(new java.util.ArrayList<>("
+ + "java.util.Arrays.asList(_" + upper + "_OP_KEY_NAMES)))")
+ .scope("private").comment(comment).write(out);
+ }
+
+ /**
+ * @return the expression that creates the operation, message by message.
+ */
+ private static String operationValue(MOModel model, Operation operation) {
+ String upper = operation.getName().toUpperCase();
+ StringBuilder buf = new StringBuilder("new ");
+ buf.append(JavaNaming.MAL).append(operationTypeOf(operation)).append("(SERVICE_KEY, ");
+ buf.append(ARGUMENT).append(upper).append("_OP_NUMBER, ");
+ buf.append(ARGUMENT).append("new ").append(JavaNaming.MAL_STRUCTURES)
+ .append("Identifier(\"").append(operation.getName()).append("\"), ");
+ buf.append(ARGUMENT).append("new ").append(JavaNaming.MAL_STRUCTURES)
+ .append("UShort(").append(operation.getParent().getNumber()).append("), ");
+
+ for (InteractionStage stage : bodyStagesOf(operation)) {
+ buf.append(ARGUMENT).append(messageBody(model, operation.getMessage(stage))).append(", ");
+ }
+
+ buf.append(ARGUMENT).append(literal(operation.getComment())).append(')');
+ return buf.toString();
+ }
+
+ /**
+ * The stages an operation declares a body for, in the order the operation takes them as
+ * arguments. A publish-subscribe operation is described by what it publishes alone.
+ */
+ private static List<InteractionStage> bodyStagesOf(Operation operation) {
+ List<InteractionStage> stages = new ArrayList<InteractionStage>();
+ switch (operation.getPattern()) {
+ case SEND:
+ stages.add(InteractionStage.SEND);
+ break;
+ case SUBMIT:
+ stages.add(InteractionStage.SUBMIT);
+ break;
+ case REQUEST:
+ stages.add(InteractionStage.REQUEST);
+ stages.add(InteractionStage.RESPONSE);
+ break;
+ case INVOKE:
+ stages.add(InteractionStage.INVOKE);
+ stages.add(InteractionStage.ACK);
+ stages.add(InteractionStage.RESPONSE);
+ break;
+ case PROGRESS:
+ stages.add(InteractionStage.PROGRESS);
+ stages.add(InteractionStage.ACK);
+ stages.add(InteractionStage.UPDATE);
+ stages.add(InteractionStage.RESPONSE);
+ break;
+ case PUBSUB:
+ stages.add(InteractionStage.PUBLISH_NOTIFY);
+ break;
+ default:
+ break;
+ }
+ return stages;
+ }
+
+ /**
+ * @return the array of fields one message carries, empty if it carries none.
+ */
+ private static String messageBody(MOModel model, MessageBody body) {
+ StringBuilder buf = new StringBuilder("new " + OPERATION_FIELD + "[] {");
+ if (body != null) {
+ List<Field> fields = body.getFields();
+ for (int i = 0; i < fields.size(); i++) {
+ Field field = fields.get(i);
+ buf.append(FIELD).append("new ").append(OPERATION_FIELD).append("(\"")
+ .append(field.getName()).append("\", ").append(field.isCanBeNull())
+ .append(", ").append(JavaTypeName.shortFormOf(model, field.getType()))
+ .append(", ").append(literal(field.getComment())).append(')');
+ if (i != fields.size() - 1) {
+ buf.append(',');
+ }
+ }
+ }
+ return buf.append('}').toString();
+ }
+
+ /**
+ * Writes the constants describing the COM objects and events of a service.
+ *
+ * @return the names of the objects written, in order.
+ */
+ private static List<String> writeComObjects(JavaSource out, MOModel model, Area area,
+ Service service) {
+ List<String> written = new ArrayList<String>();
+ if (service.getCom() == null) {
+ return written;
+ }
+ for (COMObject object : service.getCom().getObjects()) {
+ written.add(writeComObject(out, model, area, service, object, false));
+ }
+ for (COMObject event : service.getCom().getEvents()) {
+ written.add(writeComObject(out, model, area, service, event, true));
+ }
+ return written;
+ }
+
+ /**
+ * Writes the five constants that describe one COM object. They are deprecated: a COM
+ * object is reached through the service rather than through the ServiceInfo.
+ *
+ * @return the name of the object, in capitals.
+ */
+ private static String writeComObject(JavaSource out, MOModel model, Area area,
+ Service service, COMObject object, boolean isEvent) {
+ String upper = object.getName().toUpperCase();
+ String serviceUpper = service.getName().toUpperCase();
+
+ constant("_" + upper + "_OBJECT_NUMBER", "int", String.valueOf(object.getNumber()))
+ .asDeprecated().comment("Literal for object " + upper).write(out);
+ constant(upper + "_OBJECT_NUMBER", JavaNaming.MAL_STRUCTURES + "UShort",
+ "new " + JavaNaming.MAL_STRUCTURES + "UShort(_" + upper + "_OBJECT_NUMBER)")
+ .asDeprecated().comment("Instance for object " + upper).write(out);
+ constant(upper + "_OBJECT_NAME", JavaNaming.MAL_STRUCTURES + "Identifier",
+ "new " + JavaNaming.MAL_STRUCTURES + "Identifier(\"" + object.getName() + "\")")
+ .asDeprecated().comment("Object name constant.").write(out);
+ constant(upper + "_OBJECT_TYPE", JavaNaming.ROOT + "com.structures.ObjectType",
+ "new " + JavaNaming.ROOT + "com.structures.ObjectType(new "
+ + JavaNaming.MAL_STRUCTURES + "UShort(" + area.getNumber() + "), "
+ + serviceUpper + "_SERVICE_NUMBER, new " + JavaNaming.MAL_STRUCTURES
+ + "UOctet(" + area.getVersion() + "), " + upper + "_OBJECT_NUMBER)")
+ .asDeprecated().comment("Object type constant.").write(out);
+
+ String related = objectTypeOf(model, object.getRelated());
+ String source = objectTypeOf(model, object.getSource());
+ JavaFieldBuilder.named(upper + "_OBJECT").asStatic()
+ .ofType(JavaNaming.ROOT + "com.COMObject")
+ .value("new " + JavaNaming.ROOT + "com.COMObject(" + upper + "_OBJECT_TYPE, "
+ + upper + "_OBJECT_NAME, "
+ + JavaTypeName.shortFormOf(model, object.getBodyType()) + ", "
+ + (object.getRelated() != null) + ", " + related + ", "
+ + (object.getSource() != null) + ", " + source + ", " + isEvent + ")")
+ .asDeprecated().comment("Object instance.").write(out);
+ return upper;
+ }
+
+ /**
+ * Names the object type constant a link points at. A link into an object this model
+ * does not hold is left unresolved rather than named, which is what the reference does.
+ *
+ * @param model The model to look the object up in.
+ * @param link The link, may be null.
+ * @return the constant, or the literal null.
+ */
+ private static String objectTypeOf(MOModel model, ObjectLink link) {
+ if (link == null || link.getTarget() == null) {
+ return "null";
+ }
+ ObjectReference reference = link.getTarget();
+ for (Area area : model.getAreas()) {
+ if (!area.getName().equals(reference.getArea())) {
+ continue;
+ }
+ for (Service service : area.getServices()) {
+ if (!service.getName().equals(reference.getService()) || service.getCom() == null) {
+ continue;
+ }
+ for (COMObject object : allObjectsOf(service)) {
+ if (object.getNumber() == reference.getNumber()) {
+ return JavaNaming.packageOf(service) + "." + service.getName()
+ + "ServiceInfo." + object.getName().toUpperCase() + "_OBJECT_TYPE";
+ }
+ }
+ }
+ }
+ return "null";
+ }
+
+ private static List<COMObject> allObjectsOf(Service service) {
+ List<COMObject> all = new ArrayList<COMObject>(service.getCom().getObjects());
+ all.addAll(service.getCom().getEvents());
+ return all;
+ }
+
+ /**
+ * Writes the method that turns an error number back into the exception it stands for.
+ * Only the errors of the area are answered for: a service's own errors are not reached
+ * this way.
+ */
+ private static void writeGenerateMOError(JavaSource out, Area area) {
+ JavaMethodBuilder method = JavaMethodBuilder.named("generateMOError").asOverride()
+ .returns(JavaNaming.MAL + "MOErrorException", null)
+ .argument("int", "errorNumber", null)
+ .argument("Object", "extraInfo", null);
+
+ method.line("switch (errorNumber) {");
+ for (ErrorDefinition error : area.getErrors()) {
+ method.line(" case " + error.getNumber() + ":");
+ method.line(" return new " + JavaNaming.packageOf(area) + "."
+ + ExceptionWriter.classNameOf(error.getName()) + "(extraInfo);");
+ }
+ method.line("}");
+ method.line("return null;");
+ method.write(out);
+ }
+
+ /**
+ * @return the names of the operations, one per line after the first.
+ */
+ private static String operationList(List<Operation> operations) {
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < operations.size(); i++) {
+ buf.append(i == 0 ? "" : ",\n ")
+ .append(operations.get(i).getName().toUpperCase()).append("_OP");
+ }
+ return buf.toString();
+ }
+
+ /**
+ * @return the MAL class that stands for the operation's interaction pattern.
+ */
+ private static String operationTypeOf(Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ return "MALSendOperation";
+ case SUBMIT:
+ return "MALSubmitOperation";
+ case REQUEST:
+ return "MALRequestOperation";
+ case INVOKE:
+ return "MALInvokeOperation";
+ case PROGRESS:
+ return "MALProgressOperation";
+ case PUBSUB:
+ return "MALPubSubOperation";
+ default:
+ return null;
+ }
+ }
+
+ /**
+ * @return the comment as a Java string literal, or the literal null where there is none.
+ */
+ private static String literal(String comment) {
+ if (comment == null) {
+ return "null";
+ }
+ return "\"" + comment.replace("\\", "\\\\").replace("\"", "\\\"")
+ .replace("\n", "\\n").replace("\r", "\\r") + "\"";
+ }
+
+ private static JavaFieldBuilder constant(String name, String type, String value) {
+ return JavaFieldBuilder.named(name).asStatic().asFinal().ofType(type).value(value);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/SubscriptionKeysWriter.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/SubscriptionKeysWriter.java
new file mode 100644
index 00000000..1d7eeb14
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/java/writers/SubscriptionKeysWriter.java
@@ -0,0 +1,181 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.java.writers;
+
+import esa.mo.apigen.generators.java.JavaClassBuilder;
+import esa.mo.apigen.generators.java.JavaFieldBuilder;
+import esa.mo.apigen.generators.java.JavaMethodBuilder;
+import esa.mo.apigen.generators.java.JavaNaming;
+import esa.mo.apigen.generators.java.JavaSource;
+import esa.mo.apigen.generators.java.JavaTypeName;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Writes the class that reads the subscription keys of one publish-subscribe operation.
+ * <p>
+ * A notify message carries its key values in the UpdateHeader, in the order the operation
+ * declared them - but a subscription may have asked for only some of them, in which case
+ * the values that arrive are fewer and the names that go with them come from the
+ * subscription rather than from the operation. This class holds both and pairs them up by
+ * name, so a consumer asks for a key rather than for an index. The UpdateHeader itself is
+ * never modified.
+ */
+public final class SubscriptionKeysWriter {
+
+ private static final String ATTRIBUTE = JavaNaming.MAL_STRUCTURES + "Attribute";
+
+ private SubscriptionKeysWriter() {
+ }
+
+ /**
+ * @return the name of the class, which is the operation's with the kind appended.
+ */
+ public static String classNameOf(Operation operation) {
+ String name = operation.getName();
+ return Character.toUpperCase(name.charAt(0)) + name.substring(1) + "SubscriptionKeys";
+ }
+
+ /**
+ * @return the source of the subscription key accessors.
+ */
+ public static String write(MOModel model, Service service, Operation operation) {
+ String className = classNameOf(operation);
+ List<Field> keys = keysOf(operation);
+
+ JavaClassBuilder clazz = JavaClassBuilder.named(className).asFinal()
+ .inPackage(JavaNaming.packageOf(service, JavaNaming.CONSUMER))
+ .comment("Typed accessors for the Subscription Keys of the "
+ + operation.getName() + " PubSub operation.");
+ JavaSource out = clazz.open();
+
+ JavaFieldBuilder.named("keyValues").scope("private")
+ .ofType(JavaNaming.MAL_STRUCTURES + "NullableAttributeList")
+ .comment("The key values as received in the UpdateHeader").write(out);
+ JavaFieldBuilder.named("keyNames").scope("private")
+ .ofType(JavaNaming.MAL_STRUCTURES + "IdentifierList")
+ .comment("The effective key names for the received key values").write(out);
+
+ StringBuilder canonical = new StringBuilder("new " + JavaNaming.MAL_STRUCTURES
+ + "IdentifierList(new java.util.ArrayList<>(java.util.Arrays.asList(");
+ for (int i = 0; i < keys.size(); i++) {
+ canonical.append(i == 0 ? "" : ", ").append("new ").append(JavaNaming.MAL_STRUCTURES)
+ .append("Identifier(\"").append(keys.get(i).getName()).append("\")");
+ }
+ JavaFieldBuilder.named("CANONICAL_KEY_NAMES").scope("private").asStatic().asFinal()
+ .ofType(JavaNaming.MAL_STRUCTURES + "IdentifierList")
+ .value(canonical.append(")))").toString())
+ .comment("The Subscription Key names defined by the operation, in order")
+ .write(out);
+
+ JavaMethodBuilder.constructor(className)
+ .comment("Creates an instance from the received UpdateHeader and the"
+ + " subscription selectedKeys.")
+ .argument(JavaNaming.MAL_STRUCTURES + "UpdateHeader", "updateHeader",
+ "The UpdateHeader received in the NOTIFY message")
+ .argument(JavaNaming.MAL_STRUCTURES + "IdentifierList", "selectedKeys",
+ "The selectedKeys of the subscription, or null if trimming was not enabled")
+ .line("this.keyValues = (updateHeader == null) ? null : updateHeader.getKeyValues();")
+ .line("this.keyNames = (selectedKeys != null) ? selectedKeys : CANONICAL_KEY_NAMES;")
+ .write(out);
+
+ for (Field key : keys) {
+ writeGetter(out, model, key);
+ }
+
+ JavaMethodBuilder.named("getByName").returns(ATTRIBUTE, "The key value, or null if not present")
+ .comment("Returns the Subscription Key value with the given name, or null if it"
+ + " is not present (for example when it was trimmed away or is a custom"
+ + " key that is not part of this subscription).")
+ .argument("String", "name", "The Subscription Key name")
+ .line("return valueByName(name);")
+ .write(out);
+
+ JavaMethodBuilder.named("valueByName").scope("private").returns(ATTRIBUTE, null)
+ .argument("String", "name", "The Subscription Key name")
+ .line("if (keyNames == null || keyValues == null) {")
+ .line(" return null;")
+ .line("}")
+ .line("for (int i = 0; i < keyNames.size(); i++) {")
+ .line(" if (name.equals(keyNames.get(i).getValue())) {")
+ .line(" if (i >= keyValues.size()) {")
+ .line(" return null;")
+ .line(" }")
+ .line(" " + JavaNaming.MAL_STRUCTURES + "NullableAttribute na = keyValues.get(i);")
+ .line(" return (na == null) ? null : na.getValue();")
+ .line(" }")
+ .line("}")
+ .line("return null;")
+ .write(out);
+
+ return clazz.close();
+ }
+
+ /**
+ * Writes the accessor of one key, which answers in the type the key was declared as
+ * rather than in the Attribute it arrived as.
+ */
+ private static void writeGetter(JavaSource out, MOModel model, Field key) {
+ String name = key.getName();
+ String getter = "get" + Character.toUpperCase(name.charAt(0)) + name.substring(1);
+ String comment = "Returns the value of the \"" + name
+ + "\" Subscription Key, or null if not present.";
+ String type = JavaTypeName.of(model, key.getType());
+ JavaMethodBuilder method = JavaMethodBuilder.named(getter)
+ .returns(type, "The key value, or null if not present");
+
+ TypeDefinition definition = model.resolve(key.getType());
+ if (definition instanceof EnumerationType) {
+ // An enumeration travels as the number that stands for it, so it is rebuilt
+ // rather than cast.
+ method.comment(comment + " Enumeration keys are transmitted as their UShort"
+ + " numeric value.")
+ .line(JavaNaming.MAL_STRUCTURES + "UShort v = ("
+ + JavaNaming.MAL_STRUCTURES + "UShort) valueByName(\"" + name + "\");")
+ .line("return (v == null) ? null : new " + type + "(v.getValue());");
+ } else if (JavaTypeName.isNativeAttribute(model, key.getType())) {
+ // A native attribute is a plain Java type, so it is unwrapped rather than cast.
+ method.comment(comment)
+ .line(ATTRIBUTE + " v = valueByName(\"" + name + "\");")
+ .line("return (v == null) ? null : (" + type + ") " + ATTRIBUTE
+ + ".attribute2JavaType(v);");
+ } else {
+ method.comment(comment).line("return (" + type + ") valueByName(\"" + name + "\");");
+ }
+ method.write(out);
+ }
+
+ /**
+ * @return the keys the operation declares, in order, empty if it declares none.
+ */
+ private static List<Field> keysOf(Operation operation) {
+ MessageBody keys = operation.getMessage(InteractionStage.SUBSCRIPTION_KEYS);
+ return keys == null ? new ArrayList<Field>() : keys.getFields();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/SvgDiagram.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/SvgDiagram.java
new file mode 100644
index 00000000..4955953e
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/SvgDiagram.java
@@ -0,0 +1,288 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.xhtml;
+
+/**
+ * One drawing: boxes for fields, each naming the field over the type in it.
+ * <p>
+ * The surface is a grid rather than a canvas. A column is one field wide and a row is a
+ * name over a type, so everything is placed in column and row units and multiplied up on
+ * the way out. The drawing sizes itself: the extent of what has been placed is what the
+ * {@code svg} element ends up declaring.
+ * <p>
+ * Two kinds of drawing share it. A message is drawn flat, one field per column, with what
+ * applies to a field bracketed underneath it. A type is drawn expanded, each composite
+ * opened out into the fields it holds on the row below, so a field spans as many columns
+ * as its contents need and as many rows as it has left above the bottom.
+ */
+public final class SvgDiagram {
+
+ /**
+ * The width of one field.
+ */
+ static final int WIDTH = 160;
+
+ /**
+ * The height of the box naming the field.
+ */
+ static final int PRIMARY_HEIGHT = 30;
+
+ /**
+ * The height of the box naming its type.
+ */
+ static final int SECONDARY_HEIGHT = 20;
+
+ static final int ROW_HEIGHT = PRIMARY_HEIGHT + SECONDARY_HEIGHT;
+
+ /**
+ * How far a bracket sits below one drawn over the same fields.
+ */
+ private static final int SPAN_STEP = 16;
+
+ /**
+ * The height of a bracket.
+ */
+ private static final int SPAN_HEIGHT = 10;
+
+ private static final int HALF_TEXT_HEIGHT = 4;
+
+ private static final int MARGIN = 10;
+
+ private static final String PARENT_COLOUR = "grey";
+
+ private static final String HEADER_COLOUR = "yellow";
+
+ private static final String COMPOSITE_COLOUR = "lavender";
+
+ private static final String FIELD_COLOUR = "lightsteelblue";
+
+ private static final String STROKE = "navy";
+
+ private final StringBuilder buf = new StringBuilder();
+
+ private final int baseLine = MARGIN;
+
+ private int column = 1;
+
+ private int maxWidth = 2;
+
+ private int maxHeight = MARGIN;
+
+ /**
+ * Draws the type a composite extends, ahead of the fields it adds.
+ *
+ * @param type The name of the parent type.
+ * @param href Where it is described, or null if nothing loaded describes it.
+ */
+ public void parent(String type, String href) {
+ box(column * WIDTH, baseLine, WIDTH, PRIMARY_HEIGHT, PARENT_COLOUR, "EXTENDS", null,
+ false, false, true);
+ box(column * WIDTH, baseLine + PRIMARY_HEIGHT, WIDTH, SECONDARY_HEIGHT, PARENT_COLOUR,
+ type, href, true, false, true);
+ column++;
+ widen();
+ }
+
+ /**
+ * Draws one field: its name over the name of its type.
+ *
+ * @param name The field name.
+ * @param type The name of its type.
+ * @param href Where that type is described, or null.
+ * @param italic Whether the type is abstract, which is how an abstract type is shown.
+ * @param bold Whether the type is an enumeration.
+ */
+ public void field(String name, String type, String href, boolean italic, boolean bold) {
+ box(column * WIDTH, baseLine, WIDTH, PRIMARY_HEIGHT, FIELD_COLOUR, name, null,
+ false, false, true);
+ box(column * WIDTH, baseLine + PRIMARY_HEIGHT, WIDTH, SECONDARY_HEIGHT, FIELD_COLOUR,
+ type, href, italic, bold, true);
+ column++;
+ widen();
+ }
+
+ /**
+ * Brackets the fields about to be drawn, saying something that applies to all of them.
+ *
+ * @param index How many brackets already sit under them, so this one clears them.
+ * @param count How many fields it covers.
+ * @param text What it says.
+ */
+ public void span(int index, int count, String text) {
+ int x1 = column * WIDTH;
+ int x2 = (column + count) * WIDTH;
+ int y1 = baseLine + ROW_HEIGHT + (index * SPAN_STEP);
+ bracket(x1, y1, x2, y1 + SPAN_HEIGHT, text);
+ }
+
+ /**
+ * Draws a field of an expanded type.
+ *
+ * @param name The field name.
+ * @param type The name of its type.
+ * @param href Where that type is described, or null.
+ * @param x The column it starts at.
+ * @param y The row it starts at.
+ * @param columns How many columns it covers.
+ * @param rows How many rows it covers.
+ * @param italic Whether the type is abstract.
+ * @param bold Whether the type is an enumeration.
+ * @param composite Whether the type is a composite, which is shown in its own colour.
+ */
+ public void nestedField(String name, String type, String href, int x, int y,
+ int columns, int rows, boolean italic, boolean bold, boolean composite) {
+ int top = baseLine + (y * ROW_HEIGHT);
+ box(x * WIDTH, top, WIDTH * columns, PRIMARY_HEIGHT, HEADER_COLOUR, name, null,
+ false, false, false);
+ box(x * WIDTH, top + PRIMARY_HEIGHT, WIDTH * columns,
+ (rows * ROW_HEIGHT) - PRIMARY_HEIGHT,
+ composite ? COMPOSITE_COLOUR : FIELD_COLOUR, type, href, italic, bold, false);
+ if (maxWidth < x + columns) {
+ maxWidth = x + columns;
+ }
+ }
+
+ /**
+ * Rules under a field of an expanded type, saying something that applies to it.
+ * <p>
+ * Wider than a bracket and drawn as a line with the text knocked out of it, because
+ * what it spans can be a good many columns of an opened-out composite.
+ *
+ * @param x The column it starts at.
+ * @param row The row it sits under.
+ * @param columns How many columns it covers.
+ * @param depth How many rules are drawn under the same field, this one being the last.
+ * @param text What it says.
+ */
+ public void nestedSpan(int x, int row, int columns, int depth, String text) {
+ int x1 = x * WIDTH;
+ int x2 = (x + columns) * WIDTH;
+ int y1 = baseLine + (row * ROW_HEIGHT) + (depth * SPAN_STEP);
+ int y2 = y1 + SPAN_HEIGHT;
+ int middle = y1 + (y2 - y1) / 2;
+
+ line(x1, y1, x1, y2);
+ line(x2, y1, x2, y2);
+ line(x1, middle, x2, middle);
+
+ // The label is set in a box of clear ground so the rule does not run through it.
+ int width = text.length() * 8;
+ knockOut(x1 + ((x2 - x1) / 2 - (width / 2)), y1, width, y2 - y1);
+ text(x1, y1, x2 - x1, HALF_TEXT_HEIGHT, text, null, false, false);
+ grow(y2);
+ }
+
+ /**
+ * @param indent How many steps in the element sits.
+ * @return the drawing as an svg element, sized to what it holds.
+ */
+ public String render(int indent) {
+ StringBuilder out = new StringBuilder();
+ out.append(XhtmlText.line(indent, "<svg:svg version=\"1.1\" width=\""
+ + ((maxWidth * WIDTH) + MARGIN) + "px\" height=\""
+ + (maxHeight + MARGIN) + "px\">"));
+ out.append(buf);
+ out.append(XhtmlText.line(indent, "</svg:svg>"));
+ return out.toString();
+ }
+
+ /**
+ * @return true if nothing has been drawn.
+ */
+ public boolean isEmpty() {
+ return buf.length() == 0;
+ }
+
+ private void bracket(int x1, int y1, int x2, int y2, String text) {
+ int middle = y1 + (y2 - y1) / 2;
+ line(x1, y1, x1, y2);
+ line(x2, y1, x2, y2);
+ line(x1, middle, x1 + SECONDARY_HEIGHT, middle);
+ line(x2, middle, x2 - SECONDARY_HEIGHT, middle);
+ text(x1, y1, x2 - x1, y2 - y1, text, null, false, false);
+ grow(y2);
+ }
+
+ private void widen() {
+ if (maxWidth < column) {
+ maxWidth = column;
+ }
+ }
+
+ /**
+ * Draws a box with its text in it.
+ *
+ * @param centred Whether the text sits in the middle of the box. A box of an expanded
+ * type is as tall as the type is deep, and text floating in the middle of it would sit
+ * nowhere near the name it belongs to, so it stays at the top.
+ */
+ private void box(int x, int y, int width, int height, String colour, String text,
+ String href, boolean italic, boolean bold, boolean centred) {
+ append("<svg:rect x=\"" + x + "\" y=\"" + y + "\" width=\"" + width + "\" height=\""
+ + height + "\" fill=\"" + colour + "\" stroke=\"" + STROKE
+ + "\" stroke-width=\"2\"/>");
+ text(x, y, width, centred ? height : SECONDARY_HEIGHT, text, href, italic, bold);
+ grow(y + height);
+ }
+
+ private void knockOut(int x, int y, int width, int height) {
+ append("<svg:rect x=\"" + x + "\" y=\"" + y + "\" width=\"" + width + "\" height=\""
+ + height + "\" fill=\"white\" stroke=\"" + STROKE + "\" stroke-width=\"0\"/>");
+ grow(y + height);
+ }
+
+ private void line(int x1, int y1, int x2, int y2) {
+ append("<svg:line x1=\"" + x1 + "\" y1=\"" + y1 + "\" x2=\"" + x2 + "\" y2=\"" + y2
+ + "\" stroke=\"" + STROKE + "\" stroke-width=\"1\"/>");
+ }
+
+ private void text(int x, int y, int width, int height, String text, String href,
+ boolean italic, boolean bold) {
+ String style = italic ? " font-style=\"italic\"" : "";
+ if (bold) {
+ style += " font-weight=\"bold\"";
+ }
+ String shown = XhtmlBody.escape(text);
+ if (href != null && !href.isEmpty()) {
+ shown = "<svg:a xlink:href=\"" + XhtmlBody.escape(href) + "\">" + shown + "</svg:a>";
+ }
+ append("<svg:text x=\"" + (x + width / 2) + "\" y=\""
+ + (y + height / 2 + HALF_TEXT_HEIGHT) + "\" font-family=\"Verdana\""
+ + " font-size=\"12\"" + style + " fill=\"" + STROKE
+ + "\" text-anchor=\"middle\" alignment-baseline=\"middle\">");
+ append(1, shown);
+ append("</svg:text>");
+ }
+
+ private void grow(int height) {
+ if (maxHeight < height) {
+ maxHeight = height;
+ }
+ }
+
+ private void append(String text) {
+ append(0, text);
+ }
+
+ private void append(int extra, String text) {
+ buf.append(XhtmlText.line(XhtmlBody.INDENT + 2 + extra, text));
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/TypeNode.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/TypeNode.java
new file mode 100644
index 00000000..123bea84
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/TypeNode.java
@@ -0,0 +1,340 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.xhtml;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * A message or a type opened out into everything it is made of.
+ * <p>
+ * Each node is one field: its name, the type in it, and - where that type is a composite -
+ * the fields of that composite on the row below. A node knows how wide it is, in columns of
+ * whatever it eventually holds, and how deep, so the drawing can be laid out before any of
+ * it is drawn.
+ * <p>
+ * <b>A composite may contain itself.</b> Mission Planning declares six that do: a Plan
+ * names a precursor Plan and a target Plan, an ActivityInstance holds its children, an
+ * EventDefinition holds the definitions under it. These are ordinary models - a plan really
+ * does supersede a plan - and the generator this replaces expanded them until the stack ran
+ * out, so the whole area produced an empty file. Here a type already open above is drawn
+ * but not opened again: it names the type, and the name is a link to where that type is
+ * described in full.
+ */
+final class TypeNode {
+
+ /**
+ * How wide a drawing is allowed to get, in fields.
+ * <p>
+ * Opening a composite replaces one field with all of its own, so a message of nested
+ * composites grows by multiplication: Mission Planning's plan status report opens out
+ * to 824 fields, thirty metres of drawing, in a page of twenty megabytes. Nothing is
+ * read at that size. The widest drawing anywhere else in the specifications is 46
+ * fields, so this leaves every one of those alone and stops only what has stopped
+ * being a diagram.
+ */
+ private static final int MAX_COLUMNS = 120;
+
+ private final String name;
+
+ private final TypeRef type;
+
+ private final boolean list;
+
+ private final boolean optional;
+
+ private final List<TypeNode> children = new ArrayList<TypeNode>();
+
+ private final boolean composite;
+
+ private final boolean enumeration;
+
+ private final boolean typeIsAbstract;
+
+ /**
+ * True where this node names a type that is already open above it, and so is left
+ * closed. Kept because it is the reason a composite has no children, which is
+ * otherwise indistinguishable from a composite with no fields.
+ */
+ private boolean closedOnCycle;
+
+ /**
+ * The types open from the root down to this node, which are the ones it must not open
+ * again.
+ */
+ private List<TypeRef> open;
+
+ /**
+ * Hands out the number of each list in a drawing, so that "N1" and "N2" say which
+ * count each "Repeated" refers to. Held by the root and asked for from anywhere below.
+ */
+ private int nextListIndex = 1;
+
+ /**
+ * The Integer of the MAL generation this specification is written against, which is
+ * what the count of a list is. Held by the root, since it is the same throughout.
+ */
+ private TypeRef counter;
+
+ private TypeNode root;
+
+ private TypeNode(String name, TypeRef type, boolean list, boolean optional,
+ MOModel model) {
+ this.name = name;
+ this.type = type;
+ this.list = list;
+ this.optional = optional;
+ this.root = this;
+
+ TypeDefinition definition = type == null ? null : model.resolve(type);
+ this.composite = definition instanceof CompositeType;
+ this.enumeration = definition instanceof EnumerationType;
+ this.typeIsAbstract = definition != null && definition.isAbstract();
+ }
+
+ /**
+ * Opens out a message.
+ *
+ * @param fields The fields of the message.
+ * @param model Every loaded specification.
+ * @param counter The Integer that counts a list, of the MAL generation in use.
+ * @return the root of the tree, which draws the fields and nothing of its own.
+ */
+ static TypeNode ofMessage(List<Field> fields, MOModel model, TypeRef counter) {
+ TypeNode root = new TypeNode(null, null, false, false, model);
+ root.counter = counter;
+ root.open = new ArrayList<TypeRef>();
+ for (Field field : fields) {
+ root.add(field.getName(), field.getType(), field.isCanBeNull(), model);
+ }
+
+ // A level at a time, so that what the drawing shows is the first so-many levels of
+ // everything rather than the whole of whatever happens to be drawn first.
+ List<TypeNode> frontier = compositesIn(root.children);
+ while (!frontier.isEmpty()) {
+ for (TypeNode node : frontier) {
+ node.openOut(model);
+ }
+ if (root.width() > MAX_COLUMNS) {
+ // This level does not fit. Close it again rather than show part of it, and
+ // leave those types named and linked instead of opened.
+ for (TypeNode node : frontier) {
+ node.children.clear();
+ }
+ break;
+ }
+ List<TypeNode> next = new ArrayList<TypeNode>();
+ for (TypeNode node : frontier) {
+ next.addAll(compositesIn(node.children));
+ }
+ frontier = next;
+ }
+ return root;
+ }
+
+ /**
+ * @return those of these nodes that hold a composite still to be opened.
+ */
+ private static List<TypeNode> compositesIn(List<TypeNode> nodes) {
+ List<TypeNode> found = new ArrayList<TypeNode>();
+ for (TypeNode node : nodes) {
+ if (node.composite && !node.closedOnCycle) {
+ found.add(node);
+ }
+ }
+ return found;
+ }
+
+ /**
+ * @return true if this is the root, which stands for the message rather than for any
+ * field of it.
+ */
+ private boolean isRoot() {
+ return type == null;
+ }
+
+ private void add(String fieldName, TypeRef fieldType, boolean canBeNull, MOModel model) {
+ TypeRef bare = fieldType.unwrapped();
+ TypeNode child = new TypeNode(nameOr(fieldName), bare, bare.isList(), canBeNull, model);
+ child.root = root;
+ child.open = new ArrayList<TypeRef>(open);
+ if (!isRoot()) {
+ child.open.add(keyOf(type));
+ }
+ child.closedOnCycle = child.composite && child.open.contains(keyOf(bare));
+ children.add(child);
+ }
+
+ /**
+ * Adds the fields of the type in this node, one level down.
+ */
+ private void openOut(MOModel model) {
+ CompositeType definition = (CompositeType) model.resolve(type);
+ if (definition == null) {
+ return;
+ }
+ // What a composite extends is drawn as a field of its own, opened out in turn, so
+ // the fields it inherits arrive through it rather than being repeated here.
+ TypeRef parent = definition.getSuperType();
+ if (parent != null && !"Composite".equals(parent.getName())) {
+ add(parent.getName(), parent, false, model);
+ }
+ for (Field field : definition.getFields()) {
+ add(field.getName(), field.getType(), field.isCanBeNull(), model);
+ }
+ }
+
+ /**
+ * @return how many columns this node takes up, which is however many its contents need.
+ */
+ int width() {
+ if (children.isEmpty()) {
+ return isRoot() ? 0 : 1 + (list ? 1 : 0);
+ }
+ int width = list ? 1 : 0;
+ for (TypeNode child : children) {
+ width += child.width();
+ }
+ return width;
+ }
+
+ /**
+ * @param above How many rows are above this one.
+ * @return the row the deepest thing under this node sits on.
+ */
+ int depth(int above) {
+ int mine = isRoot() ? above : above + 1;
+ int deepest = mine;
+ for (TypeNode child : children) {
+ int reach = child.depth(mine);
+ if (reach > deepest) {
+ deepest = reach;
+ }
+ }
+ return deepest;
+ }
+
+ /**
+ * @return how many rules are drawn under this node and everything in it, so that the
+ * ones belonging to a node higher up clear them.
+ */
+ int spanDepth() {
+ int mine = 0;
+ if (!isRoot()) {
+ mine = (list ? 1 : 0) + (optional ? 1 : 0);
+ }
+ int deepest = 0;
+ for (TypeNode child : children) {
+ int reach = child.spanDepth();
+ if (reach > deepest) {
+ deepest = reach;
+ }
+ }
+ return deepest + mine;
+ }
+
+ /**
+ * Draws this node and everything in it.
+ *
+ * @param diagram The drawing to place it on.
+ * @param area The area whose page is being written, so that links within it are short.
+ * @param model Every loaded specification.
+ * @param x The column to start at.
+ * @param y The row to start at.
+ * @param remaining How many rows are left below this one, which is how tall the box of
+ * a node with nothing under it has to be.
+ */
+ void draw(SvgDiagram diagram, Area area, MOModel model, int x, int y, int remaining) {
+ if (!isRoot()) {
+ drawSelf(diagram, area, model, x, y, remaining);
+ }
+ int at = x + (isRoot() || !list ? 0 : 1);
+ for (TypeNode child : children) {
+ child.draw(diagram, area, model, at, isRoot() ? y : y + 1,
+ isRoot() ? remaining : remaining - 1);
+ at += child.width();
+ }
+ }
+
+ private void drawSelf(SvgDiagram diagram, Area area, MOModel model,
+ int x, int y, int remaining) {
+ // What is left below this node is what the box has to fill: a field with nothing in
+ // it reaches the bottom of the drawing, one with a composite in it stops above it.
+ int height = remaining - depth(0) + 1;
+ String href = XhtmlLink.hrefTo(model, area, type);
+ String typeName = type.getName();
+
+ if (list) {
+ int index = root.nextListIndex++;
+ diagram.nestedField("N" + index, "Integer",
+ XhtmlLink.hrefTo(model, area, root.counter),
+ x, y, 1, remaining, false, false, false);
+ diagram.nestedField(name, typeName, href, x + 1, y, width() - 1, height,
+ typeIsAbstract, enumeration, composite);
+
+ int rules = spanDepth();
+ if (optional) {
+ diagram.nestedSpan(x, y + remaining, width(), rules, "Nullable");
+ rules--;
+ }
+ diagram.nestedSpan(x + 1, y + remaining, width() - 1, rules,
+ "Repeated N" + index + " times");
+ } else {
+ diagram.nestedField(name, typeName, href, x, y, width(), height,
+ typeIsAbstract, enumeration, composite);
+ if (optional) {
+ diagram.nestedSpan(x, y + remaining, width(), spanDepth(), "Nullable");
+ }
+ }
+ }
+
+ /**
+ * A message field need not be named - the specifications leave the name off where the
+ * body is a single value - and a box has to say something.
+ */
+ private static String nameOr(String fieldName) {
+ return fieldName == null || fieldName.isEmpty() ? "Part" : fieldName;
+ }
+
+ /**
+ * What makes two references the same type for the purpose of noticing a cycle: the
+ * type itself, whether or not this mention of it is a list.
+ */
+ private static TypeRef keyOf(TypeRef type) {
+ return new TypeRef(type.getArea(), type.getAreaVersion(), type.getService(),
+ type.getName(), false, false);
+ }
+
+ /**
+ * @return true where the type in this node was left closed because it is already open
+ * higher up the drawing.
+ */
+ boolean isClosedOnCycle() {
+ return closedOnCycle;
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlBody.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlBody.java
new file mode 100644
index 00000000..bf31a649
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlBody.java
@@ -0,0 +1,184 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.xhtml;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A run of page content, built up and then appended to another.
+ * <p>
+ * A page is not written in the order it is read: the index of a service has to be written
+ * above the operations it indexes, and both are only known once the operations have been
+ * walked. So sections are written into bodies of their own and assembled at the end.
+ */
+public final class XhtmlBody {
+
+ /**
+ * How far in the content of a page sits: inside html and body.
+ */
+ static final int INDENT = 2;
+
+ private final StringBuilder buf = new StringBuilder();
+
+ /**
+ * Escapes what XHTML reserves.
+ * <p>
+ * The generator this replaces escaped the text of a paragraph and not the text of a
+ * field description, so a description containing a {@code <} or an {@code &} - and the
+ * specifications contain both - produced a page no parser would accept.
+ *
+ * @param text The text, may be null.
+ * @return the text, safe to put between tags.
+ */
+ public static String escape(String text) {
+ if (text == null) {
+ return "";
+ }
+ return text.replace("&", "&").replace("<", "<").replace(">", ">");
+ }
+
+ /**
+ * Writes a heading.
+ *
+ * @param level The heading level, 1 to 6.
+ * @param prefix What the heading is, such as "Composite: ".
+ * @param anchor The anchor to give it, or null for none.
+ * @param text The name, which is what the prefix introduces.
+ * @param italic Whether the name is set in italics, which is how an abstract type is
+ * shown.
+ */
+ public void title(int level, String prefix, String anchor, String text, boolean italic) {
+ String name = escape(text);
+ if (italic) {
+ name = "<i>" + name + "</i>";
+ }
+ String id = anchor == null ? "" : " id=\"" + escape(anchor) + "\"";
+ line("<h" + level + id + ">" + escape(prefix) + name + "</h" + level + ">");
+ }
+
+ /**
+ * Writes a comment as one paragraph per paragraph of the comment.
+ *
+ * @param text The comment, may be null or empty.
+ */
+ public void comment(String text) {
+ if (text == null || text.isEmpty()) {
+ return;
+ }
+ for (String block : XhtmlText.blocksOf(text)) {
+ line(block);
+ }
+ }
+
+ /**
+ * Writes several comments in turn.
+ *
+ * @param texts The comments, any of which may be null or empty.
+ */
+ public void comments(List<String> texts) {
+ for (String text : texts) {
+ comment(text);
+ }
+ }
+
+ /**
+ * Describes one field of a type or a message, under its name.
+ *
+ * @param name The field name.
+ * @param text What it is, may be null or empty.
+ */
+ public void fieldComment(String name, String text) {
+ line("<h5>" + escape(name) + "</h5>");
+ if (text == null || text.isEmpty()) {
+ return;
+ }
+ for (String block : XhtmlText.blocksOf(text)) {
+ line(block);
+ }
+ }
+
+ /**
+ * Writes a list of links to elsewhere in the page.
+ *
+ * @param title What the index is of.
+ * @param level The heading level of that title.
+ * @param entries The entries, name to href, in the order they are to be shown.
+ */
+ public void index(String title, int level, List<Map.Entry<String, String>> entries) {
+ if (entries.isEmpty()) {
+ return;
+ }
+ line("<div class=\"index\">");
+ title(level, title, null, "", false);
+ line("<ul>");
+ for (Map.Entry<String, String> entry : entries) {
+ line("<li><a href=\"" + escape(entry.getValue()) + "\">"
+ + escape(entry.getKey()) + "</a></li>");
+ }
+ line("</ul>");
+ line("</div>");
+ }
+
+ /**
+ * Writes a diagram.
+ *
+ * @param diagram The diagram to write, already drawn.
+ */
+ public void diagram(SvgDiagram diagram) {
+ line("<p class=\"diagram\">");
+ buf.append(diagram.render(INDENT + 1));
+ line("</p>");
+ }
+
+ /**
+ * Appends another body to this one.
+ *
+ * @param other The body to append.
+ */
+ public void append(XhtmlBody other) {
+ buf.append(other.buf);
+ }
+
+ /**
+ * @return true if nothing has been written.
+ */
+ public boolean isEmpty() {
+ return buf.length() == 0;
+ }
+
+ @Override
+ public String toString() {
+ return buf.toString();
+ }
+
+ private void line(String text) {
+ buf.append(XhtmlText.line(INDENT, text));
+ }
+
+ /**
+ * @return an empty list of index entries, ready to add to.
+ */
+ static List<Map.Entry<String, String>> newIndex() {
+ return new ArrayList<Map.Entry<String, String>>();
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlGenerator.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlGenerator.java
new file mode 100644
index 00000000..ef321690
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlGenerator.java
@@ -0,0 +1,423 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.xhtml;
+
+import esa.mo.apigen.generators.Generator;
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.Field;
+import esa.mo.apigen.model.InteractionPattern;
+import esa.mo.apigen.model.InteractionStage;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.MessageBody;
+import esa.mo.apigen.model.Operation;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.com.COMFeatures;
+import esa.mo.apigen.model.com.COMObject;
+import esa.mo.apigen.model.types.CompositeType;
+import esa.mo.apigen.model.types.EnumerationItem;
+import esa.mo.apigen.model.types.EnumerationType;
+import esa.mo.apigen.model.types.FundamentalType;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.AbstractMap;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Writes a browsable page describing a specification, in an ECSS PUS style.
+ * <p>
+ * One page per area: what the area is, then a section per service and per operation, then
+ * every data type it declares, with an index of the lot at the end. The messages and the
+ * types are drawn rather than tabulated - each message once as it goes on the wire and once
+ * opened out into everything it is made of - and every type named anywhere is a link to
+ * where that type is described, whether that is this page or another.
+ * <p>
+ * This is not the generator that draws the diagrams in the Word documents. Those are SVG
+ * the specification itself declares, and the document generator rasterises them; these are
+ * drawn here from the model. The two share no code and no output.
+ */
+public final class XhtmlGenerator implements Generator {
+
+ /**
+ * What each message of an interaction is called on the page.
+ */
+ private static final String ARGUMENT_TITLE = "Telecommand application data:";
+
+ private static final String ACK_TITLE = "Acknowledgement telemetry report application data:";
+
+ private static final String UPDATE_TITLE = "Progress telemetry report application data:";
+
+ private static final String RESPONSE_TITLE = "Response telemetry report application data:";
+
+ private static final String NOTIFY_TITLE = "Notify telemetry report application data:";
+
+ private static final String EVENT_TITLE = "Event additional application data:";
+
+ @Override
+ public String getShortName() {
+ return "xhtml";
+ }
+
+ @Override
+ public String getDescription() {
+ return "Generates a navigable XHTML page of a set of MO service specifications";
+ }
+
+ @Override
+ public void generate(MOModel model, List<Area> targets, Path outputDir)
+ throws IOException {
+ for (Area area : targets) {
+ generateArea(model, area, outputDir);
+ }
+ }
+
+ private void generateArea(MOModel model, Area area, Path outputDir) throws IOException {
+ XhtmlBody page = new XhtmlBody();
+ page.title(1, "Specification: ", XhtmlLink.anchorOf(null, null), area.getName(), false);
+ page.comment(area.getComment());
+
+ // Every type described anywhere on the page, gathered as the page is written and
+ // shown in one alphabetical list at the end. The generator this replaces gathered
+ // them into a hash map and wrote them out in whatever order it iterated in, which
+ // is an index only in the sense that everything was in it.
+ Map<String, String> index = new TreeMap<String, String>();
+
+ List<Map.Entry<String, String>> serviceIndex = XhtmlBody.newIndex();
+ XhtmlBody services = new XhtmlBody();
+ for (Service service : area.getServices()) {
+ writeService(services, serviceIndex, model, area, service);
+ }
+ page.index("Services", 2, serviceIndex);
+ page.append(services);
+
+ page.title(1, "Data types", null, "", false);
+ writeDataTypes(page, index, model, area);
+
+ List<Map.Entry<String, String>> entries = XhtmlBody.newIndex();
+ for (Map.Entry<String, String> entry : index.entrySet()) {
+ entries.add(entry);
+ }
+ page.index("Index", 1, entries);
+
+ XhtmlPage.write(outputDir.resolve(XhtmlLink.pageOf(area)), area.getName(), page);
+ }
+
+ private void writeService(XhtmlBody body, List<Map.Entry<String, String>> serviceIndex,
+ MOModel model, Area area, Service service) {
+ body.title(2, "Service: ", XhtmlLink.anchorOf(service, null), service.getName(), false);
+ body.comment(service.getComment());
+ serviceIndex.add(entry(service.getName(), XhtmlLink.hrefWithin(service, null)));
+
+ List<Map.Entry<String, String>> operationIndex = XhtmlBody.newIndex();
+ XhtmlBody operations = new XhtmlBody();
+ for (Operation operation : service.getOperations()) {
+ operations.title(3, "Operation: ",
+ XhtmlLink.anchorOf(service, operation.getName()), operation.getName(), false);
+ operations.comment(operation.getComment());
+ operationIndex.add(entry(operation.getName(),
+ XhtmlLink.hrefWithin(service, operation.getName())));
+ writeMessages(operations, model, area, operation);
+ }
+ body.index("Operations", 3, operationIndex);
+ body.append(operations);
+
+ writeEvents(body, model, area, service);
+ }
+
+ /**
+ * Describes the events a service declares, each carrying whatever its object type says.
+ */
+ private void writeEvents(XhtmlBody body, MOModel model, Area area, Service service) {
+ COMFeatures com = service.getCom();
+ if (com == null || com.getEvents().isEmpty()) {
+ return;
+ }
+ List<Map.Entry<String, String>> eventIndex = XhtmlBody.newIndex();
+ XhtmlBody events = new XhtmlBody();
+ for (COMObject event : com.getEvents()) {
+ events.title(3, "Event: ", XhtmlLink.anchorOf(service, event.getName()),
+ event.getName(), false);
+ eventIndex.add(entry(event.getName(),
+ XhtmlLink.hrefWithin(service, event.getName())));
+
+ List<Field> carried = new ArrayList<Field>();
+ if (event.getBodyType() != null) {
+ carried.add(field(null, event.getBodyType(), false));
+ }
+ writeMessage(events, model, area, EVENT_TITLE, carried, event.getComment());
+ }
+ body.index("Events", 3, eventIndex);
+ body.append(events);
+ }
+
+ /**
+ * Describes each message of an operation, in the order the interaction sends them.
+ */
+ private void writeMessages(XhtmlBody body, MOModel model, Area area, Operation operation) {
+ switch (operation.getPattern()) {
+ case SEND:
+ message(body, model, area, operation, ARGUMENT_TITLE, InteractionStage.SEND);
+ break;
+ case SUBMIT:
+ message(body, model, area, operation, ARGUMENT_TITLE, InteractionStage.SUBMIT);
+ break;
+ case REQUEST:
+ message(body, model, area, operation, ARGUMENT_TITLE, InteractionStage.REQUEST);
+ message(body, model, area, operation, RESPONSE_TITLE, InteractionStage.RESPONSE);
+ break;
+ case INVOKE:
+ message(body, model, area, operation, ARGUMENT_TITLE, InteractionStage.INVOKE);
+ message(body, model, area, operation, ACK_TITLE, InteractionStage.ACK);
+ message(body, model, area, operation, RESPONSE_TITLE, InteractionStage.RESPONSE);
+ break;
+ case PROGRESS:
+ message(body, model, area, operation, ARGUMENT_TITLE, InteractionStage.PROGRESS);
+ message(body, model, area, operation, ACK_TITLE, InteractionStage.ACK);
+ message(body, model, area, operation, UPDATE_TITLE, InteractionStage.UPDATE);
+ message(body, model, area, operation, RESPONSE_TITLE, InteractionStage.RESPONSE);
+ break;
+ case PUBSUB:
+ MessageBody notify = operation.getMessage(InteractionStage.PUBLISH_NOTIFY);
+ writeMessage(body, model, area, NOTIFY_TITLE, notifyFields(model, area, notify),
+ notify == null ? null : notify.getComment());
+ break;
+ default:
+ break;
+ }
+ }
+
+ private void message(XhtmlBody body, MOModel model, Area area, Operation operation,
+ String title, InteractionStage stage) {
+ MessageBody message = operation.getMessage(stage);
+ writeMessage(body, model, area, title,
+ message == null ? new ArrayList<Field>() : message.getFields(),
+ message == null ? null : message.getComment());
+ }
+
+ /**
+ * What a NOTIFY carries, which is not what the specification writes.
+ * <p>
+ * A specification says what a publish-subscribe operation publishes; the message that
+ * arrives holds the identifier of the subscription it answers and a header for each
+ * update, and carries a list of every published value rather than one of each. The
+ * diagram shows the message, so it is assembled here.
+ */
+ private List<Field> notifyFields(MOModel model, Area area, MessageBody published) {
+ List<Field> fields = new ArrayList<Field>();
+ int mal = malVersionOf(area);
+ // Every part of a NOTIFY is there: the message says which subscription it answers
+ // and carries a header for each update, whatever the values themselves are.
+ fields.add(field("subscriptionId", new TypeRef("MAL", mal, null,
+ "Identifier", false, false), false));
+ fields.add(field("updateHeaders", new TypeRef("MAL", mal, null,
+ "UpdateHeader", true, false), false));
+ if (published != null) {
+ for (Field declared : published.getFields()) {
+ TypeRef type = declared.getType().unwrapped();
+ fields.add(field(declared.getName(), new TypeRef(type.getArea(),
+ type.getAreaVersion(), type.getService(), type.getName(), true, false),
+ false));
+ }
+ }
+ return fields;
+ }
+
+ /**
+ * Describes one message: what it carries, drawn as it goes on the wire and drawn again
+ * opened out, then what each field of it is.
+ */
+ private void writeMessage(XhtmlBody body, MOModel model, Area area, String title,
+ List<Field> fields, String comment) {
+ body.title(4, title, null, fields.isEmpty() ? " None" : "", false);
+ if (fields.isEmpty()) {
+ body.comment(comment);
+ return;
+ }
+
+ SvgDiagram flat = new SvgDiagram();
+ for (Field field : fields) {
+ drawField(flat, model, area, field);
+ }
+ body.diagram(flat);
+
+ SvgDiagram expanded = new SvgDiagram();
+ TypeNode root = TypeNode.ofMessage(fields, model,
+ new TypeRef("MAL", malVersionOf(area), null, "Integer", false, false));
+ root.draw(expanded, area, model, 1, 0, root.depth(0));
+ body.diagram(expanded);
+
+ body.comment(comment);
+ for (Field field : fields) {
+ if (field.getComment() != null && !field.getComment().isEmpty()) {
+ body.fieldComment(nameOf(field), field.getComment());
+ }
+ }
+ }
+
+ /**
+ * Draws one field as it goes on the wire: a list is a count followed by that many of
+ * the type in it.
+ */
+ private void drawField(SvgDiagram diagram, MOModel model, Area area, Field field) {
+ TypeRef type = field.getType().unwrapped();
+ if (type.isList()) {
+ diagram.field("N", "Integer", XhtmlLink.hrefTo(model, area,
+ new TypeRef("MAL", malVersionOf(area), null, "Integer", false, false)),
+ false, false);
+ diagram.span(1, 1, "Repeated N times");
+ }
+ diagram.field(nameOf(field), type.getName(), XhtmlLink.hrefTo(model, area, type),
+ isAbstract(model, type), isEnumeration(model, type));
+ }
+
+ /**
+ * Describes every type the specification declares, area level first and then service by
+ * service.
+ */
+ private void writeDataTypes(XhtmlBody body, Map<String, String> index,
+ MOModel model, Area area) {
+ if (!area.getDataTypes().isEmpty()) {
+ body.title(2, "Area data types: ", null, area.getName(), false);
+ for (TypeDefinition type : area.getDataTypes()) {
+ writeDataType(body, index, model, area, null, type);
+ }
+ }
+ for (Service service : area.getServices()) {
+ if (service.getDataTypes().isEmpty()) {
+ continue;
+ }
+ body.title(2, "Service data types: ", null, service.getName(), false);
+ for (TypeDefinition type : service.getDataTypes()) {
+ writeDataType(body, index, model, area, service, type);
+ }
+ }
+ }
+
+ private void writeDataType(XhtmlBody body, Map<String, String> index, MOModel model,
+ Area area, Service service, TypeDefinition type) {
+ if (type instanceof FundamentalType) {
+ body.title(3, "Fundamental: ", XhtmlLink.anchorOf(service, type.getName()),
+ type.getName(), true);
+ body.comment(type.getComment());
+ } else if (type instanceof esa.mo.apigen.model.types.AttributeType) {
+ body.title(3, "Attribute: ", XhtmlLink.anchorOf(service, type.getName()),
+ type.getName(), true);
+ body.comment(type.getComment());
+ } else if (type instanceof EnumerationType) {
+ writeEnumeration(body, (EnumerationType) type, service);
+ } else if (type instanceof CompositeType) {
+ writeComposite(body, model, area, service, (CompositeType) type);
+ } else {
+ throw new IllegalArgumentException("A data type of "
+ + area.getName() + " is a " + type.getClass().getName()
+ + ", which is not something a page can describe");
+ }
+ index.put(type.getName(), XhtmlLink.hrefWithin(service, type.getName()));
+ }
+
+ private void writeEnumeration(XhtmlBody body, EnumerationType type, Service service) {
+ body.title(3, "Enum: ", XhtmlLink.anchorOf(service, type.getName()),
+ type.getName(), false);
+ body.comment(type.getComment());
+ for (EnumerationItem item : type.getItems()) {
+ body.fieldComment(item.getValue(), item.getComment());
+ }
+ }
+
+ private void writeComposite(XhtmlBody body, MOModel model, Area area, Service service,
+ CompositeType type) {
+ body.title(3, "Composite: ", XhtmlLink.anchorOf(service, type.getName()),
+ type.getName(), type.isAbstract());
+ body.comment(type.getComment());
+
+ SvgDiagram diagram = new SvgDiagram();
+ TypeRef parent = type.getSuperType();
+ if (parent != null && !"Composite".equals(parent.getName())) {
+ diagram.parent(parent.getName(), XhtmlLink.hrefTo(model, area, parent));
+ }
+ for (Field field : type.getFields()) {
+ TypeRef fieldType = field.getType().unwrapped();
+ if (field.isCanBeNull()) {
+ int covered = fieldType.isList() ? 2 : 1;
+ diagram.span(covered, covered, "Nullable");
+ }
+ if (fieldType.isList()) {
+ diagram.field("N", "Integer", XhtmlLink.hrefTo(model, area,
+ new TypeRef("MAL", malVersionOf(area), null, "Integer", false, false)),
+ false, false);
+ diagram.span(1, 1, "Repeated N times");
+ }
+ diagram.field(field.getName(), fieldType.getName(),
+ XhtmlLink.hrefTo(model, area, fieldType),
+ isAbstract(model, fieldType), isEnumeration(model, fieldType));
+ }
+ body.diagram(diagram);
+
+ for (Field field : type.getFields()) {
+ if (field.getComment() != null && !field.getComment().isEmpty()) {
+ body.fieldComment(field.getName(), field.getComment());
+ }
+ }
+ }
+
+ /**
+ * The MAL generation a specification is written against, which decides which MAL its
+ * Integer and its UpdateHeader are.
+ */
+ private static int malVersionOf(Area area) {
+ if (area.getSpecification() == null || area.getSpecification().getSchemaVersion() == null) {
+ return 1;
+ }
+ return area.getSpecification().getSchemaVersion().getMalVersion();
+ }
+
+ private static boolean isAbstract(MOModel model, TypeRef type) {
+ TypeDefinition definition = model.resolve(type);
+ return definition != null && definition.isAbstract();
+ }
+
+ private static boolean isEnumeration(MOModel model, TypeRef type) {
+ return model.resolve(type) instanceof EnumerationType;
+ }
+
+ /**
+ * A message field need not be named, and a box has to say something.
+ */
+ private static String nameOf(Field field) {
+ return field.getName() == null || field.getName().isEmpty() ? "Part" : field.getName();
+ }
+
+ private static Field field(String name, TypeRef type, boolean canBeNull) {
+ Field field = new Field();
+ field.setName(name);
+ field.setType(type);
+ field.setCanBeNull(canBeNull);
+ return field;
+ }
+
+ private static Map.Entry<String, String> entry(String name, String href) {
+ return new AbstractMap.SimpleEntry<String, String>(name, href);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlLink.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlLink.java
new file mode 100644
index 00000000..201b465e
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlLink.java
@@ -0,0 +1,113 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.xhtml;
+
+import esa.mo.apigen.model.Area;
+import esa.mo.apigen.model.MOModel;
+import esa.mo.apigen.model.Service;
+import esa.mo.apigen.model.types.TypeDefinition;
+import esa.mo.apigen.model.types.TypeRef;
+
+/**
+ * Names the pages and the anchors within them, and links one to another.
+ * <p>
+ * Every anchor is {@code service_name}, or {@code _name} for something an area declares
+ * itself, so an anchor is unique within its page whether or not two services name a type
+ * the same way.
+ * <p>
+ * A link is only written when the target is known to exist. The generator this replaces
+ * wrote one for every type it mentioned, so a list type linked to an anchor no page ever
+ * defines - seven of them across the standards, {@code #_ElementList} among them, because
+ * the name it linked to was the name of the list rather than of the type in it.
+ */
+public final class XhtmlLink {
+
+ private XhtmlLink() {
+ }
+
+ /**
+ * Names the page of an area, after the specification it is generated from.
+ * <p>
+ * The number and the version are part of the name because the name alone is not an
+ * identity: MAL is published at version 1 and version 3, Monitor and Control at 1 and
+ * 2, and the generator this replaces wrote both of each pair to {@code outputMAL.xhtml}
+ * and {@code outputMC.xhtml}, so whichever specification was read second was the only
+ * one that survived.
+ *
+ * @param area The area the page describes.
+ * @return the file name of its page.
+ */
+ public static String pageOf(Area area) {
+ return String.format("area%03d-v%03d-%s.xhtml",
+ area.getNumber(), area.getVersion(), area.getName());
+ }
+
+ /**
+ * The anchor of something a page describes.
+ *
+ * @param service The service that declares it, or null if the area does.
+ * @param name The name of the thing, or null for the top of the page.
+ * @return the anchor, without its '#'.
+ */
+ public static String anchorOf(Service service, String name) {
+ return (service == null ? "" : service.getName()) + "_" + (name == null ? "" : name);
+ }
+
+ /**
+ * Links to a type from the page of an area.
+ * <p>
+ * A list is drawn as a count and the type in it, so what is linked to is the type in
+ * it: {@code List<UpdateHeader>} resolves to wherever UpdateHeader is described.
+ *
+ * @param model Every loaded specification.
+ * @param from The area whose page is being written.
+ * @param type The type to link to.
+ * @return the href, or null if nothing loaded declares the type - in which case the
+ * name is written without a link rather than linking nowhere.
+ */
+ public static String hrefTo(MOModel model, Area from, TypeRef type) {
+ if (type == null) {
+ return null;
+ }
+ TypeRef target = type.unwrapped();
+ TypeDefinition declaration = model.resolve(target);
+ if (declaration == null) {
+ return null;
+ }
+ Area declaring = declaration.getArea();
+ String anchor = anchorOf(declaration.getService(), declaration.getName());
+ if (declaring == from) {
+ return "#" + anchor;
+ }
+ return pageOf(declaring) + "#" + anchor;
+ }
+
+ /**
+ * Links to something on the page being written.
+ *
+ * @param service The service that declares it, or null if the area does.
+ * @param name The name of the thing.
+ * @return the href.
+ */
+ public static String hrefWithin(Service service, String name) {
+ return "#" + anchorOf(service, name);
+ }
+}
diff --git a/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlPage.java b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlPage.java
new file mode 100644
index 00000000..c8624296
--- /dev/null
+++ b/api-generator/api-generator-lib/src/main/java/esa/mo/apigen/generators/xhtml/XhtmlPage.java
@@ -0,0 +1,99 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2026 European Space Agency
+ * European Space Operations Centre
+ * Darmstadt
+ * Germany
+ * ----------------------------------------------------------------------------
+ * System : CCSDS MO API Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.apigen.generators.xhtml;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * The file a page is written to: what wraps the content, and the writing of it.
+ */
+public final class XhtmlPage {
+
+ private static final Charset UTF8 = Charset.forName("UTF-8");
+
+ /**
+ * The style sheet, carried as the file it is so it can be read and edited as CSS. It
+ * is written into the page rather than beside it, so that a page is one file that can
+ * be moved, mailed or opened from anywhere.
+ */
+ private static final String STYLESHEET = "/xhtml/page.css";
+
+ private XhtmlPage() {
+ }
+
+ /**
+ * Writes a page.
+ *
+ * @param file Where to write it.
+ * @param title What the page is about, which is what a browser shows in its tab. The
+ * generator this replaces wrote every page with an empty title, so a reader with
+ * several open could not tell one from another.
+ * @param body The content of the page.
+ * @throws IOException if writing fails.
+ */
+ public static void write(Path file, String title, XhtmlBody body) throws IOException {
+ StringBuilder out = new StringBuilder();
+ out.append(XhtmlText.line(0, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"));
+ out.append(XhtmlText.line(0, "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\""
+ + " \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">"));
+ out.append(XhtmlText.line(0, "<html xmlns=\"http://www.w3.org/1999/xhtml\""
+ + " xmlns:svg=\"http://www.w3.org/2000/svg\""
+ + " xmlns:xlink=\"http://www.w3.org/1999/xlink\">"));
+ out.append(XhtmlText.line(1, "<head>"));
+ out.append(XhtmlText.line(2, "<title>" + XhtmlBody.escape(title) + ""));
+ out.append(XhtmlText.line(2, ""));
+ out.append(XhtmlText.line(1, ""));
+ out.append(XhtmlText.line(1, ""));
+ out.append(body.toString());
+ out.append(XhtmlText.line(1, ""));
+ out.append(XhtmlText.line(0, "