From 3842399d76c125b9d7fde52ae3b5e670c1342776 Mon Sep 17 00:00:00 2001 From: James Rosewell Date: Sat, 14 Nov 2026 12:06:57 +0000 Subject: [PATCH] Describe the examples as they run today in AGENTS.md and the example READMEs AGENTS.md said the IP Intelligence example needs the Lite file as an argument and stops without one, that an example started in an examples folder cannot find its data file, and gave output with a pricing link. The examples now default to the Lite file, look for cxx/data in each folder above the one Java runs in, and end with the Enterprise note, the contact link and the Find out more section. The READMEs gave jar names from 4.4.20 and 4.4.19, and the IP Intelligence README named only TestResourceKey for the cloud examples. --- AGENTS.md | 87 ++++++++++++++--------------- examples/device-detection/README.md | 9 +-- examples/ip-intelligence/README.md | 11 ++-- 3 files changed, 55 insertions(+), 52 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index df51ec15e..d299ea6a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,29 +104,33 @@ where `` is the `` in that examples folder's `pom.xml`, ### Run -Run the examples from the repository root. They find `logback.xml`, the data -file and their options file with `FileFinder`, which searches only below the -folder Java runs in (`pipeline/pipeline.core/src/main/java/fiftyone/pipeline/util/FileFinder.java`). -When a free data file is not there, the example finds its `.link` the same way -and runs the download script for it (`findDataFile` in each examples folder's -`shared` module, `DataFileHelper.java`), with Windows PowerShell on Windows and -`sh` on Linux and macOS. The same commands work on Windows, Linux and macOS. +Run the examples from the repository root, or from a product's examples +folder as its README does. They look for the data repository, `cxx/data`, in +the folder Java runs in and then in each folder above it, and find a data file +or its `.link` there (`findDataFile` in each examples folder's `shared` +module, `DataFileHelper.java`). When a free data file is not there, the +example runs the download script for its `.link`, with Windows PowerShell on +Windows and `sh` on Linux and macOS. They find `logback.xml` with +`FileFinder`, which searches below the folder Java runs in +(`pipeline/pipeline.core/src/main/java/fiftyone/pipeline/util/FileFinder.java`), +and the root and both examples folders have one. The same commands work on +Windows, Linux and macOS. ``` java -cp examples/device-detection/console/target/device-detection-java-examples.console-4.5.127-SNAPSHOT-jar-with-dependencies.jar fiftyone.devicedetection.examples.console.GettingStartedOnPrem ``` -The IP Intelligence example looks for the paid Enterprise file, -`ip-intelligence/51Degrees-EnterpriseIpiV41.ipi`, so give it the Lite file as -its first argument. +The IP Intelligence example uses the free Lite file, +`ip-intelligence/51Degrees-LiteV41.ipi`, when it is given no argument, and +downloads it first when it is not there. ``` -java -cp examples/ip-intelligence/console/target/ip-intelligence-java-examples.console-4.5.127-SNAPSHOT-jar-with-dependencies.jar fiftyone.ipintelligence.examples.console.GettingStartedOnPrem cxx/data/ip-intelligence/51Degrees-LiteV41.ipi +java -cp examples/ip-intelligence/console/target/ip-intelligence-java-examples.console-4.5.127-SNAPSHOT-jar-with-dependencies.jar fiftyone.ipintelligence.examples.console.GettingStartedOnPrem ``` -The example downloads the Lite file first when it is not there. In place of -the argument, the `_51DEGREES_IPI_PATH` environment variable or system property -can give the absolute path of a data file that is already there. +An absolute path as the first argument names another data file. Otherwise the +`_51DEGREES_IPI_PATH` environment variable or system property, when it names +a file that is there, comes before the argument or the Lite file. On Java 24 or later, add `--enable-native-access=ALL-UNNAMED` before the class name, as @@ -141,32 +145,29 @@ and the script's `Downloading` and `Saved` lines follow. The Device Detection example processes five sets of evidence. For each it prints `Input values:` and the evidence, then `Results:` with -`Mobile Device`, `Platform Name`, `Platform Version`, `Browser Name` and -`Browser Version`. Logback lines come before and after. The last ones report -the data file and end the run, with these messages. - -``` -Used a 'Lite' data file, created , days ago, from location '' -This example is using the 'Lite ' data file. This is used for illustration, ... -All done -``` - -A warning that the data file is more than 28 days old may come too, which is -expected with the Lite file. The exit code is 0. +`Mobile Device`, `Platform Name`, `Platform Version`, `Browser Name`, +`Browser Version`, `Hardware Vendor`, `Hardware Name` and `Device Type`. The +Lite file does not have the last three, so each of them reads +`needs the Enterprise data file`. 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 -`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 -`All done`. +`TimeZoneOffset`. The Lite file has RegisteredName, RegisteredOwner and +RegisteredCountry, so every other line reads `needs the Enterprise data file`. -The paid data files have many more properties, as the -[pricing page](https://51degrees.com/pricing?utm_source=github&utm_medium=docs&utm_campaign=51degrees-java&utm_content=agents.md&utm_term=correct-output) -describes. +Both then end the same way. + +``` +Some of these properties need the Enterprise data file. Contact us for a copy at https://51degrees.com/contact-us?... +INFO ... Used a 'Lite' data file, created , days ago, from location '' +INFO ... All done +``` + +Then comes the "Find out more" section, between two rules, with the +product's pages on 51degrees.com and the repositories. A warning that the +data file is more than 28 days old may come before `All done`, which is +expected with the Lite file. The exit code is 0. ### Cloud examples @@ -196,16 +197,14 @@ example. The IP Intelligence cloud examples read their key from 'device-detection/51Degrees-LiteV4.1.hash' which must be somewhere in the project space to be found.` Run `git submodule update --init --recursive`. A zip download of the repository has no submodules, so clone with Git. -- **Running from another folder.** `FileFinder` looks only below the folder - Java runs in, so `java` started in `examples/device-detection`, as the - examples' README shows, cannot find the data file or its link in `cxx`. - Start it from the repository root. The same applies to `mvn exec:java`, +- **Running from outside the repository.** An example started in a folder + outside the repository, such as one the jar was copied to, finds no + `cxx/data` above it and no `logback.xml` below it. Start it in the + repository root or a folder inside it. The same applies to `mvn exec:java`, which runs in the folder Maven starts in. -- **The version in the jar name.** The examples' READMEs show jar names with - `4.4.20` and `4.4.19`, which are out of date. Use the name in `target`. -- **The IP Intelligence example without an argument.** It searches for the - Enterprise file, logs `Failed to find IP Intelligence data file` and stops, - even when the Lite file is in place. +- **The version in the jar name.** A jar carries the examples folder's own + ``, `4.5.127-SNAPSHOT` on `rc` today, not the version of the + packages the examples use, `4.5.130`. Use the name in `target`. - **The `dev` profile.** `-Pdev`, which CI uses, builds the examples against the libraries here, which needs `mvn install` at the root first and so the native build, with CMake 3.10 or later and a C++ toolchain. It is not needed diff --git a/examples/device-detection/README.md b/examples/device-detection/README.md index 5e1f575ba..a035c58c1 100644 --- a/examples/device-detection/README.md +++ b/examples/device-detection/README.md @@ -103,12 +103,13 @@ Running mvn package ``` -will produce "fat" JARs inside `target` subfolders. +will produce "fat" JARs inside `target` subfolders. The version in each name is the one in this folder's `pom.xml`, which is not +the version of the packages the examples use. Use them with relevant example class entrypoints like: ```bash -java -cp ./console/target/device-detection-java-examples.console-4.4.20-jar-with-dependencies.jar fiftyone.devicedetection.examples.console.OfflineProcessing +java -cp ./console/target/device-detection-java-examples.console-4.5.127-SNAPSHOT-jar-with-dependencies.jar fiftyone.devicedetection.examples.console.OfflineProcessing ``` ### Web examples @@ -119,7 +120,7 @@ is pressed. Set the `PORT` environment variable to listen on another port, in wh case the example runs until the process is stopped: ```bash -PORT=8100 java -jar ./web/getting-started.onprem/target/device-detection-java-examples.web.getting-started.onprem-4.4.20-jar-with-dependencies.jar +PORT=8100 java -jar ./web/getting-started.onprem/target/device-detection-java-examples.web.getting-started.onprem-4.5.127-SNAPSHOT-jar-with-dependencies.jar ``` The on-premise web example takes its data file from the `_51DEGREES_DD_PATH` @@ -137,7 +138,7 @@ The fat JARs above bundle everything into a single jar on the classpath, so the permission to use is `ALL-UNNAMED`: ```bash -java -cp ./console/target/device-detection-java-examples.console-4.4.20-jar-with-dependencies.jar --enable-native-access=ALL-UNNAMED fiftyone.devicedetection.examples.console.OfflineProcessing +java -cp ./console/target/device-detection-java-examples.console-4.5.127-SNAPSHOT-jar-with-dependencies.jar --enable-native-access=ALL-UNNAMED fiftyone.devicedetection.examples.console.OfflineProcessing ``` With the Maven exec plugin, use the `exec:exec` goal. `exec:java` runs in the Maven JVM diff --git a/examples/ip-intelligence/README.md b/examples/ip-intelligence/README.md index ae3cd8d52..3875b4a26 100644 --- a/examples/ip-intelligence/README.md +++ b/examples/ip-intelligence/README.md @@ -90,8 +90,9 @@ The tables below describe the examples available in this repository. ### Cloud -Cloud examples require a resource key, supplied via the `TestResourceKey` -environment variable, system property, or command line argument. Resource keys +Cloud examples require a resource key, supplied via the `_51DEGREES_RESOURCE_KEY` +environment variable or system property, the legacy `TestResourceKey` name, or a +command line argument. Resource keys for IP Intelligence are not yet generally available, so these examples can also be pointed at a custom hosted cloud endpoint using the `TestCloudEndPoint` environment variable or system property. @@ -199,8 +200,10 @@ mvn package This will produce JARs with dependencies inside `target` subfolders. -Then run examples using the JAR: +Then run examples using the JAR, from this folder. The version in the name is +the one in this folder's `pom.xml`, which is not the version of the packages +the examples use. ```bash -java -cp .\console\target\ip-intelligence-java-examples.console-4.4.19-jar-with-dependencies.jar fiftyone.ipintelligence.examples.console.OfflineProcessing +java -cp ./console/target/ip-intelligence-java-examples.console-4.5.127-SNAPSHOT-jar-with-dependencies.jar fiftyone.ipintelligence.examples.console.OfflineProcessing ```