org.miv.mbox.net
Class Receiver

java.lang.Object
  java.lang.Thread
      org.miv.mbox.net.Receiver

All Implemented Interfaces:

Runnable

public class Receiver
extends Thread

Receives messages and dispatches them to message boxes.

A message receiver listen at a given address and port. Several senders (Sender) can connect to it, the receiver will demultiplex the data flow and dispatch incoming messages to registered message boxes.

A receiver is created by giving it the host and port on which it must listen at incoming messages (using a MBoxLocator, although, the receiver is not a real message box, is represents a set of them). Then one registers several message boxes inside the receiver. The receiver runs in its own thread.

There exist two way to receive messages with the receiver. One is to register a MBoxListener using the register(String,MBoxListener) method. This will return a message box implementation of type MBoxStandalone that can buffer messages from the receiver thread an later dispatch them to the MBoxListener.

The other way is to directly implement the MBox interface or reify the MBoxBase abstract class to receive messages directly by registering using the register(String,org.miv.mbox.MBox) method. This is more flexible, but the user must ensure proper locking since the MBox.post(String,Object...) method will be invoked from the receiver thread (the MBoxBase class already does this job).

TODO: What happen to messages that are directed to inexistent message boxes?

Since:

20040624

Author:

Antoine Dutot

See Also:

MBox, MBoxBase, MBoxListener, Sender

Nested Class Summary

protected class

Receiver.IncomingBuffer The connection to a sender.

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

protected HashMap<String,MBox>	boxes Pairs (key,value) where the key is the listener ID and the value the MBox of the listener.
protected boolean	debug Show debugging messages.
protected HashMap<SelectionKey,Receiver.IncomingBuffer>	incoming Current active incoming connections.
protected SelectionKey	key Key for the selector.
protected String	lastError Last encountered error.
protected static String	LIGHT_YELLOW
protected MBoxLocator	locator Host name for this application.
protected boolean	loop While true, the received is running.
protected static String	RESET
protected Selector	selector Multiplexor.
protected ServerSocketChannel	server Receiver socket.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Receiver(MBoxLocator locator)
New receiver, awaiting for messages in its own thread at the given locator.

Receiver(MBoxLocator locator, boolean debug)
New receiver, awaiting for messages in its own thread at the given locator.

Receiver(String hostname, int port)
Like Receiver(MBoxLocator) but specify the host name and port explicitly.

Receiver(String hostname, int port, boolean debug)
Like Receiver(MBoxLocator,boolean) but specify the host name and port explicitly.

Method Summary

protected void	debug(String message, Object... data)
protected void	error(String message, Object... data)
protected void	error(Throwable e, String message, Object... data)
MBoxLocator	getLocator() Locator of this receiver.
MBox	getMBox(String name) Message box attached to the given message box name, or null if no MBox is registered at this name.
protected void	init() Initialise the server socket.
boolean	isRunning() False as soon as the receiver terminates.
void	poll() Wait until one or several chunks of message are acceptable.
void	quit() Stop the receiver.
protected void	readDataChunk(SelectionKey key) When data is readable on a socket, send it to the appropriate buffer (creating it if needed).
void	register(String name, MBox box) Register a message box.
MBoxStandalone	register(String name, MBoxListener listener) Register a message box listener for incoming messages.
void	run() Wait for connections, accept them, demultiplexes them and dispatch messages to registered message boxes.
void	setDebugOn(boolean on) Enable or disable debugging.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

locator

protected MBoxLocator locator

Host name for this application.

server

protected ServerSocketChannel server

Receiver socket.

selector

protected Selector selector

Multiplexor.

key

protected SelectionKey key

Key for the selector.

loop

protected boolean loop

While true, the received is running.

debug

protected boolean debug

Show debugging messages.

lastError

protected String lastError

Last encountered error.

boxes

protected HashMap<String,MBox> boxes

Pairs (key,value) where the key is the listener ID and the value the MBox of the listener. This can be modified by other threads and must be properly locked.

See Also:

register(String,MBoxListener)

incoming

protected HashMap<SelectionKey,Receiver.IncomingBuffer> incoming

Current active incoming connections.

LIGHT_YELLOW

protected static final String LIGHT_YELLOW

See Also:

Constant Field Values

RESET

protected static final String RESET

See Also:

Constant Field Values

Constructor Detail

Receiver

public Receiver(MBoxLocator locator)
         throws IOException,
                UnknownHostException

New receiver, awaiting for messages in its own thread at the given locator. The receiver aggregates several message boxes, therefore its locator will only contain a host id, something of the form "//"+hostname+":"+port. The initialisation is done in the thread that creates this receiver. Then the receiver will run in a thread of its own.

Parameters:

locator - the host and port of this receiver to listen at messages.

Throws:

IOException

UnknownHostException

Receiver

public Receiver(MBoxLocator locator,
                boolean debug)
         throws IOException,
                UnknownHostException

New receiver, awaiting for messages in its own thread at the given locator. The receiver aggregates several message boxes, therefore its locator will only contain a host id, something of the form "//"+hostname+":"+port. The initialisation is done in the thread that creates this receiver. Then the receiver will run in a thread of its own.

Parameters:

locator - the host and port of this receiver to listen at messages.

debug - If true informations are output for each message received.

Throws:

IOException

UnknownHostException

Receiver

public Receiver(String hostname,
                int port)
         throws IOException,
                UnknownHostException

Like Receiver(MBoxLocator) but specify the host name and port explicitly.

Parameters:

hostname - The host name to listen at messages.

port - The port to listen at messages.

Throws:

IOException

UnknownHostException

Receiver

public Receiver(String hostname,
                int port,
                boolean debug)
         throws IOException,
                UnknownHostException

Like Receiver(MBoxLocator,boolean) but specify the host name and port explicitly.

Parameters:

hostname - The host name to listen at messages.

port - The port to listen at messages.

debug - If true informations are output for each message received.

Throws:

IOException

UnknownHostException

Method Detail

isRunning

public boolean isRunning()

False as soon as the receiver terminates.

getLocator

public MBoxLocator getLocator()

Locator of this receiver.

getMBox

public MBox getMBox(String name)

Message box attached to the given message box name, or null if no MBox is registered at this name.

Parameters:

name - Identifier of the MBox listener.

init

protected void init()
             throws IOException,
                    UnknownHostException

Initialise the server socket.

Throws:

IOException

UnknownHostException

setDebugOn

public void setDebugOn(boolean on)

Enable or disable debugging.

register

public MBoxStandalone register(String name,
                               MBoxListener listener)
                        throws IdAlreadyInUseException

Register a message box listener for incoming messages. All messages with the given name will be directed to it. The listener can then call MBoxBase.processMessages() to receive its pending messages.

Parameters:

name - Filter only message with this name to the given listener.

listener - The listener to register.

Throws:

IdAlreadyInUseException - If another message box is already registered at the given name.

register

public void register(String name,
                     MBox box)
              throws IdAlreadyInUseException

Register a message box. All messages with the given name will be directed to it. Unlike with the MBoxListener, the messages are directly posted to the given message box that must ensure proper locking (since the receiver runs in a distinct thread) that is implemented by the user.

Parameters:

name - Filter only message with this name to the given message box.

box - The message box implementation to post messages to.

Throws:

IdAlreadyInUseException - If another message box is already registered at the given name.

quit

public void quit()

Stop the receiver.

run

public void run()

Wait for connections, accept them, demultiplexes them and dispatch messages to registered message boxes.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

poll

public void poll()

Wait until one or several chunks of message are acceptable. This method should be called in a loop. It can be used to block a program until some data is available.

readDataChunk

protected void readDataChunk(SelectionKey key)
                      throws IOException

When data is readable on a socket, send it to the appropriate buffer (creating it if needed).

Throws:

IOException

error

protected void error(String message,
                     Object... data)

error

protected void error(Throwable e,
                     String message,
                     Object... data)

debug

protected void debug(String message,
                     Object... data)