This is an automated email from the ASF dual-hosted git repository. sergehuber pushed a commit to branch UNOMI-1017-sum-interests in repository https://gitbox.apache.org/repos/asf/unomi.git
commit 3cf658d4e53dccfeae473bd87d2f348bfecb7773 Author: Serge Huber <[email protected]> AuthorDate: Fri Nov 13 08:34:24 2026 +0100 UNOMI-1017: Sum interest points by key when profiles merge The last merged profile was replacing properties.interests. A dedicated merge strategy now adds the points that share a key, and the built-in interests property uses it. --- .../asciidoc/migrations/migrate-3.0-to-4.0.adoc | 1 + manual/src/main/asciidoc/property-types.adoc | 3 + .../SumByKeyPropertyMergeStrategyExecutor.java | 134 +++++++++++++++++++ .../cxs/mergers/sumByKeyPropertyMergeStrategy.json | 4 + .../cxs/properties/profiles/system/interests.json | 17 +++ .../resources/OSGI-INF/blueprint/blueprint.xml | 8 ++ .../SumByKeyPropertyMergeStrategyExecutorTest.java | 143 +++++++++++++++++++++ 7 files changed, 310 insertions(+) diff --git a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc index 96c6c75cf..0acc0914a 100644 --- a/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc +++ b/manual/src/main/asciidoc/migrations/migrate-3.0-to-4.0.adoc @@ -564,6 +564,7 @@ The sections above cover authentication and client-facing hardening. The lists b ==== Integrators / REST clients * Creating a profile without an `itemId` is refused. +* Merging profiles adds the points of `properties.interests` by key. Previously the last profile's list replaced the others. See <<_property_types,Property Types>>. * Condition validation failures on REST return a generic `badRequest` response. Detailed messages stay in the server log. See <<_condition_validation,Condition validation>>. * Public endpoints need a tenant public API key unless <<_v2_compatibility_mode,single-tenant compatibility mode>> is on (for clients written for Unomi 2 or Unomi 3). See <<_updating_applications_consuming_unomi,Updating applications consuming Unomi>> and the client-facing hardening notes above. * Websites on another origin must be listed for the visitor cookie; see <<_public_tracker_origins,Websites on other origins>>. diff --git a/manual/src/main/asciidoc/property-types.adoc b/manual/src/main/asciidoc/property-types.adoc index 7d8316433..879c2c87c 100644 --- a/manual/src/main/asciidoc/property-types.adoc +++ b/manual/src/main/asciidoc/property-types.adoc @@ -463,6 +463,9 @@ Common merge strategies include: * `oldestMergeStrategy` - Use the oldest value (for dates and timestamps) * `addMergeStrategy` - Add values together (for numeric types) * `nonEmptyMergeStrategy` - Prefer non-empty values +* `sumByKeyMergeStrategy` - For a list of `{key, value}` objects, add `value` for entries that share a `key` + +The built-in profile property `interests` uses `sumByKeyMergeStrategy`. NOTE: The merge strategy identifier in property type JSON files should match the `id` field from the merge strategy definition JSON files located in the `META-INF/cxs/mergers/` directory (this is a file system path within plugin bundles, not an API endpoint). diff --git a/services/src/main/java/org/apache/unomi/services/mergers/SumByKeyPropertyMergeStrategyExecutor.java b/services/src/main/java/org/apache/unomi/services/mergers/SumByKeyPropertyMergeStrategyExecutor.java new file mode 100644 index 000000000..f7b87e2ea --- /dev/null +++ b/services/src/main/java/org/apache/unomi/services/mergers/SumByKeyPropertyMergeStrategyExecutor.java @@ -0,0 +1,134 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.unomi.services.mergers; + +import org.apache.unomi.api.Profile; +import org.apache.unomi.api.PropertyMergeStrategyExecutor; +import org.apache.unomi.api.PropertyType; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * Adds {@code value} for entries that share a {@code key}. + * Used for {@code properties.interests}, a list of {@code {key, value}} objects. + * A value that is not that list is left unchanged. + */ +public class SumByKeyPropertyMergeStrategyExecutor implements PropertyMergeStrategyExecutor { + + @Override + public boolean mergeProperty(String propertyName, PropertyType propertyType, List<Profile> profilesToMerge, Profile targetProfile) { + Object current = targetProfile.getProperty(propertyName); + if (current != null && !(current instanceof List)) { + return false; + } + + List<Map<String, Object>> merged = entries(current); + boolean changed = false; + for (Profile profileToMerge : profilesToMerge) { + Object incoming = profileToMerge.getProperty(propertyName); + if (incoming == null) { + continue; + } + if (!(incoming instanceof List)) { + continue; + } + changed |= addInto(merged, entries(incoming)); + } + if (!changed) { + return false; + } + targetProfile.setProperty(propertyName, merged); + return true; + } + + private static boolean addInto(List<Map<String, Object>> target, List<Map<String, Object>> incoming) { + boolean changed = false; + for (Map<String, Object> entry : incoming) { + String key = (String) entry.get("key"); + Map<String, Object> existing = null; + for (Map<String, Object> candidate : target) { + if (key.equals(candidate.get("key"))) { + existing = candidate; + break; + } + } + if (existing == null) { + target.add(entry); + changed = true; + } else { + Number sum = add((Number) existing.get("value"), (Number) entry.get("value")); + if (!sum.equals(existing.get("value"))) { + existing.put("value", sum); + changed = true; + } + } + } + return changed; + } + + private static List<Map<String, Object>> entries(Object value) { + List<Map<String, Object>> entries = new ArrayList<>(); + if (!(value instanceof List)) { + return entries; + } + List<Map<String, Object>> raw = new ArrayList<>(); + for (Object item : (List<?>) value) { + if (!(item instanceof Map)) { + continue; + } + Map<?, ?> source = (Map<?, ?>) item; + Object key = source.get("key"); + Number number = toNumber(source.get("value")); + if (key == null || number == null) { + continue; + } + Map<String, Object> copy = new LinkedHashMap<>(); + for (Map.Entry<?, ?> field : source.entrySet()) { + if (field.getKey() != null) { + copy.put(field.getKey().toString(), field.getValue()); + } + } + copy.put("key", key.toString()); + copy.put("value", number); + raw.add(copy); + } + addInto(entries, raw); + return entries; + } + + private static Number toNumber(Object value) { + if (value instanceof Number) { + return (Number) value; + } + return null; + } + + private static Number add(Number left, Number right) { + if (left instanceof Double || left instanceof Float || right instanceof Double || right instanceof Float) { + return left.doubleValue() + right.doubleValue(); + } + long sum = left.longValue() + right.longValue(); + if (sum >= Integer.MIN_VALUE && sum <= Integer.MAX_VALUE) { + return (int) sum; + } + return sum; + } +} diff --git a/services/src/main/resources/META-INF/cxs/mergers/sumByKeyPropertyMergeStrategy.json b/services/src/main/resources/META-INF/cxs/mergers/sumByKeyPropertyMergeStrategy.json new file mode 100644 index 000000000..f502ebf87 --- /dev/null +++ b/services/src/main/resources/META-INF/cxs/mergers/sumByKeyPropertyMergeStrategy.json @@ -0,0 +1,4 @@ +{ + "id": "sumByKeyMergeStrategy", + "filter": "(propertyMergeStrategyExecutorId=sumByKeyPropertyMergeStrategyExecutor)" +} diff --git a/services/src/main/resources/META-INF/cxs/properties/profiles/system/interests.json b/services/src/main/resources/META-INF/cxs/properties/profiles/system/interests.json new file mode 100644 index 000000000..58ee5a6cc --- /dev/null +++ b/services/src/main/resources/META-INF/cxs/properties/profiles/system/interests.json @@ -0,0 +1,17 @@ +{ + "metadata": { + "id": "interests", + "name": "Interests", + "systemTags": [ + "properties", + "profileProperties", + "systemProfileProperties" + ] + }, + "type": "json", + "defaultValue": "", + "automaticMappingsFrom": [ ], + "mergeStrategy": "sumByKeyMergeStrategy", + "multivalued": true, + "rank": "103.0" +} diff --git a/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml b/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml index e5d416fc2..76a75e49d 100644 --- a/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml +++ b/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml @@ -628,6 +628,14 @@ </bean> </service> + <service interface="org.apache.unomi.api.PropertyMergeStrategyExecutor"> + <service-properties> + <entry key="propertyMergeStrategyExecutorId" value="sumByKeyPropertyMergeStrategyExecutor"/> + </service-properties> + <bean class="org.apache.unomi.services.mergers.SumByKeyPropertyMergeStrategyExecutor"> + </bean> + </service> + <service interface="org.apache.unomi.api.PersonalizationStrategy"> <service-properties> <entry key="personalizationStrategyId" value="matching-first"/> diff --git a/services/src/test/java/org/apache/unomi/services/mergers/SumByKeyPropertyMergeStrategyExecutorTest.java b/services/src/test/java/org/apache/unomi/services/mergers/SumByKeyPropertyMergeStrategyExecutorTest.java new file mode 100644 index 000000000..18ef064b0 --- /dev/null +++ b/services/src/test/java/org/apache/unomi/services/mergers/SumByKeyPropertyMergeStrategyExecutorTest.java @@ -0,0 +1,143 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.unomi.services.mergers; + +import org.apache.unomi.api.Profile; +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +public class SumByKeyPropertyMergeStrategyExecutorTest { + + private final SumByKeyPropertyMergeStrategyExecutor executor = new SumByKeyPropertyMergeStrategyExecutor(); + + @Test + public void sumsPointsThatShareAKeyAndKeepsKeysThatAppearOnOnlyOneProfile() { + Profile master = profile(interests(entry("funds", 30))); + Profile other = profile(interests(entry("funds", 5), entry("pension", 7))); + + assertTrue(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + + assertEquals(interests(entry("funds", 35), entry("pension", 7)), master.getProperty("interests")); + assertEquals(interests(entry("funds", 5), entry("pension", 7)), other.getProperty("interests")); + } + + @Test + public void copiesInterestsOntoAProfileThatHasNone() { + Profile master = profile(null); + Profile other = profile(interests(entry("funds", 5))); + + assertTrue(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + + assertEquals(interests(entry("funds", 5)), master.getProperty("interests")); + } + + @Test + public void leavesTheMasterUntouchedWhenNothingIsAdded() { + List<Map<String, Object>> original = interests(entry("funds", 30)); + Profile master = profile(original); + Profile other = profile(null); + + assertFalse(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + assertSame(original, master.getProperty("interests")); + } + + @Test + public void sumsTheSameKeyAcrossSeveralProfiles() { + Profile master = profile(interests(entry("funds", 1))); + Profile first = profile(interests(entry("funds", 2))); + Profile second = profile(interests(entry("funds", 3))); + + assertTrue(executor.mergeProperty("interests", null, Arrays.asList(first, second), master)); + + assertEquals(interests(entry("funds", 6)), master.getProperty("interests")); + } + + @Test + public void sumsDuplicateKeysInsideOneList() { + Profile master = profile(interests(entry("funds", 1), entry("funds", 2))); + Profile other = profile(interests(entry("funds", 3))); + + assertTrue(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + + assertEquals(interests(entry("funds", 6)), master.getProperty("interests")); + } + + @Test + public void keepsAFractionalScoreAsADouble() { + Profile master = profile(interests(entry("funds", 1.5d))); + Profile other = profile(interests(entry("funds", 2))); + + assertTrue(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + + assertEquals(interests(entry("funds", 3.5d)), master.getProperty("interests")); + } + + @Test + public void leavesAValueThatIsNotAListUnchanged() { + Profile master = profile("funds"); + Profile other = profile(interests(entry("funds", 5))); + + assertFalse(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + assertEquals("funds", master.getProperty("interests")); + } + + @Test + public void skipsEntriesThatHaveNoKeyOrNoNumber() { + Map<String, Object> missingKey = new LinkedHashMap<>(); + missingKey.put("value", 9); + Map<String, Object> missingNumber = new LinkedHashMap<>(); + missingNumber.put("key", "pension"); + missingNumber.put("value", "high"); + Profile master = profile(interests(entry("funds", 1))); + Profile other = profile(new ArrayList<>(Arrays.asList(missingKey, missingNumber, entry("funds", 4)))); + + assertTrue(executor.mergeProperty("interests", null, Collections.singletonList(other), master)); + + assertEquals(interests(entry("funds", 5)), master.getProperty("interests")); + } + + private static Profile profile(Object interests) { + Profile profile = new Profile("profile-" + System.nanoTime()); + if (interests != null) { + profile.setProperty("interests", interests); + } + return profile; + } + + @SafeVarargs + private static List<Map<String, Object>> interests(Map<String, Object>... entries) { + return new ArrayList<>(Arrays.asList(entries)); + } + + private static Map<String, Object> entry(String key, Number value) { + Map<String, Object> entry = new LinkedHashMap<>(); + entry.put("key", key); + entry.put("value", value); + return entry; + } +}
