Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
b627d35
Test: the usage sharing example has a unit test
jwrosewell Nov 15, 2026
57ecdd2
Fix: the usage sharing example can send to an endpoint it is given, s…
jwrosewell Nov 15, 2026
f234c41
Test: each example runs with no arguments or settings, as from a fres…
jwrosewell Nov 15, 2026
84f79fa
Fix: the cloud examples end without an error when no resource key is …
jwrosewell Nov 15, 2026
c4f644a
Test: the comparison runs out of the box with the free data file
jwrosewell Nov 15, 2026
b157f26
Fix: the comparison uses the free Lite data file when there is no Ent…
jwrosewell Nov 15, 2026
ed5c951
Test: the comparison shows what only the Enterprise data file can do
jwrosewell Nov 15, 2026
6ca2304
Fix: the comparison shows the properties it found, says which need th…
jwrosewell Nov 15, 2026
fdbb543
Test: there is an example for the Derived Property Element that runs …
jwrosewell Nov 15, 2026
fd0aaf9
Fix: add the Derived Property Element, reading scripts in format 1, a…
jwrosewell Nov 15, 2026
4d4998a
Test: the Derived Property Element example shows a script in code, a …
jwrosewell Nov 15, 2026
4829a19
Fix: the Derived Property Element example reads a script from a file …
jwrosewell Nov 15, 2026
90198fa
Test: the Derived Property Element example shows a source property th…
jwrosewell Nov 15, 2026
97a7a5b
Fix: the Derived Property Element example shows a reading with no hum…
jwrosewell Nov 15, 2026
92dbd8e
Test: the on-premise web example sets and documents suppressing proce…
jwrosewell Nov 15, 2026
85adf05
Test: the console examples make pipelines from options files for on-p…
jwrosewell Nov 15, 2026
51569ef
Test: the same code reads the results of the cloud engine and the on-…
jwrosewell Nov 15, 2026
07b0874
Test: the client-side element example builds, runs in a Pipeline and …
jwrosewell Nov 15, 2026
a7b03e3
Fix: the client-side element example compares dates of birth by day a…
jwrosewell Nov 15, 2026
b638246
Test: each cloud example run with no resource key ends without an err…
jwrosewell Nov 15, 2026
f4062c0
Test: the link to the configurator itself, not another link, is tagge…
jwrosewell Nov 15, 2026
682d273
Fix: each cloud example given no resource key says which variable to …
jwrosewell Nov 15, 2026
a816cd7
Test: the data update example illustrates a programmatic update, aski…
jwrosewell Nov 15, 2026
e9e98cd
Fix: the data update example illustrates a programmatic update, askin…
jwrosewell Nov 15, 2026
3c61c50
Test: the web examples illustrate obtaining high entropy values by th…
jwrosewell Nov 15, 2026
e89a0ee
Fix: the web examples' pages say how they obtain high entropy values,…
jwrosewell Nov 15, 2026
ffb3dc8
Test: every Flow Element in the repository is made by its builder cla…
jwrosewell Nov 15, 2026
ed039e9
Fix: the translation engines' base class is abstract, so a translatio…
jwrosewell Nov 15, 2026
117cf46
Test: the on-premise getting started console example adds no Usage Sh…
jwrosewell Nov 15, 2026
c0203ce
Fix: the on-premise getting started console example turns usage shari…
jwrosewell Nov 15, 2026
efc7b8c
Fix: put the note that the translation engines' base class is abstrac…
jwrosewell Nov 15, 2026
dc71201
Merge rc into the section 5 conformance work
jwrosewell Nov 16, 2026
3b3a671
Fix: list the new web example test as reading the old data file name,…
jwrosewell Nov 16, 2026
7a8ae6d
Merge rc into the examples work
jwrosewell Nov 16, 2026
8a20d1e
Use the examples' own key check in hasResourceKey
jwrosewell Nov 16, 2026
77914ce
Take Comparer and its test off the deprecated FileUtils
jwrosewell Nov 16, 2026
bd93f86
Leave the Derived Property Element, Comparer and the cloud examples w…
jwrosewell Nov 16, 2026
06ac80d
Read each options file from the example's own resources in the config…
jwrosewell Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions ci/check-environment-variable-names.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)) {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -120,16 +120,34 @@ 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,
(int)(SHARE_PERCENTAGE * 100),
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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
* <p>
* Three main aspects are demonstrated:
* Four main aspects are demonstrated:
* <ol>
* <li>Update on Start-Up</li>
* <li>Filesystem Watcher</li>
* <li>Daily auto-update</li>
* <li>Programmatic update</li>
* </ol>
* ## License Key
* Updating the data file needs a 51Degrees licence key for the Enterprise data file. Without
Expand Down Expand Up @@ -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).
*
Expand All @@ -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.
* <p>
* Three main aspects are demonstrated:
* Four main aspects are demonstrated:
* <ol>
* <li>Update on Start-Up</li>
* <li>Filesystem Watcher</li>
* <li>Daily auto-update</li>
* <li>Programmatic update</li>
* </ol>
* <p>
* To update the data file you need a licence key, which you can ask for on our
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,13 @@
<BuilderName>JavaScriptBuilderElement</BuilderName>
</Element>
--> </Elements>
<BuildParameters>
<!--
This example processes evidence 51Degrees already holds, so it does
not share usage, but in normal operation usage sharing should be
enabled by adding a Usage Sharing Element to the Pipeline, which the
FiftyOnePipelineBuilder does when ShareUsage is true, its default.
-->
<ShareUsage>false</ShareUsage>
</BuildParameters>
</PipelineOptions>
Original file line number Diff line number Diff line change
@@ -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));
}
}
}
Loading
Loading