Skip to content

Run every example with no settings, and the usage sharing example under test - #173

Merged
ben51degrees merged 40 commits into
rcfrom
remote/java-05
Nov 19, 2026
Merged

ben51degrees merged 40 commits into
rcfrom
remote/java-05

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

The specification this brings the code into conformance with

All quotations are at specifications dbaf099c.

  1. Examples have unit tests, including a run with nothing set. device-detection-specification/required-examples.md lines 13 and 20 to 21 say "There MUST be unit tests for examples" and "Those tests MUST include a run of each example with no arguments or settings, as someone would run it from a fresh clone". The usage sharing example and the client-side element developer example had no unit test, and the on-premise web example could not be started with nothing set as its main starts it.
  2. Console examples inhibit usage sharing, and say so. Lines 201 to 211 say console examples leave the Usage Sharing Element out and "Every example in which usage sharing is inhibited needs to have a comment saying that in normal operation usage sharing should be enabled by adding a Usage Sharing Element to the Pipeline." The on-premise getting started console example's options file did not turn it off.
  3. A non-default setting is shown. Lines 162 to 164 say "Examples MUST also demonstrate or at least document commonly used, but non-default settings. For example using setSuppressProcessExceptions(true)". The on-premise web example's configuration file already set it, as SuppressProcessException, and nothing held it there.
  4. The console examples show the fluent builder and an options file. Lines 237 to 243 say this "is met when the console examples between them show both the fluent builder and an options file". Nothing held them to it.
  5. High entropy values in the web examples. Lines 266 to 268 say "The example SHOULD illustrate various techniques for obtaining "high entropy values" for presentation to the origin server as well as to the 51degrees cloud service."
  6. A programmatic data update. Lines 338 to 344 say implementors "SHOULD illustrate" a "programmatic (non-automatic) update". The data update example did not.
  7. A cloud engine is a drop-in replacement. device-detection-specification/usage-examples.md lines 16 and 17 say "a cloud Engine MUST be a drop-in replacement for an on-premise Engine for performing Device Detection and querying the results." Nothing tested it.
  8. Flow Elements are made one way. pipeline-specification/usage-examples.md line 13 says "Creating Flow Elements SHOULD always be done using a consistent mechanism", which in Java is a builder class. Nothing held the repository's Flow Elements to it.
  9. The client-side element developer example is one of the star sign examples pipeline-specification/required-examples.md lines 7 to 9 says "MUST be implemented in the core". Its star sign was wrong for a date of birth near the end of a sign that runs over the end of the year.

What changed

Links are to the head, f34859be.

  1. The usage sharing example can be tested without sharing. ShareUsageExample sends to an endpoint it is given, and ShareUsageExampleTest gives it one in the test, so the test shares nothing with the live service.
  2. The on-premise getting started console example turns usage sharing off in gettingStartedOnPrem.xml, with the comment the specification asks for, and GettingStartedOnPremUsageSharingTest holds both.
  3. The on-premise web example can be started with nothing set as its main starts it, through a start(port) method main now calls, and WebOnPremWithoutSettingsTest holds that. NonDefaultSettingsTest holds its configuration file to setting SuppressProcessException with a comment saying why, which it already did. The comment in 51Degrees-OnPrem.xml on secure origins now says that browsers run getHighEntropyValues only in an https origin or on localhost.
  4. ConsoleConfigurationCoverageTest holds the console examples to showing both the fluent builder and an options file, for on-premise and cloud.
  5. The web examples' pages say how they obtain high entropy values, by the Accept-CH header and by getHighEntropyValues in the client-side JavaScript, and that the cloud example presents them to the cloud service. HighEntropyValuesTest in each web example holds the page to it.
  6. The data update example asks for an update now. UpdateDataFile shows a programmatic update through the data update service, and ProgrammaticUpdateTest holds it.
  7. CloudDropInTest reads the results of the cloud engine and the on-premise engine through the same code.
  8. ElementCreationConsistencyTest holds every Flow Element in the repository to being made by its builder class. TranslationEngineBase stays concrete with its public constructor, as released, because only a SHOULD asks for one way of making Flow Elements, and its documentation says to make a translation engine through its builder. The test treats a class whose name ends in Base as a base class, and TranslationEngineBasePublicTests holds the released class concrete (7014ac9, f34859b).
  9. The client-side element developer example compares a date of birth by day and month alone and finds a sign that runs over the end of the year, and its ExampleTests builds it, runs it in a Pipeline and checks a sign for every date of birth.

Before you upgrade

  1. The on-premise getting started console example no longer shares usage, as the specification asks of console examples (required-examples.md lines 201 to 211). To share usage from it, add a Usage Sharing Element to its Pipeline.

No public class or method changes. TranslationEngineBase stays concrete, as released.

What this draft no longer carries

At bd93f86c this draft put back rc's version of every file it changed only for work that three other drafts carry, so each piece of work is in one draft.

  • The Derived Property Element and its developer example are #156's.
  • Comparer running on the free data file, with the Enterprise note, is #158's.
  • Every cloud example ending cleanly with no resource key is #163's, so the cloud cases of this draft's no-settings tests and its own WithoutKeyTest files went with it, as End every cloud example cleanly when it has no resource key #163's tests run each cloud example with no key. The usage sharing example's case in the no-settings test went too, because run with no settings it sends to the live service.

Tests

Red, run 43913952515 on tmp/red-173b, one job per test commit, each building its module and running the new test in that module alone. All five failed.

Job Test commit Result
Every Flow Element is made by its builder ffb3dc8 ElementCreationConsistencyTest fails, "TranslationEngineBase is made by no builder". The test now treats a class named ...Base as a base class (7014ac9), so it fails for any other concrete Flow Element made outside a builder
The console example shares no usage 117cf46 GettingStartedOnPremUsageSharingTest fails 2 of 2, "The example's Pipeline should not share usage" and the options file comment missing
The client-side element example 07b0874 ExampleTests fails 2 of 4, "expected: but was: " for the first and last days of a sign and "expected: but was: " across the end of the year
High entropy values in the web examples 3c61c50 HighEntropyValuesTest fails 2 of 2, the page not naming getHighEntropyValues and the options file comment saying it fails in a secure origin
The on-premise web example with no settings f234c41 Stops at test compile, "cannot find symbol" for start(int), which only the fix adds. So this job shows the test cannot pass without the fix, not a test failing at run time

Two more test commits stop at test compile for the same reason, and an earlier run shows it, 43870415154: ProgrammaticUpdateTest (a816cd7) calls updateNow, and ShareUsageExampleTest (b627d35) the endpoint the fix adds. That earlier run's other three jobs stopped before their test ran, because its test step ran on every module, so they are not cited. ConsoleConfigurationCoverageTest, CloudDropInTest and NonDefaultSettingsTest cover what the examples already did and have no red. A full build of bd93f86, run 43910501413, failed ConsoleConfigurationCoverageTest.onPremiseOptionsFile in four of its nine jobs with "[IPIntelligenceOnPremiseEngine]", because the test found gettingStartedOnPrem.xml by searching the file system and, from where those jobs ran, found the IP Intelligence example's file of the same name first. Commit 06ac80d reads each options file from the Device Detection example's own resources.

Red and green of the TranslationEngineBase fix, run 44451557389 on tmp/fixconf-java-173 (workflow commit f7ef66e on f34859b). The red job ran TranslationEngineBasePublicTests at the test commit 7014ac9 and failed as intended, translationEngineBase_IsConcrete "TranslationEngineBase is abstract, so code that makes one with new no longer compiles". The green job ran every test of pipeline.core, pipeline.translation and ip-intelligence.translation, the module whose engines extend TranslationEngineBase, at f34859b, and all passed, 160, 55 and 23 tests with 1 skipped, ElementCreationConsistencyTest and TranslationEngineBasePublicTests among them. The run reports failure only because the red job failed, as it should.

Green, the full build below, of 06ac80d, and the green job above for the two commits after it.

Build

Run 43940789635 built 06ac80d merged with rc on nine configurations, Ubuntu x64 with Java 8, 11, 17 and 21, Ubuntu arm64 with Java 17, and Windows with Java 8, 11, 17 and 21. Configure and all nine Build and Test jobs passed, read from each job's log, and ConsoleConfigurationCoverageTest passed 2 of 2 in all nine. Each of its ten Setting 'PullRequestSha' lines names 06ac80d, and its Configure job printed "Left out 6 macOS entries". The run's last job, which only gathers the results, was still running when the build was first written up.

macOS was left out of this draft's full build under the 9 November decision. The rc head is built with macOS before it merges into main.

Base branch

rc 81e3d4a is merged into the head with a merge commit, and the head merges into today's rc with no conflict. The examples' KeyHelper changes this draft made for the no-key endings went with them at bd93f86.

Changes at the last head

7014ac9 adds TranslationEngineBasePublicTests, and f34859b makes TranslationEngineBase concrete again with its public constructor, as released, so nothing about it is listed under Before you upgrade. The title no longer names Comparer, which another pull request carries, and What remains names the one example still without a no-settings run.

What remains

  1. The usage sharing example has no run with no settings, because with no settings it sends to the live service. ShareUsageExampleTest runs it against an endpoint it gives. A no-settings run that checks only that it starts and stops, with the endpoint unreachable, would close that.
  2. WebOnPremWithoutSettingsTest leaves TestDataFile set to the Lite file when it was not set before, because the example sets it while finding its data file. Clearing it in the test's finally would keep it from reaching a later test in the same JVM.
  3. Making TranslationEngineBase abstract, so a translation engine is made only by its builder, waits for a release that may break public names.

Answers device-detection-specification/required-examples.md line 13 at 706de1f0: There MUST be unit tests for examples, to verify that the example remains valid through various code changes. (EX-3)
…o its test shares nothing

Answers device-detection-specification/required-examples.md line 13 at 706de1f0: There MUST be unit tests for examples, to verify that the example remains valid through various code changes. (EX-3)
…h clone

Answers device-detection-specification/required-examples.md line 20 at 706de1f0: Those tests MUST include a run of each example with no arguments or settings, as someone would run it from a fresh clone, so that the run uses the free data files. (EX-4)
…set, and the on-premise web example can be started as its main starts it

Answers device-detection-specification/required-examples.md line 20 at 706de1f0: Those tests MUST include a run of each example with no arguments or settings, as someone would run it from a fresh clone, so that the run uses the free data files. (EX-4)
Answers device-detection-specification/required-examples.md line 91 at 706de1f0: Examples MUST run out of the box with the free data files. (EX-6)
…erprise data file

Answers device-detection-specification/required-examples.md line 91 at 706de1f0: Examples MUST run out of the box with the free data files. (EX-6)
Answers device-detection-specification/required-examples.md line 101 at 706de1f0: Examples MUST also show what only the Enterprise Data File can do, because the examples are where a developer first sees what the paid data files add. (EX-7)
…e Enterprise data file, and gives the contact page link once

Answers device-detection-specification/required-examples.md line 101 at 706de1f0: Examples MUST also show what only the Enterprise Data File can do, because the examples are where a developer first sees what the paid data files add. (EX-7)
…with nothing set

Answers pipeline-specification/required-examples.md line 30 at 706de1f0: Every reference implementation MUST provide one example for the Derived Property Element. (EX-19)
@jwrosewell jwrosewell added the remote-conformance Specification conformance work from the remote packs label Nov 15, 2026
…nd an example of it that needs no key, data file or network

The element is in the pipeline.translation package, beside the Translation Element, which uses the same YAML 1.2 library. Answers pipeline-specification/required-examples.md line 30 at 706de1f0: Every reference implementation MUST provide one example for the Derived Property Element. (EX-19)
…script from a file, and the pipeline built from a configuration file

Answers pipeline-specification/required-examples.md line 37 at 706de1f0: The example MUST show all four of the following. The fourth is EX-22. (EX-21)
…beside it and builds the same pipeline from a configuration file

Answers pipeline-specification/required-examples.md line 37 at 706de1f0: The example MUST show all four of the following. (EX-21)
…at is not available

Answers pipeline-specification/required-examples.md line 50 at 706de1f0: This case MUST be shown rather than only described, because it is the behaviour customers most often meet first and the one the two valued model exists to make plain. (EX-22)
…idity, and the message naming the missing property

Answers pipeline-specification/required-examples.md line 50 at 706de1f0: This case MUST be shown rather than only described, because it is the behaviour customers most often meet first and the one the two valued model exists to make plain. (EX-22)
…ss exceptions

Answers device-detection-specification/required-examples.md line 150 at 706de1f0: Examples MUST also demonstrate or at least document commonly used, but non-default settings. (EX-8)
…remise and cloud

Answers device-detection-specification/required-examples.md line 225 at 706de1f0: Examples MUST be provided that illustrate basic usage of the API for both Cloud and On-Prem, using fluent builder and options file configuration, when executed as a console (command line) application. (EX-9)
…premise engine

Answers device-detection-specification/usage-examples.md line 16 at 706de1f0: In particular, a cloud Engine MUST be a drop-in replacement for an on-premise Engine for performing Device Detection and querying the results. (EX-13)
…gives a star sign for every date of birth

Answers pipeline-specification/required-examples.md line 7 at 706de1f0: The examples that MUST be implemented in the core are all demonstrations of how to create Flow Elements. (EX-18)
…nd month alone, and finds a sign that runs over the end of the year

Answers pipeline-specification/required-examples.md line 7 at 706de1f0: The examples that MUST be implemented in the core are all demonstrations of how to create Flow Elements. (EX-18)

A date on the last day of a sign gave no sign, because each date kept the time of day it was made at, and Capricorn was never found, because its start is after its end.
…or, names the variable to set and links to the configurator, tagged with its own file

Answers device-detection-specification/required-examples.md line 140 at dbaf099c: A cloud example run with no Resource Key MUST end without an error, name the environment variable to set, give a link to where a Resource Key is created, such as the configurator, and exit successfully, so that its test runs it with no arguments or settings. (EX-25)
…d with the example's file

Answers device-detection-specification/required-examples.md line 140 at dbaf099c (EX-25). The first form of the test passed for four examples whose configurator link names the shared key helper, because their Find out more links carry the example's own tag.
…set and links to the configurator tagged with its own file, and ends without an error

Answers device-detection-specification/required-examples.md line 140 at dbaf099c: A cloud example run with no Resource Key MUST end without an error, name the environment variable to set, give a link to where a Resource Key is created, such as the configurator, and exit successfully, so that its test runs it with no arguments or settings. (EX-25)

The IP Intelligence cloud examples threw with no key. The Device Detection ones tagged the link with the shared key helper's file. The minimal example also takes its key from TestResourceKey and names it, and treats an empty key as none.
…ng for an update of the engine now

Answers device-detection-specification/required-examples.md line 323 at 706de1f0: Implementors SHOULD illustrate: (file system watcher, remote update polling, update on start-up, programmatic (non-automatic) update). (EX-11)
…g the data update service for an update of the engine now

Answers device-detection-specification/required-examples.md line 323 at 706de1f0: Implementors SHOULD illustrate: (file system watcher, remote update polling, update on start-up, programmatic (non-automatic) update). (EX-11)
…e Accept-CH header and by getHighEntropyValues in the client-side JavaScript

Answers device-detection-specification/required-examples.md line 250 at 706de1f0: The example SHOULD illustrate various techniques for obtaining high entropy values for presentation to the origin server as well as to the 51degrees cloud service. (EX-10)
… by Accept-CH and by getHighEntropyValues, and that the cloud example presents them to the cloud service

Answers device-detection-specification/required-examples.md line 250 at 706de1f0: The example SHOULD illustrate various techniques for obtaining high entropy values for presentation to the origin server as well as to the 51degrees cloud service. (EX-10)

The options files' comment said getHighEntropyValues could not run in a secure origin. Browsers give the values only to a secure origin or localhost, and the comment now says so.
…ss, and by nothing else

Answers pipeline-specification/usage-examples.md line 13 at 706de1f0: Creating Flow Elements SHOULD always be done using a consistent mechanism. (EX-24)
…n engine is only made by its builder

Answers pipeline-specification/usage-examples.md line 13 at 706de1f0: Creating Flow Elements SHOULD always be done using a consistent mechanism. (EX-24)

Every other Flow Element is made by its builder alone. TranslationEngineBase was a concrete class with no builder, which nothing made directly.
…aring Element, and says to add one in normal operation

Answers device-detection-specification/required-examples.md lines 201 and 209 at dbaf099c: Reference implementations inhibit usage sharing for console examples by ensuring the Usage Sharing Element is not added to the Pipeline, but enable it for web examples. Every example in which usage sharing is inhibited needs to have a comment saying that in normal operation usage sharing should be enabled by adding a Usage Sharing Element to the Pipeline.
…ng off in its options file, with the comment saying to share usage in normal operation

Answers device-detection-specification/required-examples.md lines 201 and 209 at dbaf099c: Reference implementations inhibit usage sharing for console examples by ensuring the Usage Sharing Element is not added to the Pipeline, but enable it for web examples. Every example in which usage sharing is inhibited needs to have a comment saying that in normal operation usage sharing should be enabled by adding a Usage Sharing Element to the Pipeline.

The example built its Pipeline with the FiftyOnePipelineBuilder, which adds a Usage Sharing Element unless ShareUsage is false, so every run shared the example's evidence.
…t before its type parameter, so it is not read as part of it

Follows the fix for pipeline-specification/usage-examples.md line 13 at 706de1f0 (EX-24).
rc moved the examples off the packages' test helpers in #175, so TacCloud
and UpdateDataFile take the key helper from the examples' own shared module
whilst keeping this draft's ending for an example run with no resource
key.
… and build the example links so the link lint can read them
@jwrosewell jwrosewell changed the title Specification conformance, 51degrees-java, section 5 Run every example with no settings, Comparer on the free data file, and the usage sharing example under test Nov 16, 2026
…ith no key to the drafts that carry them

The Derived Property Element and its example are #156's, Comparer on the
free data file is #158's, and every cloud example ending cleanly with no
resource key is #163's, so each file this draft changed only for those
is put back to rc's version. The cloud cases of the no-settings tests go
with them, as #163's tests cover each cloud example run with no key.
TranslationEngineBase and its public constructor are in the last release, so
code may make one with new. The only sentence behind making it abstract is a
SHOULD, "Creating Flow Elements SHOULD always be done using a consistent
mechanism", and a SHOULD leaves released behaviour as it is.
TranslationEngineBasePublicTests holds the class concrete with a public
constructor. ElementCreationConsistencyTest treats a class whose name ends
in Base as a base class rather than a Flow Element, so a released base class
that is still concrete is not required to have a builder.
TranslationEngineBase is concrete with a public constructor again, as in the
last release, so code that makes one with new still compiles. Its
documentation says to make a translation engine through its builder.
Making the class abstract is a breaking change that no MUST requires, so it
waits for a release that may break.
@jwrosewell jwrosewell changed the title Run every example with no settings, Comparer on the free data file, and the usage sharing example under test Run every example with no settings, and the usage sharing example under test Nov 19, 2026
@ben51degrees
ben51degrees marked this pull request as ready for review November 19, 2026 05:08
@ben51degrees
ben51degrees merged commit c31e733 into rc Nov 19, 2026
9 checks passed
@ben51degrees
ben51degrees deleted the remote/java-05 branch November 19, 2026 05:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

remote-conformance Specification conformance work from the remote packs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants