Release 24.0.0: Java 24 / Jakarta

.cursor/rules/ascii-source.mdc

@@ -0,0 +1,22 @@
+---
+description: Tracked source and docs must be ASCII only
+alwaysApply: true
+---
+
+# ASCII source
+
+Every file you **add or edit** must be **ASCII only** (bytes 0x00-0x7F). Scan touched paths before finishing.
+
+Replace:
+
+| Non-ASCII          | ASCII       |
+| ------------------ | ----------- |
+| em/en dash, minus  | `-`         |
+| ellipsis           | `...`       |
+| curly quotes       | `'` / `"`   |
+| arrows             | `->` / `<-` |
+| non-breaking space | space       |
+
+Do not introduce Unicode symbols, emoji, or locale punctuation in code, comments, XML, or docs.
+
+WSDL/XSD copied from the licensed toolkit may contain non-ASCII. Do not add more. Prefer ASCII in files you author.

.cursor/rules/common-library-project.mdc

@@ -0,0 +1,47 @@
+---
+description: common-library-java artifact repo layout, release lines, and build
+alwaysApply: true
+---
+
+# common-library-java
+
+Maven artifact **`au.gov.nehta:common-library`** - shared Java utility classes used by other ADHA/NEHTA libraries (CDA package operations, argument validation, web-service helpers).
+
+## Documentation
+
+Follow **`documentation-standards.mdc`**. Integrator docs use **version numbers** - not Git branch names.
+
+The **first number** of **`au.gov.nehta:common-library`** is the **Java SE** target, aligned with the HI/MHR client release lines.
+
+| Version    | Java | XML stack   |
+| ---------- | ---- | ----------- |
+| **8.0.0**  | 8    | **javax**   |
+| **11.0.0** | 11   | **Jakarta** |
+| **17.0.0** | 17   | **Jakarta** |
+| **21.0.0** | 21   | **Jakarta** |
+| **24.0.0** | 24   | **Jakarta** |
+
+**Git branch mapping (maintainers only - never in integrator docs):**
+
+| Version    | Official Git branch |
+| ---------- | ------------------- |
+| **8.0.0**  | `java-8`            |
+| **11.0.0** | `java-11`           |
+| **17.0.0** | `java-17`           |
+| **21.0.0** | `java-21`           |
+| **24.0.0** | `java-24`           |
+
+## This 24.0.0 line
+
+**`24.0.0-SNAPSHOT`**: Java **24**, **Jakarta** XML APIs, **`jaxws-rt` 4.0.5**. Siblings **`smi-common-utils`** and **`smi-xsp`** at **`${project.version}`**.
+
+## Build
+
+- JDK **24+**, from repo root: `mvn -B "-Dgpg.skip=true" clean verify` (quote `-D` on PowerShell).
+
+## Doc split
+
+- **`documentation-standards.mdc`**: implementor-first, Maven Central default, local/OS sections, relative paths, no secrets
+- **`README.md`**: integrators (Maven Central default)
+- **`CONTRIBUTING.md`**: build from source, local SNAPSHOT install
+- **`MAINTAINERS.md`**: POM internals

.cursor/rules/documentation-standards.mdc

@@ -0,0 +1,50 @@
+---
+description: Documentation and build scripts - implementor-first, Maven Central default, no secrets
+alwaysApply: true
+---
+
+# Documentation and build scripts
+
+Applies when writing or editing **README**, **CONTRIBUTING**, integrator guides, **SECURITY**, release notes, **build.*** / **build.xml** header comments, **settings.xml.example**, **local.properties.example**, and similar tracked material.
+
+## Priority: implementors
+
+- Primary audience: developers **consuming** published Maven artifacts.
+- Contributor/maintainer workflow lives in **CONTRIBUTING.md**, **MAINTAINERS.md**, or labelled subsections - not mixed into the integrator main flow.
+- Do not duplicate agent workflow in README or CONTRIBUTING (**AGENTS.md** -> `.cursor/rules/`).
+
+## Default narrative: Maven Central
+
+- Write as if **released** coordinates are on Maven Central (no SNAPSHOT, sibling-repo checkout, or `-P...` profiles in the main integrator path).
+- Use **version numbers** in integrator docs - not Git branch names.
+- SNAPSHOT installs and sibling `mvn install` belong under **Local development** / **Local builds** only.
+
+## Structure
+
+| Where | What |
+| ----- | ---- |
+| README / integrator docs | Dependency, runtime config, capabilities |
+| Local development | Unpublished builds, SNAPSHOT, source-tree prerequisites |
+| By OS (when needed) | Separate **Windows**, **macOS**, **Linux** blocks (wrappers, cleanup, path notes) |
+
+## Paths
+
+- **Relative paths only** (e.g. `src/main/resources/`, `pom.xml` beside repo root).
+- **Never** hardcode machine paths (`C:\...`, `/Users/...`, `~/`, worktree folders) in tracked docs.
+- Override only when strictly required to remove ambiguity - say why.
+
+## Current state only
+
+- No migration, legacy, or branch-history commentary in user-facing docs.
+- Describe **what is true now**; omit "removed", "used to", and repo archaeology in integrator material.
+- **CHANGELOG** entries: current release capabilities; avoid branch names and migration essays in new notes.
+
+## Secrets - MUST NOT
+
+- **Never** put real or plausible **passwords**, **tokens**, **API keys**, **private keys**, or **keystore passphrases** in tracked files (code, comments, examples, docs).
+- Use placeholders or empty values in `.example` files.
+- See **SECURITY.md**.
+
+## Override
+
+These rules may be overridden **only when necessary** to clear ambiguity (e.g. maintainer branch mapping in **MAINTAINERS.md** or `.cursor/rules/`, clearly labelled maintainer-only).

.cursor/rules/multi-branch-worktrees.mdc

@@ -0,0 +1,45 @@
+---
+description: Use git worktree when editing multiple branches of the same repository
+alwaysApply: true
+---
+
+# Multi-branch work - use git worktree
+
+When a task requires **changes on two or more branches of the same Git repository**, use **`git worktree`** - do **not** hop branches with `git checkout` while carrying uncommitted edits or stashes.
+
+## When this applies
+
+- Same-repo edits across release lines (e.g. `java-8`, `java-11`)
+- Applying the same fix to several branches before commit
+- Comparing or building two branches side by side
+
+## When checkout is fine
+
+- Single branch for the whole task
+- Read-only inspection: `git show <branch>:path`
+- Clean working tree and only one target branch
+
+## Workflow
+
+1. **Primary clone** stays on the main working branch; do not stash-and-hop to edit other branches.
+2. **Add a worktree per extra branch** (paths are local - never commit them to tracked docs):
+
+   ```bash
+   git worktree add ../<repo>-<branch-slug> <branch>
+   ```
+
+3. **Edit and commit in each worktree** independently; verify build/tests per branch.
+4. **Remove when done**: `git worktree remove ../<repo>-<branch-slug>` (or `git worktree prune` after manual delete).
+
+## Do not
+
+- `git checkout` other branches with uncommitted changes (Git will block or force stash churn).
+- Stash the same files across multiple branch switches - causes merge conflicts on `stash pop`.
+- Put worktree directory paths in README, CONTRIBUTING, or other tracked docs (see repo **`worktrees.mdc`** / **`documentation-standards.mdc`**).
+
+## Example (maintainer-local paths only)
+
+```bash
+git worktree add <path> java-8
+git worktree add <path> java-11
+```

.cursor/rules/worktrees.mdc

@@ -0,0 +1,37 @@
+---
+description: Worktree paths are local only - versions belong in integrator docs
+alwaysApply: true
+---
+
+# Worktrees (local convenience only)
+
+**`git worktree`** lets a maintainer check out multiple branches of the **same repository** at once. Worktree **directory paths are machine-specific** and must **not** appear in tracked documentation.
+
+## What tracked docs describe
+
+Follow **`documentation-standards.mdc`** (implementor-first, Maven Central default).
+
+| Doc | Audience | Use |
+| --- | --------- | --- |
+| **README**, integrator guides | Implementors | **Maven version** (`11.0.0`), Central coordinates, JAR contents |
+| **CONTRIBUTING** | Contributors | Build from source, **Local builds**, OS-specific steps |
+| **MAINTAINERS**, **`.cursor/rules/`** | Maintainers | POM internals; **branch mapping** only when labelled maintainer-only |
+
+Integrator docs: **version numbers**, not Git branch names. Local/SNAPSHOT flows: **CONTRIBUTING** only.
+
+## Do not put in tracked docs
+
+- Hardcoded worktree or machine paths (`wt/`, `C:\...`, `/Users/...`, `~/`, `this worktree`, `primary clone`)
+- References to **`wt/README.md`** or other local-only layout files
+- "Open folder X to switch branches" - IDE/local workflow, not repo documentation
+
+## Allowed (maintainer-only, when labelled)
+
+- **Git branch mapping** table (version -> branch) in **MAINTAINERS.md** or agent rules
+- Generic worktree example only: `git worktree add <path> <branch>` (placeholder **`<path>`**, never a committed example)
+- Optional **untracked** local notes outside the repo
+
+## When editing docs
+
+1. Identify the **Maven version / release line** the text applies to, not the worktree folder Cursor has open.
+2. Remove or rewrite any committed worktree path tables or branch names in integrator-facing files.

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [ java-24 ]
+  pull_request:
+    branches: [ java-24 ]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "24"
+          cache: maven
+      - name: Maven verify
+        run: mvn -B "-Dgpg.skip=true" clean verify

AGENTS.md

@@ -0,0 +1,13 @@
+# Cursor agents
+
+Rules: `.cursor/rules/*.mdc`. Do not duplicate in README or CONTRIBUTING.
+
+| Concern | Rule |
+|---------|------|
+| ASCII only in authored files | `ascii-source.mdc` |
+| Documentation and build scripts (implementor-first, Central, local, OS, paths, no secrets) | `documentation-standards.mdc` |
+| common-library scope, build, version lines | `common-library-project.mdc` |
+| Worktrees local only; versions in integrator docs | `worktrees.mdc` |
+| Multi-branch edits in one repo - use worktree, not checkout/stash | `multi-branch-worktrees.mdc` |
+
+Contributors (humans): README, CONTRIBUTING, MAINTAINERS, SECURITY, CHANGELOG.

CHANGELOG.md

@@ -1,16 +1,53 @@
 # Change Log/Revision History
 
-= 1.1.1 =
-=========
-- Converted to Maven
-- Changed dependencies to use Maven references
-
-= 1.1.0 =
-=======
-- updated the supplied nehta-smi-xsp library to the 1.2.0 version which supports Java 1.7_21+
-- deprecated use of verifySignature(Document,CertificateVerifier) in favour of verifySignature(Document,CertificateValidator)
-- changed Logging handler implementation to avoid XML transformations.
-
-= 1.0.4 =
-=======
-- modified WebServiceClient to add both com.sun.xml and com.sun.xml.internal binding for SSL factory
+# = 24.0.0 =
+
+- Maven **`au.gov.nehta:common-library`** **24.0.0** (Java **24** / **Jakarta**).
+- POM: **`maven.compiler.release` 24**; Jakarta XML APIs, **`jaxws-rt` 4.0.5**.
+- Sibling **`smi-xsp`** and **`smi-common-utils`** at **`${project.version}`** (**24.0.0**).
+- Enforcer requires JDK **24+**; **`maven-enforcer-plugin` 3.6.3**.
+- Same utility surface as **21.0.0** on Java **24** bytecode.
+
+# = 21.0.0 =
+
+- Maven **`au.gov.nehta:common-library`** **21.0.0** (Java **21** / **Jakarta**).
+- POM: **`maven.compiler.release` 21**; Jakarta XML APIs, **`jaxws-rt` 4.0.5**.
+- Sibling **`smi-xsp`** and **`smi-common-utils`** at **`${project.version}`** (**21.0.0**).
+- Enforcer requires JDK **21+**; **`maven-enforcer-plugin` 3.6.3**.
+- Same utility surface as **17.0.0** on Java **21** bytecode.
+
+# = 17.0.0 =
+
+- Maven **`au.gov.nehta:common-library`** **17.0.0** (Java **17** / **Jakarta**).
+- POM: **`maven.compiler.release` 17**; Jakarta XML APIs, **`jaxws-rt` 4.0.5**.
+- Sibling **`smi-xsp`** and **`smi-common-utils`** at **`${project.version}`** (**17.0.0**).
+- Enforcer requires JDK **17+**; **`maven-enforcer-plugin` 3.6.3**.
+- No unused direct **`xmlsec`** / **`slf4j`** declarations (arrive via siblings / runtime as needed).
+- **`smi-common-utils`** supplies **`JaxbUtils`** after **`smi-xsp`** dropped its unused copy.
+
+# = 11.0.0 =
+
+- Maven **`au.gov.nehta:common-library`** **11.0.0** (Java **11** / **Jakarta**).
+- POM: Jakarta XML APIs, **`jaxws-rt` 4.0.5**; declare bind/ws/soap APIs used by sources.
+- **`smi-xsp`** at **`${project.version}`** (**11.0.0**).
+- `TimeUtility` uses `java.time` (`DateTimeFormatter` / `LocalDateTime`) instead of `SimpleDateFormat`.
+- Drop unused test-only `xmlsec` / `slf4j` declarations (arrive via `smi-xsp` / runtime as needed).
+
+# = 1.2.3-SNAPSHOT =
+
+- Updated pom and deployed.
+
+# = 1.1.1 =
+
+- Converted to Maven.
+- Changed dependencies to use Maven references.
+
+# = 1.1.0 =
+
+- Updated the supplied nehta-smi-xsp library to the 1.2.0 version which supports Java 1.7_21+.
+- Deprecated use of `verifySignature(Document,CertificateVerifier)` in favour of `verifySignature(Document,CertificateValidator)`.
+- Changed Logging handler implementation to avoid XML transformations.
+
+# = 1.0.4 =
+
+- Modified WebServiceClient to add both com.sun.xml and com.sun.xml.internal binding for SSL factory.

CONTRIBUTING.md

@@ -1,41 +1,47 @@
-# How to contribute
+# Contributing
 
-Thanks for your interest in contributing to this project.
+**Audience:** developers building or changing **this repository**. Integrators should use **README.md** and Maven Central coordinates. See **SECURITY.md** before committing.
 
-You can find out a bit more about this project by reading the [README](README.md)
-file within this repository.
+## Prerequisites
 
-## Reporting issues
+- **JDK 24+** with **`JAVA_HOME`** set (see **`maven.compiler.release`** in **`pom.xml`**).
+- **Maven 3.6+** on **`PATH`**.
 
-Issues can be used to:
+Dependencies resolve from **[Maven Central](https://central.sonatype.com/)** unless you are installing a **local SNAPSHOT** (below). This POM has no sibling Maven modules.
 
-- Report a defect
-- Request a new feature or enhancement
-- Ask a question
+## Versioning
 
-New issues will be automatically populated with a template that highlights the
-information that needs to be submitted with an issue that describes a defect. If
-the issue is not related to a defect, please just delete the template and
-replace it with a detailed description of the problem you are trying to solve.
+The **first number** of **`au.gov.nehta:common-library`** is the **Java SE** version that this library targets. **24.0.0** targets Java **24** / **Jakarta**; **21.0.0** targets Java **21** / **Jakarta**; **17.0.0** targets Java **17** / **Jakarta**; **11.0.0** targets Java **11** / **Jakarta**; **8.0.0** uses **`javax`**. See **`README.md`**.
 
-## Creating a pull request
+## Build
 
-New pull requests within this project's repository are pre-populated with a
-checklist that describes the Definition of Done that we assess all new changes
-against. It is ok to submit a pull request that has not yet addressed all of
-these items, but be aware that the change will not be merged until it meets the
-Definition of Done.
+From the project root:
 
-Please communicate with us (preferably through creation of an issue) before
-embarking on any significant work within a pull request. This will prevent
-situations where people are working at cross-purposes.
+```text
+mvn -B "-Dgpg.skip=true" clean verify
+```
 
-## Code of conduct
+| Goal                                           | Command                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------- |
+| Compile + attach sources/Javadoc               | `mvn -B "-Dgpg.skip=true" clean verify`                    |
+| Skip tests                                     | `mvn -B "-Dgpg.skip=true" clean verify "-DskipTests=true"` |
+| Install SNAPSHOT to the local Maven repository | `mvn -B "-Dgpg.skip=true" clean install`                   |
 
-Before making a contribution, please read the
-[code of conduct](CODE_OF_CONDUCT.md).
+GPG signing is skipped by default (**`-Dgpg.skip=true`**). Release builds: **`-Dgpg.skip=false`**.
 
-## Contact us
+## Dependencies
 
-You can alo raise a query about this code, by emailing:
-[help@digitalhealth.gov.au](mailto:help@digitalhealth.gov.au)
+- Runtime SOAP stack: **`com.sun.xml.ws:jaxws-rt` 4.0.5** (plus declared Jakarta bind / WS / SOAP APIs).
+- Siblings **`au.gov.nehta:smi-common-utils`** and **`au.gov.nehta:smi-xsp`** at **`${project.version}`**.
+- Test: **`junit`**.
+
+## Local builds (unpublished artifacts)
+
+**`mvn install`** makes the SNAPSHOT resolvable for any local consumer of **`au.gov.nehta:common-library`** at **`${project.version}`**. Integrators using GA versions from Maven Central do not need a source checkout.
+
+Maintainer notes: **MAINTAINERS.md**.
+
+## Repository hygiene
+
+- **Do not commit** keystores, production endpoint URLs, populated **`settings.xml`** with release credentials, or generated build artefacts. See **SECURITY.md**.
+- **Line endings:** the repository uses **LF** (see **`.gitattributes`** if present). On **Windows**, run **`git config core.autocrlf false`** in your clone before committing.