The M2MI Library comprises three principal packages; see each package's documentation for further information:

• Package edu.rit.m2mi provides M2MI itself.
   
• Package edu.rit.m2mp provides the Many-to-Many Protocol (M2MP), which is used to transport M2MI messages.
   
• Package edu.rit.classfile provides the RIT Classfile Library (RCL), which is used to synthesize M2MI proxy classes.

Table of Contents

The M2MI Library requires Java Development Kit (JDK) 1.5.0.

To install the M2MI Library, just unpack the JAR file containing the M2MI distribution. The distribution expands into a subdirectory named "m2mi".

Documentation is stored under directory "m2mi/doc"; point your HTML browser to that directory.

Java source files and class files are stored under directory "m2mi/lib"; add that directory to your classpath when you run the programs.

To get started with M2MI, do the following steps on a single machine:

1. Configure the device ID for your device. Typically, you create a "device.properties" file in your home directory. See class DeviceProperties for a description of what goes in the device properties file.
    
2. Configure the M2MP Layer for your environment. Typically, you create an "m2mp.properties" file in your home directory. See package edu.rit.m2mp and class M2MPProperties for a description of what goes in the M2MP properties file.
    
3. Configure the M2MI Layer for your environment. Typically, you create an "m2mi.properties" file in your home directory. See package edu.rit.m2mi and class M2MIProperties for a description of what goes in the M2MI properties file.
    
4. Run an instance of the M2MP Daemon by typing this command in a separate process:
    
       java edu.rit.m2mp.Daemon
    
   Typically, the M2MP Layer is configured to use the M2MP Daemon. (With some configuration options the M2MP Daemon is not needed.) For further information, see package edu.rit.m2mp and class Daemon.
    
5. Run several instances of the Chat Demo application by typing this command in several separate processes:
    
       java edu.rit.chat1.Chat <name>
    
   replacing <name> with a different user name in each process. Each instance displays a chat window. A line typed into any of the chat windows shows up in all the chat windows. For further information, see package edu.rit.chat1 and class Chat.

Next, get some additional machines which are all able to send IP multicast packets to each other. Typically, the machines are all attached to the same wired Ethernet segment; the machines all use wireless Ethernet with the same access point; or the network routers between the machines are configured to forward IP multicast packets. Do the following steps:

5. Configure the M2MP Layer and M2MI Layer on each machine.
    
6. Run the M2MP Daemon in a separate process on each machine.
    
7. Run an instance of the Chat Demo application in a separate process on each machine. A line typed into any chat window on any machine shows up in all the chat windows on all the machines.

After that, trying running the Slide Show application (see package edu.rit.slides). Then try writing your own M2MI-based applications!

The documentation and Java source files in the M2MI Library, the M2MP Library, and the RIT Classfile Library ("The Libraries") are copyright © 2001-2004 by Alan Kaminsky. All rights reserved. For further information, contact the author, Alan Kaminsky, at ark­@­cs.rit.edu.

The Libraries are free software; you can redistribute them and/or modify them under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The Libraries are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is provided in the file gpl.txt. You may also obtain a copy of the GNU General Public License on the World Wide Web at http://www.gnu.org/licenses/gpl.html or by writing to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

29-Mar-2006

In package edu.rit.m2mp: Added class ControllableChannel, which displays a control panel UI for connecting and disconnecting the M2MP Layer from the external network. This can be used to simulate network failures and network partitions. Added the edu.rit.m2mp.debug.controlpanel property to the M2MP properties file to specify whether to display the control panel.
 

27-Mar-2006

Moved the Chat Demo Application Version 1 from package edu.rit.m2mi.chat1 to package edu.rit.chat1; also simplified the code.

Added package edu.rit.chat2 with the Chat Demo Application Version 2. This version supports multiple chat rooms, discovering the chat rooms that are out there, creating new chat rooms, and joining a selected chat room.
 

22-Mar-2006

Added package edu.rit.survey with the Online Survey, an example of an ad hoc collaborative application.
 

23-Nov-2004

In package edu.rit.m2mp: The M2MP channel access sublayer was eliminated and replaced with a simpler flow control sublayer, encapsulated in class FlowController. Added the ability to send each packet of an M2MP message multiple times to partially compensate for an unreliable data link layer; this feature is controlled by the edu.rit.m2mp.redundancy property in the M2MP properties file. As a result, the M2MP packet format was changed. Consequently, this version of M2MP will not interoperate with previous versions of M2MP.

In package edu.rit.m2mi: In class Handle, the getInterfaceNames() method was renamed getInterfaceName(), since the method returns only one interface name; and the iterator() method was added.

In package edu.rit.slides: Added the SlideShowToHtml program. Added constructors to class Slide and class SlideShow that take a Collection as an argument.

In package edu.rit.slides.items: Added classes ArcItem, DottedOutline, Point, and Size. Modified most of the other classes to make it easier to write programs to create slide shows. As a result, the serialization format for slide show objects was changed. Consequently, slide show objects serialized using the previous version must be re-created and re-serialized.

In package edu.rit.slides.test: Rewrote the test programs to use the new capabilities of packages edu.rit.slides and edu.rit.slides.items.

Packages edu.rit.parallel.particles and edu.rit.parallel.util were removed.

Fixed a bug in class edu.rit.m2mi.MethodInvokerSynthesizer. The wrong method signature was used when calling the writeByte(), writeShort(), or writeChar() methods in interface java.io.ObjectOutput.

Fixed a bug in class edu.rit.m2mp.MessageOutputStream. If the last fragment of a message exactly filled a packet, the last packet would not be sent, causing the receiver to time out the message.
 

26-Aug-2004

The device ID setting was pulled out of the M2MI and M2MP property files and put in its own separate device property file. (The device ID is supposed to be the same in both the M2MI Layer and the M2MP Layer, so it shouldn't be specified twice.)

Parts of the M2MP Layer were redesigned, with an eye towards using M2MP as the messaging layer in parallel programs. Specific changes include:

• The cryptographic message authentication code (MAC) in each M2MP packet was eliminated, for two reasons: (1) Doing so reduced the M2MP Layer's processing time. Parallel programs typically run on an isolated network and do not need the security of the MAC; however, parallel programs do need the best possible performance. (2) The security issues addressed by the MAC -- packet alterations and insertions -- are better addressed at other layers, such as a secure channel in the M2MI Layer or in the application.
   
• The experimental flow control mechanism in the previous version was replaced by a channel access sublayer using token passing. This achieves flow control and reduces contention for the broadcast medium much more robustly than the previous version.
   
• As a result of the above changes, the M2MP packet format was changed. Consequently, this version of M2MP will not interoperate with previous versions of M2MP.
   

02-Mar-2004

A complete rewrite of the M2MI Library and the M2MP Library. The new version has been tested on Linux, Solaris, and Cygwin/Windows. The major changes from the previous version are:

• The M2MI.initialize() method no longer has any arguments. Parameters needed to configure the M2MI Layer are now located in an "M2MI properties file." This simplifies coding M2MI-based applications and lets the M2MI Layer be configured independently of any particular applications. See class edu.rit.m2mi.M2MIProperties for further information.
   
• Handle, Omnihandle, Unihandle, and Multihandle are now classes instead of interfaces. This simplifies the design of the M2MI Layer.
   
• A handle object now can only implement one target interface. (In the previous version, a handle object could implement more than one target interface.) Handles are supposed to be analogous to Java references. Since a Java reference has only one type, a handle should implement only one target interface.
   
• The M2MI proxy objects -- handles and method invokers -- were redesigned to run faster and use less storage. M2MI calls within the same process are now an order of magnitude faster than they were in the previous version. This is a significant improvement for applications that have multiple M2MI target objects in a process.
   
• Because of the M2MI proxy object redesign, the M2MI invocation message format was changed. This version of M2MI will not interoperate with the previous version of M2MI.
   
• The M2MI Layer was redesigned to make it easier to add different kinds of handles, such as "secure handles" that encrypt and decrypt the invocations. However, this version of the M2MI Library still provides only "plain old" handles; other kinds of handles will be added in future versions.
   
• Parameters needed to configure the M2MP Layer are now located in an "M2MP properties file." This simplifies coding M2MP-based applications and lets the M2MP Layer be configured independently of any particular applications. See class edu.rit.m2mp.M2MPProperties for further information.
   
• The interface to the M2MP Layer was simplified. Classes and capabilities that have not been used in actual M2MI/M2MP-based applications were eliminated.
   
• The fixed-size packet pool in the previous version was eliminated. The M2MP Layer now dynamically allocates as many packets as it needs, until the Java Virtual Machine runs out of memory.
   
• The M2MP packet format was changed to include a cryptographic message authentication code (MAC) to detect packet alterations and prevent packet insertion attacks. Consequently, this version of M2MP will not interoperate with the previous version of M2MP.
   
• A flow control mechanism was added to the M2MP channel classes that transport M2MP packets using UDP datagrams. This attempted to solve a problem with the previous version of M2MP: When sending a long M2MP message, the sender could send packets faster than the receivers could process them, resulting in receiver buffer overruns, lost packets, and aborted messages. However, the present flow control mechanism is still experimental, is not fully tested, and must be considered unproven.
   
• The process that routes M2MP messages between multiple client processes on the same host, formerly class edu.rit.m2mp.ip.M2MPRouter, was changed to class edu.rit.m2mp.Daemon and redesigned. The M2MP Daemon process is configured via the M2MP properties file. The M2MP client processes can be configured either to go through the M2MP Daemon process or to go directly to the external network via the M2MP properties file.

This version also includes the following example M2MI-based applications:

• Chat Demo, an ad hoc collaborative application (package edu.rit.m2mi.chat1).
   
• Slides, an ad hoc collaborative application (package edu.rit.slides).
   
• Particle Simulation, a parallel program (package edu.rit.parallel.particles).
   

02-Jul-2002

Changed the channel implementation used to broadcast M2MP messages to all processes on the local host so it will work properly on Sun Solaris systems as well as Linux systems; the implementation is now contained in classes edu.rit.m2mp.ip.M2MPRouter (revised) and edu.rit.m2mp.ip.M2MPRouterChannel (new). Changed the chat demo application (class edu.rit.m2mi.test.ChatDemo) to put the user interface in a separate class from the exported chat object.
 

07-Jun-2002

Initial version. Released under the terms of the GNU General Public License.