Better error handling for pushed updates

This commit defines the exceptions that will be used to fail pushed updates, including bulk updates, and will be used to fail the returned promise. These exceptions return the error, and the original DTO so that users can attempt to work out what they did wrong.

Signed-off-by: Tim Ward <timothyjward@apache.org>

core/api/src/main/java/org/eclipse/sensinact/core/push/DataMappingException.java

@@ -0,0 +1,24 @@
+/*********************************************************************
+* Copyright (c) 2024 Contributors to the Eclipse Foundation.
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which is available at https://www.eclipse.org/legal/epl-2.0/
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*   Kentyou - initial implementation
+**********************************************************************/
+package org.eclipse.sensinact.core.push;
+
+public class DataMappingException extends DataUpdateException {
+
+    private static final long serialVersionUID = -1312692222440022024L;
+
+    public DataMappingException(String modelPackageUri, String model, String provider, String service, String resource,
+            Object originalDto, Throwable cause) {
+        super(modelPackageUri, model, provider, service, resource, originalDto,
+                "Unable to map DTO data into an update " + cause.getMessage(), cause);
+    }
+}

core/api/src/main/java/org/eclipse/sensinact/core/push/DataUpdate.java

@@ -1,5 +1,5 @@
 /*********************************************************************
-* Copyright (c) 2022 Contributors to the Eclipse Foundation.
+* Copyright (c) 2024 Contributors to the Eclipse Foundation.
 *
 * This program and the accompanying materials are made
 * available under the terms of the Eclipse Public License 2.0
@@ -16,6 +16,18 @@
 
 public interface DataUpdate {
 
+    /**
+     * Push an update into the sensiNact Digital Twin
+     * @param o - the update data
+     * @return a Promise representing the status of the update.
+     * <p> This promise will resolve successfully if the update(s)
+     * all complete normally. If any updates fail then the promise
+     * will fail with a {@link FailedUpdatesException} indicating
+     * which update(s) failed.</p>
+     * <p><strong>N.B.</strong> A failed promise does not indicate
+     * that no updates were successfully processed, only that
+     * at least one update failed to be applied.</p>
+     */
     Promise<?> pushUpdate(Object o);
 
 }

core/api/src/main/java/org/eclipse/sensinact/core/push/DataUpdateException.java

@@ -0,0 +1,92 @@
+/*********************************************************************
+* Copyright (c) 2024 Contributors to the Eclipse Foundation.
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which is available at https://www.eclipse.org/legal/epl-2.0/
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*   Kentyou - initial implementation
+**********************************************************************/
+package org.eclipse.sensinact.core.push;
+
+import java.util.Objects;
+
+public class DataUpdateException extends Exception {
+
+    private static final long serialVersionUID = -3948871450647637647L;
+    private final String modelPackageUri;
+    private final String model;
+    private final String provider;
+    private final String service;
+    private final String resource;
+
+    private final Object originalDto;
+
+    public DataUpdateException(String modelPackageUri, String model, String provider, String service, String resource,
+            Object originalDto, Throwable cause) {
+        this(modelPackageUri, model, provider, service, resource, originalDto,
+                cause == null ? getDefaultMessage(provider, service, resource) : cause.getMessage(), cause);
+    }
+
+    private static String getDefaultMessage(String provider, String service, String resource) {
+        return String.format("Data update failed for %s/%s/%s", provider, service, resource);
+    }
+
+    protected DataUpdateException(String modelPackageUri, String model, String provider, String service, String resource,
+            Object originalDto, String message, Throwable cause) {
+        super(message, cause);
+        Objects.requireNonNull(originalDto);
+        this.modelPackageUri = modelPackageUri;
+        this.model = model;
+        this.provider = provider;
+        this.service = service;
+        this.resource = resource;
+        this.originalDto = originalDto;
+    }
+
+    /**
+     * @return The discovered modelPackageUri, or null
+     */
+    public String getModelPackageUri() {
+        return modelPackageUri;
+    }
+
+    /**
+     * @return The discovered model, or null
+     */
+    public String getModel() {
+        return model;
+    }
+
+    /**
+     * @return The discovered provider, or null
+     */
+    public String getProvider() {
+        return provider;
+    }
+
+    /**
+     * @return The discovered service, or null
+     */
+    public String getService() {
+        return service;
+    }
+
+    /**
+     * @return The discovered resource, or null
+     */
+    public String getResource() {
+        return resource;
+    }
+
+    /**
+     * @return The DTO that was being mapped
+     */
+    public Object getOriginalDto() {
+        return originalDto;
+    }
+
+}

core/api/src/main/java/org/eclipse/sensinact/core/push/FailedUpdatesException.java

@@ -0,0 +1,42 @@
+/*********************************************************************
+* Copyright (c) 2024 Contributors to the Eclipse Foundation.
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which is available at https://www.eclipse.org/legal/epl-2.0/
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*   Kentyou - initial implementation
+**********************************************************************/
+package org.eclipse.sensinact.core.push;
+
+import static java.util.stream.Collectors.toUnmodifiableList;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Stream;
+
+public class FailedUpdatesException extends Exception {
+
+    private static final long serialVersionUID = 558905737809687311L;
+
+    private final List<DataUpdateException> failedUpdates;
+
+    public FailedUpdatesException(DataUpdateException failedUpdate) {
+        Objects.requireNonNull(failedUpdate);
+        failedUpdates = List.of(failedUpdate);
+        addSuppressed(failedUpdate);
+    }
+
+    public FailedUpdatesException(Stream<? extends DataUpdateException> failedUpdates) {
+        Objects.requireNonNull(failedUpdates);
+        this.failedUpdates = failedUpdates.collect(toUnmodifiableList());
+        this.failedUpdates.forEach(this::addSuppressed);
+    }
+
+    public List<DataUpdateException> getFailedUpdates() {
+        return failedUpdates;
+    }
+}

core/impl/integration-test.bndrun

@@ -5,7 +5,7 @@
 	bnd.identity;id='ch.qos.logback.classic'
 -resolve.effective: active
 
--runee: JavaSE-11
+-runee: JavaSE-17
 -runfw: org.apache.felix.framework
 -runproperties: \
 	org.osgi.framework.bootdelegation=org.mockito.internal.creation.bytebuddy.inject,\

core/impl/src/main/java/org/eclipse/sensinact/core/dto/impl/AbstractUpdateDto.java

@@ -45,4 +45,9 @@ public abstract class AbstractUpdateDto {
      * The timestamp for this update. If not set then the current time is used.
      */
     public Instant timestamp;
+
+    /**
+     * The original object which this update is derived from
+     */
+    public Object originalDto;
 }

core/impl/src/main/java/org/eclipse/sensinact/core/dto/impl/FailedMappingDto.java

@@ -0,0 +1,19 @@
+/*********************************************************************
+* Copyright (c) 2024 Contributors to the Eclipse Foundation.
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which is available at https://www.eclipse.org/legal/epl-2.0/
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*   Kentyou - initial implementation
+**********************************************************************/
+package org.eclipse.sensinact.core.dto.impl;
+
+public class FailedMappingDto extends AbstractUpdateDto {
+
+    public Throwable mappingFailure;
+
+}