com.faunos.util.net
Interface Stagelet

All Superinterfaces:

Handlet

All Known Implementing Classes:

AsynchStagelet, ExceptionStagelet, FileChannelStagelet, NotFoundStage, RequestStage, ResponseHeaderStage

public interface Stagelet
extends Handlet

An extension to Handlet in order to encapsulate a "stack frame".

There are 2 categories of stagelets. One, the stack-aware which may push other stagelets onto a common stack. Conceptually, these behave like function calls within a function. Two, the stack-unaware which though themselves on the stack, don't push anything else on the stack. These are analogous to a function that doesn't call any other function.

In order to make the analogy to function calls more concrete, the following protocol regarding interaction with the StageletStack is observed. (Although StageletStack does not appear in the signature of any method defined here, still, it's tied to this interface definition.)

1. A stagelet may only ever push a stage onto the stack when it is the current stage on the stack. Corollaries to this rule are:
   1. A stagelet never pushes itself onto the stack; it's pushed onto the stack by someone else (e.g. the calling stagelet).
   2. A stagelet waits to be pushed onto the stack before it pushes any other stage onto the stack.
   A stagelet may push at most one stagelet onto the stack at a time.
2. When the instance's init method is invoked, the stagelet is already on the stack. This is the stagelet's signal that it has been pushed on the stack, and that it is now at the top of the stack.
3. A stagelet may only ever push another stagelet on the stack when its Handlet.init(HandletContext), Handlet.read(java.nio.channels.ScatteringByteChannel), or Handlet.write(java.nio.channels.GatheringByteChannel) method is invoked.

   If any of the above methods pushes another stagelet asynchronously, then the method must return IoState.PROCESSING.

Author:

Babak Farhang

See Also:

StageletStack

Method Summary

IoState

unwind(IoState preState) Callback method invoked when the previous stage[let] returned DONE.

Methods inherited from interface com.faunos.util.net.Handlet

discard, init, read, state, write

Method Detail

unwind

IoState unwind(IoState preState)

Callback method invoked when the previous stage[let] returned DONE. In the event this method returns DONE, the stack will call the Handlet.discard() method on the super interface.

Parameters:

preState - the state of the previous stage prior to its flipping to DONE

Returns:

the state of this stage. If DONE, and there is another Stagelet on the execution stack, then that stage's unwind() method will also be invoked with the same preState argument.