diff --git a/.github/workflows/examples-fresh-clone.yml b/.github/workflows/examples-fresh-clone.yml index eb7d8e1ad..c2974cc41 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 + -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/AGENTS.md b/AGENTS.md index 3d495c2ae..bd7f29bdb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,8 +155,10 @@ Lite file does not have the last three, so each of them reads 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 RegisteredName, RegisteredOwner and -RegisteredCountry, so every other line reads `needs the Enterprise data file`. +`TimeZoneOffset`. Each value is followed by its weighting, as in +`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/ci/run-fresh-clone-example.Tests.ps1 b/ci/run-fresh-clone-example.Tests.ps1 index edc3e7176..28deef366 100644 --- a/ci/run-fresh-clone-example.Tests.ps1 +++ b/ci/run-fresh-clone-example.Tests.ps1 @@ -118,6 +118,21 @@ Describe 'run-fresh-clone-example.ps1 called with pwsh -File' { } } +Describe 'run-fresh-clone-example.ps1 given text the output must hold' { + + It 'passes when the output holds the text' { + $run = Invoke-File 'FromCache' @('-Expect', 'Results:') + $run.Text | Should -Not -Match '::error::' + $run.Code | Should -Be 0 + } + + It 'fails when the output does not hold the text' { + $run = Invoke-File 'FromCache' @('-Expect', '(weighting ') + $run.Text | Should -Match "::error::The example's output does not hold '\(weighting '\." + $run.Code | Should -Be 1 + } +} + Describe 'run-fresh-clone-example.ps1 called as the workflow calls it' { It 'finds both of the workflow''s calls' -ForEach @( @@ -134,6 +149,9 @@ Describe 'run-fresh-clone-example.ps1 called as the workflow calls it' { $quoted = $script:Script.Replace("'", "''") $call = $Command.Replace('./ci/run-fresh-clone-example.ps1', "& '$quoted'") $call = $call.Replace('${{ matrix.product }}', 'device-detection') + # The stand-in prints no weighting, so the expected text is the one + # the device-detection entries give, which is none. + $call = $call.Replace('${{ matrix.expect }}', '') $call = "`$ErrorActionPreference = 'stop'`n$call`n" + "if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit `$LASTEXITCODE }" $expected, $other = if ($Job -eq 'download') { diff --git a/ci/run-fresh-clone-example.ps1 b/ci/run-fresh-clone-example.ps1 index 137feec70..c3d9474ee 100644 --- a/ci/run-fresh-clone-example.ps1 +++ b/ci/run-fresh-clone-example.ps1 @@ -5,13 +5,16 @@ param ( # has to download the file. Left out, or given as -ExpectDownload:$false, # where the file is already in place. A switch, so that it works the same # with pwsh -File, which passes every other value as a string. - [switch]$ExpectDownload + [switch]$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 @@ -41,6 +44,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 } 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 68b45b83b..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 @@ -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; @@ -58,8 +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 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 */ @@ -73,8 +74,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"; }) 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