bees.core
Class Protocol

java.lang.Object
  |
  +--bees.core.Protocol

Direct Known Subclasses:

BenchmarkProtocol, DiscoveryProtocol, DLProtocol, HealthProtocol, HelloProtocol, IDTranslationProtocol, LivenessProtocol, PathfinderProtocol, UnknownProtocol

public class Protocol

extends java.lang.Object

Protocol is used to describe the classes, data, and companion protocols that make up an Bees protocol. Subclasses are expected to override the constructor and use the functions in this class to build the protocol description. Once the constructor has finished executing, the resulting Protocol should describe a completely self contained entity that can be transferred between nodes.

Actual construction of the description is done on end nodes where the protocol has access to files on the local file system and capabilities that may not be available elsewhere. Besides simple byte arrays, the protocol can also specify "companion" protocols, which can be used to assist the protocol perform its task. For example, the system provides the "DLProtocol" and "IDTranslationProtocol" companions which take care of downloading the protocol to other nodes. Once the protocol has been successfully built, it can then be used as a companion for other protocols (if it implements CompanionProtocol) or it can be used as the primary protocol for a ProtocolFlow.

Starting a Protocol on a node is done by registering a ProtocolFlow through a Node object or by externally starting up a ProtocolBDomain with the Protocol class name as the first argument. Once the flow has been instantiated, the primary protocol will receive a "boot" capsule from the system and the rest is up to the implementation.

Example:

 public class ExampleProtocol
   extends Protocol
 {
   public ExampleProtocol()
   {
     super.startProtocolDefn();
     {
       super.addCapsule("MyCapsule", new PermissionSet(new Permission[] {
         new CountPermission("returns", 1),
       }));
       super.setBootStrap("MyBootCapsule", new PermissionSet());
       super.addCode("MyHelperClass");
       super.setSession("MySession");
       super.addCompanion(new DLProtocol());
       super.addCompanion(new IDTranslationProtocol());
     }
     super.endProtocolDefn();
   }
 }
 

See Also:

Node, ProtocolFlow, DLProtocol, IDTranslationProtocol, CompanionProtocol

Constructor Summary

protected

Protocol() Construct an empty Protocol object.

Method Summary

protected void	addByteArray(java.lang.String byteArrayName, byte[] ba) Add a plain byte array to the protocol.
protected void	addByteArray(java.lang.String byteArrayName, byte[] ba, VersionString vs) Add a plain byte array to the protocol.
protected void	addCapsule(java.lang.String className, PermissionSet ps) Add a full capsule class to the protocol.
protected void	addCapsule(java.lang.String className, VersionString versionID, PermissionSet ps) Add a full capsule class to the protocol.
protected void	addCode(java.lang.String className) Add a class to the protocol.
protected void	addCode(java.lang.String className, VersionString versionID) Add a class to the protocol.
protected void	addCompanion(CompanionProtocol protocol) Add a companion to the protocol.
protected void	addFile(java.lang.String fileName) Add a file from the class path to the protocol.
protected void	endProtocolDefn() End the protocol definition, this will demarcate the end of the definition and finalize any internal hashed identifiers.
int	getByteArrayLength()
protected Node	getNode()
protected void	setBootStrap(java.lang.String className, PermissionSet ps) Set the boot strap capsule class name.
protected void	setSession(java.lang.String className) Set the ProtocolSession class name.
protected void	startProtocolDefn() Start the protocol definition, this is mostly for demarking the start of the definition.
byte[]	toByteArray()
void	toByteArray(XdrByteArray xdr) Encode this Protocol object in the given byte array.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Protocol

protected Protocol()

Construct an empty Protocol object.

Method Detail

getNode

protected final Node getNode()

Returns:

The current Node object.

startProtocolDefn

protected void startProtocolDefn()

Start the protocol definition, this is mostly for demarking the start of the definition.

endProtocolDefn

protected void endProtocolDefn()
                        throws java.lang.IllegalStateException

End the protocol definition, this will demarcate the end of the definition and finalize any internal hashed identifiers.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

addByteArray

protected void addByteArray(java.lang.String byteArrayName,
                            byte[] ba,
                            VersionString vs)
                     throws java.lang.IllegalStateException

Add a plain byte array to the protocol.

Parameters:

byteArrayName - The name of the byte array, used when addressing it through the ProtocolSession.

ba - The actual byte array to store.

vs - The optional VersionString to use when computing the hash id of "ba".

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

addByteArray

protected void addByteArray(java.lang.String byteArrayName,
                            byte[] ba)
                     throws java.lang.IllegalStateException

Add a plain byte array to the protocol.

Parameters:

byteArrayName - The name of the byte array, used when addressing it through the ProtocolSession.

ba - The actual byte array to store.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

addFile

protected void addFile(java.lang.String fileName)
                throws java.io.FileNotFoundException,
                       java.lang.IllegalStateException

Add a file from the class path to the protocol.

Parameters:

fileName - The name of the file, used to load the file and address through the ProtocolSession.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

addCode

protected void addCode(java.lang.String className,
                       VersionString versionID)
                throws java.lang.ClassNotFoundException,
                       java.lang.IllegalStateException

Add a class to the protocol.

Parameters:

className - The name of the class to add.

versionID - The optional VersionString to use when computing the hash id of the class.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

addCode

protected void addCode(java.lang.String className)
                throws java.lang.ClassNotFoundException,
                       java.lang.IllegalStateException

Add a class to the protocol.

Parameters:

className - The name of the class to add.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

addCapsule

protected void addCapsule(java.lang.String className,
                          VersionString versionID,
                          PermissionSet ps)
                   throws java.lang.ClassNotFoundException,
                          java.lang.IllegalStateException

Add a full capsule class to the protocol. This method differs from addCode() in that these types of Capsules can be received by Neighbor objects. For example, a subclass of Capsule that is added with addCode() will be available as a base class, but capsules of this type will not be received from neighbors.

The PermissionSet that gets passed to this method describes the properties of this Capsule type. The propagation properties, encoded as CountPermission objects, are:

• initial - Number of times a Capsule initialized from an ExternalCapsule can be sent.
• returns - Number of times a Capsule can be sent back to its source.
• forwards - Number of times a Capsule can be forwarded to another neighbor.
• externals - Number of times a Capsule can be used to create an outgoing ExternalCapsule.
• neighborhood - Number of times a Capsule can be sent to a neighborhood.
• groups - Number of times a Capsule can be used to replenish a CapsuleGroup.
• transfers - Number of times a Capsule can be used to replenish a Capsule of the same type.
• transformTo. - Number of times a Capsule can be used to replenish a Capsule of the type, .
• interval - The minimum number of milliseconds allowed for an expiration time on a Capsule added to a NodeCache. Note: This value should be specified using a MinimumIntegerPermission and not a CountPermission.

The global properties, also encoded as CountPermissions, are:

• cached - The total number of Capsules of this type that can be placed in NodeCaches.
• grouped - The total number of Capsules of this type that can be placed in CapsuleGroups.
• threadCount - The maximum number of threads that can process Capsules from a single neighbor. (This number is passed to the InChannel constructor.)
• bufferCount - The number of buffers to use when receiving Capsules from a neighbor.

Parameters:

className - The name of the class to add.

versionID - The optional VersionString to use when computing the hash id of the class.

ps - The PermissionSet describing the propagation properties of Capsule classes.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

See Also:

Capsule

addCapsule

protected void addCapsule(java.lang.String className,
                          PermissionSet ps)
                   throws java.lang.ClassNotFoundException,
                          java.lang.IllegalStateException

Add a full capsule class to the protocol.

Parameters:

className - The name of the class to add.

requiredPermissions - The PermissionSet describing the propagation properties of Capsule classes.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

See Also:

addCapsule(String, VersionString, PermissionSet)

addCompanion

protected void addCompanion(CompanionProtocol protocol)
                     throws java.lang.IllegalStateException

Add a companion to the protocol.

Parameters:

protocol - A companion protocol.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

setSession

protected final void setSession(java.lang.String className)
                         throws java.lang.ClassNotFoundException,
                                java.lang.IllegalStateException

Set the ProtocolSession class name.

Parameters:

className - The name of the ProtocolSession class to use.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

setBootStrap

protected final void setBootStrap(java.lang.String className,
                                  PermissionSet ps)
                           throws java.lang.ClassNotFoundException,
                                  java.lang.IllegalStateException

Set the boot strap capsule class name. This will add the capsule class and declare it the type to be executed when a protocol is booted. Note: Only the primary protocol in a ProtocolFlow will receive a boot capsule.

Parameters:

className - The name of the class to add.

requiredPermissions - The PermissionSet describing the propagation properties of Capsule classes.

Throws:

java.lang.IllegalStateException - if startProtocolDefn() wasn't called before calling this method.

getByteArrayLength

public final int getByteArrayLength()

Returns:

The number of bytes needed to encode this protocol.

toByteArray

public final void toByteArray(XdrByteArray xdr)

Encode this Protocol object in the given byte array.

Parameters:

xdr - An XdrByteArray large enough to hold the flattened version of this Protocol.

toByteArray

public final byte[] toByteArray()

Returns:

A flattened version of this Protocol object.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()