com.adobe.cq.screens.DeviceMessageQueue 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;

import java.util.List;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import org.apache.sling.commons.json.JSONObject;

import aQute.bnd.annotation.ProviderType;

/**
 * The device message queue allows to queue messages
 * unidirectional to the devices
 */
@ProviderType
public interface DeviceMessageQueue {

    /**
     * Queue message and payload
     * @param path The path of the resource that this message belongs.
     * @param entry The message queue entry.
     */
    void queueEntry(@Nonnull String path, @Nonnull Entry entry);

    /**
     * Dequeue message and payload
     * @param path The path of the resource that this message belongs.
     * @return the next entry or {@code null} if the queue is empty.
     */
    @CheckForNull
    Entry dequeueEntry(@Nonnull String path);

    /**
     * Creates a new device message queue entry builder with the given message.
     * @param message the message for the entry.
     * @return the builder.
     */
    @Nonnull
    EntryBuilder createEntryBuilder(@Nonnull String message);

    /**
     * Queue message
     * @param path The path of the resource that this message belongs.
     * @param message A simple message with no payload.
     */
    void queue(@Nonnull String path, @Nonnull String message);

    /**
     * Queue message
     * @param path The path of the resource that this message belongs.
     * @param message A simple message with no payload.
     * @param requiresAck Whether acknowledgement for the message is required.
     */
    void queue(@Nonnull String path, @Nonnull String message, boolean requiresAck);

    /**
     * Dequeue message
     * @param path The path of the resource that this message belongs.
     * @return the next message or {@code null} if the queue is empty.
     */
    @CheckForNull
    String dequeue(@Nonnull String path);

    /**
     * Get entities for a device that require ack
     * @param path The path of the resource that this message belongs.
     * @return list of entities requiring ack
     */
    List getEntriesRequiringAck(@Nonnull String path);

    /**
     * Remove the specified message from the queue defined by the path
     * @param path The path of the resource that this message belongs.
     * @param message The specific message to remove.
     */
    void remove(@Nonnull String path, @Nonnull String message);

    /**
     * Dequeue message and payload to be delivered.
     * If the entry being dequeued requires acknowledgement, then it is marked as delivered and still kept in the queue until acknowledged;
     * otherwise, it is simply removed from the queue.
     * @param path The path of the resource that this message belongs.
     * @return the next entry not delivered or {@code null} if none is found.
     */
    @CheckForNull
    Entry dequeueDeliverableEntry(@Nonnull String path);

    /**
     * Mark the entry containing the message as delivered and, if not requiring acknowledgement or already acknowledged, remove it from the queue given by the path
     * @param path The path of the resource that this message belongs.
     * @param message The message for which to handle delivery.
     */
    void markDeliveredOrRemove(@Nonnull String path, @Nonnull String message);

    /**
     * Mark the entry containing the message as acknowledged
     * @param path The path of the resource that this message belongs.
     * @param message The message to mark acknowledged.
     */
    void markAcknowledged(@Nonnull String path, @Nonnull String message);

    /**
     * Entry that can be added to the queue.
     */
    @ProviderType
    interface Entry {

        /**
         * Returns the message of the entry
         * @return the message
         */
        @Nonnull
        String getMessage();

        /**
         * Returns the payload of the entry or {@code null} if it does not contain a payload.
         * @return the payload.
         */
        @CheckForNull
        JSONObject getPayload();

        /**
         * Returns whether the message of the entry requires acknowledgement or not
         */
        boolean requiresAck();

        /**
         * Returns whether the message of the entry is acknowledged or not
         */
        boolean isAcknowledged();

        /**
         * Returns whether the message of the entry was delivered or not
         */
        boolean isDelivered();
    }

    /**
     * Builder for device message queue entries.
     */
    @ProviderType
    interface EntryBuilder {

        /**
         * Sets the payload of this entry
         * @param obj the payload to send
         * @return {@code this} builder.
         */
        @Nonnull
        EntryBuilder setPayload(@Nullable JSONObject obj);

        /**
         * Marks that this entry requires acknowledgement
         * @param requiresAck whether acknowledgement is required or not
         * @return {@code this} builder.
         */
        @Nonnull
        EntryBuilder setRequiresAck(boolean requiresAck);

        /**
         * Marks the entry as delivered
         * @param delivered whether delivered or not
         */
        EntryBuilder setDelivered(boolean delivered);

        /**
         * Marks the entry as acknowledged
         * @param acknowledged whether acknowledged or not
         */
        EntryBuilder setAcknowledged(boolean acknowledged);

        /**
         * Creates the entry of this builder.
         * @return the entry.
         */
        @Nonnull
        DeviceMessageQueue.Entry build();

    }
}