edu.rit.m2mp
Class M2MP

java.lang.Object
  extended by edu.rit.m2mp.M2MP

public class M2MP
extends Object

Class M2MP provides the Many-to-Many Protocol (M2MP) Layer.

To use M2MP in an application, create an instance of class M2MP. The constructor obtains various parameters for configuring the M2MP Layer from the M2MP properties file (see class M2MPProperties).

To send an outgoing M2MP message, call the createOutgoingMessage() method to create an output stream for the message; write the message contents to the output stream; and close the output stream. You may write multiple outgoing messages concurrently in separate threads.

To receive incoming M2MP messages, first register one or more appropriate message filters by calling the addMessageFilter() method. If you don't register any message filters, the M2MP Layer will never receive any messages. Then call the acceptIncomingMessage() method to obtain an input stream for reading an incoming message that matched one of the registered message filters; read the message contents from the input stream; and close the input stream. Repeat these steps to receive the next incoming M2MP message. You may read and process multiple incoming messages concurrently by calling acceptIncomingMessage() in one thread and reading each message's input stream in its own separate thread.

A message filter is specified by a message prefix, a sequence of bytes. An incoming message matches a message filter if the initial bytes of the message are the same as the message filter's message prefix. A zero-length message prefix matches any incoming message.

The M2MP Layer receives any M2MP message sent anywhere in the system, regardless of its source, provided the M2MP message matches one of the registered message filters. A different device may have sent the M2MP message, or a different process on the same device may have sent the M2MP message. There is one exception: An outgoing message created by a certain M2MP instance will not be received by that same M2MP instance. In other words, an instance of the M2MP Layer broadcasts outgoing messages everywhere, except to itself.


Constructor Summary
M2MP()
          Construct a new instance of the M2MP Layer.
 
Method Summary
 InputStream acceptIncomingMessage()
          Obtain the next incoming message from this M2MP Layer.
 InputStream acceptIncomingMessage(long timeout)
          Obtain the next incoming message from this M2MP Layer, with a timeout.
 void addMessageFilter(byte[] thePrefix)
          Register the given message filter with this M2MP Layer.
 OutputStream createOutgoingMessage()
          Create an outgoing message to send to this M2MP Layer.
 void removeMessageFilter(byte[] thePrefix)
          Deregister the given message filter from this M2MP Layer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

M2MP

public M2MP()
Construct a new instance of the M2MP Layer. The constructor obtains various parameters for configuring the M2MP Layer from the M2MP properties file (see class M2MPProperties).

Throws:
M2MPInitializationException - (unchecked exception) Thrown if the M2MP Layer cannot be initialized.
Method Detail

createOutgoingMessage

public OutputStream createOutgoingMessage()
                                   throws IOException
Create an outgoing message to send to this M2MP Layer.

Returns:
Output stream for writing the outgoing message.
Throws:
IOException - Thrown if an I/O error occurred.

addMessageFilter

public void addMessageFilter(byte[] thePrefix)
                      throws IOException
Register the given message filter with this M2MP Layer. Thereafter, this M2MP Layer will receive incoming M2MP messages that match the message filter.

The message prefix's length must be greater than or equal to 0 bytes and less than or equal to 488 bytes.

If a message filter whose message prefix is equal to thePrefix is already registered with this M2MP Layer, then addMessageFilter() has no effect.

Parameters:
thePrefix - Message prefix for the message filter.
Throws:
NullPointerException - (unchecked exception) Thrown if thePrefix is null.
IllegalArgumentException - (unchecked exception) Thrown if thePrefix's length is not in the range 0 .. 488.
IOException - Thrown if an I/O error occurred.

removeMessageFilter

public void removeMessageFilter(byte[] thePrefix)
                         throws IOException
Deregister the given message filter from this M2MP Layer. Thereafter, this M2MP Layer will no longer receive incoming M2MP messages that match the message filter, unless they match another still-registered message filter.

The message prefix's length must be greater than or equal to 0 bytes and less than or equal to 488 bytes.

If a message filter whose message prefix is equal to thePrefix is not registered with this M2MP Layer, then removeMessageFilter() has no effect.

Parameters:
thePrefix - Message prefix for the message filter.
Throws:
NullPointerException - (unchecked exception) Thrown if thePrefix is null.
IllegalArgumentException - (unchecked exception) Thrown if thePrefix's length is not in the range 0 .. 488.
IOException - Thrown if an I/O error occurred.

acceptIncomingMessage

public InputStream acceptIncomingMessage()
                                  throws IOException
Obtain the next incoming message from this M2MP Layer. This method blocks until a message is available.

Returns:
Input stream for reading the incoming message.
Throws:
IOException - Thrown if an I/O error occurred, including if the calling thread was interrupted while blocked in this method.

acceptIncomingMessage

public InputStream acceptIncomingMessage(long timeout)
                                  throws IOException
Obtain the next incoming message from this M2MP Layer, with a timeout. This method blocks until a message is available or until the specified timeout interval has elapsed, whichever happens first. The timeout interval is timeout milliseconds. If the timeout interval is 0, this method immediately returns a message if one is available, otherwise this method immediately returns null.

Parameters:
timeout - Timeout interval (milliseconds), or 0 for a non-blocking call.
Returns:
Input stream for reading the incoming message, or null if a timeout occurred.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if timeout < 0.
IOException - Thrown if an I/O error occurred, including if the calling thread was interrupted while blocked in this method.


Copyright © 2001-2006 by Alan Kaminsky. All rights reserved. Send comments to ark­@­cs.rit.edu.