From 281779b16fda676865ba61c5882a9fd8806ca7e5 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sat, 14 Nov 2026 16:59:40 +0000 Subject: [PATCH 1/5] Test that the IP Intelligence examples show each value's weighting --- .../examples/shared/PropertyHelperTest.java | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/examples/ip-intelligence/shared/src/test/java/fiftyone/ipintelligence/examples/shared/PropertyHelperTest.java b/examples/ip-intelligence/shared/src/test/java/fiftyone/ipintelligence/examples/shared/PropertyHelperTest.java index 705ceff72..4a7bb9e65 100644 --- a/examples/ip-intelligence/shared/src/test/java/fiftyone/ipintelligence/examples/shared/PropertyHelperTest.java +++ b/examples/ip-intelligence/shared/src/test/java/fiftyone/ipintelligence/examples/shared/PropertyHelperTest.java @@ -22,11 +22,15 @@ package fiftyone.ipintelligence.examples.shared; +import fiftyone.pipeline.core.data.IWeightedValue; +import fiftyone.pipeline.core.data.WeightedValue; import fiftyone.pipeline.engines.data.AspectPropertyValue; import fiftyone.pipeline.engines.data.AspectPropertyValueDefault; import org.junit.Test; import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; import java.util.List; import static org.junit.Assert.*; @@ -60,4 +64,25 @@ public void testAsNoValue() { AspectPropertyValue> test = new AspectPropertyValueDefault<>(); assertTrue(PropertyHelper.asString(test).startsWith("Unknown")); } + + /** + * Each weighted value is shown with its weighting, as the IP + * Intelligence examples must show both. A raw weighting of 65535 is a + * weighting of 1. + */ + @Test + public void testWeightedValuesShowTheirWeighting() { + AspectPropertyValue>> one = + new AspectPropertyValueDefault<>(Collections.singletonList( + new WeightedValue<>(65535, "Japan"))); + assertEquals("Japan (weighting 1.00)", PropertyHelper.asString(one)); + + AspectPropertyValue>> two = + new AspectPropertyValueDefault<>(Arrays.asList( + new WeightedValue<>(49151, "Tokyo"), + new WeightedValue<>(16384, "Osaka"))); + assertEquals( + "Tokyo (weighting 0.75), Osaka (weighting 0.25)", + PropertyHelper.asString(two)); + } } \ No newline at end of file From b9eabc377fa46879cf06c4d0587f3635b4b38e6a Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sat, 14 Nov 2026 17:00:09 +0000 Subject: [PATCH 2/5] Show each IP Intelligence value's weighting in the examples --- .../examples/shared/PropertyHelper.java | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java b/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java index 68b45b83b..71a7e5aad 100644 --- a/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java +++ b/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java @@ -32,6 +32,7 @@ import java.util.Arrays; import java.util.List; +import java.util.Locale; import java.util.concurrent.atomic.AtomicBoolean; import java.util.function.Supplier; import java.util.stream.Collectors; @@ -60,6 +61,8 @@ public class PropertyHelper { * List<IWeightedValue<T>> even when the declared type is T). * For single-element lists, returns just the value. * For multi-element lists, returns values joined with ", ". + * A weighted value is followed by its weighting, as in + * "Japan (weighting 1.00)". * @param value the raw value from AspectPropertyValue.getValue() * @return the unwrapped string representation */ @@ -73,8 +76,16 @@ private static String unwrapValue(Object value) { return list.stream() .map(item -> { if (item instanceof IWeightedValue) { - Object inner = ((IWeightedValue) item).getValue(); - return inner != null ? inner.toString() : "Unknown"; + // An IP Intelligence value comes with the + // weighting the data gives it, which is 1 for + // a property with one answer. + IWeightedValue weighted = (IWeightedValue) item; + Object inner = weighted.getValue(); + return String.format( + Locale.ROOT, + "%s (weighting %.2f)", + inner != null ? inner.toString() : "Unknown", + weighted.getWeighting()); } return item != null ? item.toString() : "Unknown"; }) From 0eb562fc58e9f177f49e9488cc3edf189f2c6cbc Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sat, 14 Nov 2026 17:01:46 +0000 Subject: [PATCH 3/5] Say in AGENTS.md that each IP Intelligence value is shown with its weighting --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index df51ec15e..293b4d5fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -157,8 +157,9 @@ expected with the Lite file. The exit code is 0. The IP Intelligence example looks up `116.154.188.222`, `45.236.48.61` and an IPv6 address. For each it prints `Input values:` with `query.client-ip`, then `Results:` with a line for each property, from `RegisteredName` to -`TimeZoneOffset`. The Lite file has RegisteredCountry, RegisteredName and -RegisteredOwner, so a line for a property it does not have reads +`TimeZoneOffset`. Each value is followed by its weighting, as in +`Japan (weighting 1.00)`. The Lite file has RegisteredCountry, RegisteredName +and RegisteredOwner, so a line for a property it does not have reads `Unknown. The property '' is not available in this data file.` followed by a link, and the first such line also logs a warning that some properties need a paid subscription. It then logs the data file in the same way, and From 9d5db0e51754a81cc05d2368e2e014652fe2c547 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Thu, 19 Nov 2026 03:17:16 +0000 Subject: [PATCH 4/5] Check that the IP Intelligence example prints each value's weighting 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. --- .github/workflows/examples-fresh-clone.yml | 8 ++++++++ ci/run-fresh-clone-example.ps1 | 13 ++++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/.github/workflows/examples-fresh-clone.yml b/.github/workflows/examples-fresh-clone.yml index e4eb3185b..cda48cfff 100644 --- a/.github/workflows/examples-fresh-clone.yml +++ b/.github/workflows/examples-fresh-clone.yml @@ -36,9 +36,12 @@ jobs: - product: device-detection example: fiftyone.devicedetection.examples.console.GettingStartedOnPrem file: cxx/data/device-detection/51Degrees-LiteV4.1.hash + expect: '' - product: ip-intelligence example: fiftyone.ipintelligence.examples.console.GettingStartedOnPrem file: cxx/data/ip-intelligence/51Degrees-LiteV41.ipi + # Each IP Intelligence value is printed with its weighting. + expect: '(weighting ' runs-on: ubuntu-latest steps: - name: Clone the repository with its submodules @@ -63,6 +66,7 @@ jobs: run: >- ./ci/run-fresh-clone-example.ps1 -Product '${{ matrix.product }}' -Example '${{ matrix.example }}' -ExpectDownload $true + -Expect '${{ matrix.expect }}' # The key follows the link, so a new free file gets a new entry, and # the same file is kept once rather than once a run. @@ -87,9 +91,12 @@ jobs: - product: device-detection example: fiftyone.devicedetection.examples.console.GettingStartedOnPrem file: cxx/data/device-detection/51Degrees-LiteV4.1.hash + expect: '' - product: ip-intelligence example: fiftyone.ipintelligence.examples.console.GettingStartedOnPrem file: cxx/data/ip-intelligence/51Degrees-LiteV41.ipi + # Each IP Intelligence value is printed with its weighting. + expect: '(weighting ' runs-on: ${{ matrix.os }} steps: - name: Clone the repository with its submodules @@ -122,3 +129,4 @@ jobs: run: >- ./ci/run-fresh-clone-example.ps1 -Product '${{ matrix.product }}' -Example '${{ matrix.example }}' -ExpectDownload $false + -Expect '${{ matrix.expect }}' diff --git a/ci/run-fresh-clone-example.ps1 b/ci/run-fresh-clone-example.ps1 index 5c1e2102b..092197940 100644 --- a/ci/run-fresh-clone-example.ps1 +++ b/ci/run-fresh-clone-example.ps1 @@ -3,13 +3,16 @@ param ( [Parameter(Mandatory)][string]$Example, # True where the clone holds only the data file's link, so the example # has to download the file. False where the file is already in place. - [Parameter(Mandatory)][bool]$ExpectDownload + [Parameter(Mandatory)][bool]$ExpectDownload, + # Text the output must hold, such as the weighting the IP Intelligence + # example prints with each value. Empty when there is none. + [string]$Expect = '' ) # Runs a product's console example jar from the repository root with no # settings, as AGENTS.md's "Run the examples" does, and fails unless it ends -# with exit code 0, prints results, and downloads its data file exactly when -# expected. +# with exit code 0, prints results and any expected text, and downloads its +# data file exactly when expected. $jar = Get-ChildItem "examples/$Product/console/target" ` -Filter '*-jar-with-dependencies.jar' | Select-Object -First 1 @@ -39,6 +42,10 @@ if ($text -notmatch 'Results:') { Write-Output '::error::The example printed no results.' $failed = $true } +if ($Expect -and -not $text.Contains($Expect)) { + Write-Output "::error::The example's output does not hold '$Expect'." + $failed = $true +} if ($failed) { exit 1 } From 1166f45327acfe999197c7c32c3dbe4d4b89fdbc Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Thu, 19 Nov 2026 03:28:33 +0000 Subject: [PATCH 5/5] Read each IP Intelligence value by name, so the example prints its weighting 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. --- AGENTS.md | 6 +-- .../console/GettingStartedOnPrem.java | 49 +++++++++++-------- .../examples/shared/PropertyHelper.java | 6 +-- 3 files changed, 33 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 32296edb8..bd7f29bdb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -156,9 +156,9 @@ The IP Intelligence example looks up `116.154.188.222`, `45.236.48.61` and an IPv6 address. For each it prints `Input values:` with `query.client-ip`, then `Results:` with a line for each property, from `RegisteredName` to `TimeZoneOffset`. Each value is followed by its weighting, as in -`Japan (weighting 1.00)`. The Lite file has RegisteredName, RegisteredOwner -and RegisteredCountry, so every other line reads `needs the Enterprise data -file`. +`RegisteredCountry: CN (weighting 1.00)`. The Lite file has RegisteredName, +RegisteredOwner and RegisteredCountry, so every other line reads `needs the +Enterprise data file`. Both then end the same way, where `` is `Lite` for Device Detection and `IPIV4Lite` for IP Intelligence. diff --git a/examples/ip-intelligence/console/src/main/java/fiftyone/ipintelligence/examples/console/GettingStartedOnPrem.java b/examples/ip-intelligence/console/src/main/java/fiftyone/ipintelligence/examples/console/GettingStartedOnPrem.java index 54868dc60..df87c9b75 100644 --- a/examples/ip-intelligence/console/src/main/java/fiftyone/ipintelligence/examples/console/GettingStartedOnPrem.java +++ b/examples/ip-intelligence/console/src/main/java/fiftyone/ipintelligence/examples/console/GettingStartedOnPrem.java @@ -65,7 +65,6 @@ import java.io.PrintWriter; import java.util.List; import java.util.Map; -import java.util.function.Supplier; import static fiftyone.common.testhelpers.LogbackHelper.configureLogback; import static fiftyone.ipintelligence.examples.shared.PropertyHelper.asString; @@ -231,23 +230,24 @@ private static boolean analyzeEvidence(Map evidence, details of all available properties. */ // The free Lite data file has the registration properties, and - // only the Enterprise data file has the others. - needsEnterprise |= writeValue(writer, engine, "RegisteredName", ipData::getRegisteredName); - needsEnterprise |= writeValue(writer, engine, "RegisteredOwner", ipData::getRegisteredOwner); - needsEnterprise |= writeValue(writer, engine, "RegisteredCountry", ipData::getRegisteredCountry); - needsEnterprise |= writeValue(writer, engine, "IpRangeStart", ipData::getIpRangeStart); - needsEnterprise |= writeValue(writer, engine, "IpRangeEnd", ipData::getIpRangeEnd); - needsEnterprise |= writeValue(writer, engine, "Country", ipData::getCountry); - needsEnterprise |= writeValue(writer, engine, "CountryCode", ipData::getCountryCode); - needsEnterprise |= writeValue(writer, engine, "CountryCode3", ipData::getCountryCode3); - needsEnterprise |= writeValue(writer, engine, "Region", ipData::getRegion); - needsEnterprise |= writeValue(writer, engine, "State", ipData::getState); - needsEnterprise |= writeValue(writer, engine, "Town", ipData::getTown); - needsEnterprise |= writeValue(writer, engine, "Latitude", ipData::getLatitude); - needsEnterprise |= writeValue(writer, engine, "Longitude", ipData::getLongitude); - needsEnterprise |= writeValue(writer, engine, "Areas", ipData::getAreas); - needsEnterprise |= writeValue(writer, engine, "AccuracyRadiusMin", ipData::getAccuracyRadiusMin); - needsEnterprise |= writeValue(writer, engine, "TimeZoneOffset", ipData::getTimeZoneOffset); + // only the Enterprise data file has the others. Each value is + // read by name, which gives it with its weighting. + needsEnterprise |= writeValue(writer, engine, ipData, "RegisteredName"); + needsEnterprise |= writeValue(writer, engine, ipData, "RegisteredOwner"); + needsEnterprise |= writeValue(writer, engine, ipData, "RegisteredCountry"); + needsEnterprise |= writeValue(writer, engine, ipData, "IpRangeStart"); + needsEnterprise |= writeValue(writer, engine, ipData, "IpRangeEnd"); + needsEnterprise |= writeValue(writer, engine, ipData, "Country"); + needsEnterprise |= writeValue(writer, engine, ipData, "CountryCode"); + needsEnterprise |= writeValue(writer, engine, ipData, "CountryCode3"); + needsEnterprise |= writeValue(writer, engine, ipData, "Region"); + needsEnterprise |= writeValue(writer, engine, ipData, "State"); + needsEnterprise |= writeValue(writer, engine, ipData, "Town"); + needsEnterprise |= writeValue(writer, engine, ipData, "Latitude"); + needsEnterprise |= writeValue(writer, engine, ipData, "Longitude"); + needsEnterprise |= writeValue(writer, engine, ipData, "Areas"); + needsEnterprise |= writeValue(writer, engine, ipData, "AccuracyRadiusMin"); + needsEnterprise |= writeValue(writer, engine, ipData, "TimeZoneOffset"); } writer.println(); writer.flush(); @@ -258,14 +258,21 @@ private static boolean analyzeEvidence(Map evidence, * Writes a property, or that it needs the Enterprise data file when the * data file in use does not have it. The value is only read when the * data file has the property. + *

+ * IP Intelligence values are weighted. Reading a property by name gives + * a list of values, each with its weighting, and a property with one + * answer gives it with a weighting of 1. The typed getters, such as + * {@link IPIntelligenceData#getRegisteredName()}, give the value alone. * @return true if the property needs the Enterprise data file */ private static boolean writeValue(PrintWriter writer, IPIntelligenceOnPremiseEngine engine, - String property, - Supplier> value) { + IPIntelligenceData ipData, + String property) { if (DataFileHelper.hasProperty(engine, property)) { - writer.println("\t" + property + ": " + asString(value.get())); + AspectPropertyValue value = + (AspectPropertyValue) ipData.get(property); + writer.println("\t" + property + ": " + asString(value)); return false; } writer.println("\t" + property + ": " + DataFileHelper.NEEDS_ENTERPRISE); diff --git a/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java b/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java index 71a7e5aad..76d6886a3 100644 --- a/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java +++ b/examples/ip-intelligence/shared/src/main/java/fiftyone/ipintelligence/examples/shared/PropertyHelper.java @@ -59,10 +59,8 @@ public class PropertyHelper { * Unwrap a value that may be a List of IWeightedValue at runtime * (due to Java generics type erasure, the on-premise engine may return * List<IWeightedValue<T>> even when the declared type is T). - * For single-element lists, returns just the value. - * For multi-element lists, returns values joined with ", ". - * A weighted value is followed by its weighting, as in - * "Japan (weighting 1.00)". + * A list's values are joined with ", ", and a weighted value is + * followed by its weighting, as in "Japan (weighting 1.00)". * @param value the raw value from AspectPropertyValue.getValue() * @return the unwrapped string representation */