cz.zcu.fav.kiv.jsim.ipc
Class JSimMessageBox

java.lang.Object
  cz.zcu.fav.kiv.jsim.ipc.JSimMessageBox

public class JSimMessageBox
extends java.lang.Object

A message box is a data structure able to keep messages sent between processes. Every J-Sim process has its own message box that serves as a message store for messages sent directly to the process. However, a message box can be also created explicitly by the user to provide a mean of indirect communication where neither the sender nor the receiver need to be known to the opposite side.

Since:

J-Sim version 0.3.0

Version:

J-Sim version 0.6.0

Author:

Jarda KAČER

Field Summary

private static java.util.logging.Logger	logger Common logger for all instances of this class.
protected java.util.LinkedList<JSimMessage>	messages A list of all messages that this message box keeps.
private java.lang.String	myName This message box's name.
protected java.util.LinkedList<JSimProcess>	suspendedReceivers A list of all processes that got suspended when they tried to receive a message from this message box.
protected java.util.LinkedList<JSimProcess>	suspendedSenders A list of all processes that got suspended when they sent a message to this message box.

Constructor Summary

JSimMessageBox(java.lang.String name)
Creates a new message box with the specified name.

Method Summary

void	addMessage(JSimMessage message) Adds a new message to the message box.
void	addSuspendedReceiver(JSimProcess receiver) Adds a new process to the collection of processes suspended on receiving a message.
void	addSuspendedSender(JSimProcess sender) Adds a new process to the collection of processes suspended on sending a message.
boolean	containsSuspendedSender(JSimProcess sender) Indicates whether the specified process is among senders suspended on this message box.
JSimMessage	getFirstMessage() Returns the first message in the message box and removes it from there.
JSimMessage	getFirstMessageForReceiver(JSimProcess receiver) Return the first message whose receiver is equal to the specified receiver.
JSimMessage	getFirstMessageFromAndFor(JSimProcess possibleSender, JSimProcess possibleReceiver) Returns the first message whose receiver is equal to the specified receiver and whose sender is equal to the specified sender.
JSimMessage	getFirstMessageFromSender(JSimProcess sender) Return the first message whose sender is equal to the specified sender.
JSimProcess	getFirstSuspendedReceiver(JSimProcess possibleReceiver, JSimProcess possibleSender) Returns the first process that is suspended on receiving a message from this message box.
java.lang.String	getName() Returns the name of the message box.
int	getNumberOfMessages() Returns the number of messages in the message box.
boolean	isEmpty() Indicates whether this message box is empty.

Methods inherited from class java.lang.Object

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

Field Detail

logger

private static final java.util.logging.Logger logger

Common logger for all instances of this class. By default, all logging information goes to a file. Only severe events go to the console, in addition to a file.

myName

private java.lang.String myName

This message box's name.

messages

protected java.util.LinkedList<JSimMessage> messages

A list of all messages that this message box keeps.

suspendedSenders

protected java.util.LinkedList<JSimProcess> suspendedSenders

A list of all processes that got suspended when they sent a message to this message box.

suspendedReceivers

protected java.util.LinkedList<JSimProcess> suspendedReceivers

A list of all processes that got suspended when they tried to receive a message from this message box.

Constructor Detail

JSimMessageBox

public JSimMessageBox(java.lang.String name)

Creates a new message box with the specified name.

Parameters:

name - The name of the message box.

Method Detail

getName

public java.lang.String getName()

Returns the name of the message box.

Returns:

The name of the message box.

addMessage

public void addMessage(JSimMessage message)
                throws JSimInvalidParametersException

Adds a new message to the message box.

Parameters:

message - The message to be added to the box.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified message is null.

getFirstMessage

public JSimMessage getFirstMessage()

Returns the first message in the message box and removes it from there. If there are no messages in the message box, null is returned.

Returns:

The first message in the message box or null.

getFirstMessageFromSender

public JSimMessage getFirstMessageFromSender(JSimProcess sender)
                                      throws JSimInvalidParametersException

Return the first message whose sender is equal to the specified sender. The message is removed from the message box. The returned message is always an instance of a class implementing JSimMessageWithKnownSender. If no such message is found, null is returned.

Parameters:

sender - The process that sent the message we are looking for. Must not be null.

Throws:

JSimInvalidParametersException - This exception is thrown out if the sender is not specified.

getFirstMessageForReceiver

public JSimMessage getFirstMessageForReceiver(JSimProcess receiver)
                                       throws JSimInvalidParametersException

Return the first message whose receiver is equal to the specified receiver. The message is removed from the message box. The returned message is always an instance of a class implementing JSimMessageWithKnownReceiver. If no such message is found, null is returned.

Parameters:

receiver - The process that the message we are looking for was sent to. Must not be null.

Throws:

JSimInvalidParametersException - This exception is thrown out if the receiver is not specified.

getFirstMessageFromAndFor

public JSimMessage getFirstMessageFromAndFor(JSimProcess possibleSender,
                                             JSimProcess possibleReceiver)

Returns the first message whose receiver is equal to the specified receiver and whose sender is equal to the specified sender. If the sender is not specified (UNKNOWN_SENDER), the sender of the message has no importance and messages will be filtered by receiver only. If the receiver is not specified (UNKNOWN_RECEIVER), the receiver of the message has no importance and messages will be filtered by sender only. If the message does not have its sender/receiver specified, it will be accepted whatever the value of the desired sender/receiver is. The message is removed from the box. If no such message is found, null is returned.

Parameters:

possibleSender - The sender of the message we are looking for, or UNKNOWN_SENDER for any sender.

possibleReceiver - The receiver of the message we are looking for, or UNKNOWN_RECEIVER for any receiver.

Returns:

The first message whose receiver is equal to the specified receiver and whose sender is equal to the specified sender.

getNumberOfMessages

public int getNumberOfMessages()

Returns the number of messages in the message box.

Returns:

The number of messages in the message box.

isEmpty

public boolean isEmpty()

Indicates whether this message box is empty.

Returns:

True if the message box is empty, false otherwise.

containsSuspendedSender

public boolean containsSuspendedSender(JSimProcess sender)
                                throws JSimInvalidParametersException

Indicates whether the specified process is among senders suspended on this message box. If it is, true is returned and the sender is removed from the set of suspended senders. It is assumed that the calling process will supply the real sender of the message being received not the sender specified by the user.

Parameters:

sender - The sender that is or is not among suspended senders. Must not be null.

Returns:

True if the specified sender is among senders suspended on this message box, false otherwise.

Throws:

JSimInvalidParametersException - This exception is thrown out if the sender is not specified (null).

getFirstSuspendedReceiver

public JSimProcess getFirstSuspendedReceiver(JSimProcess possibleReceiver,
                                             JSimProcess possibleSender)

Returns the first process that is suspended on receiving a message from this message box. It there are no suspended receivers on this message box, null is returned. The receiver is removed from the collection of suspended receivers. Certain criteria must be met:

1. If the receiver is specified, no other process can be returned. If it not specified, any process can be returned.
2. If the sender is specified, it must be equal to the sender that the selected process is waiting for. If a suspended process does not have its sender specified, it can be selected without any regard to the possibleSender argument.
3. The selected process must have its message clipboard empty. Full clipboard means that the process has just got a message but has not run since then yet. Actually, no process with full clipboard should be in the queue.

Parameters:

possibleReceiver - A process that can be returned by this method or UNKNOWN_RECEIVER for any receiver.

possibleSender - A process that the selected process must be waiting for of UNKNOWN_SENDER for any sender. If a suspended process has not its waiting-for-sender specified, this value will be ignored for the suspended process.

Returns:

The first process that is suspended on receiving a message from this message box, or null.

addSuspendedSender

public void addSuspendedSender(JSimProcess sender)
                        throws JSimInvalidParametersException

Adds a new process to the collection of processes suspended on sending a message. The method itself does not block the process, this must be done outside. The method assumes that the real sender is passed as the first argument, not the process specified as sender in the message (which can be null). Null values are not accepted.

Parameters:

sender - The process getting blocked on sending a message via this message box.

Throws:

JSimInvalidParametersException - This exception is thrown out if the sender is not specified.

addSuspendedReceiver

public void addSuspendedReceiver(JSimProcess receiver)
                          throws JSimInvalidParametersException

Adds a new process to the collection of processes suspended on receiving a message. The method itself does not block the process, this must be done outside.

Parameters:

receiver - The process getting blocked on receiving a message via this message box.

Throws:

JSimInvalidParametersException - This exception is thrown out if the receiver is not specified.