All Packages  This Package  Class Hierarchy  Class Search  Index

java.lang.Object
   |
   +----edu.utah.janos.ants.ants.Protocol

Summary

public class  Protocol
     extends java.lang.Object
{
          // Fields 2
     static final ByteCodeReader classCode;
     Vector groups;

          // Constructors 1
     public Protocol();

          // Methods 9
     void activate(Node) throws Exception;
     protected void addCapsule(String) throws Exception;
     boolean builtin();
     protected void endGroupDefn() throws Exception;
     protected void endProtocolDefn() throws Exception, ClassNotFoundException;
     protected void startGroupDefn();
     protected void startGroupDefn(boolean);
     protected void startProtocolDefn();
     public String toString();

          // Inner Classes 2
     static class Protocol.CapsuleClassData
     static class Protocol.CodeGroupData
}

Base class for all protocols. Intended to be subclassed for each user-defined protocol for the purpose of collecting capsules into a protocol and registering it at the local node. A Protocol object is a short-lived object used only for defining a new protocol. After the protocol is defined and registered with the node it may be thrown away.

A protocol is organized into a collection of CodeGroups where each CodeGroup contains one or more CapsuleClasses. Unlike the Protocol object, CodeGroup and CapsuleClass objects are long-lived and must be kept in a cache on a node for the node to be able to process the protocol.

A protocol is intially registered at an end node. Classes are loaded from the local file system to define the protocol. When a capsule is sent from a protocol, the receiving node (probably) won't have the code to process it. The receiving node will then send a request for a specific CapsuleClass to the node which sent the capsule. The node will respond with the relevant CodeGroup which contains the requested class. Note that the receving node will never ask for a Protocol object it just uses CodeGroups and CapsuleClasses. There is no useful state in a Protocol object.

This class should probably be abstract, but its used as a concrete class for weak reasons in a number of test cases.

To define a protocol requires definining the relevant CodeGroups and the CapsuleClasses contained in each CodeGroup. For example:

 public class MulticastProtocol extends Protocol
 {
   public MulticastProtocol()
   {
     startProtocolDefn();
  
     startGroupDefn();
     addCapsule("apps.MulticastCapsule");
     endGroupDefn();
  
     startGroupDefn();
     addCapsule("apps.MulticastSubscribeCapsule");
     endGroupDefn();
  
     endProtocolDefn();
   }
 }
 

XXX This class defines a new protocol with two code groups....

Author:

David Wetherall

See Also: CodeGroup, CapsuleClass

Cross Reference

Extended By:

BuiltinProtocol, PingProtocol, DynamicRouteProtocol

   Vector groups

A list of CodeGroupData objects associated with this Protocol.

XXX Drop these vectors completely. Just require a parameter on StartProtocolDefn() that says how many groups will be defined. (use arrays).

   static final ByteCodeReader classCode

Bytecodereader that uses default class path. XXX this is static...

Constructors

· Protocol

Summary  |  Top

   public Protocol() 

Default constructor

   protected void startProtocolDefn() 

Start the definition of a new protocol. Subclasses of Protocol should invoke startProtocolDefn(), followed by startGroupDefn()/endGroupDefn() pairs and finally endProtocolDefn(). Calls to addCapsule() must be inserted in the start/end group pairs.

See Also: endProtocolDefn, startGroupDefn, endGroupDefn, addCapsule

   protected void endProtocolDefn()  throws Exception, ClassNotFoundException

End the protocol definition. This ties all of the elements of the protocol together. Each CodeGroup is given a list of all the other code Groups.

Throws: Exception

if the CodeGroup has too many chunks (currently the limit is 32).

See Also: startProtocolDefn, startGroupDefn, endGroupDefn, addCapsule

   void activate(Node node)  throws Exception

   protected void startGroupDefn() 

Start a new CodeGroup definition. Must be called in the context of a ProtocolDefn(). Subsequent CapsuleClasses will be added to this CodeGroup until it is ended. Must not be called after startGroupDefn() without an intervening endGroupDefn().

See Also: startProtocolDefn, endProtocolDefn, endGroupDefn, addCapsule

   protected void startGroupDefn(boolean active) 

   protected void endGroupDefn()  throws Exception

End a CodeGroup definition. Must be called in the context of a ProtocolDefn() and after an unmatched startGroupDefn(). Ending a CodeGroup without having added any capsules to it is a bad idea.

See Also: startProtocolDefn, endProtocolDefn, startGroupDefn, addCapsule

   protected void addCapsule(String name)  throws Exception

Add a Capsule class to a CodeGroup. Must be called in the context of a GroupDefn().

XXX rename to addCapsuleClass() or addCapsuleType()

Parameter	Description
name	Name of the class to include in the group.

See Also: startProtocolDefn, endProtocolDefn, startGroupDefn, endGroupDefn

   boolean builtin() 

Returns non-zero if this defines a builtin protocol. Overridden in BuiltinProtocol.

   public String toString() 

Return a string representation of this Protocol.

Returns:

A string.

Overrides:

toString in class Object

All Packages  This Package  Class Hierarchy  Class Search  Index