diff --git a/device-detection/device-detection.cloud/src/test/java/fiftyone/devicedetection/cloud/flowelements/ElementDataKeyFormatTests.java b/device-detection/device-detection.cloud/src/test/java/fiftyone/devicedetection/cloud/flowelements/ElementDataKeyFormatTests.java new file mode 100644 index 000000000..59fd7698c --- /dev/null +++ b/device-detection/device-detection.cloud/src/test/java/fiftyone/devicedetection/cloud/flowelements/ElementDataKeyFormatTests.java @@ -0,0 +1,69 @@ +/* ********************************************************************* + * 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.cloud.flowelements; + +import org.junit.Test; +import org.slf4j.Logger; + +import java.util.Locale; + +import static org.junit.Assert.assertTrue; +import static org.mockito.Mockito.mock; + +/** + * The string key of each Device Detection cloud engine's data contains only + * alphanumeric characters, full stop or hyphen. + *

+ * Specification: pipeline-specification/features/access-to-results.md line 7 + * at 51Degrees/specifications 706de1f0, "Strings SHOULD only contain + * alphanumeric characters, full stop or hyphen." + */ +public class ElementDataKeyFormatTests { + + private static String[] keys() { + return new String[] { + new DeviceDetectionCloudEngine(mock(Logger.class), null) + .getElementDataKey(), + new HardwareProfileCloudEngine(mock(Logger.class), null) + .getElementDataKey() + }; + } + + @Test + public void keys_OnlyAlphanumericFullStopOrHyphen() { + for (String key : keys()) { + assertTrue(key, key.matches("[A-Za-z0-9.-]+")); + } + } + + /** + * Specification: access-to-results.md line 10, "Lower-case SHOULD be + * used." + */ + @Test + public void keys_LowerCase() { + for (String key : keys()) { + assertTrue(key, key.equals(key.toLowerCase(Locale.ROOT))); + } + } +} diff --git a/device-detection/device-detection.hash.engine.on-premise/src/test/java/fiftyone/devicedetection/hash/engine/onpremise/flowelements/PropertyMetaDataTests.java b/device-detection/device-detection.hash.engine.on-premise/src/test/java/fiftyone/devicedetection/hash/engine/onpremise/flowelements/PropertyMetaDataTests.java new file mode 100644 index 000000000..edd639ed9 --- /dev/null +++ b/device-detection/device-detection.hash.engine.on-premise/src/test/java/fiftyone/devicedetection/hash/engine/onpremise/flowelements/PropertyMetaDataTests.java @@ -0,0 +1,102 @@ +/* ********************************************************************* + * 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.hash.engine.onpremise.flowelements; + +import fiftyone.pipeline.engines.Constants; +import fiftyone.pipeline.engines.fiftyone.data.FiftyOneAspectPropertyMetaData; +import org.junit.Test; +import org.slf4j.LoggerFactory; + +import java.io.File; + +import static fiftyone.devicedetection.shared.testhelpers.TestFileUtils.LITE_HASH_DATA_FILE_PATH; +import static fiftyone.pipeline.util.FileFinder.getFilePath; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertNotNull; +import static org.junit.Assert.assertTrue; +import static org.junit.Assume.assumeTrue; + +/** + * Every Property of the Hash engine has the metadata an Aspect Engine must + * add to that of a Flow Element: a description, and the data tiers where the + * Property is present. + *

+ * Specification: pipeline-specification/features/properties.md line 101 at + * 51Degrees/specifications 706de1f0, "Aspect Engines are REQUIRED to + * populate some additional metadata values beyond those described for Flow + * Elements.", with lines 108 and 109 naming Description and Data tiers where + * present. + */ +public class PropertyMetaDataTests { + + @Test + public void everyProperty_HasDescriptionAndDataTiers() throws Exception { + File dataFile = null; + try { + dataFile = getFilePath(LITE_HASH_DATA_FILE_PATH); + } catch (IllegalArgumentException e) { + assumeTrue(e.getMessage(), false); + } + + try (DeviceDetectionHashEngine engine = + new DeviceDetectionHashEngineBuilder( + LoggerFactory.getILoggerFactory(), null) + .setPerformanceProfile( + Constants.PerformanceProfiles.LowMemory) + .setAutoUpdate(false) + .build(dataFile.toString(), false)) { + String tier = engine.getDataSourceTier(); + assertFalse(engine.getProperties().isEmpty()); + for (FiftyOneAspectPropertyMetaData property : + engine.getProperties()) { + String name = property.getName(); + assertNotNull(name + " has a description", + property.getDescription()); + assertFalse(name + " has a description", + property.getDescription().trim().isEmpty()); + assertNotNull(name + " has data tiers", + property.getDataTiersWherePresent()); + assertFalse(name + " has data tiers", + property.getDataTiersWherePresent().isEmpty()); + if (property.isAvailable()) { + assertTrue( + name + " is in the data file, so its tiers name " + + "the data file's tier '" + tier + "'", + containsIgnoringCase( + property.getDataTiersWherePresent(), tier)); + } + } + } + } + + private static boolean containsIgnoringCase( + Iterable values, + String value) { + for (String candidate : values) { + if (candidate.equalsIgnoreCase(value)) { + return true; + } + } + return false; + } +} diff --git a/device-detection/device-detection.shared/src/main/java/fiftyone/devicedetection/shared/DeviceDataBaseOnPremise.java b/device-detection/device-detection.shared/src/main/java/fiftyone/devicedetection/shared/DeviceDataBaseOnPremise.java index fcf900ce6..65fdd26f3 100644 --- a/device-detection/device-detection.shared/src/main/java/fiftyone/devicedetection/shared/DeviceDataBaseOnPremise.java +++ b/device-detection/device-detection.shared/src/main/java/fiftyone/devicedetection/shared/DeviceDataBaseOnPremise.java @@ -29,6 +29,7 @@ import fiftyone.pipeline.engines.data.AspectData; import fiftyone.pipeline.engines.data.AspectPropertyMetaData; import fiftyone.pipeline.engines.data.AspectPropertyValue; +import fiftyone.pipeline.engines.data.ProvidesValuesAsString; import fiftyone.pipeline.engines.flowelements.AspectEngine; import fiftyone.pipeline.engines.services.MissingPropertyService; import org.slf4j.Logger; @@ -42,7 +43,8 @@ /** * Base class used for all 51Degrees on-premise device detection results classes. */ -public abstract class DeviceDataBaseOnPremise extends DeviceDataBase { +public abstract class DeviceDataBaseOnPremise extends DeviceDataBase + implements ProvidesValuesAsString { protected final Map, Class> primitiveTypes; private final Object dataLock = new Object(); @@ -93,6 +95,25 @@ public abstract AspectPropertyValue> getValues( protected abstract AspectPropertyValue getValueAsString( String propertyName); + /** + * {@inheritDoc} + *

+ * The Property is first read through its typed accessor, so a Property + * that is not in the results throws, and a lazy loaded result is waited + * for, exactly as for that accessor. + */ + @SuppressWarnings("unchecked") + @Override + public AspectPropertyValue getStoredValueAsString( + String propertyName) { + getAs(propertyName, + AspectPropertyValue.class, + getPropertyType(propertyName)); + synchronized (getLock) { + return getValueAsString(propertyName); + } + } + /** * Get the value for the specified property as an {@link Integer}. If the * property cannot be represented as an {@link Integer}, then the result diff --git a/device-detection/device-detection/src/test/java/fiftyone/devicedetection/data/StoredValueAsStringTests.java b/device-detection/device-detection/src/test/java/fiftyone/devicedetection/data/StoredValueAsStringTests.java new file mode 100644 index 000000000..b6cd95da4 --- /dev/null +++ b/device-detection/device-detection/src/test/java/fiftyone/devicedetection/data/StoredValueAsStringTests.java @@ -0,0 +1,227 @@ +/* ********************************************************************* + * 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.data; + +import fiftyone.devicedetection.shared.DeviceDataBaseOnPremise; +import fiftyone.pipeline.core.data.ElementPropertyMetaData; +import fiftyone.pipeline.core.data.ElementPropertyMetaDataDefault; +import fiftyone.pipeline.core.data.FlowData; +import fiftyone.pipeline.core.data.types.JavaScript; +import fiftyone.pipeline.core.flowelements.Pipeline; +import fiftyone.pipeline.engines.data.AspectData; +import fiftyone.pipeline.engines.data.AspectPropertyMetaData; +import fiftyone.pipeline.engines.data.AspectPropertyValue; +import fiftyone.pipeline.engines.data.AspectPropertyValueDefault; +import fiftyone.pipeline.engines.data.ProvidesValuesAsString; +import fiftyone.pipeline.engines.exceptions.PropertyMissingException; +import fiftyone.pipeline.engines.flowelements.AspectEngine; +import fiftyone.pipeline.engines.services.MissingPropertyReason; +import fiftyone.pipeline.engines.services.MissingPropertyResult; +import fiftyone.pipeline.engines.services.MissingPropertyService; +import org.junit.Before; +import org.junit.Test; +import org.slf4j.Logger; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.TreeMap; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertTrue; +import static org.junit.Assert.fail; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * On-premise Device Data holds Property values as strings, and the string + * stored for a Property can be read as well as the parsed value. + *

+ * Specification: pipeline-specification/features/access-to-results.md lines + * 65 to 67 at 51Degrees/specifications 706de1f0, "Where an Element Data + * instance holds Property values as strings and parses them into the type + * each Property declares, it SHOULD be possible to get the stored string for + * a Property as well as the parsed value.", and value-types.md lines 39 to + * 53 for what an implementation offering it must do. + */ +public class StoredValueAsStringTests { + + private static final String MISSING_DESCRIPTION = "Not in this file."; + + private TestData data; + + @Before + @SuppressWarnings("unchecked") + public void init() { + AspectEngine + engine = mock(AspectEngine.class); + when(engine.getElementDataKey()).thenReturn("device"); + Map properties = + new TreeMap<>(String.CASE_INSENSITIVE_ORDER); + properties.put("ismobile", new ElementPropertyMetaDataDefault( + "ismobile", engine, "category", Boolean.class, true)); + properties.put("screenpixelswidth", new ElementPropertyMetaDataDefault( + "screenpixelswidth", engine, "category", Integer.class, true)); + Map> available = + new HashMap<>(); + available.put("device", properties); + Pipeline pipeline = mock(Pipeline.class); + when(pipeline.getElementAvailableProperties()).thenReturn(available); + FlowData flowData = mock(FlowData.class); + when(flowData.getPipeline()).thenReturn(pipeline); + MissingPropertyService missing = mock(MissingPropertyService.class); + when(missing.getMissingPropertyReason(anyString(), any(List.class))) + .thenReturn(new MissingPropertyResult( + MissingPropertyReason.DataFileUpgradeRequired, + MISSING_DESCRIPTION)); + + Map stored = new HashMap<>(); + stored.put("ismobile", "Unknown"); + stored.put("screenpixelswidth", "N/A"); + data = new TestData(flowData, engine, missing, stored); + } + + @Test + public void capability_CanBeTestedFor() { + assertTrue(data instanceof ProvidesValuesAsString); + } + + @Test + public void storedString_IsReturnedAsStored() { + ProvidesValuesAsString strings = data; + + assertEquals("Unknown", + strings.getStoredValueAsString("ismobile").getValue()); + assertEquals("N/A", + strings.getStoredValueAsString("ScreenPixelsWidth").getValue()); + } + + @Test + public void typedAccessor_IsUnchanged() { + data.getStoredValueAsString("ismobile"); + + assertFalse(data.getIsMobile().getValue()); + assertEquals(0, (int) data.getScreenPixelsWidth().getValue()); + } + + @Test + public void missingProperty_ReportedAsByTheTypedAccessor() { + String typed = null; + try { + data.getIsTablet(); + fail("The typed accessor throws for a missing property"); + } catch (PropertyMissingException e) { + typed = e.getMessage(); + } + try { + data.getStoredValueAsString("istablet"); + fail("The stored value throws for a missing property"); + } catch (PropertyMissingException e) { + assertEquals(typed, e.getMessage()); + assertEquals(MissingPropertyReason.DataFileUpgradeRequired, + e.getReason()); + } + } + + /** + * Device Data that holds its values as strings and parses them as the C + * library does. + */ + private static class TestData extends DeviceDataBaseOnPremise { + private final Map stored; + + TestData( + FlowData flowData, + AspectEngine engine, + MissingPropertyService missingPropertyService, + Map stored) { + super(mock(Logger.class), flowData, engine, + missingPropertyService); + this.stored = new TreeMap<>(String.CASE_INSENSITIVE_ORDER); + this.stored.putAll(stored); + } + + @Override + protected boolean propertyIsAvailable(String propertyName) { + return stored.containsKey(propertyName); + } + + @Override + public AspectPropertyValue> getValues( + String propertyName) { + throw new UnsupportedOperationException(); + } + + @Override + protected AspectPropertyValue getValueAsString( + String propertyName) { + return new AspectPropertyValueDefault<>(stored.get(propertyName)); + } + + @Override + protected AspectPropertyValue getValueAsInteger( + String propertyName) { + String value = stored.get(propertyName); + int parsed = 0; + try { + parsed = Integer.parseInt(value); + } catch (NumberFormatException e) { + // As C's atoi, text that is not a number gives 0. + } + return new AspectPropertyValueDefault<>(parsed); + } + + @Override + protected AspectPropertyValue getValueAsBool( + String propertyName) { + return new AspectPropertyValueDefault<>( + "True".equals(stored.get(propertyName))); + } + + @Override + protected AspectPropertyValue getValueAsDouble( + String propertyName) { + throw new UnsupportedOperationException(); + } + + @Override + protected AspectPropertyValue getValueAsJavaScript( + String propertyName) { + throw new UnsupportedOperationException(); + } + + @Override + public AspectPropertyValue> getUserAgents() { + throw new UnsupportedOperationException(); + } + + @Override + public AspectPropertyValue getDeviceId() { + throw new UnsupportedOperationException(); + } + } +} diff --git a/examples/ip-intelligence/web/getting-started.api/pom.xml b/examples/ip-intelligence/web/getting-started.api/pom.xml index ef29feee4..9035ee9d1 100644 --- a/examples/ip-intelligence/web/getting-started.api/pom.xml +++ b/examples/ip-intelligence/web/getting-started.api/pom.xml @@ -41,6 +41,18 @@ 20231013 + + + + dev + + ${project.version} + + + + diff --git a/ip-intelligence/ip-intelligence.cloud/src/test/java/fiftyone/ipintelligence/cloud/flowelements/ElementDataKeyFormatTests.java b/ip-intelligence/ip-intelligence.cloud/src/test/java/fiftyone/ipintelligence/cloud/flowelements/ElementDataKeyFormatTests.java new file mode 100644 index 000000000..d2dd2ace5 --- /dev/null +++ b/ip-intelligence/ip-intelligence.cloud/src/test/java/fiftyone/ipintelligence/cloud/flowelements/ElementDataKeyFormatTests.java @@ -0,0 +1,69 @@ +/* ********************************************************************* + * 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.ipintelligence.cloud.flowelements; + +import org.junit.Test; +import org.slf4j.Logger; + +import java.util.Locale; + +import static org.junit.Assert.assertTrue; +import static org.mockito.Mockito.mock; + +/** + * The string key of each IP Intelligence cloud engine's data contains only + * alphanumeric characters, full stop or hyphen. + *

+ * Specification: pipeline-specification/features/access-to-results.md line 7 + * at 51Degrees/specifications 706de1f0, "Strings SHOULD only contain + * alphanumeric characters, full stop or hyphen." + */ +public class ElementDataKeyFormatTests { + + private static String[] keys() { + return new String[] { + new IPIntelligenceCloudEngine(mock(Logger.class), null) + .getElementDataKey(), + new HardwareProfileCloudEngine(mock(Logger.class), null) + .getElementDataKey() + }; + } + + @Test + public void keys_OnlyAlphanumericFullStopOrHyphen() { + for (String key : keys()) { + assertTrue(key, key.matches("[A-Za-z0-9.-]+")); + } + } + + /** + * Specification: access-to-results.md line 10, "Lower-case SHOULD be + * used." + */ + @Test + public void keys_LowerCase() { + for (String key : keys()) { + assertTrue(key, key.equals(key.toLowerCase(Locale.ROOT))); + } + } +} diff --git a/ip-intelligence/ip-intelligence.shared/src/main/java/fiftyone/ipintelligence/shared/IPIntelligenceDataBaseOnPremise.java b/ip-intelligence/ip-intelligence.shared/src/main/java/fiftyone/ipintelligence/shared/IPIntelligenceDataBaseOnPremise.java index 32b2729e2..46481411a 100644 --- a/ip-intelligence/ip-intelligence.shared/src/main/java/fiftyone/ipintelligence/shared/IPIntelligenceDataBaseOnPremise.java +++ b/ip-intelligence/ip-intelligence.shared/src/main/java/fiftyone/ipintelligence/shared/IPIntelligenceDataBaseOnPremise.java @@ -32,6 +32,7 @@ import fiftyone.pipeline.engines.data.AspectPropertyMetaData; import fiftyone.pipeline.engines.data.AspectPropertyValue; import fiftyone.pipeline.engines.data.AspectPropertyValueDefault; +import fiftyone.pipeline.engines.data.ProvidesValuesAsString; import fiftyone.pipeline.engines.flowelements.AspectEngine; import fiftyone.pipeline.engines.services.MissingPropertyService; import org.slf4j.Logger; @@ -48,7 +49,8 @@ /** * Base class used for all 51Degrees on-premise IP Intelligence results classes. */ -public abstract class IPIntelligenceDataBaseOnPremise extends IPIntelligenceDataBase { +public abstract class IPIntelligenceDataBaseOnPremise extends IPIntelligenceDataBase + implements ProvidesValuesAsString { protected final Map, Class> primitiveTypes; private final Object dataLock = new Object(); @@ -99,6 +101,22 @@ public abstract AspectPropertyValue> getValues( protected abstract AspectPropertyValue getValueAsString( String propertyName); + /** + * {@inheritDoc} + *

+ * The Property is first read as {@link #get(String)} reads it, so a + * Property that is not in the results throws, and a lazy loaded result + * is waited for, exactly as for that accessor. + */ + @Override + public AspectPropertyValue getStoredValueAsString( + String propertyName) { + get(propertyName); + synchronized (getLock) { + return getValueAsString(propertyName); + } + } + /** * Get the value for the specified property as an {@link Integer}. If the * property cannot be represented as an {@link Integer}, then the result diff --git a/location/geo-location/src/test/java/fiftyone/geolocation/ElementDataKeyFormatTests.java b/location/geo-location/src/test/java/fiftyone/geolocation/ElementDataKeyFormatTests.java new file mode 100644 index 000000000..6a57f74d8 --- /dev/null +++ b/location/geo-location/src/test/java/fiftyone/geolocation/ElementDataKeyFormatTests.java @@ -0,0 +1,75 @@ +/* ********************************************************************* + * 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.geolocation; + +import fiftyone.geolocation.core.Enums; +import fiftyone.geolocation.flowelements.GeoLocationCloudEngine; +import org.junit.Test; +import org.slf4j.LoggerFactory; + +import java.util.Locale; + +import static org.junit.Assert.assertTrue; + +/** + * The string key of the Location cloud engine's data contains only + * alphanumeric characters, full stop or hyphen. + *

+ * The key for the DigitalElement provider, "location_digitalelement", is + * left out. It is the name the cloud service gives that product in its + * response and property list, which the engine reads by its key, and the + * name every language uses, so it cannot change here alone. + *

+ * Specification: pipeline-specification/features/access-to-results.md line 7 + * at 51Degrees/specifications 706de1f0, "Strings SHOULD only contain + * alphanumeric characters, full stop or hyphen." + */ +public class ElementDataKeyFormatTests { + + private static String key(Enums.GeoLocationProvider provider) { + return new GeoLocationCloudEngine( + LoggerFactory.getLogger(GeoLocationCloudEngine.class), + null, + provider).getElementDataKey(); + } + + @Test + public void keys_OnlyAlphanumericFullStopOrHyphen() { + String key = key(Enums.GeoLocationProvider.FiftyOneDegrees); + assertTrue(key, key.matches("[A-Za-z0-9.-]+")); + } + + /** + * Every provider's key, the DigitalElement one included, is lower-case. + * Specification: access-to-results.md line 10, "Lower-case SHOULD be + * used." + */ + @Test + public void keys_LowerCase() { + for (Enums.GeoLocationProvider provider : + Enums.GeoLocationProvider.values()) { + String key = key(provider); + assertTrue(key, key.equals(key.toLowerCase(Locale.ROOT))); + } + } +} diff --git a/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilder.java b/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilder.java index f10d49d1c..73495e4c8 100644 --- a/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilder.java +++ b/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilder.java @@ -1004,6 +1004,20 @@ private Object parseToType( Class targetType, String value, String errorTextPrefix) { + // A configuration file gives an enumeration value as the name of the + // value, which is matched without regard to case. An enumeration + // with a parse method of its own is left to that method, which may + // accept more spellings and give its own message. + if (targetType.isEnum() && hasParseMethod(targetType) == false) { + for (Object constant : targetType.getEnumConstants()) { + if (((Enum) constant).name().equalsIgnoreCase(value.trim())) { + return constant; + } + } + throw new PipelineConfigurationException( + errorTextPrefix + ". '" + value + "' is not the name of " + + "one of its values."); + } // Check for a TryParse method on the type Method parse = null; Class nonPrimitiveType; @@ -1044,6 +1058,21 @@ private Object parseToType( return parsedValue; } + /** + * Whether the type has a method named 'parse...' that takes one string, + * as {@link #parseToType} looks for. + */ + private static boolean hasParseMethod(Class type) { + for (Method method : type.getMethods()) { + if (method.getName().startsWith("parse") && + method.getParameterTypes().length == 1 && + method.getParameterTypes()[0].equals(String.class)) { + return true; + } + } + return false; + } + /** * Evaluate strings for substitution of system properties etc. */ diff --git a/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilderBase.java b/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilderBase.java index 147c7dc1a..0563da140 100644 --- a/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilderBase.java +++ b/pipeline/pipeline.core/src/main/java/fiftyone/pipeline/core/flowelements/PipelineBuilderBase.java @@ -22,6 +22,7 @@ package fiftyone.pipeline.core.flowelements; +import fiftyone.pipeline.annotations.AlternateName; import fiftyone.pipeline.core.Constants; import fiftyone.pipeline.core.configuration.PipelineOptions; import fiftyone.pipeline.core.data.FlowData; @@ -181,11 +182,15 @@ protected void addServicesToPipeline(Pipeline pipeline) { /** * Configure the {@link Pipeline} to either call dispose on it's child * {@link FlowElement}s when it is disposed or not. + *

+ * A configuration file may also give this option as 'AutoDisposeElements' + * or 'SetAutoDisposeElements', the name other languages use. * @param autoClose true if the Pipeline should call dispose on it's child * elements when it is disposed * @return this builder */ @SuppressWarnings("unchecked") + @AlternateName("SetAutoDisposeElements") public T setAutoCloseElements(boolean autoClose) { this.autoCloseElements = autoClose; return (T) this; diff --git a/pipeline/pipeline.core/src/test/java/fiftyone/pipeline/core/configuration/ConfigurationFileLanguagesTest.java b/pipeline/pipeline.core/src/test/java/fiftyone/pipeline/core/configuration/ConfigurationFileLanguagesTest.java new file mode 100644 index 000000000..049c2b8bb --- /dev/null +++ b/pipeline/pipeline.core/src/test/java/fiftyone/pipeline/core/configuration/ConfigurationFileLanguagesTest.java @@ -0,0 +1,73 @@ +/* ********************************************************************* + * 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.pipeline.core.configuration; + +import fiftyone.pipeline.core.flowelements.Pipeline; +import fiftyone.pipeline.core.flowelements.PipelineBuilder; +import org.junit.Test; +import org.slf4j.LoggerFactory; + +import static fiftyone.pipeline.util.FileFinder.getFilePath; +import static org.junit.Assert.assertEquals; + +/** + * A configuration file written with the structure and names the .NET sample + * configuration file uses (PipelineOptions, Elements, Element, BuilderName, + * BuildParameters, a builder name ending 'Builder' and builder method names + * starting 'Set', at element and Pipeline level) is read and builds a + * Pipeline. + *

+ * Specification: pipeline-specification/features/pipeline-configuration.md + * line 40 at 51Degrees/specifications 706de1f0, "The configuration file + * definition MUST be as similar as possible to configuration files for other + * languages." + */ +public class ConfigurationFileLanguagesTest { + + @Test + public void dotNetNames_AreRead() throws Exception { + PipelineOptions options = PipelineOptionsFactory.getOptionsFromFile( + getFilePath("options-dotnet-names.xml")); + + assertEquals(1, options.elements.size()); + assertEquals( + "MultiplyByElementBuilder", + options.elements.get(0).builderName); + assertEquals("8", options.elements.get(0).buildParameters.get("multiple")); + assertEquals( + "true", + options.pipelineBuilderParameters.get("SetAutoDisposeElements")); + } + + @Test + public void dotNetNames_BuildAPipeline() throws Exception { + PipelineOptions options = PipelineOptionsFactory.getOptionsFromFile( + getFilePath("options-dotnet-names.xml")); + + try (Pipeline pipeline = new PipelineBuilder( + LoggerFactory.getILoggerFactory()) + .buildFromConfiguration(options)) { + assertEquals(1, pipeline.getFlowElements().size()); + } + } +} diff --git a/pipeline/pipeline.core/src/test/java/fiftyone/pipeline/core/flowelements/ElementDataKeyCaseTests.java b/pipeline/pipeline.core/src/test/java/fiftyone/pipeline/core/flowelements/ElementDataKeyCaseTests.java new file mode 100644 index 000000000..dbcaceef5 --- /dev/null +++ b/pipeline/pipeline.core/src/test/java/fiftyone/pipeline/core/flowelements/ElementDataKeyCaseTests.java @@ -0,0 +1,116 @@ +/* ********************************************************************* + * 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.pipeline.core.flowelements; + +import fiftyone.pipeline.core.data.ElementData; +import fiftyone.pipeline.core.data.TryGetResult; +import fiftyone.pipeline.core.testclasses.data.TestElementData; +import fiftyone.pipeline.core.typed.TypedKey; +import fiftyone.pipeline.core.typed.TypedKeyDefault; +import org.junit.After; +import org.junit.Before; +import org.junit.Test; +import org.slf4j.Logger; + +import java.util.Locale; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertSame; +import static org.junit.Assert.assertTrue; +import static org.mockito.Mockito.mock; + +/** + * The string key of an Element Data instance is compared without regard to + * case. + *

+ * Specification: pipeline-specification/features/access-to-results.md line 11 + * at 51Degrees/specifications 706de1f0, "String comparisons MUST be case + * insensitive." + */ +public class ElementDataKeyCaseTests { + + private FlowDataDefault flowData; + private ElementData data; + + @Before + public void init() { + flowData = new FlowDataDefault( + mock(Logger.class), + mock(PipelineInternal.class), + new EvidenceDefault(mock(Logger.class))); + flowData.process(); + data = flowData.getOrAdd( + "device", + (FlowElement.DataFactory) fd -> + new TestElementData(mock(Logger.class), fd)); + } + + @After + public void close() throws Exception { + flowData.close(); + } + + @Test + public void get_StringKeyInAnotherCase_ReturnsTheData() { + assertSame(data, flowData.get("Device")); + assertSame(data, flowData.get("DEVICE")); + } + + @Test + public void get_TypedKeyInAnotherCase_ReturnsTheData() { + TypedKey key = new TypedKeyDefault<>( + "Device", + TestElementData.class); + + assertSame(data, flowData.get(key)); + TryGetResult result = flowData.tryGetValue(key); + assertTrue(result.hasValue()); + assertSame(data, result.getValue()); + } + + @Test + public void getOrAdd_KeyInAnotherCase_KeepsOneInstance() { + ElementData again = flowData.getOrAdd( + "DEVICE", + (FlowElement.DataFactory) fd -> + new TestElementData(mock(Logger.class), fd)); + + assertSame(data, again); + assertEquals(1, flowData.elementDataAsMap().size()); + } + + @Test + public void get_KeyInAnotherCase_TurkishLocale_ReturnsTheData() { + Locale original = Locale.getDefault(); + Locale.setDefault(Locale.forLanguageTag("tr-TR")); + try { + ElementData ip = flowData.getOrAdd( + "ip", + (FlowElement.DataFactory) fd -> + new TestElementData(mock(Logger.class), fd)); + assertSame(ip, flowData.get("IP")); + } finally { + Locale.setDefault(original); + } + } +} diff --git a/pipeline/pipeline.core/src/test/resources/options-dotnet-names.xml b/pipeline/pipeline.core/src/test/resources/options-dotnet-names.xml new file mode 100644 index 000000000..75987d234 --- /dev/null +++ b/pipeline/pipeline.core/src/test/resources/options-dotnet-names.xml @@ -0,0 +1,19 @@ + + + + + + MultiplyByElementBuilder + + 8 + + + + + true + false + + diff --git a/pipeline/pipeline.engines/src/main/java/fiftyone/pipeline/engines/data/ProvidesValuesAsString.java b/pipeline/pipeline.engines/src/main/java/fiftyone/pipeline/engines/data/ProvidesValuesAsString.java new file mode 100644 index 000000000..292632357 --- /dev/null +++ b/pipeline/pipeline.engines/src/main/java/fiftyone/pipeline/engines/data/ProvidesValuesAsString.java @@ -0,0 +1,51 @@ +/* ********************************************************************* + * 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.pipeline.engines.data; + +import fiftyone.pipeline.engines.exceptions.PropertyMissingException; + +/** + * Implemented by Element Data that holds Property values as strings and + * parses them into the type each Property declares, so a caller can read the + * string the data holds as well as the parsed value. + *

+ * A parsed value cannot always say what the data holds. "Unknown" in a + * Boolean Property, for example, is parsed to false, which cannot be told + * apart from a false the data really holds. Test for this interface at run + * time, and use the typed accessors where it is absent. + * @see Specification + */ +public interface ProvidesValuesAsString { + + /** + * Get the string stored for a Property, as it was stored. The string is + * never made from a parsed value, and reading it changes nothing the + * other accessors return. + * @param propertyName the name of the Property, in any case + * @return the stored string, or the reason there is no value, as for any + * other accessor + * @throws PropertyMissingException where the Property is not in the + * results, in the same way as any other accessor + */ + AspectPropertyValue getStoredValueAsString(String propertyName); +} diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/flowelements/ConfigurationValueTypesTests.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/flowelements/ConfigurationValueTypesTests.java new file mode 100644 index 000000000..495df35a8 --- /dev/null +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/flowelements/ConfigurationValueTypesTests.java @@ -0,0 +1,89 @@ +/* ********************************************************************* + * 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.pipeline.engines.flowelements; + +import fiftyone.pipeline.core.configuration.ElementOptions; +import fiftyone.pipeline.core.configuration.PipelineOptions; +import fiftyone.pipeline.core.flowelements.Pipeline; +import fiftyone.pipeline.core.flowelements.PipelineBuilder; +import fiftyone.pipeline.engines.testhelpers.flowelements.ConfiguredEngineBuilder; +import org.junit.Test; +import org.slf4j.LoggerFactory; + +import java.util.Arrays; + +import static org.junit.Assert.assertEquals; + +/** + * Configuration files hold a list of strings as a comma-separated string and + * an enumeration value as the name of the value, the same in every language. + *

+ * Specification: pipeline-specification/features/pipeline-configuration.md + * line 50 at 51Degrees/specifications 706de1f0, "Configuration files MUST be + * human-readable and consistent between languages.", and lines 60 and 61, + * "list of strings (represented as a comma-separated string)" and + * "enumeration value (represented as the string name of the value)". + */ +public class ConfigurationValueTypesTests { + + private static void build(String name, String value) throws Exception { + ElementOptions element = new ElementOptions(); + element.builderName = "ConfiguredEngine"; + element.buildParameters.put(name, value); + PipelineOptions options = new PipelineOptions(); + options.elements.add(element); + try (Pipeline ignored = new PipelineBuilder( + LoggerFactory.getILoggerFactory()) + .buildFromConfiguration(options)) { + // Building is enough. + } + } + + @Test + public void properties_CommaSeparated_AreEachProperty() throws Exception { + build("Properties", "IsMobile,BrowserName"); + + assertEquals( + Arrays.asList("IsMobile", "BrowserName"), + ConfiguredEngineBuilder.lastProperties); + } + + @Test + public void properties_CommaAndSpaceSeparated_AreEachProperty() + throws Exception { + build("Properties", "IsMobile, BrowserName ,PlatformName"); + + assertEquals( + Arrays.asList("IsMobile", "BrowserName", "PlatformName"), + ConfiguredEngineBuilder.lastProperties); + } + + @Test + public void enumeration_ByName_IsSet() throws Exception { + build("Speed", "FAST"); + + assertEquals( + ConfiguredEngineBuilder.Speed.FAST, + ConfiguredEngineBuilder.lastSpeed); + } +} diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/flowelements/RelativePathTests.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/flowelements/RelativePathTests.java new file mode 100644 index 000000000..437e061a9 --- /dev/null +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/flowelements/RelativePathTests.java @@ -0,0 +1,195 @@ +/* ********************************************************************* + * 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.pipeline.engines.flowelements; + +import fiftyone.common.wrappers.io.FileWrapperFactoryDefault; +import fiftyone.pipeline.core.data.FlowData; +import fiftyone.pipeline.core.flowelements.Pipeline; +import fiftyone.pipeline.core.flowelements.PipelineBuilder; +import fiftyone.pipeline.engines.services.DataUpdateServiceDefault; +import fiftyone.pipeline.engines.services.HttpClient; +import fiftyone.pipeline.engines.services.update.FutureFactory; +import fiftyone.pipeline.engines.testhelpers.data.EmptyEngineData; +import fiftyone.pipeline.engines.testhelpers.flowelements.TextFileEngine; +import fiftyone.pipeline.engines.testhelpers.flowelements.TextFileEngineBuilder; +import org.junit.After; +import org.junit.Before; +import org.junit.Test; +import org.slf4j.ILoggerFactory; +import org.slf4j.LoggerFactory; + +import java.io.File; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.UUID; +import java.util.concurrent.ScheduledFuture; +import java.util.concurrent.atomic.AtomicReference; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertNotNull; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyLong; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * A data file path, and a temporary folder path, may be relative to the + * working directory of the process. + *

+ * Specification: pipeline-specification/features/file-system-paths.md lines + * 3 to 5 at 51Degrees/specifications 706de1f0, "Where file system paths are + * supplied as parameters, the Pipeline API MUST be able to work with relative + * paths. A relative path is resolved against the working directory of the + * process." + */ +public class RelativePathTests { + + private static final long WAIT_FOR_EVENT_MILLIS = 10000; + + private static final long RETRY_MILLIS = 100; + + private final ILoggerFactory loggerFactory = + LoggerFactory.getILoggerFactory(); + + /** + * The folder for the test's files, relative to the working directory. + */ + private Path folder; + + /** + * The data file, relative to the working directory. + */ + private String dataFile; + + @Before + public void createDataFile() throws Exception { + folder = Paths.get("target", "relative-" + UUID.randomUUID()); + Files.createDirectories(folder); + dataFile = folder.resolve("data.txt").toString(); + Files.write( + Paths.get(dataFile), + "Old".getBytes(StandardCharsets.UTF_8)); + assertFalse( + "The path in the test is relative", + Paths.get(dataFile).isAbsolute()); + } + + @After + public void deleteFiles() { + File[] files = folder.toFile().listFiles(); + if (files != null) { + for (File file : files) { + if (file.delete() == false) { + file.deleteOnExit(); + } + } + } + if (folder.toFile().delete() == false) { + folder.toFile().deleteOnExit(); + } + } + + @Test + public void dataFile_Relative_EngineReadsIt() throws Exception { + try (TextFileEngine engine = + new TextFileEngineBuilder(loggerFactory, null) + .setAutoUpdate(false) + .build(dataFile, false); + Pipeline pipeline = new PipelineBuilder(loggerFactory) + .addFlowElement(engine) + .build(); + FlowData data = pipeline.createFlowData()) { + assertEquals("Old", engine.getText()); + assertEquals(dataFile, engine.getDataFileMetaData().getDataFilePath()); + + data.process(); + assertEquals(3, data.get(EmptyEngineData.class).getValueOne()); + } + } + + @Test + public void tempDir_Relative_ResolvedAgainstTheWorkingDirectory() + throws Exception { + String tempDir = folder.resolve("temp").toString(); + try (TextFileEngine engine = + new TextFileEngineBuilder(loggerFactory, null) + .setAutoUpdate(false) + .setTempDirPath(tempDir) + .build(dataFile, false)) { + assertEquals( + Paths.get(tempDir).toAbsolutePath().normalize(), + Paths.get(engine.getTempDataDirPath()) + .toAbsolutePath().normalize()); + assertEquals( + Paths.get(tempDir, "data.txt").toAbsolutePath().normalize(), + Paths.get(engine.getDataFileMetaData().getTempDataFilePath()) + .toAbsolutePath().normalize()); + } + } + + @Test + public void dataFile_Relative_WatcherLoadsANewFile() throws Exception { + AtomicReference watcher = new AtomicReference<>(); + FutureFactory futureFactory = mock(FutureFactory.class); + when(futureFactory.schedule(any(Runnable.class), anyLong())) + .then(invocation -> mock(ScheduledFuture.class)); + when(futureFactory.scheduleRepeating(any(Runnable.class), anyLong())) + .then(invocation -> { + watcher.set(invocation.getArgument(0)); + return mock(ScheduledFuture.class); + }); + DataUpdateServiceDefault dataUpdate = new DataUpdateServiceDefault( + loggerFactory.getLogger(DataUpdateServiceDefault.class.getName()), + mock(HttpClient.class), + new FileWrapperFactoryDefault(), + futureFactory); + + try (TextFileEngine engine = + new TextFileEngineBuilder(loggerFactory, dataUpdate) + .setAutoUpdate(false) + .setDataFileSystemWatcher(true) + .setUpdatePollingIntervalSeconds(1) + .build(dataFile, false)) { + assertNotNull( + "A watcher is set up for the relative path", + engine.getDataFileMetaData().getConfiguration().getWatchKey()); + assertNotNull(watcher.get()); + + Files.write( + Paths.get(dataFile), + "New".getBytes(StandardCharsets.UTF_8)); + long end = System.currentTimeMillis() + WAIT_FOR_EVENT_MILLIS; + while ("New".equals(engine.getText()) == false && + System.currentTimeMillis() < end) { + watcher.get().run(); + Thread.sleep(RETRY_MILLIS); + } + + assertEquals("New", engine.getText()); + dataUpdate.unregisterDataFile(engine.getDataFileMetaData()); + } + } +} diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/performance/PipelineOverheadTests.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/performance/PipelineOverheadTests.java index 409ddd278..cff4b768f 100644 --- a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/performance/PipelineOverheadTests.java +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/performance/PipelineOverheadTests.java @@ -114,14 +114,21 @@ public void PipelineOverhead_Cache() throws Exception { CacheConfiguration cacheConfig = new CacheConfiguration( new LruPutCache.Builder(),100); engine.setCache(new FlowCacheDefault(cacheConfig)); - // Set process cost to 0.2 sec. Therefore, the test cannot pass - // unless the cache is mitigating this cost as it should do. + // Set process cost to 0.2 sec, so every call the cache does not answer + // costs far more than the overhead permitted. engine.setProcessCost(200); int iterations = 10_000; Map evidence = new HashMap<>(); evidence.put("test.value", 10); + // Fill the cache before timing. The one call that misses the cache + // costs 0.2 sec, which is 0.02 ms of the permitted average over + // 10,000 calls, so timing it measured the process cost and not the + // overhead. + new TestCallable(pipeline, 1, evidence).call(); long result = new TestCallable(pipeline, iterations, evidence).call(); + // The cache answered every call after the first. + assertEquals(1, engine.getProcessCount()); double msOverheadPerCall = (double)(result) / iterations; logger.info("Process cost {}", engine.getProcessCost()); logger.info("Average was {} millis", msOverheadPerCall); diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/ConfiguredEngineBuilder.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/ConfiguredEngineBuilder.java new file mode 100644 index 000000000..6916a1c5f --- /dev/null +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/ConfiguredEngineBuilder.java @@ -0,0 +1,78 @@ +/* ********************************************************************* + * 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.pipeline.engines.testhelpers.flowelements; + +import fiftyone.pipeline.annotations.ElementBuilder; +import org.slf4j.ILoggerFactory; + +import java.util.ArrayList; +import java.util.List; + +/** + * A builder for an {@link EmptyEngine} that records the options a + * configuration file gave it, so a test can check how they were read. + */ +@ElementBuilder +public class ConfiguredEngineBuilder extends EmptyEngineBuilder { + + /** + * An option whose builder method takes only an enumeration. + */ + public enum Speed { + SLOW, + FAST + } + + /** + * The properties the last engine was built with. + */ + public static volatile List lastProperties = null; + + /** + * The speed the last engine was built with. + */ + public static volatile Speed lastSpeed = null; + + private Speed speed = Speed.SLOW; + + public ConfiguredEngineBuilder(ILoggerFactory loggerFactory) { + super(loggerFactory); + } + + /** + * Set the speed. There is no overload that takes a string. + * @param speed the speed + * @return this builder + */ + public ConfiguredEngineBuilder setSpeed(Speed speed) { + this.speed = speed; + return this; + } + + @Override + public EmptyEngine build() throws Exception { + lastProperties = new ArrayList<>(getProperties()); + lastSpeed = speed; + return super.build(); + } +} diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/EmptyEngine.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/EmptyEngine.java index 0230799c7..39b2532dd 100644 --- a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/EmptyEngine.java +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/EmptyEngine.java @@ -37,11 +37,13 @@ import java.util.ArrayList; import java.util.Arrays; import java.util.List; +import java.util.concurrent.atomic.AtomicInteger; public class EmptyEngine extends AspectEngineBase { private long processCost = 0; + private final AtomicInteger processCount = new AtomicInteger(); private Exception exception = null; private List properties = null; private EvidenceKeyFilterWhitelist evidenceWhitelist = @@ -70,6 +72,14 @@ public void setProcessCost(long milliseconds) { processCost = milliseconds; } + /** + * @return the number of times the engine has processed, which does not + * count results taken from the cache + */ + public int getProcessCount() { + return processCount.get(); + } + public void setException(Exception exception) { this.exception = exception; } @@ -101,6 +111,7 @@ public String getDataSourceTier() { @Override protected void processEngine(FlowData data, EmptyEngineData aspectData) throws Exception { + processCount.incrementAndGet(); if (exception != null) { throw exception; } diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/TextFileEngine.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/TextFileEngine.java new file mode 100644 index 000000000..2018f247d --- /dev/null +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/TextFileEngine.java @@ -0,0 +1,140 @@ +/* ********************************************************************* + * 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.pipeline.engines.testhelpers.flowelements; + +import fiftyone.pipeline.core.data.EvidenceKeyFilter; +import fiftyone.pipeline.core.data.EvidenceKeyFilterWhitelist; +import fiftyone.pipeline.core.data.FlowData; +import fiftyone.pipeline.core.data.factories.ElementDataFactory; +import fiftyone.pipeline.core.typed.TypedKey; +import fiftyone.pipeline.core.typed.TypedKeyDefault; +import fiftyone.pipeline.engines.data.AspectPropertyMetaData; +import fiftyone.pipeline.engines.flowelements.OnPremiseAspectEngineBase; +import fiftyone.pipeline.engines.testhelpers.data.EmptyEngineData; +import org.slf4j.Logger; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Paths; +import java.util.Collections; +import java.util.Date; +import java.util.List; + +/** + * An on-premise engine whose data file is a text file, which it reads when it + * is built and again whenever its data is refreshed. + */ +public class TextFileEngine + extends OnPremiseAspectEngineBase { + + private final String dataFilePath; + + private volatile String text; + + @SuppressWarnings("this-escape") + private final TypedKey typedKey = + new TypedKeyDefault<>(getElementDataKey(), EmptyEngineData.class); + + public TextFileEngine( + String dataFilePath, + Logger logger, + ElementDataFactory aspectDataFactory, + String tempDataDirPath) throws IOException { + super(logger, aspectDataFactory, tempDataDirPath); + this.dataFilePath = dataFilePath; + read(); + } + + private void read() throws IOException { + text = new String( + Files.readAllBytes(Paths.get(dataFilePath)), + StandardCharsets.UTF_8); + } + + /** + * @return the text the data file held when it was last read + */ + public String getText() { + return text; + } + + @Override + public Date getDataFilePublishedDate(String dataFileIdentifier) { + return null; + } + + @Override + public Date getDataFileUpdateAvailableTime(String dataFileIdentifier) { + return null; + } + + @Override + public void refreshData(String dataFileIdentifier) { + try { + read(); + } catch (IOException e) { + throw new IllegalStateException(e); + } + } + + @Override + public void refreshData(String dataFileIdentifier, byte[] data) { + text = new String(data, StandardCharsets.UTF_8); + } + + @Override + protected void processEngine(FlowData data, EmptyEngineData aspectData) { + aspectData.setValueOne(text.length()); + } + + @Override + public String getElementDataKey() { + return "text-file"; + } + + @Override + public TypedKey getTypedDataKey() { + return typedKey; + } + + @Override + public EvidenceKeyFilter getEvidenceKeyFilter() { + return new EvidenceKeyFilterWhitelist( + Collections.emptyList()); + } + + @Override + public List getProperties() { + return Collections.emptyList(); + } + + @Override + public String getDataSourceTier() { + return "free"; + } + + @Override + protected void unmanagedResourcesCleanup() { + } +} diff --git a/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/TextFileEngineBuilder.java b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/TextFileEngineBuilder.java new file mode 100644 index 000000000..3eb6752fc --- /dev/null +++ b/pipeline/pipeline.engines/src/test/java/fiftyone/pipeline/engines/testhelpers/flowelements/TextFileEngineBuilder.java @@ -0,0 +1,73 @@ +/* ********************************************************************* + * 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.pipeline.engines.testhelpers.flowelements; + +import fiftyone.pipeline.engines.Constants; +import fiftyone.pipeline.engines.configuration.DataFileConfiguration; +import fiftyone.pipeline.engines.data.AspectData; +import fiftyone.pipeline.engines.data.AspectPropertyMetaData; +import fiftyone.pipeline.engines.flowelements.AspectEngine; +import fiftyone.pipeline.engines.flowelements.SingleFileAspectEngineBuilderBase; +import fiftyone.pipeline.engines.services.DataUpdateService; +import fiftyone.pipeline.engines.services.MissingPropertyServiceDefault; +import fiftyone.pipeline.engines.testhelpers.data.EmptyEngineData; +import org.slf4j.ILoggerFactory; + +import java.util.List; + +/** + * Builds a {@link TextFileEngine} from one data file. + */ +public class TextFileEngineBuilder extends SingleFileAspectEngineBuilderBase< + TextFileEngineBuilder, + TextFileEngine> { + + public TextFileEngineBuilder( + ILoggerFactory loggerFactory, + DataUpdateService dataUpdateService) { + super(loggerFactory, dataUpdateService); + } + + @Override + @SuppressWarnings("unchecked") + protected TextFileEngine newEngine(List properties) + throws Exception { + DataFileConfiguration config = dataFileConfigs.get(0); + return new TextFileEngine( + config.getDataFilePath(), + loggerFactory.getLogger(TextFileEngine.class.getName()), + (flowData, element) -> new EmptyEngineData( + loggerFactory.getLogger(EmptyEngineData.class.getName()), + flowData, + (AspectEngine) element, + MissingPropertyServiceDefault.getInstance()), + tempDir); + } + + @Override + public TextFileEngineBuilder setPerformanceProfile( + Constants.PerformanceProfiles profile) { + return this; + } +} diff --git a/pipeline/pipeline.javascriptbuilder/src/test/java/fiftyone/pipeline/javascriptbuilder/flowelements/ElementDataKeyFormatTests.java b/pipeline/pipeline.javascriptbuilder/src/test/java/fiftyone/pipeline/javascriptbuilder/flowelements/ElementDataKeyFormatTests.java new file mode 100644 index 000000000..b9bfbf6e2 --- /dev/null +++ b/pipeline/pipeline.javascriptbuilder/src/test/java/fiftyone/pipeline/javascriptbuilder/flowelements/ElementDataKeyFormatTests.java @@ -0,0 +1,90 @@ +/* ********************************************************************* + * 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.pipeline.javascriptbuilder.flowelements; + +import fiftyone.pipeline.core.flowelements.FlowElement; +import fiftyone.pipeline.engines.fiftyone.flowelements.SequenceElementBuilder; +import fiftyone.pipeline.engines.fiftyone.flowelements.SetHeadersElementBuilder; +import fiftyone.pipeline.engines.fiftyone.flowelements.ShareUsageBuilder; +import fiftyone.pipeline.jsonbuilder.flowelements.JsonBuilderElementBuilder; +import org.junit.jupiter.api.Test; +import org.slf4j.ILoggerFactory; +import org.slf4j.LoggerFactory; + +import java.util.ArrayList; +import java.util.List; +import java.util.Locale; + +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * The string key of each Pipeline API element's data contains only + * alphanumeric characters, full stop or hyphen. + *

+ * Specification: pipeline-specification/features/access-to-results.md line 7 + * at 51Degrees/specifications 706de1f0, "Strings SHOULD only contain + * alphanumeric characters, full stop or hyphen." + */ +public class ElementDataKeyFormatTests { + + private static List> elements() throws Exception { + ILoggerFactory loggerFactory = LoggerFactory.getILoggerFactory(); + List> elements = new ArrayList<>(); + elements.add(new JavaScriptBuilderElementBuilder(loggerFactory).build()); + elements.add(new JsonBuilderElementBuilder(loggerFactory).build()); + elements.add(new SequenceElementBuilder(loggerFactory).build()); + elements.add(new SetHeadersElementBuilder(loggerFactory).build()); + elements.add(new ShareUsageBuilder(loggerFactory).build()); + return elements; + } + + @Test + public void keys_OnlyAlphanumericFullStopOrHyphen() throws Exception { + for (FlowElement element : elements()) { + try { + String key = element.getElementDataKey(); + assertTrue(key.matches("[A-Za-z0-9.-]+"), + element.getClass().getSimpleName() + " key '" + key + "'"); + } finally { + element.close(); + } + } + } + + /** + * Specification: access-to-results.md line 10, "Lower-case SHOULD be + * used." + */ + @Test + public void keys_LowerCase() throws Exception { + for (FlowElement element : elements()) { + try { + String key = element.getElementDataKey(); + assertTrue(key.equals(key.toLowerCase(Locale.ROOT)), + element.getClass().getSimpleName() + " key '" + key + "'"); + } finally { + element.close(); + } + } + } +}