gov.lbl.dsd.sea.nio
Class Peer

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

Direct Known Subclasses:

SingleClient, SingleEchoServer, SinglePingPongBench, SingleTimeServer

public class Peer

extends Object

Efficient and scalable NIO based non-blocking single-threaded network peer 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 peer
2. Configure it via setters and getters. Convenience methods simplify starting outgoing client connections and listening on ports for incoming connections.
3. Start the peer 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 peer. The peer will process the requests and enqueue responses to the requests onto the asynchronous observer stage of the given network channel (connection), for example an AsyncPeerHandler's stage.
5. Finally, stop the peer 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.

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

Version:

$Revision: 1.41 $, $Date: 2004/06/02 00:41:22 $

Constructor Summary

Peer()
Constructs a new peer; the peer is not yet started.

Method Summary

Peer	addConnectAddress(Stage observer, InetSocketAddress address) Tells the peer to start a TCP client connection to the given remote address.
Peer	addListenPort(Stage observer, int port) Tells the peer 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 peer; the request will be processed the next time the peer thread comes around the select loop.
boolean	getAutoClose() Returns the channel closing policy.
BufferPool	getReadBufferPool() Returns the buffer pool to be used on reading from the network.
void	setAutoClose(boolean autoClose) Sets the channel closing policy to be applied when IOExceptions are thrown.
void	setFailFast(boolean failFast) Sets the policy to be applied when IOExceptions are thrown.
void	setReadBufferPool(BufferPool 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 peer selector in the current thread.
void	stop() Cleanly shut the peer 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

Peer

public Peer()

Constructs a new peer; the peer is not yet started.

Method Detail

addListenPort

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

Tells the peer 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 peer itself (for method chaining convenience)

Throws:

IOException

addConnectAddress

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

Tells the peer 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 peer itself (for method chaining convenience)

Throws:

IOException

setFailFast

public void setFailFast(boolean failFast)

Sets the policy to be applied when IOExceptions are thrown. true throws an exception in the peer thread, whereas false logs and forwards the exception to the observer (if possible), in the hope that we can continue functioning, possibly after corrective actions taken by the observer (such as sending a ChannelRequest.Close).

Parameters:

failFast - the policiy to use

setAutoClose

public void setAutoClose(boolean autoClose)

Sets the channel closing policy to be applied when IOExceptions are thrown.

When autoClose==true the peer automatically closes a channel whenever an IOException or EOS (end-of-stream) is encountered, and enqueues a ChannelResponse.Closed response to the observer (subject to the failFast mode).

When autoClose==false the peer does not close the channel, and leaves it up to the user to appropriately react to the exception (e.g. by issueing a ChannelRequest.Close).

In ANY case, a ChannelResponse with the IOException is first posted to the observer (e.g. a ChannelResponse.Closedor ChannelResponse.Writeor ChannelResponse.Reador ChannelResponse.Connectedor ChannelResponse.Registered). If autoClose==true this is followed by a by a ChannelResponse.Closedresponse containing the very same exception (unless closing throws yet another exception). (Again, all subject to the failFast mode).

Most applications using autoClose==true can therefore ignore responses containing exceptions, unless it is a ChannelResponse.Closed.

Parameters:

autoClose - the policiy to use

getAutoClose

public boolean getAutoClose()

Returns the channel closing policy.

setReadBufferPool

public void setReadBufferPool(BufferPool 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 BufferPool 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 peer; the request will be processed the next time the peer thread comes around the select loop.

Parameters:

event - the event to hand to the peer.

start

public void start()

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

stop

public void stop()

Cleanly shut the peer down, releasing acquired resources.

toDebugString

public String toDebugString()

Returns a summary string representation of the receiver.