Add message cancellation and Entity-Component-System pattern support

Author: tomcashman

CHANGES

@@ -1,3 +1,9 @@
+[1.6.0]
+- Add EntityMessageData for transportation of entities in an Entity-Component-System pattern
+- Allow for cancellation of messages in the bus queue
+- Add method to notify message bus of deleted entities so that messages are cancelled
+- Add CancelledMessageHandler that can be notified of cancelled messages
+
 [1.5.0]
 - Add LockProvider interface to allow for alternative locking implementations
 

build.gradle

@@ -27,7 +27,7 @@ if(project.hasProperty('ossrhUser') && project.hasProperty("release")) {
 }
 
 group = 'org.mini2Dx'
-version = '1.5.1-SNAPSHOT'
+version = '1.6.0-SNAPSHOT'
 description = 'A lightweight message bus library for Java-based game engines'
 
 repositories {

src/main/java/org/mini2Dx/minibus/CancelledMessageHandler.java

@@ -0,0 +1,43 @@
+/**
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 See AUTHORS file
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.mini2Dx.minibus;
+
+/**
+ * Common interface for processing cancelled messages
+ */
+public interface CancelledMessageHandler {
+
+	/**
+	 * Called when a message is cancelled
+	 *
+	 * @param messageType The string representing the message type
+	 * @param source
+	 *            The {@link MessageExchange} that sent the message
+	 * @param receiver
+	 *            The {@link MessageExchange} that received the message
+	 * @param messageData
+	 *            The {@link MessageData} that was received if any (i.e. possibly null)
+	 */
+	public void onMessageCancelled(String messageType, MessageExchange source, MessageExchange receiver, MessageData messageData);
+}

src/main/java/org/mini2Dx/minibus/EntityMessageData.java

@@ -0,0 +1,32 @@
+/**
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 See AUTHORS file
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.mini2Dx.minibus;
+
+/**
+ * Interface for message data that contains an entity in an Entity-Component-System pattern
+ */
+public interface EntityMessageData extends MessageData {
+
+	public int getEntityId();
+}

src/main/java/org/mini2Dx/minibus/MessageBus.java

@@ -47,6 +47,7 @@ public class MessageBus {
 	public static LockProvider LOCK_PROVIDER = new JvmLockProvider();
 
 	final List<MessageExchange> exchangers = new SnapshotArrayList<MessageExchange>();
+	final List<CancelledMessageHandler> cancelledMessageHandlers = new SnapshotArrayList<CancelledMessageHandler>();
 	final MessageTransmissionPool transmissionPool = new MessageTransmissionPool();
 
 	private final MessageExchange anonymousExchange;
@@ -371,7 +372,72 @@ public void broadcastQuery(String messageType, MessageData messageData, String r
 		broadcast(queryMessageExchange, messageType, messageData);
 	}
 
-	void dispose(MessageExchange messageExchange) {
+	/**
+	 * Cancels all messages in the bus.
+	 */
+	public void cancelAllMessages() {
+		cancelAllMessages(true);
+	}
+
+	/**
+	 * Cancels all messages in the bus
+	 * @param notify True if {@link CancelledMessageHandler}s should be notified
+	 */
+	public void cancelAllMessages(boolean notify) {
+		for(int i = exchangers.size() - 1; i >= 0; i--) {
+			if(i >= exchangers.size()) {
+				continue;
+			}
+			exchangers.get(i).cancelAllMessages(notify);
+		}
+	}
+
+	/**
+	 * Cancels all messages of a specific type in the bus
+	 * @param messageType The message type to cancel
+	 */
+	public void cancelAllMessages(String messageType) {
+		cancelAllMessages(messageType, true);
+	}
+
+	/**
+	 * Cancels all messages of a specific type in the bus
+	 * @param messageType The message type to cancel
+	 * @param notify True if {@link CancelledMessageHandler}s should be notified
+	 */
+	public void cancelAllMessages(String messageType, boolean notify) {
+		for(int i = exchangers.size() - 1; i >= 0; i--) {
+			if(i >= exchangers.size()) {
+				continue;
+			}
+			exchangers.get(i).cancelAllMessages(messageType, notify);
+		}
+	}
+
+	/**
+	 * Notify message exchanges of a deleted entity
+	 * @param entityId The entity ID
+	 */
+	public void entityDeleted(int entityId) {
+		for(int i = exchangers.size() - 1; i >= 0; i--) {
+			if(i >= exchangers.size()) {
+				continue;
+			}
+			exchangers.get(i).entityDeleted(entityId);
+		}
+	}
+
+	void notifyMessageCancelled(String messageType, MessageExchange source, MessageExchange receiver, MessageData messageData) {
+		for(int i = cancelledMessageHandlers.size() - 1; i >= 0; i--) {
+			if(i >= cancelledMessageHandlers.size()) {
+				continue;
+			}
+			final CancelledMessageHandler handler = cancelledMessageHandlers.get(i);
+			handler.onMessageCancelled(messageType, source, receiver, messageData);
+		}
+	}
+
+ 	void dispose(MessageExchange messageExchange) {
 		exchangers.remove(messageExchange);
 	}
 
@@ -403,6 +469,14 @@ public int getTotalActiveExchanges() {
 		return exchangers.size();
 	}
 
+	public void addCancelledMessageHandler(CancelledMessageHandler handler) {
+		cancelledMessageHandlers.add(handler);
+	}
+
+	public void removeCancelledMessageHandler(CancelledMessageHandler handler) {
+		cancelledMessageHandlers.remove(handler);
+	}
+
 	/**
 	 * An internal {@link MessageExchange} for anonymous message sending
 	 */

src/main/java/org/mini2Dx/minibus/MessageExchange.java

@@ -42,7 +42,7 @@ public abstract class MessageExchange {
 
 	protected final MessageBus messageBus;
 	protected final MessageTransmissionPool messageTransmissionPool;
-	protected final Queue<MessageTransmission> messageQueue = new SynchronizedQueue<>();
+	protected final SynchronizedQueue<MessageTransmission> messageQueue = new SynchronizedQueue<>();
 
 	private final int id;
 
@@ -67,6 +67,51 @@ public MessageExchange(MessageBus messageBus, MessageHandler... messageHandlers)
 		}
 	}
 
+	void entityDeleted(int entityId) {
+		for(int i = messageQueue.size() - 1; i >= 0; i--) {
+			if(i >= messageQueue.size()) {
+				continue;
+			}
+			final MessageTransmission messageTransmission = messageQueue.get(i);
+			if(messageTransmission.getMessage() instanceof EntityMessageData) {
+				final EntityMessageData entityMessageData = (EntityMessageData) messageTransmission.getMessage();
+				if(entityMessageData.getEntityId() != entityId) {
+					continue;
+				}
+				messageQueue.remove(i);
+				messageBus.notifyMessageCancelled(messageTransmission.getMessageType(), messageTransmission.getSource(), this, messageTransmission.getMessage());
+				messageTransmission.release();
+			}
+		}
+	}
+
+	public void cancelAllMessages(boolean notify) {
+		while(!messageQueue.isEmpty()) {
+			final MessageTransmission messageTransmission = messageQueue.poll();
+			if(notify) {
+				messageBus.notifyMessageCancelled(messageTransmission.getMessageType(), messageTransmission.getSource(), this, messageTransmission.getMessage());
+			}
+			messageTransmission.release();
+		}
+	}
+
+	public void cancelAllMessages(String messageType, boolean notify) {
+		for(int i = messageQueue.size() - 1; i >= 0; i--) {
+			if(i >= messageQueue.size()) {
+				continue;
+			}
+			final MessageTransmission messageTransmission = messageQueue.get(i);
+			if(!messageTransmission.getMessageType().equals(messageType)) {
+				continue;
+			}
+			messageQueue.remove(i);
+			if(notify) {
+				messageBus.notifyMessageCancelled(messageTransmission.getMessageType(), messageTransmission.getSource(), this, messageTransmission.getMessage());
+			}
+			messageTransmission.release();
+		}
+	}
+
 	/**
 	 * An overidable method for processing a {@link MessageTransmission} before
 	 * queueing into this {@link MessageExchange}
@@ -223,4 +268,12 @@ public int getId() {
 	public boolean isAnonymous() {
 		return false;
 	}
+
+	/**
+	 * Returns the current amount of messages queued
+	 * @return 0 if no messages queued
+	 */
+	public int getMessageQueueSize() {
+		return messageQueue.size();
+	}
 }

src/main/java/org/mini2Dx/minibus/util/SnapshotArrayList.java

@@ -32,10 +32,20 @@ public class SnapshotArrayList<T> implements List<T> {
 	private final Object iteratorLock = new Object();
 	private final ReadWriteLock lock = MessageBus.LOCK_PROVIDER.newReadWriteLock();
 	private final Queue<SnapshotIterator<T>> iteratorPool = new ArrayDeque<SnapshotIterator<T>>();
+
+	private final boolean ordered;
 	private Object[] array = new Object[32];
 
 	private int size = 0;
 
+	public SnapshotArrayList() {
+		this(false);
+	}
+
+	public SnapshotArrayList(boolean ordered) {
+		this.ordered = ordered;
+	}
+
 	private void ensureCapacity(int capacity) {
 		ArrayList list = new ArrayList();
 		if(capacity <= array.length) {
@@ -119,8 +129,14 @@ public boolean remove(Object o) {
 			if(!array[i].equals(o)) {
 				continue;
 			}
-			array[i] = array[size - 1];
-			array[size - 1] = null;
+			if(ordered) {
+				remove(i);
+				i--;
+			} else {
+				array[i] = array[size - 1];
+				array[size - 1] = null;
+			}
+
 			size--;
 			result = true;
 			break;
@@ -207,26 +223,46 @@ public void add(int index, T element) {
 		throw new UnsupportedOperationException();
 	}
 
-	@Override
-	public T remove(int index) {
+	private T remove(int index, boolean throwException) {
 		Object result = null;
 		lock.writeLock().lock();
 		if(index < 0) {
 			lock.writeLock().unlock();
-			throw new IndexOutOfBoundsException();
+			if(throwException) {
+				throw new IndexOutOfBoundsException();
+			}
+			return null;
 		}
 		if(index >= size) {
 			lock.writeLock().unlock();
-			throw new IndexOutOfBoundsException();
+			if(throwException) {
+				throw new IndexOutOfBoundsException();
+			}
+			return null;
 		}
 
 		result = array[index];
-		array[index] = array[size - 1];
+
+		if(ordered) {
+			System.arraycopy(array, index + 1, array, index, size - 1 - index);
+		} else {
+			array[index] = array[size - 1];
+		}
+
 		size--;
 		lock.writeLock().unlock();
 		return (T) result;
 	}
 
+	public T safeRemove(int index) {
+		return remove(index, false);
+	}
+
+	@Override
+	public T remove(int index) {
+		return remove(index, true);
+	}
+
 	@Override
 	public int indexOf(Object o) {
 		lock.readLock().lock();