The M2MI Library is the API for
Many-to-Many Invocation (M2MI),
a new paradigm for building distributed systems,
especially ad hoc collaborative systems
that run in proximal wireless networks
of fixed and mobile computing devices,
as well as traditional client-server systems.
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
1. Installation
2. Getting Started
3. License
4. Revision History
1. Installation
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.
2. Getting Started
To get started with M2MI,
do the following steps on a single machine:
-
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.
-
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.
-
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.
-
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.
-
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:
-
Configure the M2MP Layer and M2MI Layer on each machine.
-
Run the M2MP Daemon in a separate process on each machine.
-
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!
3. License
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.
4. Revision History
- 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.