All Packages  This Package  Class Hierarchy  Class Search  Index

Class edu.utah.janos.antsr.core.Capsule
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()





  Fields

· ANEPVERSION

Summary  |  Top
   static final byte ANEPVERSION


· ANTSTYPE

Summary  |  Top
   static final short ANTSTYPE


· ANTSRTYPE

Summary  |  Top
   static final short ANTSRTYPE


· SRCOPTTYPE

Summary  |  Top
   static final short SRCOPTTYPE


· DESTOPTTYPE

Summary  |  Top
   static final short DESTOPTTYPE


· IPV4SCHEME

Summary  |  Top
   static final int IPV4SCHEME


· ANTSRVERSION

Summary  |  Top
   static final int ANTSRVERSION


· HEADERLENGTH

Summary  |  Top
   static final int HEADERLENGTH


· MAX_TTL

Summary  |  Top
   public static final int MAX_TTL


· src

Summary  |  Top
   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


· dst

Summary  |  Top
   private int dst

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

See Also: getDst, setDst


· previous

Summary  |  Top
   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


· xdr

Summary  |  Top
   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.


· ttl

Summary  |  Top
   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.



  Methods

· mid

Summary  |  Top
   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



· pid

Summary  |  Top
   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



· getPrevious

Summary  |  Top
   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.



· setPrevious

Summary  |  Top
   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



· getTTL

Summary  |  Top
   public int getTTL() 

Return the TTL-like counter for this capsule.

Returns:
a TTL value for this Capsule.


· findMID

Summary  |  Top
   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.


· findPID

Summary  |  Top
   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



· findExtension

Summary  |  Top
   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



· evaluate

Summary  |  Top
   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.


· getSrc

Summary  |  Top
   public int getSrc() 

Return the source IP address of this capsule.

Returns:
the source IP address of this capsule.


· getDst

Summary  |  Top
   public int getDst() 

Return the destination IP address of this capsule.

Returns:
the destination IP address of this capsule.


· setDst

Summary  |  Top
   public void setDst(int dst) 

Set the destination IP address of this capsule.

Parameter Description
dst the destination IP address of this capsule.



· length

Summary  |  Top
   public int length() 

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

Returns:
the length of the capsule header


· encode

Summary  |  Top
   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

Summary  |  Top
   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


· decodeWith

Summary  |  Top
   void decodeWith(Xdr xdr) 


· decode

Summary  |  Top
   public Xdr decode() 

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

Returns:
the new Xdr based on the current xdr.


· peekPrevious

Summary  |  Top
   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.


· prime

Summary  |  Top
   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.



· prime

Summary  |  Top
   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



· enqueueCapsule

Summary  |  Top
   final void enqueueCapsule(CommQueue queue) 

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



· dequeueCapsule

Summary  |  Top
   static final Capsule dequeueCapsule(Node node, 
                                       CommQueue queue) 

Produce a capsule from data pushed through a CommQueue by enqueueCapsule



· toString

Summary  |  Top
   public String toString() 

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

Overrides:
toString in class Object


· create

Summary  |  Top
   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
Freshly brewed Java API Documentation automatically generated with polardoc Version 1.0.7