com.arm.mbed.cloud.sdk.subscribe.Observer Maven / Gradle / Ivy

Go to download
package com.arm.mbed.cloud.sdk.subscribe;

import java.util.concurrent.Future;

import io.reactivex.Flowable;
import io.reactivex.Single;

import com.arm.mbed.cloud.sdk.annotations.Nullable;
import com.arm.mbed.cloud.sdk.annotations.Preamble;
import com.arm.mbed.cloud.sdk.common.MbedCloudException;
import com.arm.mbed.cloud.sdk.common.TimePeriod;

/**
 * Object based on ReactiveX's Flowable
 * and attempting to provide a solution following the Observer
 * pattern which reacts to Pelion Cloud notifications such as device state changes, sensor value changes, etc.
 *
 * @param 
 *            Type of the notification message value.
 */
@Preamble(description = "Cloud notification observer")
public interface Observer {
    /**
     * Gets Observer's unique identifier.
     *
     * @return a UUID.
     */
    String getId();

    /**
     * Adds a callback function to be executed every time a notification is received.
     * 
     * Note: use callbacks when you want to carry out single actions when notifications are received.
     * 

     * If you want to perform combined and complex actions in such events, please consider using {@link #flow()}
     * instead.
     *
     * @param callback
     *            callback to add.
     */
    void addCallback(NotificationCallback callback);

    /**
     * Notifies a message to the observer.
     *
     * @param message
     *            a notification message.
     * @throws MbedCloudException
     *             if a problem occurred during the process.
     */
    void notify(NotificationMessage message) throws MbedCloudException;

    /**
     * Notifies data change to the observer.
     *
     * @param data
     *            some data of interest
     * @throws MbedCloudException
     *             if a problem occurred during the process.
     */
    void notify(T data) throws MbedCloudException;

    /**
     * Removes all callbacks registered to the observer.
     */
    void removeCallback();

    /**
     * Unregister the observer from the system.
     * 

     * Note: the communication channel comprised within the observer will also be closed.
     * 

     * Hence, the observer should not be used after this action.
     *
     * @throws MbedCloudException
     *             if an error happened during the process
     */
    void unsubscribe() throws MbedCloudException;

    /**
     * Gets the RxJava
     * Flowable/communication channel
     * the observer is based on.
     * 

     * Such object can be considered as a stream of asynchronous events with the same sort of simple, composable
     * operations that you use for collections of data items like arrays.
     *
     * @see ReactiveX documentation
     * @return underlying flowable.
     */
    Flowable flow();

    /**
     * Gets an RxJava Single for one notification.
     *
     * @param timeout
     *            time before which a notification must be received.
     * @return a single.
     * @throws MbedCloudException
     *             if a problem occurred during the process.
     */
    Single singleNotification(@Nullable TimePeriod timeout) throws MbedCloudException;

    /**
     * Gets a future for one notification.
     * 

     * The data will be returned when a notification has been emitted to the communication channel.
     *
     * @return a future.
     * @throws MbedCloudException
     *             if a problem occurred during the process.
     */
    Future futureOne() throws MbedCloudException;

    /**
     * Gets a future for one notification.
     * 

     * Similar to {@link #futureOne()} but a timeout is set on the communication channel.
     *
     * @param timeout
     *            time before which a notification must be received.
     * @return a future.
     * @throws MbedCloudException
     *             if a problem occurred during the process.
     */
    Future futureOne(@Nullable TimePeriod timeout) throws MbedCloudException;

    /**
     * Gets one notification data (the first one emitted to the communication channel).
     * 

     * Note: after the notification is received, the observer is unsubscribed and therefore will become unusable.
     *
     * @return notification data.
     * @throws MbedCloudException
     *             if a problem occurred during the process or the timeout was elapsed.
     */
    @Nullable
    T one() throws MbedCloudException;

    /**
     * Gets one notification data (the first one emitted to the communication channel).
     * 

     * Similar to {@link #futureOne()} but a timeout is set on the communication channel.
     *
     * @param timeout
     *            time before which a notification must be received.
     * @return notification data.
     * @throws MbedCloudException
     *             if a problem occurred during the process or the timeout was elapsed.
     */
    @Nullable
    T one(@Nullable TimePeriod timeout) throws MbedCloudException;

    /**
     * Gets the number of callbacks registered to this observer.
     *
     * @return the number of callbacks.
     */
    int numberOfCallbacks();

    /**
     * States whether the observer has been disposed or not.
     * 
     * If it is the case, no messages will be able to go through the communication channel it comprises.
     *
     * @return True if the observer has been disposed. False otherwise.
     */
    boolean isDisposed();

    /**
     * Gets the subscription type of the observer.
     *
     * @return type
     */
    SubscriptionType getSubscriptionType();

    /**
     * Gets the string representation of the observer.
     *
     * @return string
     */
    @Override
    String toString();
}