com.adobe.cq.screens.device.DeviceManager Maven / Gradle / Ivy

/*************************************************************************
 *
 * ADOBE CONFIDENTIAL
 * __________________
 *
 *  Copyright 2016 Adobe Systems Incorporated
 *  All Rights Reserved.
 *
 * NOTICE:  All information contained herein is, and remains
 * the property of Adobe Systems Incorporated and its suppliers,
 * if any.  The intellectual and technical concepts contained
 * herein are proprietary to Adobe Systems Incorporated and its
 * suppliers and are protected by trade secret or copyright law.
 * Dissemination of this information or reproduction of this material
 * is strictly forbidden unless prior written permission is obtained
 * from Adobe Systems Incorporated.
 ************************************************************************/
package com.adobe.cq.screens.device;

import java.io.InputStream;
import java.util.Iterator;

import aQute.bnd.annotation.ProviderType;
import org.apache.commons.collections.Predicate;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.commons.json.JSONException;
import org.apache.sling.commons.json.JSONObject;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.jcr.Node;
import javax.jcr.RepositoryException;

/**
 * Manages the devices in the repository.
 */
@ProviderType
public interface DeviceManager {

    /**
     * Returns the device with the given id or {@code null}
     * @param deviceId the device id
     * @return the device or {@code null}
     */
    @CheckForNull
    Device getDevice(@Nonnull String deviceId);

    /**
     * Returns the status of the device with the given id.
     * @param deviceId the device id
     * @return status or {@code null} if the device does not exist.
     */
    @CheckForNull
    DeviceStatus getDeviceStatus(@Nonnull String deviceId);

    /**
     * Returns an iterator over all devices.
     * @return an iterator.
     */
    @Nonnull
    Iterator getDevices();

    /**
     * Returns an iterator over all devices that fulfill the given predicate.
     * @param predicate the filter predicate or {@code null}
     * @return the iterator.
     */
    @Nonnull
    Iterator getDevices(@Nullable Predicate predicate);

    /**
     * Returns an iterator over all devices that are related to the specified Resource.
     * @param resource the resource that the devices are related to
     * @return the iterator.
     */
    @Nonnull
    Iterator getRelatedDevices(@Nonnull Resource resource);

    /**
     * Creates a new device for the given tenant.
     * @param tenant the name of the tenant. eg "we-retail".
     * @return the newly created device
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device createDevice(@Nonnull String tenant) throws RepositoryException;

    /**
     * Deletes an existing device, and removes any existing assignment to a display.
     * @param deviceId the device id
     * @throws RepositoryException if an error occurrs.
     */
    void deleteDevice(@Nonnull String deviceId) throws RepositoryException;

    /**
     * Generates and sets a new password for the device user.
     * @param device the device
     * @return the new password
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    String updatePassword(@Nonnull Device device) throws RepositoryException;

    /**
     * Updates the device metadata.
     * @param device the device
     * @param metadata the metadata.
     * @return the device for chaining.
     * @throws JSONException if a JSON error occurrs
     * @throws RepositoryException if an error occurrs
     */
    @Nonnull
    Device setMetadata(@Nonnull Device device, @Nonnull JSONObject metadata) throws JSONException, RepositoryException;

    /**
     * Assigns a display to a device and creates a new DeviceConfig.
     *
     * @param device the device
     * @param displayPath the display path
     * @return the device for chaining.
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device assignDisplay(@Nonnull Device device, @Nonnull String displayPath) throws RepositoryException;

    /**
     * Assigns a device to an existing device config.
     *
     * @param device the device
     * @param config the device config
     * @return the device for chaining.
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device assignDeviceConfig(@Nonnull Device device, @Nonnull DeviceConfig config) throws RepositoryException;

    /**
     * Removes the display assignment from the device.
     * @param device the device
     * @param removeConfig {@code true} to also remove the device config from the display.
     * @return the device for chaining.
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device removeDisplay(@Nonnull Device device, boolean removeConfig) throws RepositoryException;

    /**
     * Saves the provided device logs to the repository.
     * @param device the device
     * @param type the type of logs to save
     * @param data the log data
     * @return the device for chaining.
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device saveLogs(@Nonnull Device device, @Nonnull String type, @Nonnull InputStream data) throws RepositoryException;

    /**
     * Deletes the existing device logs from the repository.
     * @param device the device
     * @param type the type of logs to delete, if not specified all logs will be deleted
     * @return the device for chaining.
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device deleteLogs(@Nonnull Device device, @Nullable String type) throws RepositoryException;


    /**
     * Adds new screenshot content as a nt:file under device's profile_screens node
     * @param device the device
     * @return the device for chaining.
     * @throws RepositoryException if an error occurrs.
     */
    @Nonnull
    Device saveScreenshot(@Nonnull Device device, @Nonnull InputStream data) throws RepositoryException;

    /**
     * Acknowledge the command for the specified device.
     *
     * @param device  the device for which the command is acknowledged
     * @param command the command to acknowledge
     * @throws RepositoryException if an error accessing the repository occurs.
     */
    void acknowledgeCommand(@Nonnull Device device, @Nonnull String command) throws RepositoryException;

    /**
     * Execute the desired command on the specified device.
     *
     * @param device  the device to execute the command on
     * @param command the command to execute
     * @throws RepositoryException if an error accessing the repository occurs.
     */
    void executeCommand(@Nonnull Device device, @Nonnull String command) throws RepositoryException;

    /**
     * Execute the desired command on the specified device.
     *
     * @param device  the device to execute the command on
     * @param command the command to execute
     * @param payload the payload to add to the command. If {@code null} then the command doesn't have a payload.
     * @throws RepositoryException if an error accessing the repository occurs.
     */
    void executeCommand(@Nonnull Device device, @Nonnull String command, @Nullable JSONObject payload) throws RepositoryException;

    /**
     * Execute the desired command on the specified device.
     *
     * @param device  the device to execute the command on
     * @param command the command to execute
     * @param payload the payload to add to the command. If {@code null} then the command doesn't have a payload.
     * @param requiresAck whether the command requires acknowledgement that the device has processed it.
     * @throws RepositoryException if an error accessing the repository occurs.
     */
    void executeCommand(@Nonnull Device device, @Nonnull String command, @Nullable JSONObject payload, boolean requiresAck) throws RepositoryException;
}