Framework E (17.104.x): Java 21 / WildFly 32 / Jakarta EE 10 upgrade

CHANGELOG.md

@@ -5,6 +5,24 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [21.0.0-M1] - 2026-06-02
+### Changed
+- Upgraded to Java 21 and Jakarta EE 10 (17.104.x release line)
+- Updated `maven-framework-parent-pom` to `21.0.0-M3-SNAPSHOT` for local chain validation; pinned to `21.0.0-M2` released version for CI
+- Migrated all `javax.*` imports to `jakarta.*` across all modules
+- Replaced `javax.xml.bind:jaxb-api` with `jakarta.xml.bind:jakarta.xml.bind-api` in all raml-maven and generator-maven-plugin module POMs
+- Migrated `javax.jms.*` to `jakarta.jms.*` in embedded Artemis and JMS test utility classes
+- Removed `embedded-artemis` module (server-side Artemis internals; not upgradeable and architecturally unsound)
+- Upgraded OpenEJB from `8.0.13` to `10.1.4` (Jakarta EE 10 / CDI 4.0 compatible)
+
+### Fixed
+- RAML parser modules (`raml-parser`, `raml-generator-core`, `generator-core`, `generator-raml-parser`, `raml-maven-plugin`, `generator-plugin`): `org.raml:raml-parser` uses `javax.xml.bind.*` classes internally (pre-Jakarta EE 9 namespace). Fixed by pinning `jakarta.xml.bind:jakarta.xml.bind-api` to version `2.3.2` — the last release where the API classes remained in the `javax.xml.bind.*` namespace. Version is controlled by the `jakarta.xml.bind-api.raml.version` property in the root pom (with full explanation). Do not upgrade to 3.x or 4.x.
+- Fixed `IntegerEnumDeserializer`: changed `super(enumResolver)` to `super(enumResolver, Boolean.FALSE)` — Jackson 2.15.x single-arg `EnumDeserializer(EnumResolver)` passes `null` for `caseInsensitive` causing `NullPointerException` on unboxing
+- Fixed `HasEventsMatcherTest` `UnnecessaryStubbingException`: replaced `lenient()` stubbing with strict `when()` stubs and used plain `mock(JsonNode.class)` for event nodes that are never queried via `fieldNames()`
+- Fixed Maven plugin scope warnings: added `<scope>provided</scope>` to `maven-plugin-api`, `maven-compat`, `maven-core`, and `maven-model` in `annotation-validator-maven-plugin`, `generator-plugin`, and `raml-maven-plugin`
+
+### Added
+- `jakarta.xml.bind-api.raml.version` root pom property: documents why `jakarta.xml.bind:jakarta.xml.bind-api` is pinned to `2.3.2` for RAML parser modules (org.raml:raml-parser requires the pre-EE9 `javax.xml.bind.*` namespace)
 # [17.104.0] - 2025-12-16
 ### Added
 - New module `framework-libraries-version` that contains a maven generated json file that has this project's version number

README.md

@@ -1,41 +1,68 @@
-# Framework Libraries
+# cp-framework-libraries
 
-[![Coverage Status](https://coveralls.io/repos/github/hmcts/cp-framework-libraries/badge.svg?branch=main)](https://coveralls.io/github/hmcts/cp-framework-libraries?branch=main)
+`uk.gov.justice.framework.libraries:framework-libraries`
 
-Common Libraries used by [Microservice Framework](https://github.com/CJSCommonPlatform/microservice_framework)
+Common libraries used by the CPP microservice framework. This project provides the APIs, utilities, code generators, and testing tools that the rest of the framework stack depends on.
 
-## Library Projects
+## Position in the hierarchy
 
-# [Framework API](./framework-api/README.md)
-The Java API for a framework to support applications utilising CQRS and Event Sourcing architectures.
+```
+maven-framework-parent-pom
+└── cp-framework-libraries  ← this project
+    └── framework-libraries-bom  (imported by cp-microservice-framework and cp-event-store)
+```
 
-# [Framework Utilities](./framework-utilities/README.md)
-Main repository for utilities used by [Microservice Framework](https://github.com/CJSCommonPlatform/microservice_framework)
+`cp-microservice-framework` imports `framework-libraries-bom` to consume the artifacts from this project.
 
-# [Maven Generator Plugin](./generator-maven-plugin/README.md)
-A plugin for using [RAML](http://raml.org/) within Maven projects for the generation of [Microservice Framework](https://github.com/CJSCommonPlatform/microservice_framework) code. 
+## Modules
 
-# [Job Manager](./job-manager/README.md)
-A stateful multi-threaded Job and Task executor. 
+| Module | Artifact | Description |
+|---|---|---|
+| `framework-api` | `framework-api-*` | Java API contracts (interfaces and annotations) for CQRS/ES — `@Handles`, `@ServiceComponent`, `Sender`, `Envelope`, `JsonEnvelope`, `Requester` |
+| `framework-utilities` | `utilities-core`, `utilities-file`, `test-utils-*` | Core utilities (UUID generation, date/time helpers, JSON utilities) plus a set of test utilities used across all projects |
+| `generator-maven-plugin` | `generator-maven-plugin` | Maven plugin that drives RAML-based code generation (REST adapters, messaging adapters, JMS listeners) |
+| `json-schema-catalog` | `json-schema-catalog-*` | JSON Schema catalog — resolves `$ref` URIs to local schema files, mirroring the XML Catalog concept |
+| `jsonschema-pojo-generator` | `pojo-generation-plugin`, `jsonschema-pojo-generator` | Generates Java POJOs from JSON Schema definitions; used for domain event payload classes |
+| `raml-maven` | `raml-maven-plugin`, `raml-maven` | RAML parsing support for Maven projects; validates RAML files and extracts schema/action metadata |
+| `annotation-validator` | `annotation-validator-maven-plugin` | Maven plugin that validates `@Handles`, `@ServiceComponent`, and other framework annotations are applied correctly |
+| `domain-test-dsl` | `domain-test-dsl` | Fluent DSL for writing aggregate unit tests — builds event sequences and asserts raised events |
+| `job-manager` | `job-manager` | Priority-aware multi-threaded job and task executor; worker slots and priority percentages are JNDI-configurable (see `jndi-configuration.md`) |
+| `json-transformer` | `json-transformer` | JSON document transformation utilities (Jolt-based and custom) |
+| `framework-datasources` | `framework-datasources` | CDI producers for `@EventStoreDataSource`, `@ViewStoreDataSource`, and `@FileStoreDataSource` JNDI datasource lookups |
+| `framework-libraries-bom` | `framework-libraries-bom` | BOM that imports all `framework-libraries` artifacts at a consistent version |
 
-# [Json Schema Catalog](./json-schema-catalog/README.md)
-A json version of [XML Catalogs](https://www.oasis-open.org/committees/entity/spec-2001-08-06.html)
+## Key APIs
 
-# [Pojo Generator](./jsonschema-pojo-generator/README.md)
-Generator for domain event POJOs defined in json schemas
+**Envelope / messaging**
+- `JsonEnvelope` — the universal message wrapper carrying a `Metadata` header and a `JsonValue` payload
+- `Envelope<T>` — typed variant for domain command/event payloads
+- `Metadata` — carries the action name, stream ID, causation chain, session info
 
-# [Maven Raml](./raml-maven/README.md)
-A plugin for using [RAML](http://raml.org/) documents within Maven projects.
+**Dispatch**
+- `Sender` — fire-and-forget command dispatch (`sender.send(envelope)`)
+- `Requester` — request/response query dispatch (`requester.request(envelope)`)
+- `@Handles("action.name")` — marks a method as the handler for a named action
 
-# [Embedded Artemis](./embedded-artemis/README.md)
-An embedded version of Artemis that can be included in a project for testing.
+**Service component**
+- `@ServiceComponent(SERVICE_COMPONENT)` — CDI qualifier that identifies a bean as a framework service component (command API, command handler, event listener, etc.)
 
-# [Annotation Validator Maven Plugin](./annotation-validator/README.md)
-A plugin for validating annotations, that creates a report that lists what classes have which annotations
+**Testing**
+- `domain-test-dsl` — `given(events).when(command).thenExpect(event)` style aggregate tests
+- `test-utils-core` / `test-utils-common` — builder helpers, envelope factories, mock producers
 
-# [Json Transformer](./json-transformer/README.md)
+## Build
 
-# [Domain Test DSL](./domain-test-dsl/README.md)
-
+```bash
+# Build and install all modules
+mvn clean install
 
+# Skip integration tests (no PostgreSQL needed)
+mvn clean install -DskipTests
 
+# Build a specific module and its dependencies
+mvn clean install -pl json-schema-catalog -am
+```
+
+## JNDI configuration
+
+See [jndi-configuration.md](./jndi-configuration.md) for JNDI keys used by `job-manager`.

annotation-validator/annotation-validator-core/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>uk.gov.justice.maven</groupId>
         <artifactId>annotation-validator</artifactId>
-        <version>17.104.1-SNAPSHOT</version>
+        <version>21.0.0-M1-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

annotation-validator/annotation-validator-maven-plugin/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>uk.gov.justice.maven</groupId>
         <artifactId>annotation-validator</artifactId>
-        <version>17.104.1-SNAPSHOT</version>
+        <version>21.0.0-M1-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
@@ -28,21 +28,25 @@
         <dependency>
             <groupId>org.apache.maven</groupId>
             <artifactId>maven-plugin-api</artifactId>
+            <scope>provided</scope>
         </dependency>
 
         <dependency>
             <groupId>org.apache.maven</groupId>
             <artifactId>maven-compat</artifactId>
+            <scope>provided</scope>
         </dependency>
 
         <dependency>
             <groupId>org.apache.maven</groupId>
             <artifactId>maven-core</artifactId>
+            <scope>provided</scope>
         </dependency>
 
         <dependency>
             <groupId>org.apache.maven</groupId>
             <artifactId>maven-model</artifactId>
+            <scope>provided</scope>
         </dependency>
 
         <dependency>
@@ -82,8 +86,18 @@
             <artifactId>annotation-validator-core</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+        </dependency>
 
         <!-- Test dependencies -->
+        <dependency>
+            <groupId>jakarta.inject</groupId>
+            <artifactId>jakarta.inject-api</artifactId>
+            <version>${jakarta.inject-api.version}</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-simple</artifactId>

annotation-validator/annotation-validator-maven-plugin/src/test/java/uk/gov/justice/plugin/validator/AnnotationValidatorFactoryTest.java

@@ -9,7 +9,7 @@
 import uk.gov.justice.plugin.domain.TestAnnotation;
 import uk.gov.justice.plugin.exception.ValidatorNotFoundException;
 
-import javax.inject.Inject;
+import jakarta.inject.Inject;
 
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;

annotation-validator/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>uk.gov.justice.framework.libraries</groupId>
         <artifactId>framework-libraries</artifactId>
-        <version>17.104.1-SNAPSHOT</version>
+        <version>21.0.0-M1-SNAPSHOT</version>
     </parent>
 
     <groupId>uk.gov.justice.maven</groupId>

azure-pipelines.yaml

@@ -31,7 +31,7 @@ resources:
 pool:
   name: 'MDV-ADO-AGENT-AKS-01'
   demands:
-    - identifier -equals centos8-j17-postgres
+    - identifier -equals ubuntu-j21
 
 variables:
   - name: sonarqubeProject

domain-test-dsl/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>uk.gov.justice.framework.libraries</groupId>
         <artifactId>framework-libraries</artifactId>
-        <version>17.104.1-SNAPSHOT</version>
+        <version>21.0.0-M1-SNAPSHOT</version>
     </parent>
 
     <groupId>uk.gov.justice.services</groupId>
@@ -30,7 +30,7 @@
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-failsafe-plugin</artifactId>
-                        <version>2.22.2</version>
+                        <version>${plugins.maven.failsafe.version}</version>
                         <executions>
                             <execution>
                                 <goals>

domain-test-dsl/src/test/java/uk/gov/justice/services/test/AggregateMethodInvocationTest.java

@@ -10,7 +10,7 @@
 import uk.gov.justice.services.test.domain.aggregate.GenericAggregate;
 import uk.gov.justice.services.test.domain.arg.ComplexArgument;
 
-import java.time.ZoneId;
+import java.time.ZoneOffset;
 import java.util.UUID;
 
 import org.junit.jupiter.api.BeforeEach;
@@ -85,7 +85,7 @@ public void shouldCallMethodWithDateTimeArgFromFile() throws Exception {
 
         assertMethodInvocations(aggregateWrapper, "doSthWithDateTimeArg", 1,
                 arrayContaining(ZonedDateTimes.fromString("2017-01-21T16:42:03.522Z")
-                        .withZoneSameInstant(ZoneId.of("UTC"))));
+                        .withZoneSameInstant(ZoneOffset.UTC)));
     }
 
     @Test

domain-test-dsl/src/test/java/uk/gov/justice/services/test/matchers/HasEventsMatcherTest.java

@@ -43,7 +43,7 @@ public void shouldReturnTrueIfAllExpectedEventsAreInTheActualEventList() throws
 
         final JsonNode event_1 = create("event_1");
         final JsonNode event_2 = create("event_2");
-        final JsonNode event_3 = create("event_3");
+        final JsonNode event_3 = mock(JsonNode.class, "event_3");
 
         final Description description = mock(Description.class);