Extended DevicePackageManagementService API

Signed-off-by: coduz <alberto.codutti@eurotech.com>

service/device/commons/src/main/java/org/eclipse/kapua/service/device/management/commons/AbstractDeviceManagementServiceImpl.java

@@ -21,6 +21,8 @@
 import org.eclipse.kapua.model.id.KapuaId;
 import org.eclipse.kapua.model.type.ObjectTypeConverter;
 import org.eclipse.kapua.model.type.ObjectValueConverter;
+import org.eclipse.kapua.service.authorization.AuthorizationService;
+import org.eclipse.kapua.service.authorization.permission.PermissionFactory;
 import org.eclipse.kapua.service.device.management.message.notification.OperationStatus;
 import org.eclipse.kapua.service.device.management.message.request.KapuaRequestMessage;
 import org.eclipse.kapua.service.device.management.message.response.KapuaResponseMessage;
@@ -49,6 +51,9 @@ public abstract class AbstractDeviceManagementServiceImpl {
 
     private static final KapuaLocator LOCATOR = KapuaLocator.getInstance();
 
+    private static final AuthorizationService AUTHORIZATION_SERVICE = LOCATOR.getService(AuthorizationService.class);
+    private static final PermissionFactory PERMISSION_FACTORY = LOCATOR.getFactory(PermissionFactory.class);
+
     private static final DeviceEventService DEVICE_EVENT_SERVICE = LOCATOR.getService(DeviceEventService.class);
     private static final DeviceEventFactory DEVICE_EVENT_FACTORY = LOCATOR.getFactory(DeviceEventFactory.class);
 

service/device/management/packages/api/src/main/java/org/eclipse/kapua/service/device/management/packages/DevicePackageFactory.java

@@ -17,42 +17,49 @@
 import org.eclipse.kapua.service.device.management.packages.model.DevicePackageBundleInfos;
 import org.eclipse.kapua.service.device.management.packages.model.DevicePackages;
 import org.eclipse.kapua.service.device.management.packages.model.download.DevicePackageDownloadOperation;
+import org.eclipse.kapua.service.device.management.packages.model.download.DevicePackageDownloadOptions;
 import org.eclipse.kapua.service.device.management.packages.model.download.DevicePackageDownloadRequest;
+import org.eclipse.kapua.service.device.management.packages.model.install.DevicePackageInstallOptions;
 import org.eclipse.kapua.service.device.management.packages.model.install.DevicePackageInstallRequest;
+import org.eclipse.kapua.service.device.management.packages.model.uninstall.DevicePackageUninstallOptions;
 import org.eclipse.kapua.service.device.management.packages.model.uninstall.DevicePackageUninstallRequest;
 
 /**
- * Device package service definition.
+ * {@link DevicePackageFactory} definition.
  *
- * @since 1.0
+ * @since 1.0.0
  */
 public interface DevicePackageFactory extends KapuaObjectFactory {
 
     /**
      * Creates a new {@link DevicePackages}
      *
-     * @return
+     * @return the newly created {@link DevicePackages}
+     * @since 1.0.0
      */
     DevicePackages newDeviceDeploymentPackages();
 
     /**
      * Creates a new {@link DevicePackage}
      *
-     * @return
+     * @return The newly created {@link DevicePackage}
+     * @since 1.0.0
      */
     DevicePackage newDeviceDeploymentPackage();
 
     /**
-     * Creates a new device package bundle information
+     * Creates a new {@link DevicePackageBundleInfo}
      *
-     * @return
+     * @return the newly created {@link DevicePackageBundleInfo}
+     * @since 1.0.0
      */
     DevicePackageBundleInfo newDevicePackageBundleInfo();
 
     /**
-     * Creates a new device package bundle informations
+     * Creates a new {@link DevicePackageBundleInfos}
      *
-     * @return
+     * @return the newly created {@link DevicePackageBundleInfos}
+     * @since 1.0.0
      */
     DevicePackageBundleInfos newDevicePackageBundleInfos();
 
@@ -61,16 +68,26 @@ public interface DevicePackageFactory extends KapuaObjectFactory {
     //
 
     /**
-     * Creates a new device package download request
+     * Creates a new {@link DevicePackageDownloadRequest}
      *
-     * @return
+     * @return The newly created {@link DevicePackageDownloadRequest}
+     * @since 1.0.0
      */
     DevicePackageDownloadRequest newPackageDownloadRequest();
 
     /**
-     * Creates a new device package download operation
+     * Creates a new {@link DevicePackageDownloadOptions}
      *
-     * @return
+     * @return the newly created {@link DevicePackageDownloadOptions}
+     * @since 1.1.0
+     */
+    DevicePackageDownloadOptions newDevicePackageDownloadOptions();
+
+    /**
+     * Creates a new {@link DevicePackageDownloadOperation}
+     *
+     * @return the newly created {@link DevicePackageDownloadOperation}
+     * @since 1.0.0
      */
     DevicePackageDownloadOperation newPackageDownloadOperation();
 
@@ -81,18 +98,37 @@ public interface DevicePackageFactory extends KapuaObjectFactory {
     /**
      * Creates a new {@link DevicePackageInstallRequest}
      *
-     * @return
+     * @return the newly created {@link DevicePackageInstallRequest}
+     * @since 1.0.0
      */
     DevicePackageInstallRequest newPackageInstallRequest();
 
+    /**
+     * Creates a new {@link DevicePackageInstallOptions}
+     *
+     * @return the newly created {@link DevicePackageInstallOptions}
+     * @since 1.1.0
+     */
+    DevicePackageInstallOptions newDevicePackageInstallOptions();
+
+
     //
     // Uninstall operation
     //
 
     /**
-     * Creates a new device package uninstall request
+     * Creates a new {@link DevicePackageUninstallRequest}
      *
-     * @return
+     * @return the newly created {@link DevicePackageUninstallRequest}
+     * @since 1.0.0
      */
     DevicePackageUninstallRequest newPackageUninstallRequest();
+
+    /**
+     * Creates a new {@link DevicePackageUninstallOptions}
+     *
+     * @return the newly created {@link DevicePackageUninstallOptions}
+     * @since 1.1.0
+     */
+    DevicePackageUninstallOptions newDevicePackageUninstallOptions();
 }

service/device/management/packages/api/src/main/java/org/eclipse/kapua/service/device/management/packages/DevicePackageManagementService.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011, 2016 Eurotech and/or its affiliates and others
+ * Copyright (c) 2016, 2019 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -16,103 +16,170 @@
 import org.eclipse.kapua.service.KapuaService;
 import org.eclipse.kapua.service.device.management.packages.model.DevicePackages;
 import org.eclipse.kapua.service.device.management.packages.model.download.DevicePackageDownloadOperation;
+import org.eclipse.kapua.service.device.management.packages.model.download.DevicePackageDownloadOptions;
 import org.eclipse.kapua.service.device.management.packages.model.download.DevicePackageDownloadRequest;
 import org.eclipse.kapua.service.device.management.packages.model.install.DevicePackageInstallOperation;
+import org.eclipse.kapua.service.device.management.packages.model.install.DevicePackageInstallOptions;
 import org.eclipse.kapua.service.device.management.packages.model.install.DevicePackageInstallRequest;
 import org.eclipse.kapua.service.device.management.packages.model.uninstall.DevicePackageUninstallOperation;
+import org.eclipse.kapua.service.device.management.packages.model.uninstall.DevicePackageUninstallOptions;
 import org.eclipse.kapua.service.device.management.packages.model.uninstall.DevicePackageUninstallRequest;
 
 /**
- * Device package service definition.
+ * {@link DevicePackageManagementService} definition.
+ * <p>
+ * The {@link DevicePackageManagementService} is used to interact with the DEPLOY-V2 device application.
  *
- * @since 1.0
+ * @since 1.0.0
  */
 public interface DevicePackageManagementService extends KapuaService {
 
     /**
-     * Get the installed packages list
+     * Gets the installed {@link DevicePackages}s
      *
-     * @param scopeId
-     * @param deviceId
-     * @param timeout
-     * @return
-     * @throws KapuaException
+     * @param scopeId  The scope {@link KapuaId} of the target device
+     * @param deviceId The device {@link KapuaId} of the target device
+     * @param timeout  The timeout in milliseconds for the request to complete
+     * @return The {@link DevicePackages}
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
      */
     DevicePackages getInstalled(KapuaId scopeId, KapuaId deviceId, Long timeout) throws KapuaException;
 
+    //
+    // Download
+    //
+
     /**
-     * Starts a download package operation
+     * Downloads a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage}
      *
-     * @param scopeId
-     * @param deviceId
-     * @param packageDownloadRequest
-     * @param timeout
-     * @throws KapuaException
+     * @param scopeId                The scope {@link KapuaId} of the target device
+     * @param deviceId               The device {@link KapuaId} of the target device
+     * @param packageDownloadRequest The {@link DevicePackageDownloadRequest} for this request
+     * @param timeout                The timeout in milliseconds for the request to complete
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
+     * @deprecated since 1.1.0. Please make use of {@link #downloadExec(KapuaId, KapuaId, DevicePackageDownloadRequest, DevicePackageDownloadOptions)}.
      */
+    @Deprecated
     void downloadExec(KapuaId scopeId, KapuaId deviceId, DevicePackageDownloadRequest packageDownloadRequest, Long timeout) throws KapuaException;
 
     /**
-     * Interrupt a download package operation
+     * Downloads a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage}
+     *
+     * @param scopeId                The scope {@link KapuaId} of the target device
+     * @param deviceId               The device {@link KapuaId} of the target device
+     * @param packageDownloadRequest The {@link DevicePackageDownloadRequest} for this request
+     * @param packageDownloadOptions The {@link DevicePackageDownloadOptions} for this request
+     * @throws KapuaException if error occurs during processing
+     * @since 1.1.0
+     */
+    void downloadExec(KapuaId scopeId, KapuaId deviceId, DevicePackageDownloadRequest packageDownloadRequest, DevicePackageDownloadOptions packageDownloadOptions) throws KapuaException;
+
+    /**
+     * Interrupts a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage} download operation
      *
-     * @param scopeId
-     * @param deviceId
-     * @param timeout
+     * @param scopeId  The scope {@link KapuaId} of the target device
+     * @param deviceId The device {@link KapuaId} of the target device
+     * @param timeout  The timeout in milliseconds for the request to complete
      * @throws KapuaException
+     * @since 1.0.0
      */
     void downloadStop(KapuaId scopeId, KapuaId deviceId, Long timeout) throws KapuaException;
 
     /**
-     * Gets the download package status
+     * Gets the {@link DevicePackageDownloadOperation} status.
      *
-     * @param scopeId
-     * @param deviceId
-     * @param timeout
+     * @param scopeId  The scope {@link KapuaId} of the target device
+     * @param deviceId The device {@link KapuaId} of the target device
+     * @param timeout  The timeout in milliseconds for the request to complete
      * @return
-     * @throws KapuaException
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
      */
     DevicePackageDownloadOperation downloadStatus(KapuaId scopeId, KapuaId deviceId, Long timeout) throws KapuaException;
 
+    //
+    // Install
+    //
+
     /**
-     * Installs a package
+     * Installs a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage}
      *
-     * @param scopeId
-     * @param deviceId
-     * @param packageInstallRequest
-     * @param timeout
-     * @throws KapuaException
+     * @param scopeId               The scope {@link KapuaId} of the target device
+     * @param deviceId              The device {@link KapuaId} of the target device
+     * @param packageInstallRequest The {@link DevicePackageInstallRequest} for this request
+     * @param timeout               The timeout in milliseconds for the request to complete
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
+     * @deprecated since 1.1.0. Please make use of {@link #installExec(KapuaId, KapuaId, DevicePackageInstallRequest, DevicePackageInstallOptions)}.
      */
+    @Deprecated
     void installExec(KapuaId scopeId, KapuaId deviceId, DevicePackageInstallRequest packageInstallRequest, Long timeout) throws KapuaException;
 
     /**
-     * Gets the package installation status
+     * Installs a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage}
      *
-     * @param scopeId
-     * @param deviceId
-     * @param timeout
+     * @param scopeId               The scope {@link KapuaId} of the target device
+     * @param deviceId              The device {@link KapuaId} of the target device
+     * @param packageInstallRequest The {@link DevicePackageInstallRequest} for this request
+     * @param packageInstallOptions The {@link DevicePackageInstallOptions} for this request
+     * @throws KapuaException if error occurs during processing
+     * @since 1.1.0
+     */
+    void installExec(KapuaId scopeId, KapuaId deviceId, DevicePackageInstallRequest packageInstallRequest, DevicePackageInstallOptions packageInstallOptions) throws KapuaException;
+
+    /**
+     * Gets the {@link DevicePackageInstallOperation} status.
+     *
+     * @param scopeId  The scope {@link KapuaId} of the target device
+     * @param deviceId The device {@link KapuaId} of the target device
+     * @param timeout  The timeout in milliseconds for the request to complete
      * @return
-     * @throws KapuaException
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
      */
     DevicePackageInstallOperation installStatus(KapuaId scopeId, KapuaId deviceId, Long timeout) throws KapuaException;
 
+    //
+    // Uninstall
+    //
+
     /**
-     * Uninstalls a package
+     * Uninstalls a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage}
      *
-     * @param scopeId
-     * @param deviceId
-     * @param packageUninstallRequest
-     * @param timeout
-     * @throws KapuaException
+     * @param scopeId                 The scope {@link KapuaId} of the target device
+     * @param deviceId                The device {@link KapuaId} of the target device
+     * @param packageUninstallRequest The {@link DevicePackageUninstallRequest} for this request
+     * @param timeout                 The timeout in milliseconds for the request to complete
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
+     * @deprecated since 1.1.0. Please make use of {@link #uninstallExec(KapuaId, KapuaId, DevicePackageUninstallRequest, DevicePackageUninstallOptions)}.
      */
+    @Deprecated
     void uninstallExec(KapuaId scopeId, KapuaId deviceId, DevicePackageUninstallRequest packageUninstallRequest, Long timeout) throws KapuaException;
 
     /**
-     * Gets the package uninstallation status
+     * Uninstalls a {@link org.eclipse.kapua.service.device.management.packages.model.DevicePackage}
      *
-     * @param scopeId
-     * @param deviceId
-     * @param timeout
+     * @param scopeId                 The scope {@link KapuaId} of the target device
+     * @param deviceId                The device {@link KapuaId} of the target device
+     * @param packageUninstallRequest The {@link DevicePackageUninstallRequest} for this request
+     * @param packageUninstallOptions The The {@link DevicePackageUninstallOptions} for this request
+     * @throws KapuaException if error occurs during processing
+     * @since 1.1.0
+     */
+    void uninstallExec(KapuaId scopeId, KapuaId deviceId, DevicePackageUninstallRequest packageUninstallRequest, DevicePackageUninstallOptions packageUninstallOptions) throws KapuaException;
+
+    /**
+     * Gets the {@link DevicePackageUninstallOperation}.
+     *
+     * @param scopeId  The scope {@link KapuaId} of the target device
+     * @param deviceId The device {@link KapuaId} of the target device
+     * @param timeout  The timeout in milliseconds for the request to complete
      * @return
-     * @throws KapuaException
+     * @throws KapuaException if error occurs during processing
+     * @since 1.0.0
      */
     DevicePackageUninstallOperation uninstallStatus(KapuaId scopeId, KapuaId deviceId, Long timeout) throws KapuaException;
 }

service/device/management/packages/api/src/main/java/org/eclipse/kapua/service/device/management/packages/model/DevicePackageOptions.java

@@ -0,0 +1,25 @@
+/*******************************************************************************
+ * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     Eurotech - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.kapua.service.device.management.packages.model;
+
+import org.eclipse.kapua.model.id.KapuaId;
+
+public interface DevicePackageOptions {
+
+    void setTimeout(Long timeout);
+
+    Long getTimeout();
+
+    KapuaId getForcedOperationId();
+
+    void setForcedOperationId(KapuaId forcedOperationId);
+}