Add compiled sources for the 1.2 Wiki samples by kevinherron · Pull Request #2094 · eclipse-milo/milo

kevinherron · 2026-10-04T20:21:47Z

The 1.2 user guide now lives on the GitHub Wiki. Its Java samples need a home where the build compiles them, so that an API change which breaks a sample fails here instead of leaving broken code in the Wiki. This PR adds that home and moves the user-facing parts of the source feature guides to the Wiki.

Wiki samples

milo-examples/wiki-examples is a new module. Like the other examples, it is not deployed.

FirstServer and FirstClient are the complete programs from the first-server and first-client tutorials. FirstServer publishes a small thermostat, a Thermostat Object with a read-only Temperature, a writable Setpoint, and an AdjustSetpoint Method. The client and server guides use it as their running example, and the server pages show regions of FirstServer. FirstProgramsTest checks the thermostat behaviors the Wiki states: reads, writes and their failure statuses, browsing, and AdjustSetpoint results.
The snippets package holds every other Wiki sample that compiles against 1.2. Each sample sits between // snippet:NAME:start and // snippet:NAME:end comments, and wrapper methods supply the variables a fragment uses without declaring. Nothing calls these classes. The build only compiles them.
tools/sync_snippets.py copies the samples into a local Wiki clone. Each backed Wiki code block names its source in a comment directly above it, and --check lists stale blocks without editing anything. Whole-file listings omit the region marker comments.

<!-- snippet: snippets/ClientSnippets.java#read -->
```java
static int readInt32(OpcUaClient client, NodeId nodeId) throws UaException {
  ...
```

The three "before" samples in the 1.2.0 migration guide use 1.1.7 APIs, so they are not compiled.

An earlier revision of this PR carried behavioral integration tests for every Wiki sample, two standalone migration projects, and smoke, capture, and inventory tools, about 7,700 lines in all. They served a one-time validation of the new Wiki. Keeping them would have meant maintaining documentation-shaped tests in the product repository, and they still did not check that the Wiki showed the tested code. This revision replaces them with the compile-only snippets and the sync check.

Source documentation

The README gains a Documentation section that points to the Wiki's getting-started path, the client and server guides, and the examples index. Its feature-guide links now go to the Wiki, and its snapshot repository is the current Sonatype one.
The six guides in docs/features now point callers to the Wiki. They keep the contributor material: architecture, model regeneration, ownership boundaries, and test guidance. All 94 of their original heading anchors still resolve.
WiresharkKeyLogWriter and KeyLogExample replace the Wireshark menu path with the TShark preferences that decrypt traffic, opcua.debug_file and opcua.tcp.port.
The GdsPullExample class documentation now says the pulled trust list is applied to the client's file-based certificate group.
The access package documentation lists which services consult the AccessController, and which do not: HistoryRead, HistoryUpdate, AddNodes, TranslateBrowsePathsToNodeIds, and BrowseNext.

None of this changes runtime behavior.

Verification

mvn clean verify -DskipTests passes, so all main and test sources compile and the formatting check passes.
FirstProgramsTest passes with mvn -pl milo-examples/wiki-examples -am clean test -Dtest=FirstProgramsTest.
sync_snippets.py --check against the published Wiki reports no stale blocks among its 83 marked blocks.

The first three commits on this branch lack Signed-off-by trailers. The ECA check passes, and later commits are signed off.

greptile-apps · 2026-10-04T20:25:35Z

Confidence Score: 5/5

[Low risk] Adds compiled wiki example code and documentation links.

The PR appears safe to merge; the missing README migration link is a non-blocking documentation regression.

Findings

Migration Guide Link Removed ▶

Summary

The PR adds a compiled home for Wiki examples, a sync tool for backed Wiki code blocks, and source-documentation pointers to the Wiki. The latest change removes the README’s direct migration-guide link.

_{Reviews (9) · Last reviewed commit: "Leave the migration guide out of the REA..."}

kevinherron · 2026-10-05T02:36:19Z

@greptileai review

kevinherron · 2026-10-05T03:03:06Z

@greptileai review

kevinherron · 2026-10-05T03:24:10Z

@greptileai review

kevinherron · 2026-10-05T04:04:46Z

@greptileai review

kevinherron · 2026-10-05T04:21:24Z

@greptileai review

kevinherron · 2026-10-05T04:37:36Z

@greptileai review

kevinherron · 2026-10-05T08:22:10Z

@greptileai review

kevinherron · 2026-10-05T08:25:18Z

@greptileai review

Exercise complete tutorials and guide fragments against local OPC UA services, including version-isolated migration examples and original example bodies. Keep smoke, capture, and inventory tools with the source so documentation behavior can be checked without changing runtime APIs.

Exercise failure handling, sampling batches, history ownership, serialization limits, and version-isolated JSON and certificate migration. Correct example guidance for GDS trust installation and Wireshark decoding. Validation: full formatting and clean compilation; 163 reactor tests; six migration tests per version and four additional 1.1.7 revocation cases with --add-opens; 16 original example entry points.

Exercise primitive-array decoding, JSON mode mismatches, and Binary/XML ExtensionObject migration through separate 1.1.7 and 1.2 JVMs. Verify that batched sampling reports an omitted device value as Bad_NoData. These fixtures support the Wiki compatibility and ownership guidance. No runtime API behavior changes.

Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Keep contributor architecture, model generation, ownership boundaries, and test guidance with the source while directing callers to the complete 1.2 Wiki. Preserve existing feature-guide anchors and correct the tutorial test references, access-controller coverage, and JSON null test comment. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Rewrite the displayed helpers so each step reads on its own line: braces on every if, named intermediate values instead of nested calls, and no result-count checks for single-operation requests. The history example shares one request helper between page reads and the release. Move the test-only release counter from the displayed service override into the history namespace so the Wiki fragment no longer carries it. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

A zero page budget made readRawHistory return an empty list without reading, which a caller could not tell apart from an empty interval. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Replace the behavioral Wiki tests with compile-only snippet classes in milo-wiki-examples. Each Wiki sample sits between snippet markers, so an API change that breaks a sample fails the build, and sync_snippets.py copies the samples into a Wiki clone or reports stale blocks. Keep FirstClient, FirstServer, and one test that runs them together. Remove the integration-test fixtures, the two standalone migration projects, the consumer project, and the smoke, capture, and inventory tools. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

The restructured Wiki carries one running example through the client and server guides. FirstServer now publishes a Thermostat Object with a read-only Temperature, a writable Setpoint, and an AdjustSetpoint Method, and its snippet regions back the server pages. Client samples use those nodes and read like application code: a connect helper returns a connected client, a subscription keeps running until the caller deletes it, and Reverse Connect and GDS samples split into the parts each application runs. FirstProgramsTest now checks the thermostat behaviors the Wiki documents. The GDS install sample keeps the issuer chain the GDS returns. sync_snippets.py strips region markers from whole-file listings, rejects marker paths outside the source directory, and fails when the Wiki directory has no pages. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

AdjustSetpoint now reads, checks, and stores Setpoint while holding the node's lock, which a client write also holds when it stores a value, so concurrent changes cannot be lost. The GDS install sample accepts a chain that ends at the trusted CA itself, and writeBatch rejects a NodeId that appears twice because it reports failures by NodeId. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

The package Javadoc now describes what the packages contain. The README keeps the editing and sync instructions. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Add a Documentation section that links the Wiki's getting-started path, the client and server guides, and the 1.2.0 migration guide. Link the feature guides to their Wiki pages, and use the current Sonatype snapshot repository. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Signed-off-by: Kevin Herron <kevinherron@gmail.com>

greptile-apps Bot reviewed Oct 4, 2026

View reviewed changes

Comment thread milo-examples/wiki-examples/src/main/java/org/eclipse/milo/examples/wiki/FirstClient.java

Comment thread milo-examples/wiki-examples/tools/smoke_first_programs.py Outdated

Comment thread milo-examples/wiki-examples/tools/inventory_wiki.py Outdated

greptile-apps Bot reviewed Oct 5, 2026

View reviewed changes

Comment thread ...integration-tests/src/test/java/org/eclipse/milo/opcua/sdk/client/WikiClientHistoryTest.java Outdated

Comment thread ...integration-tests/src/test/java/org/eclipse/milo/opcua/sdk/client/WikiClientHistoryTest.java Outdated

kevinherron changed the title ~~Add executable fixtures for the 1.2 Wiki~~ Add compiled sources for the 1.2 Wiki samples Oct 5, 2026

greptile-apps Bot reviewed Oct 5, 2026

View reviewed changes

Comment thread milo-examples/wiki-examples/src/main/java/org/eclipse/milo/examples/wiki/package-info.java Outdated

greptile-apps Bot reviewed Oct 5, 2026

View reviewed changes

Comment thread README.md

kevinherron added 14 commits October 12, 2026 11:44

Check tutorial listener closure after shutdown

2510bed

Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Verify history reclamation and Matrix field limits

05b5996

Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Validate JSON null elements and history encoding rules

ef50519

Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Reject a nonpositive history page budget

8912aee

A zero page budget made readRawHistory return an empty list without reading, which a caller could not tell apart from an empty interval. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Keep snippet maintenance notes out of package docs

1f33012

The package Javadoc now describes what the packages contain. The README keeps the editing and sync instructions. Signed-off-by: Kevin Herron <kevinherron@gmail.com>

Leave the migration guide out of the README

8da5cc2

Signed-off-by: Kevin Herron <kevinherron@gmail.com>

kevinherron force-pushed the docs/wiki-1.2-validation branch from de1bf7e to 8da5cc2 Compare October 12, 2026 18:47

kevinherron changed the base branch from integration/1.2 to main October 12, 2026 18:47

kevinherron merged commit 05f1e32 into main Oct 12, 2026
9 checks passed

Conversation

kevinherron commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Wiki samples

Source documentation

Verification

Uh oh!

greptile-apps Bot commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Findings

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

Uh oh!

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

kevinherron commented Oct 5, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kevinherron commented Oct 4, 2026 •

edited

Loading

greptile-apps Bot commented Oct 4, 2026 •

edited

Loading