ANTS v2.0 API

ants.core
Class Capsule

java.lang.Object
  |
  +--ants.core.Capsule
Direct Known Subclasses:
DanteCapsule, DataCapsule, DLResponseCapsule, DynamicRouteCapsule, MobileCapsule, MobileUpdateCapsule, MulticastCapsule, MulticastSubscribeCapsule, StatsCapsule, StatsCapsule, StatsReturnCapsule

public abstract class Capsule
extends java.lang.Object

A capsule is a combination of a packet and its forwarding routine; the forwarding routine is executed at every active node the packet visits in the network.

This is an abstract, an actual Capsule is created by subclassing this class and filling in the missing routines.

Subclasses must implement the mid(), pid(), and evalutate() methods.

All ANTS capsules have the following format:

    header
   4-byte ANTS version number
   16-byte MethodID  (The MD5 hash over the class bytecode)
   4-byte logical source address
   4-byte logical destination address
   4-byte logical previous-hop address
   4-byte TTL field.
   ... Capsule-specific data ...
 

Author:
David Wetherall, Utah Janos Team

Field Summary
static int MAX_TTL
           
 
Constructor Summary
Capsule()
          Create a dull capsule.
 
Method Summary
static Capsule create(java.lang.Class cl, Xdr xdr)
          Create a new Capsule from the given Xdr.
 Xdr decode()
          Decode a capsule header from this Capsule's xdr field.
 Xdr encode()
          Encode this capsule's header into a new Xdr.
 Xdr encodeCapsuleForSend(Node node)
          Encode an outgoing capsule.
abstract  boolean evaluate(Node node)
          The forwarding routine for the Capsule.
static int findExtension(java.lang.String name)
          Find a given extension.
static byte[] findMID(java.lang.String name)
          Access point to initialze capsule methodIDs.
static byte[] findPID(java.lang.String name)
          Access point to initialze capsule protocolID.
 int getDst()
          Return the destination IP address of this capsule.
 int getPrevious()
          Get the 32-bit IP address of the active node this packet just came from.
 int getSrc()
          Return the source IP address of this capsule.
 int getTTL()
          Return the TTL-like counter for this capsule.
 int length()
          Return the length of the capsule header that all capsule encodings will include.
 void prime(Capsule parent)
          Prime this capsule for transmission.
 void setDst(int dst)
          Set the destination IP address of this capsule.
 java.lang.String toString()
          String representation of a Capsule.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MAX_TTL

public static final int MAX_TTL
Constructor Detail

Capsule

public Capsule()
Create a dull capsule.
Method Detail

getPrevious

public int getPrevious()
Get the 32-bit IP address of the active node this packet just came from. Used to find code to process this packet.

getTTL

public int getTTL()
Return the TTL-like counter for this capsule.
Returns:
a TTL value for this Capsule.

findMID

public static byte[] findMID(java.lang.String name)
Access point to initialze capsule methodIDs. Given Capsule class name, returns the appropriate MID.

XXX its probably bad that the actual underlying byte[] is returned and not a copy... Who uses this?

Parameters:
name - the name of the Capsule class
Returns:
the MD5 checksum (MID) associated with the given Capsule class.
See Also:
Node#findMID(java.lang.String)

findPID

public static byte[] findPID(java.lang.String name)
Access point to initialze capsule protocolID. Given Capsule class name, returns the appropriate PID.
Parameters:
name - the name of the Capsule class
Returns:
the MD5 checksum (PID) associated with the given Capsule class.
See Also:
Node#findPID(java.lang.String)

findExtension

public static int findExtension(java.lang.String name)
Find a given extension. Given the name for an extension, return the local "index" of that extension.

XXX This interface will need to be replaced to allow extensions to be reference counted (and unloaded).

Parameters:
name - The name of the extension to load.
Returns:
The local "index" of the given extension.

evaluate

public abstract boolean evaluate(Node node)
The forwarding routine for the Capsule. This is invoked by the router when a capsule is received.

This method should not access other Java classes, and should only interact with the local system through the local node interface. This routine should "terminate quickly."

XXX perhaps default to forwarding the Capsule?

Parameters:
node - the local node interface
Returns:
an indicationof whether the forwarding was successful.

getSrc

public int getSrc()
Return the source IP address of this capsule.
Returns:
the source IP address of this capsule.

getDst

public int getDst()
Return the destination IP address of this capsule.
Returns:
the destination IP address of this capsule.

setDst

public void setDst(int dst)
Set the destination IP address of this capsule.
Parameters:
dst - the destination IP address of this capsule.

length

public int length()
Return the length of the capsule header that all capsule encodings will include.
Returns:
the length of the capsule header

encode

public Xdr encode()
Encode this capsule's header into a new Xdr. Return the new Xdr.

Because this header must go first in the Xdr, this encoder unilaterally sets the xdr buffer pointer to the beginning of the buffer and writes its data there.

The format of the Xdr is:

 MethodID         (16 bytes)
 src address      ( 4 bytes)
 dst address      ( 4 bytes)
 previous address ( 4 bytes)
 TTL              ( 4 bytes)
 
Returns:
the new Xdr representing this capsule.
See Also:
#xdr

encodeCapsuleForSend

public Xdr encodeCapsuleForSend(Node node)
Encode an outgoing capsule.

This writes the ANEP and ANTS header for an outgoing capsule in its associated Xdr. A new Xdr is created if the Capsule doesn't already have one. Then the per-capsule encoding is called.

This function should be invoked immediately before pushing the capsule out the door.

XXX: rename to 'encodeForSend()'

Parameters:
node - the node interface
Returns:
Xdr returns Xdr in which the remainder of the capsule should be encoded.
Throws:
java.lang.SecurityException - if the source is not defined in the capsule
ResourceLimitException - if the capsule has insufficent resources

decode

public Xdr decode()
Decode a capsule header from this Capsule's xdr field.
Returns:
the new Xdr based on the current xdr.

prime

public final void prime(Capsule parent)
Prime this capsule for transmission. Use the given parent Capsule to prime the src and ttl of this capsule.

Does not maintain zero-sum ttl. This capsule gets parent's ttl minus 1. Parent loses one hop.

Parameters:
parent - the capsule to take src and ttl (minus 1) from.

toString

public java.lang.String toString()
String representation of a Capsule. Includes the class name, source and destination.
Overrides:
toString in class java.lang.Object

create

public static Capsule create(java.lang.Class cl,
                             Xdr xdr)
                      throws java.lang.Exception
Create a new Capsule from the given Xdr. The xdr will be decoded into an instance of the given class which must be a subclass of Capsule.
Parameters:
cl - the subtype of capsule to create
xdr - the encoding of the actual capsule
Returns:
the new Capsule instance.

ANTS v2.0 API

This documentation is Copyright (C) 1998-2001 The University of Utah and the University of Washington. All Rights Reserved. See the individual source files for distribution terms.
Documentation, software, and mailing lists for ANTS v2.0 can be found at the Janos Project: http://www.cs.utah.edu/flux/janos/