bees.core
Class Capsule

java.lang.Object
  |
  +--bees.core.Packet
        |
        +--bees.core.ANEPPacket
              |
              +--bees.core.Capsule

Direct Known Subclasses:

AdvertiseCapsule, BenchmarkBootCapsule, BenchmarkCapsule, ConfigurationCapsule, DataRequestCapsule, DataResponseCapsule, DiscoveryBootCapsule, HealthBootCapsule, HelloBootCapsule, HelloCapsule, LivenessBootCapsule, MinimalCapsule, MulticastCapsule, PathfinderBootCapsule, PokeCapsule, PollRequestCapsule, PrimerCapsule, SinkCapsule, StatsCapsule

public abstract class Capsule

extends bees.core.ANEPPacket

Capsule defines the base for packets that can be sent or received by a node. Subclasses are expected to implement the encode() and decode() methods to marshal and unmarshal object state, and to implement the evaluate() method which handles the arrival of a new Capsule at a node. However, they are not expected to create a unique capsule identifier and transfer their code between nodes, the system will perform these functions.

Because of the need to restrict the propagation of Capsules in the system and network, each capsule object is associated with an authorization state. This state tracks the number of times the capsule can be used in some operation, such as sending the capsule to a neighbor. After a capsule has been used to perform these operations it is considered "depleted" and needs to be "replenished" before it can be used again. Capsules can be replenished through one of the following methods:

• Using fromCapsule() with a usable Capsule object, for example, the boot capsule or one received from a neighbor.
• Using fromExternal() with an ExternalCapsule received from an application.
• Using specializeCapsule() on a companion capsule with the capsule it should be specialized to.
• Adding the Capsule to a NodeCache, when the mapping is collected, the object will be replenished. Useful for periodic replenishment.

The set of operations that a capsule is actually allowed to perform is specified with a PermissionSet when the Protocol is being built.

See Also:

Protocol.addCapsule(String, PermissionSet), Protocol

Constructor Summary

Capsule()
Create a Capsule with the default values.

Method Summary

void	addToPool() Add this capsule back to the flow local pool.
void	checkPermission(Permission what) Check the capsule for the given permission.
java.lang.Object	clone()
abstract void	decode(Xdr xdr) Decode this Capsule's state from the given Xdr.
void	decodingException(java.lang.Throwable th)
abstract void	encode(Xdr xdr) Encode this Capsule's state into the given Xdr.
boolean	equals(java.lang.Object obj)
void	evaluate(Node node) Evaluate this capsule.
void	evaluate(Node node, ProtocolSession ps) Evaluate this capsule.
void	fromCapsule(Capsule cap) Replenish this capsule from the authorization in the given capsule.
void	fromExternal(ExternalCapsule ec) Replenish this capsule from the authorization in the given external capsule.
TypeID	getCapsuleID()
PairChain	getFlowDesc()
ProtocolSession	getSession()
ProtocolSession	getSession(java.lang.String companionSessionName) Get the ProtocolSession for the given class name with the context of this Capsule's flow.
Neighbor	getSource()
protected void	internalDecode(Xdr xdr)
protected void	internalEncode(Xdr xdr)
protected void	internalReset() Reset any cached values so the capsule can be reused instead of left to garbage collector.
void	reset() Reset this Capsule's state.
protected void	skipOptions(Xdr xdr) Skip the options in the ANEP header leaving the Xdr pointing to the start of the payload.
void	specializeCapsule(Capsule cap) Replenish this companion capsule and specialize it from the given Capsule.
java.lang.String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Capsule

public Capsule()

Create a Capsule with the default values.

Method Detail

getCapsuleID

public final TypeID getCapsuleID()

Returns:

The unique identifier for this type of capsule.

getFlowDesc

public final PairChain getFlowDesc()

Returns:

A copy of the PairChain describing the flow this capsule belongs too.

getSession

public final ProtocolSession getSession(java.lang.String companionSessionName)
                                 throws java.lang.ClassNotFoundException

Get the ProtocolSession for the given class name with the context of this Capsule's flow.

Parameters:

companionSessionName - The class name of the session to retrieve.

Returns:

The ProtocolSession object that matches the given name and is within the context of this Capsule's flow.

Throws:

java.lang.ClassNotFoundException - if the given class name couldn't be found.

java.lang.IllegalStateException - if the capsule has yet to be associated with protocol session.

getSession

public final ProtocolSession getSession()

Returns:

The ProtocolSession linked to this flow.

fromExternal

public final void fromExternal(ExternalCapsule ec)

Replenish this capsule from the authorization in the given external capsule.

Parameters:

ec - The external capsule to use as authorization.

fromCapsule

public final void fromCapsule(Capsule cap)

Replenish this capsule from the authorization in the given capsule.

Parameters:

cap - The capsule to use as authorization.

specializeCapsule

public final void specializeCapsule(Capsule cap)

Replenish this companion capsule and specialize it from the given Capsule.

Parameters:

cap - The capsule this one should be specialized to.

internalDecode

protected final void internalDecode(Xdr xdr)
                             throws InvalidPacketException,
                                    DroppedPacketException

Overrides:

internalDecode in class bees.core.ANEPPacket

Following copied from class: bees.core.ANEPPacket

See Also:

bees.core.Packet#internalDecode(Xdr)

internalEncode

protected final void internalEncode(Xdr xdr)

reset

public void reset()

Reset this Capsule's state. This method will be called when this object is added back into a pool via addToPool().

decodingException

public void decodingException(java.lang.Throwable th)

decode

public abstract void decode(Xdr xdr)
                     throws java.lang.Throwable

Decode this Capsule's state from the given Xdr.

Parameters:

xdr - An Xdr object that contains this Capsule's data.

Throws:

java.lang.Throwable - if anything goes wrong.

encode

public abstract void encode(Xdr xdr)
                     throws java.lang.Throwable

Encode this Capsule's state into the given Xdr.

Parameters:

xdr - An Xdr object that should be used to encode this Capsule's state.

Throws:

java.lang.Throwable - if anything goes wrong.

evaluate

public void evaluate(Node node)
              throws java.lang.Throwable

Evaluate this capsule. Basically, this is the function that performs any computation and forwarding.

Parameters:

node - The current Node object.

Throws:

java.lang.Throwable - if anything goes wrong.

evaluate

public void evaluate(Node node,
                     ProtocolSession ps)
              throws java.lang.Throwable

Evaluate this capsule. Basically, this is the function that performs any computation and forwarding.

Parameters:

node - The current Node object.

ps - The ProtocolSession bound to this capsule type.

Throws:

java.lang.Throwable - if anything goes wrong.

checkPermission

public final void checkPermission(Permission what)
                           throws PermissionException

Check the capsule for the given permission.

Parameters:

what - The Permission to check for.

Throws:

PermissionException - if the Capsule doesn't have the given Permission.

addToPool

public void addToPool()

Add this capsule back to the flow local pool.

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class bees.core.ANEPPacket

See Also:

Object.equals(Object)

toString

public java.lang.String toString()

Overrides:

toString in class bees.core.ANEPPacket

See Also:

Object.toString()

internalReset

protected void internalReset()

Description copied from class: bees.core.Packet

Reset any cached values so the capsule can be reused instead of left to garbage collector.

Overrides:

internalReset in class bees.core.Packet

See Also:

Packet.internalReset()

skipOptions

protected void skipOptions(Xdr xdr)

Skip the options in the ANEP header leaving the Xdr pointing to the start of the payload.

Parameters:

xdr - The Xdr containing an encoded ANEP header.

getSource

public final Neighbor getSource()

Returns:

The source of the packet.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object