meerkat-java/meerkat-common/src/main/java/meerkat/bulletinboard/AsyncBulletinBoardClient.java

package meerkat.bulletinboard;

import com.google.common.util.concurrent.FutureCallback;
import com.google.protobuf.ByteString;
import meerkat.protobuf.BulletinBoardAPI.*;

import java.util.List;

/**
 * Created by Arbel Deutsch Peled on 14-Dec-15.
 */
public interface AsyncBulletinBoardClient extends BulletinBoardClient {

    public interface MessageHandler {
        void handleNewMessages(List<BulletinBoardMessage> messageList);
    }

    /**
     * Post a message to the bulletin board in an asynchronous manner
     * @param msg is the message to be posted
     * @param callback is a class containing methods to handle the result of the operation
     * @return a unique message ID for the message, that can be later used to retrieve the batch
     */
    public MessageID postMessage(BulletinBoardMessage msg, FutureCallback<Boolean> callback);

    /**
     * Perform an end-to-end post of a signed batch message
     * @param completeBatch contains all the data of the batch including the meta-data and the signature
     * @param callback is a class containing methods to handle the result of the operation
     * @return a unique identifier for the batch message
     */
    public MessageID postBatch(CompleteBatch completeBatch, FutureCallback<Boolean> callback);

    /**
     * This message informs the server about the existence of a new batch message and supplies it with the tags associated with it
     * @param beginBatchMessage contains the data required to begin the batch
     * @param callback is a callback function class for handling results of the operation
     */
    public void beginBatch(BeginBatchMessage beginBatchMessage, FutureCallback<Boolean> callback);

    /**
     * This method posts batch data into an (assumed to be open) batch
     * It does not close the batch
     * @param signerId is the canonical form for the ID of the sender of this batch
     * @param batchId is a unique (per signer) ID for this batch
     * @param batchDataList is the (canonically ordered) list of data comprising the portion of the batch to be posted
     * @param startPosition is the location (in the batch) of the first entry in batchDataList
     *                      (optionally used to continue interrupted post operations)
     *                      The first position in the batch is position 0
     * @param callback is a callback function class for handling results of the operation
     */
    public void postBatchData(byte[] signerId, int batchId, List<BatchData> batchDataList,
                              int startPosition, FutureCallback<Boolean> callback);

    /**
     * Overloading of the postBatchData method which starts at the first position in the batch
     */
    public void postBatchData(byte[] signerId, int batchId, List<BatchData> batchDataList, FutureCallback<Boolean> callback);

    /**
     * Overloading of the postBatchData method which uses ByteString
     */
    public void postBatchData(ByteString signerId, int batchId, List<BatchData> batchDataList,
                              int startPosition, FutureCallback<Boolean> callback);

    /**
     * Overloading of the postBatchData method which uses ByteString and starts at the first position in the batch
     */
    public void postBatchData(ByteString signerId, int batchId, List<BatchData> batchDataList, FutureCallback<Boolean> callback);

    /**
     * Attempts to close a batch message
     * @param closeBatchMessage contains the data required to close the batch
     * @param callback is a callback function class for handling results of the operation
     */
    public void closeBatch(CloseBatchMessage closeBatchMessage, FutureCallback<Boolean> callback);

    /**
     * Check how "safe" a given message is in an asynchronous manner
     * The result of the computation is a rank between 0.0 and 1.0 indicating the fraction of servers containing the message
     * @param id is the unique message identifier for retrieval
     * @param callback is a callback function class for handling results of the operation
     */
    public void getRedundancy(MessageID id, FutureCallback<Float> callback);

    /**
     * Read all messages posted matching the given filter in an asynchronous manner
     * Note that if messages haven't been "fully posted", this might return a different
     * set of messages in different calls. However, messages that are fully posted
     * are guaranteed to be included.
     * @param filterList return only messages that match the filters (null means no filtering).
     * @param callback is a callback function class for handling results of the operation
     */
    public void readMessages(MessageFilterList filterList, FutureCallback<List<BulletinBoardMessage>> callback);

    /**
     * Read a given batch message from the bulletin board
     * @param batchSpecificationMessage contains the data required to specify a single batch instance
     * @param callback is a callback class for handling the result of the operation
     */
    public void readBatch(BatchSpecificationMessage batchSpecificationMessage, FutureCallback<CompleteBatch> callback);

    /**
     * Subscribes to a notifier that will return any new messages on the server that match the given filters
     * @param filterList defines the set of filters for message retrieval
     * @param messageHandler defines the handler for new messages received
     */
    public void subscribe(MessageFilterList filterList, MessageHandler messageHandler);

}