io.jbotsim.core

Class DelayMessageEngine

java.lang.Object

io.jbotsim.core.DefaultMessageEngine

io.jbotsim.core.DelayMessageEngine

All Implemented Interfaces:

MessageEngine

Direct Known Subclasses:

AsyncMessageEngine, RandomDelayMessageEngine

public class DelayMessageEngine
extends DefaultMessageEngine

The DelayMessageEngine is responsible for the regular transmission of the available Messages from any sender Node of the Topology to their destination.

By default, Messages sent during round n are delivered at the beginning of round n+1; provided that the corresponding arc (a Link going, at least, from the Message's source Node to its destination) actually exists at the beginning of round n+1.

Delay feature

The previously explained default delivery duration (DEFAULT_DELAY) is said instantaneous (DELAY_INSTANT). The DelayMessageEngine allows you to modify this duration by specifying the amount of rounds Messages should take to be delivered, using setDelay(int).

Link checks

By default, each round, the DelayMessageEngine checks for each Message that the corresponding Link is still present. If not, the Message is dropped.

The time spent doing this rises with the delay and the number of Nodes and Messages. Depending on your case, you might want to disable this using disableLinksContinuityChecks().

Field Summary

Fields

Modifier and Type	Field and Description
protected int	currentTime
static int	DEFAULT_DELAY The default number of round before message delivery; value: 1.
static int	DELAY_INSTANT The delay value to use for the shortest delivery time possible; value: 1.
protected Map<Integer,List<Message>>	delayedMessages

Fields inherited from class io.jbotsim.core.DefaultMessageEngine

debug, topology

Constructor Summary

Constructors

Constructor and Description
DelayMessageEngine(Topology topology) Creates a DelayMessageEngine.
DelayMessageEngine(Topology topology, int delay) Creates a DelayMessageEngine.

Method Summary

Modifier and Type	Method and Description
protected void	cacheMessageAtTime(Map<Integer,List<Message>> messagesMap, Message message, int deliveryTime) Caches a specific Message at it's planned delivery time (round number).
protected void	cacheMessagesAtTime(List<Message> messages, int deliveryTime) Caches (internally) the specified List of Messages at that the given delivery time (round number).
protected void	cacheNewMessages(List<Message> messages) Caches the provided List of new Messages.
void	disableLinksContinuityChecks() Disables the intermediate checks on Link existence for each Message.
protected int	getCurrentDeliveryDate() Computes the delivery date (round number) for a Message collected at the start of the current round.
int	getDelay() Gets the number of round a message should be delayed.
protected int	getDelayForMessage(Message message) Computes the delay which should be applied to the provided Message.
protected List<Message>	getMessagesForCurrentDate() Retrieves the list of Messages which should be delivered during the current round, from the internal storage.
protected List<Message>	getMessagesToSend(List<Message> newMessages, Collection<Node> existingNodes) Constructs the List of Messages that must be sent during this round.
protected boolean	noCachingNeeded(List<Message> newMessages) Tests whether the provided list of Messages should be cached or not.
void	onClock() Method responsible for the delivery of the Messages.
protected Map<Integer,List<Message>>	prepareNewMessagesForCaching(List<Message> newMessages) Transforms the provided List of new Messages for caching into a suitable data structure.
protected void	removeIrrelevantMessages(Collection<Node> existingNodes) Removes any irrelevant messages from the cached delayed messages, according to the Collection of existing Nodes.
void	reset() Resets the DelayMessageEngine.
void	setDelay(int delay) Sets the number of round a message should be delayed.
void	setSpeed(int speed) Deprecated. Please use setDelay(int) instead.
boolean	shouldCheckLinksContinuity() Specifies whether a Message should be removed if the corresponding Link disappears at some point during its waiting delay.

Methods inherited from class io.jbotsim.core.DefaultMessageEngine

clearMailboxes, clearMailboxes, clearSendQueues, clearSendQueues, collectMessages, collectMessages, collectMessages, deliverMessage, deliverMessages, isMessageStillRelevant, removeIrrelevantMessages, removeNextMessageIfIrrelevant, requeueIfNeeded, requeueMessage, setDebug, setTopology

Methods inherited from class java.lang.Object

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

Field Detail

DELAY_INSTANT

public static final int DELAY_INSTANT

The delay value to use for the shortest delivery time possible; value: 1.

See Also:

setDelay(int), getDelay(), Constant Field Values

DEFAULT_DELAY

public static final int DEFAULT_DELAY

The default number of round before message delivery; value: 1.

See Also:

setDelay(int), getDelay(), Constant Field Values

delayedMessages

protected Map<Integer,List<Message>> delayedMessages

currentTime

protected int currentTime

Constructor Detail

DelayMessageEngine

public DelayMessageEngine(Topology topology)

Creates a DelayMessageEngine.

By default, the messages sent during one round are actually during the next.

Parameters:

topology - the Topology to use.

DelayMessageEngine

public DelayMessageEngine(Topology topology,
                          int delay)

Creates a DelayMessageEngine.

Parameters:

topology - the Topology to use.

delay - the number of round a message should be delayed, as an integer.

Method Detail

setSpeed

@Deprecated
public void setSpeed(int speed)

Deprecated. Please use setDelay(int) instead.

Sets the number of round a message should be delayed.

Parameters:

speed - the number of round a message should be delayed, as an integer.

setDelay

public void setDelay(int delay)

Sets the number of round a message should be delayed.

Any value below DELAY_INSTANT (i.e. 1) will be replaced by DELAY_INSTANT.

Parameters:

delay - the number of round a message should be delayed, as an integer.

See Also:

getDelay()

getDelay

public int getDelay()

Gets the number of round a message should be delayed.

Returns:

the number of round a message should be delayed, as an integer.

See Also:

setDelay(int)

shouldCheckLinksContinuity

public boolean shouldCheckLinksContinuity()

Specifies whether a Message should be removed if the corresponding Link disappears at some point during its waiting delay.

Note: Whatever the status, the link presence will be checked at sending time and delivery time.

Returns:

true if intermediate checks and removal should be performed; false otherwise.

See Also:

disableLinksContinuityChecks()

disableLinksContinuityChecks

public void disableLinksContinuityChecks()

Disables the intermediate checks on Link existence for each Message.

See Also:

shouldCheckLinksContinuity()

onClock

public void onClock()

Description copied from interface: MessageEngine

Method responsible for the delivery of the Messages. It is regularly called by the Scheduler.

Specified by:

onClock in interface MessageEngine

Overrides:

onClock in class DefaultMessageEngine

getMessagesToSend

protected List<Message> getMessagesToSend(List<Message> newMessages,
                                          Collection<Node> existingNodes)

Constructs the List of Messages that must be sent during this round.

Parameters:

newMessages - the List of new Messages which has been collected during this round.

existingNodes - the Collection of existing Nodes.

Returns:

the List of Messages that must be sent during this round.

noCachingNeeded

protected boolean noCachingNeeded(List<Message> newMessages)

Tests whether the provided list of Messages should be cached or not.

Parameters:

newMessages - a List containing new Messages.

Returns:

true if the provided messages should not be cached.

removeIrrelevantMessages

protected void removeIrrelevantMessages(Collection<Node> existingNodes)

Removes any irrelevant messages from the cached delayed messages, according to the Collection of existing Nodes.

Parameters:

existingNodes - the Collection of existing Nodes.

See Also:

DefaultMessageEngine.removeIrrelevantMessages(ListIterator, Collection)

cacheNewMessages

protected void cacheNewMessages(List<Message> messages)

Caches the provided List of new Messages.

Parameters:

messages - a List containing new Messages.

See Also:

prepareNewMessagesForCaching(List), cacheMessagesAtTime(List, int)

prepareNewMessagesForCaching

protected Map<Integer,List<Message>> prepareNewMessagesForCaching(List<Message> newMessages)

Transforms the provided List of new Messages for caching into a suitable data structure.

Parameters:

newMessages - a List containing new Messages.

Returns:

a Map containing Lists of Messages indexed by the date at which they should be delivered.

See Also:

getCurrentDeliveryDate()

cacheMessageAtTime

protected void cacheMessageAtTime(Map<Integer,List<Message>> messagesMap,
                                  Message message,
                                  int deliveryTime)

Caches a specific Message at it's planned delivery time (round number).

Parameters:

messagesMap - the Map, indexing Messages by their delivery date, in which the message should be cached.

message - the Message to cache.

deliveryTime - the round number at which the message should be delivered.

cacheMessagesAtTime

protected void cacheMessagesAtTime(List<Message> messages,
                                   int deliveryTime)

Caches (internally) the specified List of Messages at that the given delivery time (round number).

Parameters:

messages - the List of Messages to cache internally.

deliveryTime - the round number at which the messages should be delivered.

getMessagesForCurrentDate

protected List<Message> getMessagesForCurrentDate()

Retrieves the list of Messages which should be delivered during the current round, from the internal storage.

Returns:

a List of Messages containing all messages which should be delivered during the current round. Can be empty, but not null.

getDelayForMessage

protected int getDelayForMessage(Message message)

Computes the delay which should be applied to the provided Message.

Parameters:

message - the Message needing a delay.

Returns:

the delay for the provided message.

getCurrentDeliveryDate

protected int getCurrentDeliveryDate()

Computes the delivery date (round number) for a Message collected at the start of the current round.

Returns:

the delivery date for the current round, as an integer.

reset

public void reset()

Resets the DelayMessageEngine.

• Any Message (ready to be sent, "in the air" or ready to be received) handled by the DelayMessageEngine is discarded.
• Other configurations (delay or debug) remain untouched.

Specified by:

reset in interface MessageEngine

Overrides:

reset in class DefaultMessageEngine