com.faunos.util.net
Interface Handlet

All Known Subinterfaces:

Stagelet

All Known Implementing Classes:

AsynchStagelet, ExceptionStagelet, FileChannelStagelet, HttpHandlet, NotFoundStage, RequestStage, ResponseHeaderStage, StageletStack

public interface Handlet

An inversion-of-control mechanism for implementing a non-blocking network server or client. The methods defined here are designed to be invoked by a server or client container that is aware of the I/O readiness of the underlying channel.

Lifecycle

The lifecycle of a handlet instance is described below. The state of an instance only ever changes as a result of invoking either read(ScatteringByteChannel), or write(GatheringByteChannel).

1. Initialization. The container first invokes init(HandletContext). This is the familiar pattern found both in the servlet and applet architecture. No other method on the handlet instance will be invoked prior to initialization. I.e. the behavior of all the other methods is undefined prior to the invocation of init() (unless, of course, if defined by the implementation). On return, the state of the instance will not be IoState.DONE.
2. Reading. The handlet is ready to read. The next I/O invocation on the handlet instance will be a read. The state of the instance may change on invocation of read.
3. Writing. The handlet is ready to write. The next I/O invocation on the handlet instance will be a write. The state of the instance may change on invocation of write.
4. Processing. The handlet is neither ready to write nor read. No I/O methods should be invoked on the handlet until the container receives asynchronous notification that the instance has changed state via the context object supplied in init(HandletContext). The context object also provides an Executor on which the asynchronous task may be run, however, the handlet is free to use some other asynchronous mechanism.
5. Done. The handlet will not be doing anymore I/O. The container may close the communication channel.

Note that the IoState returned on invoking either of the read/write methods will not necessarily be the same as that returned by a subsequent invocation of the state method. In particular, after a read/write method returns IoState.PROCESSING, an immediate invocation might of state() might return a different value. The reason why is that the asynchronous task may have completed even before the read/write method returns. The return value in the signature of these two I/O methods provides a way for the container to reliably detect that a handlet instance went into the PROCESSING state.

Author:

Babak Farhang

Method Summary

void	discard() Discards the instance.
IoState	init(HandletContext context) Initializes the handlet.
IoState	read(ScatteringByteChannel in) Reads from the specified channel and returns the possibly new state of the instance.
IoState	state() Returns the state of the handlet.
IoState	write(GatheringByteChannel out) Writes to the specified channel and returns the possibly new state of the instance.

Method Detail

init

IoState init(HandletContext context)

Initializes the handlet.

Parameters:

context - the context supplied by the instance's container (e.g. server

state

IoState state()

Returns the state of the handlet.

read

IoState read(ScatteringByteChannel in)
             throws IOException

Reads from the specified channel and returns the possibly new state of the instance. Note that if the return value is IoState.PROCESSING, then a later invocation of state() may return a value other than PROCESSING, if the asynchronous task completes before the call to state().

The implementation must read from the channel in non-blocking manner. The behavior of this method is undefined if the state of the instance is not IoState.READING.

Throws:

IOException

write

IoState write(GatheringByteChannel out)
              throws IOException

Writes to the specified channel and returns the possibly new state of the instance. Note that if the return value is IoState.PROCESSING, then a later invocation of state() may return a value other than PROCESSING, if the asynchronous task completes before the call to state().

The implementation must write to the channel in non-blocking manner. The behavior of this method is undefined if the state of the instance is not IoState.WRITING.

Throws:

IOException

discard

void discard()

Discards the instance.