gov.lbl.dsd.sea.nio
Class NetAgent

java.lang.Object
  gov.lbl.dsd.sea.nio.NetAgent

public final class NetAgent

extends Object

Efficient and scalable NIO based non-blocking single-threaded network agent that can be used both as a client and a server, both for TCP and UDP transports; Can handle large amounts of concurrent client and server connections in a single thread; Automatically deals with the subtle grunt work of life-cycle issues, threading, I/O multiplexing and NIO gotchas; This is the main work horse of this package.

General usage pattern:

1. Construct a new agent
2. Configure it via setters and getters. Convenience methods simplify starting outgoing client connections and listening on ports for incoming connections.
3. Start the agent via start() or by enqueuing a AdminRequest.Start
4. Have your application enqueue some request events from the gov.lbl.dsd.sea.nio.eventpackage via enqueue(request) onto the agent. The agent will process the requests and enqueue responses to the requests onto the (synchronous or asynchronous) observer stage of the given network channel (connection), for example an AgentEventHandler 's stage.
5. Finally, stop the agent via stop() or by enqueuing a AdminRequest.Stop

See the demo client and servers in the gov.lbl.dsd.sea.nio.demo package for simple and complex example usage.

Whenever an IOException or EOS (end-of-stream) is encountered as a result of a channel request, the following happens, in that order:

1. A ChannelResponse with the IOException is posted to the observer stage (e.g. a ChannelResponse.Closedor ChannelResponse.Writeor ChannelResponse.Reador ChannelResponse.Connectedor ChannelResponse.Registered, depending on the type of request in use).
2. The agent automatically closes the channel
3. A ChannelResponse.Closedresponse is posted to the observer stage. The response contains the very same exception (unless closing throws yet another exception).

Hence, most applications can ignore responses containing IOExceptions, unless it is a ChannelResponse.Closed.

For a nice introduction to java networking, see here and there and also there .

Version:

$Revision: 1.14 $, $Date: 2004/08/17 18:26:54 $

Constructor Summary

NetAgent()
Constructs a new agent with default configuration options; the agent is not yet started.

Method Summary

NetAgent	addConnectAddress(Stage observer, InetSocketAddress address) Tells the agent to start a TCP client connection to the given remote address.
NetAgent	addListenPort(Stage observer, int port) Tells the agent to start listening as a server for TCP connections on the given port.
void	enqueue(Object event) Hand a request event from the gov.lbl.dsd.sea.nio.event package to the agent; the request will be processed the next time the agent thread comes around the select loop.
ByteBufferPool	getReadBufferPool() Returns the buffer pool to be used on reading from the network.
void	setAcceptHostAuthorizer(HostAuthorizer hostAuthorizer) Sets the host authorizer the server uses to allow/deny accepting connections from the network.
void	setReadBufferPool(ByteBufferPool readBufferPool) Sets the buffer pool to be used on reading from the network.
void	setSocketOptions(SocketOpts options) Set the socket options to be used for newly accepted connections as well as client connections (on OP_ACCEPT and OP_CONNECT).
void	start() The main selector loop; Runs the agent selector in the current thread.
void	stop() Cleanly shut the agent down, releasing acquired resources.
String	toDebugString() Returns a summary string representation of the receiver.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NetAgent

public NetAgent()

Constructs a new agent with default configuration options; the agent is not yet started.

Method Detail

addListenPort

public NetAgent addListenPort(Stage observer,
                              int port)
                       throws IOException

Tells the agent to start listening as a server for TCP connections on the given port. To register multiple listen ports, call this method multiple times.

Parameters:

observer - the stage onto which responses to the new server channel should be enqueued (may be null)

port - the port to listen on

Returns:

the agent itself (for method chaining convenience)

Throws:

IOException

addConnectAddress

public NetAgent addConnectAddress(Stage observer,
                                  InetSocketAddress address)
                           throws IOException

Tells the agent to start a TCP client connection to the given remote address. To register multiple connections, call this method multiple times.

Parameters:

observer - the stage onto which responses to the new client channel should be enqueued (may be null)

address - the address to connect to

Returns:

the agent itself (for method chaining convenience)

Throws:

IOException

setAcceptHostAuthorizer

public void setAcceptHostAuthorizer(HostAuthorizer hostAuthorizer)

Sets the host authorizer the server uses to allow/deny accepting connections from the network.

Parameters:

hostAuthorizer - the host authorizer to use.

setReadBufferPool

public void setReadBufferPool(ByteBufferPool readBufferPool)

Sets the buffer pool to be used on reading from the network. Use this method for maximum performance; For casual usage you can safely and entirely ignore ALL buffer pool related concerns.

Parameters:

readBufferPool - the pool to use.

getReadBufferPool

public ByteBufferPool getReadBufferPool()

Returns the buffer pool to be used on reading from the network.

setSocketOptions

public void setSocketOptions(SocketOpts options)

Set the socket options to be used for newly accepted connections as well as client connections (on OP_ACCEPT and OP_CONNECT).

Parameters:

options - the options to be set for the socket.

enqueue

public void enqueue(Object event)

Hand a request event from the gov.lbl.dsd.sea.nio.event package to the agent; the request will be processed the next time the agent thread comes around the select loop.

Parameters:

event - the event to hand to the agent.

start

public void start()

The main selector loop; Runs the agent selector in the current thread.

stop

public void stop()

Cleanly shut the agent down, releasing acquired resources.

toDebugString

public String toDebugString()

Returns a summary string representation of the receiver.