Skip to content

Release 8.0.0 (Java 8) #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gavinbaumanis wants to merge 1 commit into
base: java-8
Choose a base branch
from
Open

Release 8.0.0 (Java 8) #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 38 additions & 9 deletions .cursor/rules/hi-b2b-project.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,61 @@ alwaysApply: true

# hi-b2b-client-java

Healthcare Identifiers (HI) B2B facade client — **not** MHR/PCEHR.
Healthcare Identifiers (HI) B2B facade client - **not** MHR/PCEHR.

## Release lines (integrator docs use Maven Central versions only)
## Documentation

Follow **`documentation-standards.mdc`**. Integrator docs use **version numbers** - not Git branch names.

The **first number** of the Maven version is the **Java SE** target. **`hi-b2b-client`** and **`hi-wsdl`** always share the **same** version.

| Version | Java | APIs | Facades |
| ------- | ---- | ---- | ------- |
| **1.6.3** | 8 | javax | **14** |
| **1.6.5** | 11 | Jakarta | **14** |
| **1.7.0** | 11 | Jakarta | **26** (full MCA) |
| **8.0.0** | 8 | **javax** | **14** (standard HI B2B) |
| **11.0.0.1** | 11 | **Jakarta** | **26** (full MCA) |
| **17.0.0.1** | 17 | **Jakarta** | **26** (full MCA) |
| **21.0.0.1** | 21 | **Jakarta** | **26** (full MCA) |
| **24.0.0.1** | 24 | **Jakarta** | **26** (full MCA) |

**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 checkout:** **`1.6.3-SNAPSHOT`** — **`au.gov.nehta:hi-wsdl`** from Maven Central (or matching **`mvn install`** for SNAPSHOT), Java **8** / **`javax.*`**.
## This 8.0.0 line

**`8.0.0-SNAPSHOT`**: Java **8**, **`javax`**, **14** facades, types from **`au.gov.nehta:hi-wsdl`** at **`${project.version}`** (no in-repo **`wsimport`**). See **MAINTAINERS.md**.

## Build from source

- JDK **8**: `mvn -B "-Dgpg.skip=true" clean verify`
- **Local / unpublished:** install **`hi-wsdl`** at **`${project.version}`** then **`verify`** — see **`CONTRIBUTING.md`**
- JDK **8**: `mvn -B "-Dgpg.skip=true" clean verify` (quote `-D` on PowerShell).
- **Local / unpublished:** install matching **`hi-wsdl`** then **`verify`** - see **`CONTRIBUTING.md`**
- **`jaxws-rt` 2.3.7**
- Default Surefire: offline tests; **`-Pintegration`** for mutual-TLS

## Consumer Search IHI

- `basicSearch` requires **IHI number**; demographics-only = `detailedSearch`.
- Messages `searchIHI`: `electronicCommunication` before `dateOfBirth`.
- Interface `searchIHI`: optional `electronicCommunication` before `dateOfBirth`; unstructured address before international.

## vs hi-wsdl-java

| | **hi-wsdl-java** | **hi-b2b-client-java** |
|---|---|---|
| Delivers | WSDL on classpath + generated types | Facade clients, TLS, signing |
| Artifact | `hi-wsdl` | `hi-b2b-client` |

Align **`hi-wsdl`** and **`hi-b2b-client`** at the **same version** per release line (**8.0.0** with **8.0.0**, **11.0.0.1** with **11.0.0.1**, and so on).

## Doc split

- **`documentation-standards.mdc`**: implementor-first, Maven Central default, local/OS sections, relative paths, no secrets
- **`README.md`**: integrators (Maven Central default)
- **`README.md`**, **`CLIENT-FEATURES.md`**: integrators (Maven Central default)
- **`CONTRIBUTING.md`**: build from source, local SNAPSHOT, OS wrappers
- **`MAINTAINERS.md`**: POM / dependency internals
22 changes: 8 additions & 14 deletions .cursor/rules/multi-branch-worktrees.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ description: Use git worktree when editing multiple branches of the same reposit
alwaysApply: true
---

# Multi-branch work — use git worktree
# 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 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-javax`, `java-11-jakarta`, `master`)
- 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

Expand All @@ -22,7 +22,7 @@ When a task requires **changes on two or more branches of the same Git repositor
## 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):
2. **Add a worktree per extra branch** (paths are local - never commit them to tracked docs):

```bash
git worktree add ../<repo>-<branch-slug> <branch>
Expand All @@ -34,18 +34,12 @@ When a task requires **changes on two or more branches of the same Git repositor
## 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`.
- 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
# In hi-wsdl-java primary clone (on java-11-jakarta-full-wsdl)
git worktree add ../hi-wsdl-java-java-8-javax java-8-javax
git worktree add ../hi-wsdl-java-java-11-jakarta java-11-jakarta

# Apply edits in each ../hi-wsdl-java-* folder; commit per branch
# When finished:
git worktree remove ../hi-wsdl-java-java-8-javax
git worktree remove ../hi-wsdl-java-java-11-jakarta
```
git worktree add <path> java-8
git worktree add <path> java-11
```
2 changes: 1 addition & 1 deletion .cursor/rules/worktrees.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Follow **`documentation-standards.mdc`** (implementor-first, Maven Central defau

| Doc | Audience | Use |
| --- | -------- | --- |
| **README**, integrator guides | Implementors | **Maven version** (`1.7.0`), Central coordinates, runtime config |
| **README**, integrator guides | Implementors | **Maven version** (`8.0.0`), Central coordinates, runtime config |
| **CONTRIBUTING** | Contributors | Build from source, **Local builds**, OS-specific steps |
| **MAINTAINERS**, **`.cursor/rules/`** | Maintainers | POM/wsimport internals; **branch mapping** only when labelled maintainer-only |

Expand Down
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
name: CI
on:
push:
branches: [ java-8 ]
pull_request:
branches: [ java-8 ]

permissions:
contents: read
Expand All @@ -13,7 +15,7 @@ jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v7
- uses: actions/setup-java@v5
with:
distribution: temurin
Expand Down
15 changes: 12 additions & 3 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,17 @@
# Change Log/Revision History

= 1.6.3-SNAPSHOT =
======
Changes not yet assigned to a numbered release; **`pom.xml`** **`<version>`** is **`1.6.3-SNAPSHOT`** until release **1.6.3** is tagged.
= 8.0.0 =
=======
- Maven **`au.gov.nehta:hi-b2b-client`** **8.0.0** (Java **8** / **`javax`**, **14** facade clients). Pair with **`hi-wsdl`** **8.0.0**. The first number of both Maven versions is the targeted Java SE version.
- **`common-library`** **8.0.0** (`nehta.lib.version` = **`${project.version}`**). **`smi-xsp`** **8.0.0** (`nehta.xsp.lib.version` = **`${project.version}`**).
- **`HiRequestElementOrderParityTest`**: asserts JAXB `propOrder` for Messages `searchIHI` (`electronicCommunication` before `dateOfBirth`), Interface inquiry `searchIHI`, and batch `SearchIHIRequestType`. See **`wsdls/readme.txt`**.
- IHI sync batch and HPI batch-async facades reject a null request (and a null per-request user id) with **`IllegalArgumentException`**.
- **`BaseClient_3`** constructor names the signing-certificate argument **`signingCertificate`**.
- README: IHI **sync** batch (`SearchBatch.ArgumentValidator`) uses the same search-field rules as `ConsumerSearchIHIClient`.

= 1.6.3 =
=========
Historical past release (superseded by **8.0.0** on this line).

- Root license file renamed to **`LICENSE.md`** (Apache 2.0 canonical text plus ADHA production disclaimer); references updated from **`LICENSE.txt`**.
- **`hi-wsdl`** at **`hi.wsdl.version`** = **`${project.version}`** (SNAPSHOT locally; GA **`1.6.3`** pair on Maven Central); **`javax.*`** / Java **8** bytecode in generated types; default lifecycle does not run **`wsimport`**. Batch Search IHI types use **`au.net.electronichealth.ns.hi.xsd.consumermessages.*`** packages from **`hi-wsdl`**; tests use **`String`** country codes (no **`CountryType`** enum on this stub line).
Expand Down
217 changes: 217 additions & 0 deletions CLIENT-FEATURES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
# HI B2B Client - feature overview

Broad list of what you can do with **`au.gov.nehta:hi-b2b-client`**: typed Java facades over Australia's **Healthcare Identifiers (HI) Service** (SOAP/JAX-WS). Operation details and field rules are in ADHA specs and Javadoc; this document maps **library surface -> capability**.

**Audience:** integrators choosing APIs for **`8.0.0`** (**14** facade classes). Setup (Maven Central dependency, keystores, endpoints) is in **`README.md`**.

Full MCA coverage (**26** facades, **Jakarta**) is available from **11.0.0.1** onward (**17.0.0.1**, **21.0.0.1**, **24.0.0.1**, and later). See **`README.md`** **Versioning** before assuming a class exists in your version.

---

## What the library gives you

| Capability | How |
| ---------- | --- |
| Call HI SOAP operations from Java | One facade class per WSDL service (see tables below) |
| Mutual TLS to HI endpoints | Pass `SSLSocketFactory` (often from PKCS#12 via `KeystoreUtil`) |
| Sign outbound SOAP; verify inbound | `HISecurityHandler` on every facade (`ClientBase`) |
| HI SOAP headers (product, user, org, timestamps) | `HIHeaderHandler` + constructors on `BaseClient_3` |
| Resolve licensed WSDL/XSD at runtime | `HiWsdlArtifactRoot` (env, system property, `local.properties`, or `setRoot`) |
| Optional SOAP message logging | `LoggingHandler` |
| Request payload guardrails | Per-operation `ArgumentValidator` / `SearchBatch` before SOAP |
| Per-call user identity override | Many clients expose overloads with `QualifiedId` per request |
| Example wiring | `src/sample/java/.../hi/sample/*` (not on default classpath) |

You still need ADHA/Services Australia **registration**, **certificates**, **product metadata (PCIN)**, and **endpoint URLs** for live calls.

---

## Individual Healthcare Identifier (IHI)

Package: `au.gov.nehta.vendorlibrary.hi.ihi`.

### Search (single request)

**`ConsumerSearchIHIClient`** - find/validate an individual's IHI. Client methods enforce which `SearchIHI` fields may be set.

| Method | Typical use |
| ------ | ----------- |
| `basicSearch` | Lookup by **IHI number** (+ demographics) |
| `basicMedicareSearch` | Lookup by **Medicare card number** (+ demographics) |
| `basicDvaSearch` | Lookup by **DVA file number** (+ demographics) |
| `detailedSearch` | **Demographics only** (no IHI, Medicare, DVA, or address blocks) |
| `australianPostalAddressSearch` | Demographics + Australian postal address |
| `australianStreetAddressSearch` | Demographics + Australian street address |
| `internationalAddressSearch` | Demographics + international address |

Common mandatory demographics: family name, date of birth, sex (given name optional). **`basicSearch` requires an IHI number**; demographics-only lookup must use **`detailedSearch`**, not `basicSearch`.

### Search (batch)

| Class | What you can do |
| ----- | ---------------- |
| **`ConsumerSearchIHIBatchSyncClient`** | Submit many IHI searches in **one synchronous** batch (`batchSearch` + `SearchBatch` helper) |
| **`ConsumerSearchIHIBatchAsyncClient`** | **Submit** batch (`submitSearchIHIBatch`), **poll status** (`getSearchIHIBatchStatus`), **retrieve results** (`retrieveSearchIHIBatch`), **delete** batch (`deleteSearchIHIBatch`) |

`SearchBatch` supports the same search shapes as sync batch (basic, Medicare, DVA, detailed, address variants) with the same field rules as single search.

### Create, update, merge, resolve (lifecycle)

| Class | Operation (SOAP) | Purpose (high level) |
| ----- | ------------------ | --------------------- |
| **`ConsumerCreateProvisionalIHIClient`** | Create provisional IHI | Allocate provisional identifier |
| **`ConsumerUpdateProvisionalIHIClient`** | Update provisional IHI | Change provisional record |
| **`ConsumerMergeProvisionalIHIClient`** | Merge provisional IHI | Combine provisional with existing IHI |
| **`ConsumerResolveProvisionalIHIClient`** | Resolve provisional IHI | Finalise provisional -> active IHI |
| **`ConsumerCreateUnverifiedIHIClient`** | Create unverified IHI | Create unverified identifier |
| **`ConsumerCreateVerifiedIHIClient`** | Create verified IHI | Create verified identifier |
| **`ConsumerUpdateIHIClient`** | Update IHI | Update active IHI demographics/details |

### Notifications to HI Service

| Class | Operation | Purpose (high level) |
| ----- | --------- | --------------------- |
| **`ConsumerNotifyDuplicateIHIClient`** | Notify duplicate IHI | Report duplicate IHI situation |
| **`ConsumerNotifyReplicaIHIClient`** | Notify replica IHI | Report replica IHI situation |

Exact payloads and business rules are defined by HI Service specifications, not this library.

---

## Healthcare Provider Identifier - Individual (HPI-I)

Package: `au.gov.nehta.vendorlibrary.hi.hpii`.

| Class | Methods / capability |
| ----- | -------------------- |
| **`ProviderSearchForProviderIndividualClient`** | `identifierSearch`, `demographicSearch` - find provider individuals in HI |
| **`ProviderSearchHIProviderDirectoryForIndividualClient`** | `identifierSearch`, `demographicSearch` - search **HI Provider Directory** for individuals |
| **`SearchForProviderIndividualBatchAsyncClient`** | `submitSearch`, `retrieveSearch` - **async batch** provider-individual search |
| **`ProviderSearchTdsProviderIndividualClient`** | `searchTdsProviderIndividual` - search **TDS** (terminated/deactivated) provider individuals |
| **`ProviderManageTdsProviderIndividualClient`** | `manageTdsProviderIndividual` - manage TDS provider individual records |

---

## Healthcare Provider Identifier - Organisation (HPI-O)

Package: `au.gov.nehta.vendorlibrary.hi.hpio`.

### Search and directory

| Class | Methods / capability |
| ----- | -------------------- |
| **`ProviderSearchForProviderOrganisationClient`** | `identifierSearch` - find organisations by identifier |
| **`ProviderSearchHIProviderDirectoryForOrganisationClient`** | `identifierSearch`, `demographicSearch` - HI Provider Directory for organisations |
| **`SearchForProviderOrganisationBatchAsyncClient`** | `submitSearch`, `retrieveSearch` - async batch organisation search |

### Read

| Class | Operation | Purpose (high level) |
| ----- | --------- | --------------------- |
| **`ProviderReadProviderOrganisationClient`** | `readProvider` | Read organisation (HPI-O) details |
| **`ProviderReadAdministrativeIndividualClient`** | `readProviderAdministrativeIndividual` | Read administrative individual linked to provider context |

### Manage (mutating operations)

Payloads use HI "manage" request types (create/update/deactivate etc. per spec). Facades pass them through after optional validation.

| Class | Operation |
| ----- | --------- |
| **`ProviderManageProviderOrganisationClient`** | `manageProviderOrganisation` |
| **`ProviderManageProviderDirectoryEntryClient`** | `manageProviderDirectoryEntry` |
| **`ProviderManageProviderAdministrativeIndividualClient`** | `manageProviderAdministrativeIndividual` |

---

## Reference data

Package: `au.gov.nehta.vendorlibrary.hi.readreferencedata`.

| Class | Capability |
| ----- | ---------- |
| **`ReadReferenceDataClient`** | `readReferenceData` - fetch current allowed code lists from HI (e.g. provider type, speciality, organisation type, organisation service, operating system). Request lists **element names**; response returns acceptable values. |

---

## Cross-cutting integration patterns

### Constructing any facade

Typical constructor inputs:

- HI **endpoint URL** (cert vs production from registration)
- **`SSLSocketFactory`** for mutual TLS
- **Signing** private key + X.509 certificate (SOAP XML signature)
- **Product** header (`ProductType` / wrapped variant) - PCIN
- **Qualified user ID** (and sometimes **organisation qualified ID** for contracted service providers)
- Optional **`CertificateValidator`** for inbound signature trust

### Security and transport stack

- TLS client authentication via your socket factory
- Outbound signing of SOAP body and required header elements; inbound signature verification
- Stripping of `wsa:FaultTo` on outbound messages (Medicare/HI interoperability)
- Optional omission of HPI-O CSP header when no organisation qualified ID is configured

### WSDL and generated types

- Published JAR does **not** include licensed WSDL/XSD; you supply the ADHA bundle at runtime (`wsdl/` + `schema/` under one root). See **`README.md`** and **`wsdls/README.md`**.
- JAXB/JAX-WS types for requests/responses are generated at library build time from that bundle; your app uses those types in method arguments.

### Helpers in other packages

| Area | Examples |
| ---- | -------- |
| `au.gov.nehta.vendorlibrary.common.security` | `KeystoreUtil` - load keys/certs for TLS and signing |
| `au.gov.nehta.vendorlibrary.ws` | `WebServiceClientUtil`, `TimeUtility` |
| `au.gov.nehta.vendorlibrary.hi.wsdl` | `HiWsdlArtifactRoot` |
| `au.gov.nehta.vendorlibrary.hi.client.wrapped` | Wrapped `QualifiedId`, `ProductType` for simpler construction |

### Errors

Service faults surface as generated **`StandardErrorMsg`** (and related) types from the HI WSDL; handle in application code like any SOAP fault.

---

## Learning and verification

| Resource | Content |
| -------- | ------- |
| **`README.md`** | Dependency, WSDL root, config keys, search IHI rules summary |
| **`src/sample/java`** | Runnable-style examples for search IHI, batch sync, reference data, directory search, read/manage org |
| **Javadoc** | Attached to releases on Maven Central |
| **`CONTRIBUTING.md`** | Build, offline vs `-Pintegration` tests |
| **ADHA implementer portal** | Registration, certificates, authoritative operation specs |

---

## Quick index - all facade classes (**11.0.0.1** and later)

| # | Class |
| - | ----- |
| 1 | `ConsumerSearchIHIClient` |
| 2 | `ConsumerSearchIHIBatchSyncClient` |
| 3 | `ConsumerSearchIHIBatchAsyncClient` |
| 4 | `ConsumerCreateProvisionalIHIClient` |
| 5 | `ConsumerUpdateProvisionalIHIClient` |
| 6 | `ConsumerMergeProvisionalIHIClient` |
| 7 | `ConsumerResolveProvisionalIHIClient` |
| 8 | `ConsumerCreateUnverifiedIHIClient` |
| 9 | `ConsumerCreateVerifiedIHIClient` |
| 10 | `ConsumerUpdateIHIClient` |
| 11 | `ConsumerNotifyDuplicateIHIClient` |
| 12 | `ConsumerNotifyReplicaIHIClient` |
| 13 | `ProviderSearchForProviderIndividualClient` |
| 14 | `ProviderSearchHIProviderDirectoryForIndividualClient` |
| 15 | `SearchForProviderIndividualBatchAsyncClient` |
| 16 | `ProviderSearchTdsProviderIndividualClient` |
| 17 | `ProviderManageTdsProviderIndividualClient` |
| 18 | `ProviderSearchForProviderOrganisationClient` |
| 19 | `ProviderSearchHIProviderDirectoryForOrganisationClient` |
| 20 | `SearchForProviderOrganisationBatchAsyncClient` |
| 21 | `ProviderReadProviderOrganisationClient` |
| 22 | `ProviderReadAdministrativeIndividualClient` |
| 23 | `ProviderManageProviderOrganisationClient` |
| 24 | `ProviderManageProviderDirectoryEntryClient` |
| 25 | `ProviderManageProviderAdministrativeIndividualClient` |
| 26 | `ReadReferenceDataClient` |
Loading
Loading