Package com.faunos.util.net

Facilities for non-blocking network I/O.

See:
Description

Interface Summary

Handlet	An inversion-of-control mechanism for implementing a non-blocking network server or client.
HandletContext	An interface provided by a Handlet container to a handlet.
Stagelet	An extension to Handlet in order to encapsulate a "stack frame".

Class Summary

AsynchStagelet	A skeletal implementation of an asynchronous stagelet.
HandletServer	A Handlet container implementing the server-side of a network protocol.
StageletStack	A Handlet filter that implements something like a call stack.
Validators	A few categories of Validator are defined here for use in the implementation.

Enum Summary

IoState

The various I/O states of a Handlet.

Exception Summary

HandletException
HandletStateException

Package com.faunos.util.net Description

Facilities for non-blocking network I/O. At the time of this writing, the contents of this package concern a simple architecture for a non-blocking network server.

Analogy to the Servlet architecture

The standard Servlet architecture involves an inversion of control mechanism, whereby after the network connection is established, the servlet container calls a servlet implementing the network protocol. In the servlet architecture, this inversion call, happens only once for each client/server session. In order to support non-blocking I/O, we develop an architecture that is similar in spirit to that of servlet, but one which allows multiple inversion calls. For lack of a better name, we call this design Handlet.

The Handlet interface

A Handlet instance advertises what I/O operations it is interested in through its state (or the return value of either of its init, read, or write methods).

The handlet container, in turn, takes care of registering (and/or cancelling) interest in the relevant selection event (if any). On receiving selection events, the container invokes each loaded handlet's read or write method, depending on the selection event. The handlet then is supposed to perform the read or write in non-blocking fashion (i.e. it must perform a single read or write operation on the channel, no more).

This simple workflow allows the container to do all I/O in a single thread (although it may be advantageous to use more than one on multi-CPU hardware).

The Stagelet interface

While handlets are easy to manage in a container, coding them to do much useful is not necessarily easy. The Stagelet interface is an attempt to simply the problem incrementally by introducing the notion of a stack of Handlets that behave like functions on a call stack.

A Stagelet's call stack is represented by a StageletStack instance. The handlet container is unaware of this construct: it is a handlet implementation tool.