com.almasb.fxgl.ai.msg

Class MessageDispatcher

java.lang.Object

com.almasb.fxgl.ai.msg.MessageDispatcher

All Implemented Interfaces:

Telegraph

Direct Known Subclasses:

MessageManager

public class MessageDispatcher
extends Object
implements Telegraph

A MessageDispatcher is in charge of the creation, dispatch, and management of telegrams.

Author:

davebaol

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MessageDispatcher.PendingMessageCallback A PendingMessageCallback is used by the scanQueue method of the MessageDispatcher to report its pending messages individually.

Constructor Summary

Constructors

Constructor and Description
MessageDispatcher() Creates a MessageDispatcher

Method Summary

Modifier and Type	Method and Description
void	addListener(Telegraph listener, int msg) Registers a listener for the specified message code.
void	addListeners(Telegraph listener, int... msgs) Registers a listener for a selection of message types.
void	addProvider(TelegramProvider provider, int msg) Registers a provider for the specified message code.
void	addProviders(TelegramProvider provider, int... msgs) Registers a provider for a selection of message types.
void	clear() Removes all the telegrams from the queue and the registered listeners for all the messages.
void	clearListeners() Removes all the registered listeners for all the message codes.
void	clearListeners(int... msgs) Unregisters all the listeners for the given message codes.
void	clearListeners(int msg) Unregisters all the listeners for the specified message code.
void	clearProviders() Removes all the registered providers for all the message codes.
void	clearProviders(int... msgs) Unregisters all the providers for the given message codes.
void	clearProviders(int msg) Unregisters all the providers for the specified message code.
void	clearQueue() Removes all the telegrams from the queue and releases them to the internal pool.
void	dispatchMessage(float delay, int msg) Sends a message to all registered listeners, with the specified delay but no extra info.
void	dispatchMessage(float delay, int msg, Object extraInfo) Sends a message to all registered listeners, with the specified delay and extra info.
void	dispatchMessage(float delay, Telegraph sender, int msg) Sends a message to all registered listeners, with the specified delay but no extra info.
void	dispatchMessage(float delay, Telegraph sender, int msg, boolean needsReturnReceipt) Sends a message to all registered listeners, with the specified delay but no extra info.
void	dispatchMessage(float delay, Telegraph sender, int msg, Object extraInfo) Sends a message to all registered listeners, with the specified delay and extra info.
void	dispatchMessage(float delay, Telegraph sender, int msg, Object extraInfo, boolean needsReturnReceipt) Sends a message to all registered listeners, with the specified delay and extra info.
void	dispatchMessage(float delay, Telegraph sender, Telegraph receiver, int msg) Sends a message to the specified receiver, with the specified delay but no extra info.
void	dispatchMessage(float delay, Telegraph sender, Telegraph receiver, int msg, boolean needsReturnReceipt) Sends a message to the specified receiver, with the specified delay but no extra info.
void	dispatchMessage(float delay, Telegraph sender, Telegraph receiver, int msg, Object extraInfo) Sends a message to the specified receiver, with the specified delay but no extra info.
void	dispatchMessage(float delay, Telegraph sender, Telegraph receiver, int msg, Object extraInfo, boolean needsReturnReceipt) Given a message, a receiver, a sender and any time delay, this method routes the message to the correct agents (if no delay) or stores in the message queue to be dispatched at the correct time.
void	dispatchMessage(int msg) Sends an immediate message to all registered listeners, with no extra info.
void	dispatchMessage(int msg, Object extraInfo) Sends an immediate message to all registered listeners, with extra info.
void	dispatchMessage(Telegraph sender, int msg) Sends an immediate message to all registered listeners, with no extra info.
void	dispatchMessage(Telegraph sender, int msg, boolean needsReturnReceipt) Sends an immediate message to all registered listeners, with no extra info.
void	dispatchMessage(Telegraph sender, int msg, Object extraInfo) Sends an immediate message to all registered listeners, with extra info.
void	dispatchMessage(Telegraph sender, int msg, Object extraInfo, boolean needsReturnReceipt) Sends an immediate message to all registered listeners, with extra info.
void	dispatchMessage(Telegraph sender, Telegraph receiver, int msg) Sends an immediate message to the specified receiver with no extra info.
void	dispatchMessage(Telegraph sender, Telegraph receiver, int msg, boolean needsReturnReceipt) Sends an immediate message to the specified receiver with no extra info.
void	dispatchMessage(Telegraph sender, Telegraph receiver, int msg, Object extraInfo) Sends an immediate message to the specified receiver with extra info.
void	dispatchMessage(Telegraph sender, Telegraph receiver, int msg, Object extraInfo, boolean needsReturnReceipt) Sends an immediate message to the specified receiver with extra info.
boolean	handleMessage(Telegram msg) Handles the telegram just received.
boolean	isDebugEnabled() Returns true if debug mode is on; false otherwise.
void	removeListener(Telegraph listener, int... msgs) Unregister the specified listener for the selection of message codes.
void	removeListener(Telegraph listener, int msg) Unregister the specified listener for the specified message code.
void	scanQueue(MessageDispatcher.PendingMessageCallback callback) Scans the queue and passes pending messages to the given callback in any particular order.
void	setDebugEnabled(boolean debugEnabled) Sets debug mode on/off.
void	update() Dispatches any delayed telegrams with a timestamp that has expired.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageDispatcher

public MessageDispatcher()

Creates a MessageDispatcher

Method Detail

isDebugEnabled

public boolean isDebugEnabled()

Returns true if debug mode is on; false otherwise.

setDebugEnabled

public void setDebugEnabled(boolean debugEnabled)

Sets debug mode on/off.

addListener

public void addListener(Telegraph listener,
                        int msg)

Registers a listener for the specified message code. Messages without an explicit receiver are broadcasted to all its registered listeners.

Parameters:

listener - the listener to add

msg - the message code

addListeners

public void addListeners(Telegraph listener,
                         int... msgs)

Registers a listener for a selection of message types. Messages without an explicit receiver are broadcasted to all its registered listeners.

Parameters:

listener - the listener to add

msgs - the message codes

addProvider

public void addProvider(TelegramProvider provider,
                        int msg)

Registers a provider for the specified message code.

Parameters:

msg - the message code

provider - the provider to add

addProviders

public void addProviders(TelegramProvider provider,
                         int... msgs)

Registers a provider for a selection of message types.

Parameters:

provider - the provider to add

msgs - the message codes

removeListener

public void removeListener(Telegraph listener,
                           int msg)

Unregister the specified listener for the specified message code.

Parameters:

listener - the listener to remove

msg - the message code

removeListener

public void removeListener(Telegraph listener,
                           int... msgs)

Unregister the specified listener for the selection of message codes.

Parameters:

listener - the listener to remove

msgs - the message codes

clearListeners

public void clearListeners(int msg)

Unregisters all the listeners for the specified message code.

Parameters:

msg - the message code

clearListeners

public void clearListeners(int... msgs)

Unregisters all the listeners for the given message codes.

Parameters:

msgs - the message codes

clearListeners

public void clearListeners()

Removes all the registered listeners for all the message codes.

clearProviders

public void clearProviders(int msg)

Unregisters all the providers for the specified message code.

Parameters:

msg - the message code

clearProviders

public void clearProviders(int... msgs)

Unregisters all the providers for the given message codes.

Parameters:

msgs - the message codes

clearProviders

public void clearProviders()

Removes all the registered providers for all the message codes.

clearQueue

public void clearQueue()

Removes all the telegrams from the queue and releases them to the internal pool.

clear

public void clear()

Removes all the telegrams from the queue and the registered listeners for all the messages.

dispatchMessage

public void dispatchMessage(int msg)

Sends an immediate message to all registered listeners, with no extra info.

This is a shortcut method for dispatchMessage(0, null, null, msg, null, false)

Parameters:

msg - the message code

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            int msg)

Sends an immediate message to all registered listeners, with no extra info.

This is a shortcut method for dispatchMessage(0, sender, null, msg, null, false)

Parameters:

sender - the sender of the telegram

msg - the message code

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            int msg,
                            boolean needsReturnReceipt)

Sends an immediate message to all registered listeners, with no extra info.

This is a shortcut method for dispatchMessage(0, sender, null, msg, null, needsReturnReceipt)

Parameters:

sender - the sender of the telegram

msg - the message code

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(int msg,
                            Object extraInfo)

Sends an immediate message to all registered listeners, with extra info.

This is a shortcut method for dispatchMessage(0, null, null, msg, extraInfo, false)

Parameters:

msg - the message code

extraInfo - an optional object

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            int msg,
                            Object extraInfo)

Sends an immediate message to all registered listeners, with extra info.

This is a shortcut method for dispatchMessage(0, sender, null, msg, extraInfo, false)

Parameters:

sender - the sender of the telegram

msg - the message code

extraInfo - an optional object

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            int msg,
                            Object extraInfo,
                            boolean needsReturnReceipt)

Sends an immediate message to all registered listeners, with extra info.

This is a shortcut method for dispatchMessage(0, sender, null, msg, extraInfo, needsReturnReceipt)

Parameters:

sender - the sender of the telegram

msg - the message code

extraInfo - an optional object

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            Telegraph receiver,
                            int msg)

Sends an immediate message to the specified receiver with no extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(0, sender, receiver, msg, null, false)

Parameters:

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            Telegraph receiver,
                            int msg,
                            boolean needsReturnReceipt)

Sends an immediate message to the specified receiver with no extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(0, sender, receiver, msg, null, needsReturnReceipt)

Parameters:

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            Telegraph receiver,
                            int msg,
                            Object extraInfo)

Sends an immediate message to the specified receiver with extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(0, sender, receiver, msg, extraInfo, false)

Parameters:

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

extraInfo - an optional object

dispatchMessage

public void dispatchMessage(Telegraph sender,
                            Telegraph receiver,
                            int msg,
                            Object extraInfo,
                            boolean needsReturnReceipt)

Sends an immediate message to the specified receiver with extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(0, sender, receiver, msg, extraInfo, needsReturnReceipt)

Parameters:

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

extraInfo - an optional object

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(float delay,
                            int msg)

Sends a message to all registered listeners, with the specified delay but no extra info.

This is a shortcut method for dispatchMessage(delay, null, null, msg, null, null)

Parameters:

delay - the delay in seconds

msg - the message code

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            int msg)

Sends a message to all registered listeners, with the specified delay but no extra info.

This is a shortcut method for dispatchMessage(delay, sender, null, msg, null, false)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

msg - the message code

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            int msg,
                            boolean needsReturnReceipt)

Sends a message to all registered listeners, with the specified delay but no extra info.

This is a shortcut method for dispatchMessage(delay, sender, null, msg, null, needsReturnReceipt)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

msg - the message code

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(float delay,
                            int msg,
                            Object extraInfo)

Sends a message to all registered listeners, with the specified delay and extra info.

This is a shortcut method for dispatchMessage(delay, null, null, msg, extraInfo, false)

Parameters:

delay - the delay in seconds

msg - the message code

extraInfo - an optional object

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            int msg,
                            Object extraInfo)

Sends a message to all registered listeners, with the specified delay and extra info.

This is a shortcut method for dispatchMessage(delay, sender, null, msg, extraInfo, false)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

msg - the message code

extraInfo - an optional object

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            int msg,
                            Object extraInfo,
                            boolean needsReturnReceipt)

Sends a message to all registered listeners, with the specified delay and extra info.

This is a shortcut method for dispatchMessage(delay, sender, null, msg, extraInfo, needsReturnReceipt)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

msg - the message code

extraInfo - an optional object

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            Telegraph receiver,
                            int msg)

Sends a message to the specified receiver, with the specified delay but no extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(delay, sender, receiver, msg, null, false)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            Telegraph receiver,
                            int msg,
                            boolean needsReturnReceipt)

Sends a message to the specified receiver, with the specified delay but no extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(delay, sender, receiver, msg, null, needsReturnReceipt)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            Telegraph receiver,
                            int msg,
                            Object extraInfo)

Sends a message to the specified receiver, with the specified delay but no extra info. The receiver doesn't need to be a register listener for the specified message code.

This is a shortcut method for dispatchMessage(delay, sender, receiver, msg, extraInfo, false)

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

extraInfo - an optional object

dispatchMessage

public void dispatchMessage(float delay,
                            Telegraph sender,
                            Telegraph receiver,
                            int msg,
                            Object extraInfo,
                            boolean needsReturnReceipt)

Given a message, a receiver, a sender and any time delay, this method routes the message to the correct agents (if no delay) or stores in the message queue to be dispatched at the correct time.

Parameters:

delay - the delay in seconds

sender - the sender of the telegram

receiver - the receiver of the telegram; if it's null the telegram is broadcasted to all the receivers registered for the specified message code

msg - the message code

extraInfo - an optional object

needsReturnReceipt - whether the return receipt is needed or not

Throws:

IllegalArgumentException - if the sender is null and the return receipt is needed

update

public void update()

Dispatches any delayed telegrams with a timestamp that has expired. Dispatched telegrams are removed from the queue.

This method must be called regularly from inside the main game loop to facilitate the correct and timely dispatch of any delayed messages. Notice that the message dispatcher internally calls GdxAI.getTimepiece().getTime() to get the current AI time and properly dispatch delayed messages. This means that

• if you forget to update the timepiece the delayed messages won't be dispatched.
• ideally the timepiece should be updated before the message dispatcher.

scanQueue

public void scanQueue(MessageDispatcher.PendingMessageCallback callback)

Scans the queue and passes pending messages to the given callback in any particular order.

Typically this method is used to save (serialize) pending messages and restore (deserialize and schedule) them back on game loading.

Parameters:

callback - The callback used to report pending messages individually.

handleMessage

public boolean handleMessage(Telegram msg)

Handles the telegram just received. This method always returns false since usually the message dispatcher never receives telegrams. Actually, the message dispatcher implements Telegraph just because it can send return receipts.

Specified by:

handleMessage in interface Telegraph

Parameters:

msg - The telegram

Returns:

always false.