diff --git a/ci/check-environment-variable-names.ps1 b/ci/check-environment-variable-names.ps1
index 11d75e85c..e193af7c8 100644
--- a/ci/check-environment-variable-names.ps1
+++ b/ci/check-environment-variable-names.ps1
@@ -114,6 +114,8 @@ $script:DeprecatedFallbacks = @{
@($oldDdPath)
"$onPrem/test/java/$onPremPackage/OnPremDataFileOptionTest.java" =
@($oldDdPath)
+ "$onPrem/test/java/$onPremPackage/WebOnPremWithoutSettingsTest.java" =
+ @($oldDdPath)
}
# Whether the text matched in the file at this path, relative to the root
diff --git a/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/GettingStartedOnPrem.java b/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/GettingStartedOnPrem.java
index 067394b73..0620c2562 100644
--- a/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/GettingStartedOnPrem.java
+++ b/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/GettingStartedOnPrem.java
@@ -128,7 +128,11 @@ public static void run(String dataFile,
// load the options and if no resource key has been set in the file
// use the one supplied to this method
PipelineOptions pipelineOptions = PipelineOptionsFactory.getOptionsFromFile(optionsFile);
- // Build a new Pipeline from the configuration.
+ /* Build a new Pipeline from the configuration. The options file sets
+ ShareUsage to false, because this example processes evidence 51Degrees
+ already holds, but in normal operation usage sharing should be enabled
+ by adding a Usage Sharing Element to the Pipeline, which the
+ FiftyOnePipelineBuilder does unless ShareUsage is false. */
try (Pipeline pipeline = new FiftyOnePipelineBuilder()
.buildFromConfiguration(pipelineOptions)) {
diff --git a/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/ShareUsageExample.java b/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/ShareUsageExample.java
index bd28e5cfd..e8369b735 100644
--- a/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/ShareUsageExample.java
+++ b/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/ShareUsageExample.java
@@ -120,8 +120,21 @@ public static void main(String[] args) throws Exception {
*
* @param is an InputStream containing YAML documents with evidence
*/
- @SuppressWarnings("unchecked")
public static void run(InputStream is) throws Exception {
+ run(is, null);
+ }
+
+ /**
+ * Process evidence from a YAML input stream and share it via the
+ * ShareUsageElement, sending it to the endpoint given.
+ *
+ * @param is an InputStream containing YAML documents with evidence
+ * @param shareUsageUrl where to send the usage data, or null for the
+ * 51Degrees endpoint. A test gives an endpoint of
+ * its own, so that it shares nothing.
+ */
+ @SuppressWarnings("unchecked")
+ public static void run(InputStream is, String shareUsageUrl) throws Exception {
logger.info("Starting ShareUsage example");
logger.info("Settings: minEntriesPerMessage={}, sharePercentage={}%, recordsToProcess={}",
MINIMUM_ENTRIES_PER_MESSAGE,
@@ -129,7 +142,12 @@ public static void run(InputStream is) throws Exception {
RECORDS_TO_PROCESS);
// Build the ShareUsageElement with custom settings
- ShareUsageElement shareUsageElement = new ShareUsageBuilder(LoggerFactory.getILoggerFactory())
+ ShareUsageBuilder builder = new ShareUsageBuilder(LoggerFactory.getILoggerFactory());
+ if (shareUsageUrl != null) {
+ // Send to another endpoint than the 51Degrees one
+ builder.setShareUsageUrl(shareUsageUrl);
+ }
+ ShareUsageElement shareUsageElement = builder
// Set the minimum number of entries before sending a batch
.setMinimumEntriesPerMessage(MINIMUM_ENTRIES_PER_MESSAGE)
// Set the maximum queue size (must be > minEntriesPerMessage)
diff --git a/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/UpdateDataFile.java b/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/UpdateDataFile.java
index a56b78bbb..d8f5d60cc 100644
--- a/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/UpdateDataFile.java
+++ b/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/UpdateDataFile.java
@@ -26,7 +26,11 @@
import fiftyone.devicedetection.DeviceDetectionPipelineBuilder;
import fiftyone.devicedetection.examples.shared.DataFileHelper;
import fiftyone.devicedetection.examples.shared.KeyHelper;
+import fiftyone.devicedetection.hash.engine.onpremise.flowelements.DeviceDetectionHashEngine;
import fiftyone.pipeline.core.flowelements.Pipeline;
+import fiftyone.pipeline.engines.data.AspectData;
+import fiftyone.pipeline.engines.data.AspectPropertyMetaData;
+import fiftyone.pipeline.engines.flowelements.OnPremiseAspectEngine;
import fiftyone.pipeline.engines.services.DataUpdateService;
import fiftyone.pipeline.engines.services.DataUpdateServiceDefault;
import fiftyone.pipeline.engines.services.OnUpdateComplete;
@@ -53,11 +57,12 @@
* device detection engine, and controls when a new data file is sought and when it is loaded by
* the device detection software.
*
- * Three main aspects are demonstrated:
+ * Four main aspects are demonstrated:
*
*
Update on Start-Up
*
Filesystem Watcher
*
Daily auto-update
+ *
Programmatic update
*
* ## License Key
* Updating the data file needs a 51Degrees licence key for the Enterprise data file. Without
@@ -165,6 +170,16 @@
* ``` {java}
.setUpdateRandomisationMax(10*60)
* ```
+ * ## Programmatic update
+ * Your own code can ask for an update at a time it chooses, for example from a scheduled job
+ * with automatic updates turned off. The data update service checks for a newer data file,
+ * downloads it and refreshes the engine.
+ * ``` {java}
+ * DataUpdateService.AutoUpdateStatus status = dataUpdateService.checkForUpdate(
+ * pipeline.getElement(DeviceDetectionHashEngine.class));
+ * ```
+ * To load a data file that your own process has put in place, call the engine's
+ * `refreshData(null)` instead.
* # Location
* This example is available in full on [GitHub](https://github.com/51Degrees/51degrees-java/blob/main/examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/UpdateDataFile.java).
*
@@ -176,11 +191,12 @@
* device detection engine, and controls when a new data file is sought and when it is loaded by
* the device detection software.
*
- * Three main aspects are demonstrated:
+ * Four main aspects are demonstrated:
*
*
Update on Start-Up
*
Filesystem Watcher
*
Daily auto-update
+ *
Programmatic update
*
*
* To update the data file you need a licence key, which you can ask for on our
@@ -368,11 +384,40 @@ static void run(String dataFilename, String licenseKey, boolean interactive) thr
completionListener.args.getStatus());
}
+ // Programmatic (non-automatic) update: ask for an update now,
+ // rather than wait for the next scheduled check. The file
+ // just loaded is the newest, so the status is normally
+ // AUTO_UPDATE_NOT_NEEDED.
+ DeviceDetectionHashEngine engine =
+ pipeline.getElement(DeviceDetectionHashEngine.class);
+ logger.info("Programmatic update complete, status: {}",
+ updateNow(dataUpdateService, engine));
+
logger.info("Finished Example");
}
}
}
+ /**
+ * A programmatic (non-automatic) update. The data update service checks
+ * now for a newer data file for the engine, downloads it if there is
+ * one, and refreshes the engine with it, as an automatic update does.
+ * Call this when your own code decides it is time to update, for
+ * example from a scheduled job, with automatic updates turned off.
+ * To load a file that your own process has put in place, call the
+ * engine's {@code refreshData(null)} instead.
+ * @param dataUpdateService the service the pipeline was built with
+ * @param engine the on-premise engine to update
+ * @return the status of the update, such as AUTO_UPDATE_SUCCESS, or
+ * AUTO_UPDATE_NOT_NEEDED when the file in use is the newest
+ */
+ static DataUpdateService.AutoUpdateStatus updateNow(
+ DataUpdateService dataUpdateService,
+ OnPremiseAspectEngine extends AspectData,
+ ? extends AspectPropertyMetaData> engine) {
+ return dataUpdateService.checkForUpdate(engine);
+ }
+
/**
* Without a licence key the example cannot download a data file, so it
* shows the data file it would start from, the free Lite file unless
diff --git a/examples/device-detection/console/src/main/resources/gettingStartedOnPrem.xml b/examples/device-detection/console/src/main/resources/gettingStartedOnPrem.xml
index ee634b786..520b105bb 100644
--- a/examples/device-detection/console/src/main/resources/gettingStartedOnPrem.xml
+++ b/examples/device-detection/console/src/main/resources/gettingStartedOnPrem.xml
@@ -14,4 +14,13 @@
JavaScriptBuilderElement
-->
+
+
+ false
+
diff --git a/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/CloudDropInTest.java b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/CloudDropInTest.java
new file mode 100644
index 000000000..9d4eaabe4
--- /dev/null
+++ b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/CloudDropInTest.java
@@ -0,0 +1,152 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.devicedetection.examples.console;
+
+import com.sun.net.httpserver.HttpServer;
+import fiftyone.devicedetection.DeviceDetectionPipelineBuilder;
+import fiftyone.devicedetection.shared.DeviceData;
+import fiftyone.pipeline.core.data.ElementData;
+import fiftyone.pipeline.core.data.FlowData;
+import fiftyone.pipeline.core.flowelements.Pipeline;
+import fiftyone.pipeline.engines.data.AspectPropertyValue;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+
+import static fiftyone.pipeline.util.FileFinder.getFilePath;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * A cloud engine is a drop-in replacement for an on-premise engine: the
+ * same code reads the results of either
+ * (device-detection-specification/usage-examples.md, "In particular, a
+ * cloud Engine MUST be a drop-in replacement for an on-premise Engine for
+ * performing Device Detection and querying the results", and "However,
+ * once created, usage SHOULD be as similar as possible").
+ *
+ * {@link #isMobile(Pipeline)} is that code. It reads the result by its type,
+ * by the element data key "device", and a property by name, and it is given
+ * a cloud pipeline and an on-premise one. The cloud pipeline talks to a
+ * stand-in for the cloud service that this test starts on this machine, so
+ * no resource key or network is needed. The on-premise pipeline uses the
+ * free Lite data file, which a fresh clone fetches from the data
+ * repository; the test does not download it.
+ */
+public class CloudDropInTest {
+
+ private static final String IPHONE =
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) " +
+ "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 " +
+ "Mobile/15E148 Safari/604.1";
+
+ private HttpServer cloud;
+
+ @Before
+ public void startCloud() throws Exception {
+ cloud = HttpServer.create(
+ new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
+ cloud.createContext("/", exchange -> {
+ try (InputStream body = exchange.getRequestBody()) {
+ byte[] buffer = new byte[4096];
+ while (body.read(buffer) >= 0) {
+ // Read the whole request before answering.
+ }
+ }
+ String path = exchange.getRequestURI().getPath();
+ String answer;
+ if (path.endsWith("accessibleproperties")) {
+ answer = "{\"Products\":{\"device\":{\"DataTier\":\"Lite\"," +
+ "\"Properties\":[{\"Name\":\"IsMobile\"," +
+ "\"Type\":\"Boolean\",\"Category\":\"Device\"}]}}}";
+ } else if (path.endsWith("evidencekeys")) {
+ answer = "[\"header.user-agent\"]";
+ } else {
+ answer = "{\"device\":{\"ismobile\":true}," +
+ "\"javascriptProperties\":[]}";
+ }
+ byte[] bytes = answer.getBytes(StandardCharsets.UTF_8);
+ exchange.getResponseHeaders().add("Content-Type",
+ "application/json");
+ exchange.sendResponseHeaders(200, bytes.length);
+ try (OutputStream out = exchange.getResponseBody()) {
+ out.write(bytes);
+ }
+ });
+ cloud.start();
+ }
+
+ @After
+ public void stopCloud() {
+ cloud.stop(0);
+ }
+
+ /**
+ * The code a developer writes once, for either engine.
+ */
+ private static boolean isMobile(Pipeline pipeline) throws Exception {
+ try (FlowData data = pipeline.createFlowData()) {
+ data.addEvidence("header.user-agent", IPHONE).process();
+ DeviceData device = data.get(DeviceData.class);
+ ElementData byKey = data.get("device");
+ assertSame("The result read by type and by the key 'device' " +
+ "should be the same", device, byKey);
+ Object byName = byKey.get("ismobile");
+ assertTrue("The property read by name should be a value " +
+ "with a reason when it has none, and was " + byName,
+ byName instanceof AspectPropertyValue);
+ return device.getIsMobile().getValue();
+ }
+ }
+
+ @Test
+ public void cloudResultsReadAsOnPremise() throws Exception {
+ String endPoint = "http://" + cloud.getAddress().getHostString() +
+ ":" + cloud.getAddress().getPort() + "/api/v4/";
+ try (Pipeline pipeline = new DeviceDetectionPipelineBuilder()
+ .useCloud("dropinresourcekey")
+ .setEndPoint(endPoint)
+ .build()) {
+ assertTrue(isMobile(pipeline));
+ }
+ }
+
+ @Test
+ public void onPremiseResultsReadAsCloud() throws Exception {
+ String file = getFilePath("device-detection/51Degrees-LiteV4.1.hash")
+ .getAbsolutePath();
+ try (Pipeline pipeline = new DeviceDetectionPipelineBuilder()
+ .useOnPremise(file, false)
+ .setAutoUpdate(false)
+ .setShareUsage(false)
+ .build()) {
+ assertTrue(isMobile(pipeline));
+ }
+ }
+}
diff --git a/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/ConsoleConfigurationCoverageTest.java b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/ConsoleConfigurationCoverageTest.java
new file mode 100644
index 000000000..ffa2e69cd
--- /dev/null
+++ b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/ConsoleConfigurationCoverageTest.java
@@ -0,0 +1,81 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.devicedetection.examples.console;
+
+import fiftyone.pipeline.core.configuration.ElementOptions;
+import fiftyone.pipeline.core.configuration.PipelineOptions;
+import fiftyone.pipeline.core.configuration.PipelineOptionsFactory;
+import org.junit.Test;
+
+import java.io.File;
+import java.net.URL;
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * The console examples show both ways of making a pipeline, for both
+ * on-premise and cloud: the fluent builder (GettingStartedCloud and the
+ * other on-premise consoles, run by their own tests) and an options file,
+ * checked here without a data file or a key, as the tests that run the
+ * examples need one or the other
+ * (device-detection-specification/required-examples.md, "Examples MUST be
+ * provided that illustrate basic usage of the API for both Cloud and
+ * On-Prem, using fluent builder and options file configuration, when
+ * executed as a console (command line) application").
+ */
+public class ConsoleConfigurationCoverageTest {
+
+ /**
+ * The builders an options file names, reading the file this example
+ * module holds in its resources, so that a file of the same name in
+ * another example cannot be read in its place.
+ */
+ private static List builders(String file) throws Exception {
+ URL resource =
+ ConsoleConfigurationCoverageTest.class.getResource("/" + file);
+ assertNotNull("The example's resources hold no " + file, resource);
+ PipelineOptions options = PipelineOptionsFactory.getOptionsFromFile(
+ new File(resource.toURI()));
+ List names = new ArrayList<>();
+ for (ElementOptions element : options.elements) {
+ names.add(element.builderName);
+ }
+ return names;
+ }
+
+ @Test
+ public void onPremiseOptionsFile() throws Exception {
+ List builders = builders("gettingStartedOnPrem.xml");
+ assertTrue(builders.toString(),
+ builders.contains("DeviceDetectionHashEngine"));
+ }
+
+ @Test
+ public void cloudOptionsFile() throws Exception {
+ List builders = builders("tacCloud.xml");
+ assertTrue(builders.toString(), builders.contains("CloudRequestEngine"));
+ }
+}
diff --git a/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/GettingStartedOnPremUsageSharingTest.java b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/GettingStartedOnPremUsageSharingTest.java
new file mode 100644
index 000000000..d7eb7662d
--- /dev/null
+++ b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/GettingStartedOnPremUsageSharingTest.java
@@ -0,0 +1,93 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.devicedetection.examples.console;
+
+import fiftyone.pipeline.core.configuration.PipelineOptions;
+import fiftyone.pipeline.core.configuration.PipelineOptionsFactory;
+import fiftyone.pipeline.core.flowelements.FlowElement;
+import fiftyone.pipeline.core.flowelements.Pipeline;
+import fiftyone.pipeline.engines.fiftyone.flowelements.FiftyOnePipelineBuilder;
+import fiftyone.pipeline.engines.fiftyone.flowelements.ShareUsageElement;
+import org.junit.Test;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+
+import static fiftyone.pipeline.util.FileFinder.getFilePath;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * The on-premise getting started console example does not share usage
+ * (device-detection-specification/required-examples.md, "Reference
+ * implementations inhibit usage sharing for console examples by ensuring the
+ * Usage Sharing Element is not added to the Pipeline, but enable it for web
+ * examples", and "Every example in which usage sharing is inhibited needs to
+ * have a comment saying that in normal operation usage sharing should be
+ * enabled by adding a Usage Sharing Element to the Pipeline").
+ *
+ * The example builds its Pipeline from its options file with the
+ * FiftyOnePipelineBuilder, which adds a Usage Sharing Element unless told
+ * not to. The test builds the Pipeline from the same file in the same way,
+ * without the engine, which needs a data file, and checks that no Usage
+ * Sharing Element is added. Building shares nothing; only processing does.
+ */
+public class GettingStartedOnPremUsageSharingTest {
+
+ private static final String OPTIONS =
+ "examples/device-detection/console/src/main/resources/gettingStartedOnPrem.xml";
+
+ private static final String SOURCE =
+ "examples/device-detection/console/src/main/java/fiftyone/devicedetection/examples/console/GettingStartedOnPrem.java";
+
+ private static String read(String path) throws Exception {
+ File file = getFilePath(path);
+ return new String(Files.readAllBytes(file.toPath()),
+ StandardCharsets.UTF_8).replaceAll("\\s+", " ");
+ }
+
+ @Test
+ public void pipelineHasNoUsageSharingElement() throws Exception {
+ PipelineOptions options =
+ PipelineOptionsFactory.getOptionsFromFile(getFilePath(OPTIONS));
+ options.elements.clear();
+ try (Pipeline pipeline = new FiftyOnePipelineBuilder()
+ .buildFromConfiguration(options)) {
+ for (FlowElement, ?> element : pipeline.getFlowElements()) {
+ assertFalse("The example's Pipeline should not share usage",
+ element instanceof ShareUsageElement);
+ }
+ }
+ }
+
+ @Test
+ public void commentSaysToShareUsageInProduction() throws Exception {
+ String expected = "in normal operation usage sharing should be " +
+ "enabled by adding a Usage Sharing Element to the Pipeline";
+ assertTrue("The options file should say " + expected,
+ read(OPTIONS).contains(expected));
+ assertTrue("The example should say " + expected,
+ read(SOURCE).contains(expected));
+ }
+}
diff --git a/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/ProgrammaticUpdateTest.java b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/ProgrammaticUpdateTest.java
new file mode 100644
index 000000000..b14f856da
--- /dev/null
+++ b/examples/device-detection/console/src/test/java/fiftyone/devicedetection/examples/console/ProgrammaticUpdateTest.java
@@ -0,0 +1,95 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.devicedetection.examples.console;
+
+import fiftyone.pipeline.engines.flowelements.OnPremiseAspectEngine;
+import fiftyone.pipeline.engines.services.DataUpdateService;
+import org.junit.Test;
+
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+
+/**
+ * The data update example illustrates a programmatic (non-automatic)
+ * update as well as update on start-up, the file system watcher and
+ * polling (device-detection-specification/required-examples.md, "The data
+ * update service has a range of options available. Implementors SHOULD
+ * illustrate:", the last of which is "programmatic (non-automatic)
+ * update").
+ *
+ * An update needs a licence key and the Enterprise data file, so the test
+ * gives the example's update step a stand-in service and engine, and checks
+ * that the step asks the service to check for an update of that engine now
+ * and gives back the status the service answers.
+ */
+public class ProgrammaticUpdateTest {
+
+ /**
+ * A stand-in for an interface that answers Object's methods and records
+ * every other call.
+ */
+ @SuppressWarnings("unchecked")
+ private static T standIn(Class type, List