diff --git a/AGENTS.md b/AGENTS.md index df51ec15..d299ea6a 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 5e1f575b..a035c58c 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 ae3cd8d5..3875b4a2 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 ```