Computer Science 461

Distributed Computing and Networking

Fall 1997

Introduction to AcmeNet

AcmeNet is a software environment for writing programs that send and receive packets across the Internet. All of the programming assignments in COS 461 use AcmeNet. We provide you with the basic AcmeNet software; as you do the assignments you'll build up more layers of software to provide increasing levels of power and convenience.

AcmeNet uses Internet protocols, so AcmeNet processes can communicate across the campus or across the world. AcmeNet packets are transferred using the Internet's Unreliable Datagram Protocol (UDP). AcmeNet is written in Java, and you will do the programming assignments in Java.

In order to understand the workings of AcmeNet, there are three concepts you have to understand: addresses, network interfaces, and packets.

Addresses

An address is just a place on the network where a process can live. Think of it like a mailing address; if you know somebody's address you can send things to them. AcmeNet addresses are represented by the Java class AcmeNet.Util.NetAddress. An address consists of a machine name (like "phoenix.princeton.edu") and a port number on that machine. Port numbers uniquely identify the different programs on a machine that might be trying to use the network at the same time.

When you create a network interface, you can either ask AcmeNet to choose an address for you, or you can insist on having a particular address. If you insist on an address, you might not get it --- there might be another process at that address already. So unless you have a good reason to demand a particular address, you're better off letting AcmeNet choose the address. (If you choose your own address, port numbers between 9000 and 10000 tend to be good.)

Network Interfaces

The purpose of a network interface is to let you send and receive data across the network. If you don't have a network interface, you can't use the network.

Every network interface has a unique address. When you send data across AcmeNet, you don't send it to a person or to a program --- you send it to a network interface. Similarly, your network interface delivers to you all of the packets that are sent to it.

The most basic AcmeNet network interface is implemented in the class AcmeNet.Util.NetworkInterface. We have provided you with the code for this class, as part of the AcmeNet Utility Library. As the semester goes on, you will extend this basic network interface class to build network interfaces that are more powerful.

Packets

A packet is a bunch of bytes that gets sent across the network. An AcmeNet program can build a packet and then hand it to a network interface to send it. When the packet reaches its destination, the destination network interface inserts the packet into an arrived-packets queue. The destination program will eventually remove the packet from the queue and then consume the packet.

Let's follow the life-cycle of a packet in a bit more detail. Assume that process A (at address A_addr, with network interface A_ni) wants to send a packet to process B (at address B_addr, with network interface B_ni).

  1. Process A creates an empty packet by calling A_ni.getOutPacketStream(B_addr). This returns a DataOutputStream, which we'll call A_out..
  2. Process A fills the packet with data, by calling various methods of A_out to append data to the packet.
  3. Process A calls A_out.flush(), thereby causing the packet to be sent.
  4. (AcmeNet now automatically transfers the packet to B_ni. B_ni puts the packet into its arriving-packet queue.)
  5. Process B calls B_ni.getArrivingPacketQueue() to get a handle to B_ni's arriving-packet queue. (Or B might have done this previously and remembered the handle.) Let's call the queue B_q.
  6. Process B calls B_q.get() to get the next arriving packet. In our example, there are no other packets around, so the call will return the packet that A just sent. Call this return value B_in.
  7. B_in's class is AcmeNet.Util.PacketInputStream, which extends java.io.DataInputStream. B can learn who sent the packet by calling B_in.getSender(). Or B can read data out of the packet by calling methods of java.io.DataInputStream.
  8. At some point in reading data out of B_in, B will encounter an end-of-stream condition. This tells B that it has consumed all of the data in the packet.

Procedural Details

On-line documentation is available for all of the public classes in AcmeNet. This will be updated as necessary during the semester.

The AcmeNet code is available on-line on the CIT Sparcs in /u/cs461/Code/*. As the semester goes on, we will add code to these directories. For example, when a new assignment begins, we will generally make available some useful classes that will help you with the assignment. Also, after we are done grading an assignment, we will make code for a sample solution available.

New releases of the AcmeNet software will be announced in the course newsgroup.

Copyright (c) 1997 by Edward W. Felten

Last modified: Wednesday, September 24, 1997 10:04 AM