Merge branch '266-message-queues' into 'master'

Message queues. #266

A message queue is a group shared by two devices that delivers messages from each device to the other in order. The first 64 bits of the message body contain a sequence number that's incremented for each message sent in a given direction. The incoming and outgoing sequence numbers and information about any messages received out of order and waiting to be delivered are stored in the group metadata.

See merge request !121

briar-api/src/org/briarproject/api/clients/MessageQueueManager.java

@@ -0,0 +1,52 @@
+package org.briarproject.api.clients;
+
+import org.briarproject.api.db.DbException;
+import org.briarproject.api.db.Metadata;
+import org.briarproject.api.db.Transaction;
+import org.briarproject.api.sync.ClientId;
+import org.briarproject.api.sync.Group;
+
+public interface MessageQueueManager {
+
+	/**
+	 * The key used for storing the queue's state in the group metadata.
+	 */
+	String QUEUE_STATE_KEY = "queueState";
+
+	/**
+	 * Sends a message using the given queue.
+	 */
+	QueueMessage sendMessage(Transaction txn, Group queue, long timestamp,
+			byte[] body, Metadata meta) throws DbException;
+
+	/**
+	 * Sets the message validator for the given client.
+	 */
+	void registerMessageValidator(ClientId c, QueueMessageValidator v);
+
+	/**
+	 * Sets the incoming message hook for the given client. The hook will be
+	 * called once for each incoming message that passes validation. Messages
+	 * are passed to the hook in order.
+	 */
+	void registerIncomingMessageHook(ClientId c, IncomingQueueMessageHook hook);
+
+	interface QueueMessageValidator {
+
+		/**
+		 * Validates the given message and returns its metadata if the message
+		 * is valid, or null if the message is invalid.
+		 */
+		Metadata validateMessage(QueueMessage q, Group g);
+	}
+
+	interface IncomingQueueMessageHook {
+
+		/**
+		 * Called once for each incoming message that passes validation.
+		 * Messages are passed to the hook in order.
+		 */
+		void incomingMessage(Transaction txn, QueueMessage q, Metadata meta)
+				throws DbException;
+	}
+}

briar-api/src/org/briarproject/api/clients/QueueMessage.java

@@ -0,0 +1,28 @@
+package org.briarproject.api.clients;
+
+import org.briarproject.api.sync.GroupId;
+import org.briarproject.api.sync.Message;
+import org.briarproject.api.sync.MessageId;
+
+import static org.briarproject.api.sync.SyncConstants.MAX_MESSAGE_BODY_LENGTH;
+import static org.briarproject.api.sync.SyncConstants.MESSAGE_HEADER_LENGTH;
+
+public class QueueMessage extends Message {
+
+	public static final int QUEUE_MESSAGE_HEADER_LENGTH =
+			MESSAGE_HEADER_LENGTH + 8;
+	public static final int MAX_QUEUE_MESSAGE_BODY_LENGTH =
+			MAX_MESSAGE_BODY_LENGTH - 8;
+
+	private final long queuePosition;
+
+	public QueueMessage(MessageId id, GroupId groupId, long timestamp,
+			long queuePosition, byte[] raw) {
+		super(id, groupId, timestamp, raw);
+		this.queuePosition = queuePosition;
+	}
+
+	public long getQueuePosition() {
+		return queuePosition;
+	}
+}

briar-api/src/org/briarproject/api/clients/QueueMessageFactory.java

@@ -0,0 +1,12 @@
+package org.briarproject.api.clients;
+
+import org.briarproject.api.sync.GroupId;
+import org.briarproject.api.sync.MessageId;
+
+public interface QueueMessageFactory {
+
+	QueueMessage createMessage(GroupId groupId, long timestamp,
+			long queuePosition, byte[] body);
+
+	QueueMessage createMessage(MessageId id, byte[] raw);
+}

briar-api/src/org/briarproject/api/sync/MessageValidator.java

@@ -1,12 +0,0 @@
-package org.briarproject.api.sync;
-
-import org.briarproject.api.db.Metadata;
-
-public interface MessageValidator {
-
-	/**
-	 * Validates the given message and returns its metadata if the message
-	 * is valid, or null if the message is invalid.
-	 */
-	Metadata validateMessage(Message m, Group g);
-}

briar-api/src/org/briarproject/api/sync/ValidationManager.java

@@ -30,14 +30,32 @@ public interface ValidationManager {
 		}
 	}
 
-	/** Sets the message validator for the given client. */
+	/**
+	 * Sets the message validator for the given client.
+	 */
 	void registerMessageValidator(ClientId c, MessageValidator v);
 
-	/** Registers a hook to be called whenever a message is validated. */
-	void registerValidationHook(ValidationHook hook);
+	/**
+	 * Sets the incoming message hook for the given client. The hook will be
+	 * called once for each incoming message that passes validation.
+	 */
+	void registerIncomingMessageHook(ClientId c, IncomingMessageHook hook);
 
-	interface ValidationHook {
-		void validatingMessage(Transaction txn, Message m, ClientId c,
-				Metadata meta) throws DbException;
+	interface MessageValidator {
+
+		/**
+		 * Validates the given message and returns its metadata if the message
+		 * is valid, or null if the message is invalid.
+		 */
+		Metadata validateMessage(Message m, Group g);
+	}
+
+	interface IncomingMessageHook {
+
+		/**
+		 * Called once for each incoming message that passes validation.
+		 */
+		void incomingMessage(Transaction txn, Message m, Metadata meta)
+				throws DbException;
 	}
 }