From 699266047e250687a8454adf3674a8424416e803 Mon Sep 17 00:00:00 2001 From: Gavin Baumanis Date: Tue, 25 Aug 2026 15:03:39 +1000 Subject: [PATCH] Release 8.0.0: Java 8 / javax --- .cursor/rules/common-library-project.mdc | 48 ++++++++++ .cursor/rules/documentation-standards.mdc | 50 ++++++++++ .cursor/rules/multi-branch-worktrees.mdc | 45 +++++++++ .cursor/rules/worktrees.mdc | 37 ++++++++ AGENTS.md | 16 ++++ CHANGELOG.md | 32 +++++-- CONTRIBUTING.md | 75 +++++++++------ LICENSE.txt | 51 +++++----- MAINTAINERS.md | 110 ++++++++++++++++++++++ README.md | 108 ++++++++++++--------- SECURITY.md | 16 ++++ pom.xml | 68 +++++++++---- settings.xml.example | 28 ++++++ 13 files changed, 561 insertions(+), 123 deletions(-) create mode 100644 .cursor/rules/common-library-project.mdc create mode 100644 .cursor/rules/documentation-standards.mdc create mode 100644 .cursor/rules/multi-branch-worktrees.mdc create mode 100644 .cursor/rules/worktrees.mdc create mode 100644 AGENTS.md create mode 100644 MAINTAINERS.md create mode 100644 SECURITY.md create mode 100644 settings.xml.example diff --git a/.cursor/rules/common-library-project.mdc b/.cursor/rules/common-library-project.mdc new file mode 100644 index 0000000..18dd89a --- /dev/null +++ b/.cursor/rules/common-library-project.mdc @@ -0,0 +1,48 @@ +--- +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.1** | 11 | **Jakarta** | +| **17.0.0.1** | 17 | **Jakarta** | +| **21.0.0.1** | 21 | **Jakarta** | +| **24.0.0.1** | 24 | **Jakarta** | + +**Git branch mapping (maintainers only - never in integrator docs):** + +| Version | Official Git branch | +| ------- | ------------------- | +| **8.0.0** | `java-8` | +| **11.0.0.1** | `java-11` | +| **17.0.0.1** | `java-17` | +| **21.0.0.1** | `java-21` | +| **24.0.0.1** | `java-24` | + +## This 8.0.0 line + +**`8.0.0-SNAPSHOT`**: Java **8**, **`javax`** XML APIs, **`jaxws-rt` 2.3.7**. Compile depends on **`au.gov.nehta:smi-xsp`** at **`${project.version}`**. + +## Build + +- JDK **8+**, from repo root: `mvn -B "-Dgpg.skip=true" clean verify` (quote `-D` on PowerShell). +- Local unpublished builds: install **`smi-xsp`** **8.0.0** / **`${project.version}`** first, then this library. + +## 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 diff --git a/.cursor/rules/documentation-standards.mdc b/.cursor/rules/documentation-standards.mdc new file mode 100644 index 0000000..778c751 --- /dev/null +++ b/.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). diff --git a/.cursor/rules/multi-branch-worktrees.mdc b/.cursor/rules/multi-branch-worktrees.mdc new file mode 100644 index 0000000..aa0018b --- /dev/null +++ b/.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 :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 ../- + ``` + +3. **Edit and commit in each worktree** independently; verify build/tests per branch. +4. **Remove when done**: `git worktree remove ../-` (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 java-8 +git worktree add java-11 +``` diff --git a/.cursor/rules/worktrees.mdc b/.cursor/rules/worktrees.mdc new file mode 100644 index 0000000..7cc5d7a --- /dev/null +++ b/.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** (`8.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 ` (placeholder **``**, 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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..39ec5f6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# Cursor agents + +Rules: `.cursor/rules/*.mdc`. Do not duplicate in README or CONTRIBUTING. + +| Concern | Rule | +|---------|------| +| 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. + +## Copyright + +Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8907702..a2db882 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,16 +1,32 @@ # Change Log/Revision History += 8.0.0 = +======= +- Maven **`au.gov.nehta:common-library`** **8.0.0** (Java **8** / **`javax`**). The first number of the Maven version is the targeted Java SE version. +- Compile dependency **`au.gov.nehta:smi-xsp`** at **`${project.version}`** (**8.0.0**). +- POM: Eclipse EE4J stack alignment - **`jaxws-rt` 2.3.7**; **`maven-enforcer-plugin`** bans legacy Metro **`webservices-*`** bundles. +- Build plugins and dependency versions updated to latest Java **8**-compatible releases. +- Version aligned with the HI/MHR client release lines (`8.0.0`). + += 1.2.3-SNAPSHOT = +======= +- Updated pom and deployed. + = 1.1.1 = ========= -- Converted to Maven -- Changed dependencies to use Maven references +- 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. +========= +- 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 \ No newline at end of file +========= +- Modified WebServiceClient to add both com.sun.xml and com.sun.xml.internal binding for SSL factory. + +## Copyright + +Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5b9a08..b2860fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,60 @@ -# 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 8+** 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. **8.0.0** targets Java **8** / **`javax`**; **11.0.0.1** and later use **Jakarta**. 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) +- Compile: **`com.sun.xml.ws:jaxws-rt`** **2.3.7**, **`au.gov.nehta:smi-xsp`** at **`${project.version}`** (**8.0.0** / **`8.0.0-SNAPSHOT`**). +- Test: **`junit`**, **`org.apache.santuario:xmlsec`**, **`org.slf4j:slf4j-api`** / **`slf4j-simple`**. + +## Local builds (unpublished artifacts) + +Install matching **`smi-xsp`** first (same Java line: **`8.0.0-SNAPSHOT`**), then this library: + +```text +# in smi-xsp-java +mvn -B "-Dgpg.skip=true" clean install + +# in common-library-java +mvn -B "-Dgpg.skip=true" clean install +``` + +**`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. + +## Copyright + +Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/LICENSE.txt b/LICENSE.txt index 2bb02e8..d37530a 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,28 +1,31 @@ -Australian Digital Health Agency Production Disclaimer - +NEHTA (as Licensor) grants You a licence to this Product subject to +the terms of the Apache Licence (version 2.0), a copy of which is +available at http://www.apache.org/licenses/LICENSE-2.0, and the +following terms. -The Australian Digital Health Agency (as Licensor) grants You a -licence to this Product subject to the terms of the Apache Licence -(version 2.0), a copy of which is available at -http://www.apache.org/licenses/LICENSE-2.0, and the following terms. - -This Product licensed under the Apache Licence and these terms may -be used within production software systems. It nevertheless remains -your responsibility to test and validate the use of this product -within your software and the limitation of liability provisions in -clause 8 of the Apache Licence continue to apply. +This Product licensed under the Apache Licence and these terms is +not at a production stage and is accordingly licensed for +non-production use only. This Product should in no circumstance be +used for the processing of personal or patient data in a clinical +or operational setting, or in the provision of medical or +therapeutic advice or treatment in a clinical or operational +setting. In addition to clause 4(a) of the Apache Licence, You +must provide a copy of these terms to a recipient of any Work or +Derivative Works in addition to the Apache Licence to the extent +that NEHTA is a Contributor in respect of those Works or Derivative +Works. -Despite clause 7 of the Apache Licence, if a condition or warranty -is implied by statute or law that cannot be excluded, then the -liability of a Contributor to the extent that it has contributed to -a breach of that condition or warranty is limited to one or more of -the following at its option: (a) in the case of goods, any one of -the following: the replacement of those goods or the re-supply of -equivalent goods; the repair of those goods; the payment of the -cost of replacing those or acquiring equivalent goods; or the -payment of the cost of having those goods repaired; and (b) in the -case of services: the supplying of those services again; or the +Despite clause 7 of the Apache Licence, if a condition or warranty +is implied by statute or law that cannot be excluded, then the +liability of a Contributor to the extent that it has contributed to +a breach of that condition or warranty is limited to one or more of +the following at its option: (a) in the case of goods, any one of +the following: the replacement of those goods or the re-supply of +equivalent goods; the repair of those goods; the payment of the +cost of replacing those or acquiring equivalent goods; or the +payment of the cost of having those goods repaired; and (b) in the +case of services: the supplying of those services again; or the payment of the cost of having those services supplied again. - -A term which is given a meaning in the Apache Licence, has the same -meaning when used in these terms. +A term which is given a meaning in the Apache Licence, has the same +meaning when used in these terms. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..03a79a3 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,110 @@ +# Maintainer notes + +**Audience:** people changing the **`common-library`** build, source, or release process - not library integrators. Integrators should use **README.md**, published Javadoc, and **`pom.xml`** coordinates. + +Paths are relative to the repository root (directory containing **`pom.xml`**). + +## Versioning + +The **first number** of **``** is the **Java SE** target of **this** library. + +| Maven version | Java SE | +| ------------- | ------- | +| **8.0.0** | **8** | +| **11.0.0.1** | **11** | +| **17.0.0.1** | **17** | +| **21.0.0.1** | **21** | +| **24.0.0.1** | **24** | + +**Documentation convention:** README, CONTRIBUTING, CHANGELOG, and integrator-facing text use **version numbers only** - never Git branch names. + +| Version | Java | XML APIs | +| ------- | ---- | -------- | +| **8.0.0** | 8 | **`javax.xml.ws`**, **`javax.xml.bind`** (via `jaxws-rt` 2.3.7) | +| **11.0.0.1** | 11 | **Jakarta** XML WS / Bind | +| **17.0.0.1** | 17 | **Jakarta** XML WS / Bind | +| **21.0.0.1** | 21 | **Jakarta** XML WS / Bind | +| **24.0.0.1** | 24 | **Jakarta** XML WS / Bind | + +**Git branch mapping (maintainers / checkout only - do not use in integrator docs):** + +| Version | Official Git branch | +| ------- | ------------------- | +| **8.0.0** | `java-8` | +| **11.0.0.1** | `java-11` | +| **17.0.0.1** | `java-17` | +| **21.0.0.1** | `java-21` | +| **24.0.0.1** | `java-24` | + +Artifact id stays **`common-library`**; the version distinguishes the Java SE line. + +On a given branch, **do not change the first number** of **``**. Next GA on **`java-8`** is **`8.0.0.2`** (then **`8.0.1-SNAPSHOT`**), not **`11.x`**. A new Java SE target is a **new branch**, not a bump on this one. + +**This checkout (`8.0.0-SNAPSHOT`):** Java **8**, **`javax`** XML APIs, **`jaxws-rt` 2.3.7**. + +## Artifact + +- **`au.gov.nehta:common-library`** - shared utility classes for CDA package operations, argument validation, and web-service helpers used by other ADHA/NEHTA libraries. + +## Contributors vs release publisher (`pom.xml`) + +**Contributors (PRs, ordinary commits):** Do not change **``** (stay on **`-SNAPSHOT`** unless the maintainer requests a bump), **``**, or **`distributionManagement`**. If a maintainer requests a SNAPSHOT bump on this branch, change only the trailing numbers (**`8.0.1-SNAPSHOT`**), never the Java SE digit. Leave **`maven-gpg-plugin`** **`skip`** **`true`** so default **`mvn verify`** does not require a signing key. Record user-visible work under **`CHANGELOG.md`** in the **`= =`** block that matches **`pom.xml`** **``**. + +**Release publisher:** In the release change set: set **``** to the GA coordinate (no **`-SNAPSHOT`**); set **``** to the Git tag you will publish (match existing tag naming). Move **`CHANGELOG.md`** bullets from the snapshot section into a new **`= =`** section; add a fresh **`-SNAPSHOT`** block for the next development cycle. Deploy via Sonatype Central Portal (**`central-publishing-maven-plugin`**; copy **`settings.xml.example`** -> **`settings.xml`**, server id **`central`**). See **Release** below. + +## Release + +Publishing uses **`central-publishing-maven-plugin`** (Sonatype Central Portal). Copy **`settings.xml.example`** -> **`settings.xml`**, server id **`central`**. + +**Parallel release lines (maintainers only):** each Git branch of **this** repository publishes a **different Maven version** of **`common-library`**. Integrators choose by coordinate, not branch name. The first number of that version is the targeted Java SE version. Run **`release:prepare` / `release:perform`** (or manual deploy) **on that branch** (not detached HEAD). + +| Branch | Java | `common-library` | +| ------ | ---- | ---------------- | +| **`java-8`** | 8 / javax | **8.0.0** | +| **`java-11`** | 11 / Jakarta | **11.0.0.1** | +| **`java-17`** | 17 / Jakarta | **17.0.0.1** | +| **`java-21`** | 21 / Jakarta | **21.0.0.1** | +| **`java-24`** | 24 / Jakarta | **24.0.0.1** | + +**`-DdevelopmentVersion`:** keep the same first number as **`-DreleaseVersion`** (example on this line: **`8.0.0`** then **`8.0.1-SNAPSHOT`**). + +### SNAPSHOT or manual GA + +1. Update **CHANGELOG.md** (and **`pom.xml`** / SCM **``** for manual GA). +2. **`mvn -B "-Prelease" clean verify`** +3. **`mvn -B "-Prelease" deploy`** + +Git/SCM settings for **`maven-release-plugin`** live in **`pom.xml`** properties (**`scm.repo.url`**, **`release.*`**). Tags default to **`{artifactId}-{version}`** (e.g. **`common-library-8.0.0`**). + +### Automated GA (`maven-release-plugin`) + +Run on the **target branch** with a **clean** working tree. + +```text +mvn -B "-Prelease" release:prepare release:perform -DreleaseVersion=8.0.0 -DdevelopmentVersion=8.0.1-SNAPSHOT -Dtag=common-library-8.0.0 +``` + +Replace **`-DreleaseVersion`**, **`-DdevelopmentVersion`**, and **`-Dtag`** for the branch you are on (same first number; e.g. **`common-library-11.0.0.1`** on **`java-11`**). + +**After success:** confirm **`common-library`** GA on Central. Downstream artifacts that depend on this coordinate can then cut their matching GA. + +**`-Dgpg.skip=false`** is equivalent to **`-Prelease`** for signing. + +## Changelog and releases + +**`CHANGELOG.md`** uses **`= version =`** section headers. Match the snapshot header to **`pom.xml`** **``** until the publisher cuts GA. + +## New Java SE line + +When adding a line (e.g. Java **25**): create **`java-25`** in **this** repository from the nearest existing line; set **``** first number to **25** (e.g. **`25.0.0.1-SNAPSHOT`**); set **`maven.compiler.release`**, JAX-WS / JAXB coordinates, CI **`java-version`** / branch filter, and docs to that line. Do not retarget an existing branch. + +## Build (`8.0.0` line) + +- **`maven.compiler.release` 8** +- Runtime SOAP stack: **`com.sun.xml.ws:jaxws-rt` 2.3.7** in **consuming** applications +- **`maven-gpg-plugin`:** skipped unless **`-Dgpg.skip=false`** +- **`maven-javadoc-plugin`:** **`doclint=none`**, **`verbose=false`**, **`detectOfflineLinks=false`**, **`source=8`** + +## Copyright + +Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/README.md b/README.md index c94655a..b02a6ba 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,87 @@ # Common Library -This is a Java software library that supports producing, validating and extracting clinical packages as documented in the "CDA Package" specification. -Setup -===== -- To build and test the distributable package, an appropriate Java IDE or - build environment must be installed. +Maven artifact **`au.gov.nehta:common-library`** - shared Java utility classes for CDA package operations, argument validation, and web-service helpers used by other ADHA/NEHTA libraries. -- Java source files can be found in: - common-library-java--sources.jar +## Dependency -- For detailed API documentation, refer to the included Javadoc package. +Published releases are consumed from **[Maven Central](https://central.sonatype.com/)**. Use a **``** that matches your JDK (see **Versioning**). -Solution -===== +```xml + + au.gov.nehta + common-library + 8.0.0 + +``` -The package consists of these components: +**This line (`8.0.0`):** Java **8**, **`javax.xml.ws`** / **`javax.xml.bind`** via **`jaxws-rt` 2.3.7**. - - /common-library-java-.jar - Contains the required classes for package operations. +--- - - /common-library-java--docs.jar - Contains Javadoc documentation. +## Versioning - - /common-library-java--sources.jar - Contains library source files. +The **first number** of the Maven version is the **Java SE** version that this library targets. -Pre-Requisites -===== +| Maven version | Java SE | XML stack | +| ------------- | ------- | --------- | +| **8.0.0** | **8** | **`javax.*`** / EE4J **`jaxws-rt` 2.3.x** at runtime in consumers | +| **11.0.0.1** | **11** | **Jakarta** / EE4J **`jaxws-rt` 4.0.x** at runtime in consumers | +| **17.0.0.1** | **17** | **Jakarta** / EE4J **`jaxws-rt` 4.0.x** at runtime in consumers | +| **21.0.0.1** | **21** | **Jakarta** / EE4J **`jaxws-rt` 4.0.x** at runtime in consumers | +| **24.0.0.1** | **24** | **Jakarta** / EE4J **`jaxws-rt` 4.0.x** at runtime in consumers | -Java Development Kit (JDK) ------ -Follow the usual instructions for installing a JDK, or the instructions below. +Pick the coordinate that matches your JDK. All published versions are on **[Maven Central](https://central.sonatype.com/)**. - 1. Download and install JDK 8 Update 271 or later: +--- - URL: https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html +## Local development (SNAPSHOT) - 2. Unpack the JDK distribution into a directory of your choice. +This repository builds **`8.0.0-SNAPSHOT`**. Compile depends on **`au.gov.nehta:smi-xsp`** at **`${project.version}`** (**8.0.0** / **`8.0.0-SNAPSHOT`**). Install unpublished **`smi-xsp`** first when that coordinate is not on Central, then install this library: - This directory will be your and will be used in this document - to refer to the root directory of the JDK installation. +```text +# smi-xsp-java (same Maven version as this pom.xml) +mvn -B "-Dgpg.skip=true" clean install - will be used in this document to refer to /jre. +# common-library-java +mvn -B "-Dgpg.skip=true" clean install +``` - 3. Create a JAVA_HOME environment variable pointing to the - directory in Step 2. +If Maven warns that a **GA** POM is missing, clear stale **`au/gov/nehta/common-library`** or **`au/gov/nehta/smi-xsp`** entries in your local Maven repository (folders with only **`.lastUpdated`** files) and reinstall the SNAPSHOT. - 4. Add /bin to the system path. +## Building from source -Licensing -===== -Copyright 2012 NEHTA +**Audience:** contributors changing this repository - not integrators adding a Maven dependency. -Copyright 2021 ADHA +Prerequisites: **JDK 8+**, **Maven 3.6+**. -Licensed under the NEHTA/ADHA Open Source (Apache) License; you may not use this -file except in compliance with the License. A copy of the License is in the -'LICENSE.txt' file, which should be provided with this work. +```text +mvn -B "-Dgpg.skip=true" clean verify +``` -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -License for the specific language governing permissions and limitations -under the License. +See **`CONTRIBUTING.md`** for **`mvn install`** when testing unpublished snapshots locally. + +## Related repositories + +| Repository | Role | +| ---------- | ---- | +| [hi-b2b-client-java](https://github.com/AuDigitalHealth/hi-b2b-client-java) | HI facade clients (depends on this artifact) | +| [mhr-b2b-client-java](https://github.com/AuDigitalHealth/mhr-b2b-client-java) | MHR facades (depends on this artifact) | + +## Documentation + +| Document | Audience | +| -------- | -------- | +| **README.md** (this file) | Integrators | +| **CONTRIBUTING.md** | Contributors | +| **MAINTAINERS.md** | Releases and tooling | +| **SECURITY.md** | Secrets and credentials | +| **CHANGELOG.md** | Release history | +| **LICENSE.txt** | Apache License 2.0 + ADHA terms | + +## License + +Apache License 2.0. See **LICENSE.txt**. + +## Copyright + +Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..8e741bc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,16 @@ +# Security + +## Reporting issues + +Report security-sensitive findings through your organisation's usual channel for **ADHA / AuDigitalHealth** repositories (do not open a public issue with exploit details before it is triaged). + +## This repository + +- **Do not commit secrets to git.** That includes passwords, API tokens, private keys, real mutual-TLS keystores, production or staging endpoint URLs with embedded credentials, and Services Australia / vendor registration material - even inside comments, test fixtures, or tracked documentation. +- **`local.properties`** is gitignored. Never commit real credentials or keystores. +- **`settings.xml`** at the repository root is gitignored when it contains release credentials; do not commit populated copies. Use **`settings.xml.example`** as the template (server id **`central`**). +- In property files, prefer **forward slashes** in filesystem paths so the same values work on **Windows**, **macOS**, and **Linux**. + +## Copyright + +Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/pom.xml b/pom.xml index af683d9..8772e37 100644 --- a/pom.xml +++ b/pom.xml @@ -9,7 +9,7 @@ au.gov.nehta common-library - 1.2.3-SNAPSHOT + 8.0.0-SNAPSHOT ADHA/NEHTA Common Library Java classes for common code used by other ADHA/NEHTA libraries https://github.com/AuDigitalHealth/common-library-java @@ -98,7 +98,8 @@ 3.6.1 3.2.8 0.8.14 - 1.2.1 + + ${project.version} 3.6.2 ${project.version} @@ -113,6 +114,51 @@ com.sun.xml.ws jaxws-rt ${ee4j.jaxws.version} + + + jakarta.xml.bind + jakarta.xml.bind-api + + + jakarta.xml.ws + jakarta.xml.ws-api + + + jakarta.xml.soap + jakarta.xml.soap-api + + + jakarta.jws + jakarta.jws-api + + + jakarta.annotation + jakarta.annotation-api + + + com.sun.activation + jakarta.activation + + + com.sun.mail + jakarta.mail + + + + + javax.xml.bind + jaxb-api + 2.3.1 + + + javax.xml.ws + jaxws-api + 2.3.1 + + + javax.xml.soap + javax.xml.soap-api + 1.4.0 au.gov.nehta @@ -126,24 +172,6 @@ ${junit.version} test - - org.apache.santuario - xmlsec - 2.2.1 - test - - - org.slf4j - slf4j-api - 1.7.7 - test - - - org.slf4j - slf4j-simple - 1.7.30 - test - diff --git a/settings.xml.example b/settings.xml.example new file mode 100644 index 0000000..fee3e9f --- /dev/null +++ b/settings.xml.example @@ -0,0 +1,28 @@ + + + + +