Skip to content

Show each IP Intelligence value's weighting in the examples - #148

Merged
ben51degrees merged 7 commits into
rcfrom
examples/ipi-weightings
Nov 19, 2026
Merged

ben51degrees merged 7 commits into
rcfrom
examples/ipi-weightings

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Every IP Intelligence property is a list of weighted values, and no Java example showed a weighting. Two things hid it.

  1. The examples print their values through the shared PropertyHelper, whose unwrapValue kept each weighted value's value and dropped its weighting (PropertyHelper lines 67 to 84 at rc 49bc431e, line 76).
  2. The Getting Started on-premise example read each property through its typed getter, such as getRegisteredName(), which is declared as AspectPropertyValue<String> (IPIntelligenceData line 242) and so gives the value alone. With the free data file the example printed RegisteredName: UNICOM and no weighting at all.

So a developer running the Getting Started example saw "UNICOM" and never learned that the answer carries a weighting, or how to read it.

What the specification says

ip-intelligence-specification/required-examples.md at d79bbe3b, "Weighted Values", line 107:

Unlike Device Detection, IP Intelligence properties return weighted values, and a property with a single answer returns it with a weighting of 1. Examples MUST demonstrate accessing both the value and its associated weighting

The section's example prints each value followed by its weighting.

What changed

  1. PropertyHelper.unwrapValue writes each weighted value followed by its weighting, read with IWeightedValue.getWeighting() and written to two decimal places in the root locale, for example Japan (weighting 1.00), or Tokyo (weighting 0.75), Osaka (weighting 0.25) where there are two answers. Values that are not weighted are written as before, and the method's comment says what it does with a list.
  2. GettingStartedOnPrem.writeValue reads each property by name with ipData.get(property), which gives the list of weighted values, rather than through the typed getter. So with the free data file the example prints RegisteredName: UNICOM (weighting 1.00). Its comment says that the typed getters give the value alone.
  3. The "Examples from a fresh clone" check fails unless the IP Intelligence example's output holds (weighting . ci/run-fresh-clone-example.ps1 takes an optional -Expect text, the workflow passes (weighting for the IP Intelligence entries and an empty text for Device Detection, and ci/run-fresh-clone-example.Tests.ps1 gains a case where the output holds the text and passes, and one where it does not and fails.
  4. AGENTS.md, under "Correct output", says each value is followed by its weighting, as in RegisteredCountry: CN (weighting 1.00), which is a line the free data file prints.

examples/ip-intelligence is not among the packages ci/packages.json publishes, so this change publishes nothing.

Changes at this head

The previous head, db2907a, showed the weighting only for values that reach the helper as a list. Its own fresh clone run printed RegisteredName: UNICOM with no weighting, because the example read the three properties the free data file has through their typed getters. Three commits follow it.

  1. 9d5db0e5, the test. The fresh clone run of the IP Intelligence example fails unless its output holds (weighting , so the check shows whether a person running the example with the free data file sees a weighting.
  2. f2e9f4fc, rc 49bc431 merged in (see Base branch).
  3. 1166f453, the fix. The example reads each value by name, as item 2 of What changed says, AGENTS.md gives a line the free data file prints as its example, and the helper's comment no longer says a single value is written alone.

Tests

Two tests, each written before its fix.

  • PropertyHelperTest.testWeightedValuesShowTheirWeighting (commit 281779b). One value with a raw weighting of 65535 is written Japan (weighting 1.00), and two with raw weightings of 49151 and 16384 are written Tokyo (weighting 0.75), Osaka (weighting 0.25). Red on rc b33daa0 (281779b with the workflow, 56729f0) in run 43618736428, where PropertyHelperTest ran 5 with 1 failure, the new test, "expected:<Japan[ (weighting 1.00)]> but was:<Japan[]>". Green on the change (b9eabc3 with the workflow, aa314da) in run 43618750238, all 5 passed.
  • The fresh clone check of the example's output (commit 9d5db0e), red and green as in Changes at this head.

Released tests

The released tests on main that exercise what this draft touches are the four in the IP Intelligence examples' PropertyHelperTest and GettingStartedOnPremTest in the IP Intelligence console examples. Both files are unaltered here apart from the one test added to PropertyHelperTest.

Tests of what it touches

Run 44452870138 built 1166f45, with one temporary workflow commit on top of it (a278c23) and nothing merged, 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, and every job passed. In its Ubuntu Java 17 job the IP Intelligence examples ran PropertyHelperTest 5 of 5, GettingStartedOnPremTest 1 of 1 and ExamplesWithoutSettingsTest 11 of 11, with every other test in the examples passing. macOS was left out of this build. The rc head is built with macOS before it merges into main.

Base branch

rc 49bc431 is merged into the head with a merge commit, f2e9f4fc, after rc made -ExpectDownload a switch of ci/run-fresh-clone-example.ps1 and began testing the script and the workflow's calls of it with Pester. Two conflicts, each resolved by keeping both changes.

  • In ci/run-fresh-clone-example.ps1, rc's [switch]$ExpectDownload and its comment, then this draft's optional -Expect text.
  • In .github/workflows/examples-fresh-clone.yml, rc's -ExpectDownload and -ExpectDownload:$false, each followed by this draft's -Expect '${{ matrix.expect }}'.

rc's run-fresh-clone-example.Tests.ps1 replaces the workflow's matrix values before it runs each call, so it now also replaces matrix.expect with the empty text the Device Detection entries give.

An earlier merge of rc 81e3d4a, db2907a5, conflicted in one hunk of AGENTS.md, where #162 rewrote the IP Intelligence part of "Correct output" to say that every line the Lite file cannot answer reads needs the Enterprise data file. That resolution kept #162's text and put this draft's sentence in front of it.

rc has since moved to 3bb6e71, and the draft merges with it with no conflict. #192 also changes examples-fresh-clone.yml and AGENTS.md, in other lines, and a trial merge of the two heads is clean.

Before you upgrade

Nothing to change. The change is in the IP Intelligence examples, AGENTS.md and CI, which publish no package. The examples' output now carries each value's weighting.

What remains

Nothing for this change.

The specification's IP Intelligence required examples page says "Examples
MUST demonstrate accessing both the value and its associated weighting".
The fresh clone run of the getting started example now fails unless its
output holds "(weighting ", so the check shows whether a person running the
example with the free data file sees a weighting.
rc now passes -ExpectDownload to run-fresh-clone-example.ps1 as a switch
and tests the script and the workflow's calls of it with Pester. Two
conflicts, resolved by keeping both changes.

- In ci/run-fresh-clone-example.ps1, rc's [switch]$ExpectDownload and its
  comment, then this branch's optional -Expect text.
- In .github/workflows/examples-fresh-clone.yml, rc's -ExpectDownload and
  -ExpectDownload:$false, each followed by this branch's
  -Expect '${{ matrix.expect }}'.

rc's run-fresh-clone-example.Tests.ps1 replaces the workflow's matrix
values before running each call, so it now also replaces matrix.expect
with the empty text the device-detection entries give, and two new cases
check that -Expect passes when the output holds the text and fails when it
does not.
…ighting

The getting started example read its values through the typed getters,
such as getRegisteredName(), which give a String and no weighting. So with
the free data file it printed "RegisteredName: UNICOM" and no weighting at
all. Reading a property by name gives a list of weighted values, which the
helper prints as "UNICOM (weighting 1.00)", as the specification's "Examples
MUST demonstrate accessing both the value and its associated weighting"
asks. AGENTS.md now gives a line the free data file prints as its example,
and the helper's comment says what it does with a list.
@ben51degrees
ben51degrees marked this pull request as ready for review November 19, 2026 05:38
@ben51degrees
ben51degrees merged commit d340e1b into rc Nov 19, 2026
9 checks passed
@ben51degrees
ben51degrees deleted the examples/ipi-weightings branch November 19, 2026 05:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants