All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----edu.utah.janos.antsr.core.Capsule

Summary

public abstract class  Capsule
     extends java.lang.Object
{
          // Fields 14
     static final byte ANEPVERSION;
     static final short ANTSRTYPE;
     static final int ANTSRVERSION;
     static final short ANTSTYPE;
     static final short DESTOPTTYPE;
     static final int HEADERLENGTH;
     static final int IPV4SCHEME;
     public static final int MAX_TTL;
     static final short SRCOPTTYPE;
     private int dst;
     private int previous;
     private int src;
     private int ttl;
     private Xdr xdr;

          // Constructors 1
     public Capsule();

          // Methods 24
     public static Capsule create(Class, Xdr) throws Exception;
     static final Capsule dequeueCapsule(Node, CommQueue);
     public static int findExtension(String);
     public static byte[] findMID(String);
     public static byte[] findPID(String);
     static final int peekPrevious(BufferHandle);

     public Xdr decode();
     void decodeWith(Xdr);
     public Xdr encode();
     public Xdr encodeCapsuleForSend(Node);
     final void enqueueCapsule(CommQueue);
     public abstract boolean evaluate(Node);
     public int getDst();
     public int getPrevious();
     public int getSrc();
     public int getTTL();
     public int length();
     protected abstract byte[] mid();
     protected abstract byte[] pid();
     public final void prime(Capsule);
     final void prime(int, int);
     public void setDst(int);
     void setPrevious(int);
     public String toString();
}

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 ANTSR capsules have the following format:

   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

Cross Reference

Extended By:

MobileCapsule, MobileUpdateCapsule, MulticastCapsule, MulticastSubscribeCapsule, DLRequestCapsule, DLResponseCapsule, DataCapsule, MIDIDRequestCapsule, MIDIDResponseCapsule, DynamicRouteCapsule, CapsuleTester.TestCapsule, ProtocolTester.TestCapsule

Returned By:

ANEPFlow.decode(), Capsule.create(), Capsule.dequeueCapsule(), PendingRequest.getCapsule()

   static final byte ANEPVERSION

   static final short ANTSTYPE

   static final short ANTSRTYPE

   static final short SRCOPTTYPE

   static final short DESTOPTTYPE

   static final int IPV4SCHEME

   static final int ANTSRVERSION

   static final int HEADERLENGTH

   public static final int MAX_TTL

   private int src

All capsules originate from some source node. This is the 32-bit IP address of that source.

The source is set implicitly by the node that injects the capsule into the network and is never changed after that.

XXX what is this used for by the Node? Or is it just a convenience for subclasses? If that's all then nuke it.

See Also: getSrc

   private int dst

The destination for this capsule. Forwarding code may read/write this field.

See Also: getDst, setDst

   private int previous

32-bit IP address of previous active node. This is used by the code loading protocol to dynamically find the code to process a new packet type.

XXX security implications of giving this package access?

See Also: getPrevious, setPrevious

   private Xdr xdr

The xdr stream representing the buffer that underlies a Capsule.

For incoming packets, this field is set by the Protocol receive() function.

For outgoing packets, this field is set by the encode() method which creates a new Xdr.

   private int ttl

Time to live for a packet. Used to control packet propagation.

XXX a byte would suffice?

See Also: getTTL

Constructors

· Capsule

Summary  |  Top

   public Capsule() 

Create a dull capsule.

   protected abstract byte[] mid() 

Return the MethodID associated with this capsule.

See On_IDs.txt for more info on MethodIDs.

Returns:

the byte[] representing the MD5 checksum.

See Also: InChannel

   protected abstract byte[] pid() 

Return the ProtocolID associated with this capsule.

See On_IDs.txt for more info on ProtocolIDs.

Returns:

the byte[] representing the MD5 checksum.

See Also: findPID

   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.

   void setPrevious(int previous) 

Set the 32-bit IP address of the active node this packet "came from". Used by the outgoing channel encode() operation.

See Also: Channel

   public int getTTL() 

Return the TTL-like counter for this capsule.

Returns:

a TTL value for this Capsule.

   public static byte[] findMID(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?

Parameter	Description
name	the name of the Capsule class

Returns:

the MD5 checksum (MID) associated with the given Capsule class.

   public static byte[] findPID(String name) 

Access point to initialze capsule protocolID. Given Capsule class name, returns the appropriate PID.

Parameter	Description
name	the name of the Capsule class

Returns:

the MD5 checksum (PID) associated with the given Capsule class.

See Also: InChannel

   public static int findExtension(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 referenced counted (and unloaded).

Parameter	Description
name	The name of the extension to load.

Returns:

The local "index" of the given extension.

See Also: findNamedExtension, getExtension

   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?

Parameter	Description
node	the local node interface

Returns:

an indicationof whether the forwarding was successful.

   public int getSrc() 

Return the source IP address of this capsule.

Returns:

the source IP address of this capsule.

   public int getDst() 

Return the destination IP address of this capsule.

Returns:

the destination IP address of this capsule.

   public void setDst(int dst) 

Set the destination IP address of this capsule.

Parameter	Description
dst	the destination IP address of this capsule.

   public int length() 

Return the length of the capsule header that all capsule encodings will include.

Returns:

the length of the capsule header

   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

   public Xdr encodeCapsuleForSend(Node node) 

Encode an outgoing capsule.

This writes the ANEP and ANTSR 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()'

Parameter	Description
node	the node interface

Returns:

Xdr returns Xdr in which the remainder of the capsule should be encoded.

Throws: SecurityException

if the source is not defined in the capsule

Throws: ResourceLimitException

if the capsule has insufficent resources

   void decodeWith(Xdr xdr) 

   public Xdr decode() 

Decode a capsule header from this Capsule's xdr field.

Returns:

the new Xdr based on the current xdr.

   static final int peekPrevious(BufferHandle buf) 

Peek at the 'previous' field of buf. For bootstrapping capsule code loading.

Parameter	Description
buf	the Buffer to peek into.

Returns:

in the value of the 'previous' field in buf.

   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.

Parameter	Description
parent	the capsule to take src and ttl (minus 1) from.

   final void prime(int src, 
                    int ttl) 

Priveleged prime operation. Fill in this capsule's src and ttl fields directly. The given ttl is capped at MAX_TTL

This is package-access only, otherwise it would be a security hole.

Parameter	Description
src	the source address for the new packet.
ttl	the tll for the new packet.

See Also: MAX_TTL

   final void enqueueCapsule(CommQueue queue) 

Package up this capsule and dump it onto the queue for another application

   static final Capsule dequeueCapsule(Node node, 
                                       CommQueue queue) 

Produce a capsule from data pushed through a CommQueue by enqueueCapsule

   public String toString() 

String representation of a Capsule. Includes the class name, source and destination.

Overrides:

toString in class Object

   public static Capsule create(Class cl, 
                                Xdr xdr)  throws 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.

Parameter	Description
cl	the subtype of capsule to create
xdr	the encoding of the actual capsule

Returns:

the new Capsule instance.

All Packages  This Package  Class Hierarchy  Class Search  Index