README (top)
Overview
Ants (for active node transfer system) distribution is a Java-based
toolkit for constructing an active network and its applications,
including some supporting utilities and documentation.
Version
The version number carried across the network by capsules created
from this distribution is 1.2. A change
history describes the differences from previous versions.
Contents
The core distribution contains the following directories, each with
their own README.
- ants, the implementation of the
active node runtime
- apps, a place for network
applications (including their capsules), with samples
- docs, papers and javadoc
generated APIs
- runs, a place for network
configurations and result files, with samples
- utils, assorted general purpose
utilities
Other directories may be present in your distribution for node
extensions or application families.
Installation
ants requires Java and Tcl to build and run. This version is written
entirely in JDK1.1.x compliant Java and executes as a user-level
process (using the network atop UDP) with no special privileges. It
should be straightforward to port to any JDK1.1.x compatible runtime.
The Makefiles are written for a Unix style development
environment. If gnu make is available, it will use the GNUmakefile
in the top directory, but normal make should work, too. Some support
scripts are also written in Tcl.
Before building, if you do not use GNU make, you must set your
CLASSPATH
environment variable to include the top directory of the ants distribution,
e.g., if your copy is in ~/ants:
setenv CLASSPATH $HOME/ants:$CLASSPATH
This keeps the Java compiler happy. Now type make at the
top level and cross your fingers. ants should then be fully built.
Other targets are clean and tags. All targets work
within subdirectories.
Using ants
There are several sources of information on how to use ants within
the distribution:
- Two papers on the ants architecture and developing protocols
within it are included in the documentation directory.
- API reference pages for the key classes (Node,
Capsule, Protocol and Application) are
generated from the code by javadoc and placed in the documentation directory.
- The Ping* family of classes in the application directory provide a simple
example that can be launched with the ping.config file and
ping.start script in the runs
directory.
New applications are developed as several Java classes, all of
which are typically placed in the apps/ package and
directory:
- The end-system component of the application, including
network-independent activities such as a GUI, is developed by
extending the class Application into
MYApplication.java. This code will not be transferred into
the network substrate. It interacts with the network, e.g., sending
and receiving capsules, via a local Node instance.
- Customized processing within the network is developed by extending
the Capsule and Protocol classes into
MYCapsule.java and MYProtocol.java. (If standard
routing and data delivery is all that is needed, the built-in
DataProtocol can simply be used.) Capsule is
extended once for each new type of forwarding routine by using the
Node API, e.g., routefornode() and
delivertoapp(). This code includes intra-network processing
at the source and destination nodes, as well as at other nodes within
the network. Protocol is extended once for each set of
related capsules.
New applications are then run by writing a configuration file,
which is typically placed in the runs/ directory, and
starting one (or more) Java processes:
- The file MY.config should contain a human readable
description of a network topology and its configuration of entities at
each node. It includes comments, and describes one entity and its
parameters per line. It is used to calculate a MY.routes
file by running make.
- Set the network in motion by starting one Java process for each
node, distributed across machines according to the desired topology.
Typically, the ConfigurationManager class is used to process
the configuration file and create and configure the entities for a
single node. By convention, the command lines that launch a network
are stored in a MY.start file and output is directed to a
MY.log file. If the local process is intended to join into
an already running network, then if may be convenient to construct a
special configuration file for this purpose -- the configuration files
need only share compatible routing databases.
Feedback and Credits
The mailing list ants-interest@sds.lcs.mit.edu has been
set up to discuss ants, announce distributions, report bugs, suggest
features, and so forth. Please join it (by sending a message to
majordomo@sds.lcs.mit.edu with subscribe
ants-interest in the body) if you intend to be a regular
user.
Ants was developed by David Wetherall (djw@lcs.mit.edu) with much help from
other members of the Software Devices and Systems group at the MIT Lab
for Computer Science. In particular, Ulana Legedza, Li Lehman, David
Murphy, and Jon Santos contributed to the software design and
implementation, and John Chapin, Steve Garland, John Guttag, Erik
Nygren, Liuba Shrira, and David Tennenhouse contributed to the
architecture.