gov.lbl.dsd.sea.nio.util
Class NioUtil

java.lang.Object
  gov.lbl.dsd.sea.nio.util.NioUtil

public class NioUtil

extends Object

Various utilities related to the java.nio package.

Version:

$Revision: 1.8 $, $Date: 2004/08/17 20:17:22 $

Method Summary

static void	addInterestBits(SelectionKey key, int opBits) Adds the given operation bits to the interest set of the given key.
static SocketChannel	createClientChannel(SocketAddress address) Creates and returns a non-blocking TCP client channel bound to the given network address.
static SocketChannel	createClientChannel(String hostName, int port) Creates and returns a non-blocking TCP server channel bound to the given network host and port.
static DatagramChannel	createDatagramChannel(int port) Creates and returns a non-blocking UDP datagram channel bound to the given network port.
static DatagramChannel	createDatagramChannel(SocketAddress address) Creates and returns a non-blocking UDP datagram channel bound to the given network address.
static ServerSocketChannel	createServerChannel(int port) Creates and returns a non-blocking TCP server channel bound to the given network port.
static ServerSocketChannel	createServerChannel(SocketAddress address, int backlog) Creates and returns a non-blocking TCP server channel bound to the given network address.
static int	getNumberOfReadyOps(SelectionKey key) Returns the number of ready operations of the given selection key.
static List	getRegisteredChannels(Selector selector) Returns all selectable channels registered with the given selector, excluding channels of invalid keys.
static boolean	hasMark(Buffer buffer) Returns whether or not a given buffer has the mark defined.
static int	readMany(ReadableByteChannel channel, ByteBuffer buffer) Efficiently reads (without ever blocking) as many bytes as possible from the given non-blocking channel into the given buffer.
static void	removeInterestBits(SelectionKey key, int opBits) Removes the given operation bits from the interest set of the given key.
static String	toString(int selectionKeyOps) Returns a detailed string representation of the given selection key readyOps or interestOps for debugging purposes.
static String	toString(SelectionKey key) Returns a detailed string representation of the given selection key for debugging purposes.
static String	toString(Selector selector) Returns a detailed string representation of the given selector for debugging purposes.
static String	toString(Set keySet) Returns a detailed string representation for debugging purposes.
static int	writeMany(WritableByteChannel channel, ByteBuffer buffer) Efficiently writes (without ever blocking) as many bytes as possible from the given buffer to the given non-blocking channel.

Methods inherited from class java.lang.Object

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

Method Detail

createServerChannel

public static ServerSocketChannel createServerChannel(int port)
                                               throws IOException

Creates and returns a non-blocking TCP server channel bound to the given network port.

Parameters:

port - the port to bind to.

Returns:

the channel

Throws:

IOException - if the bind operation fails, or if the socket is already bound or if some other I/O error occurs

createServerChannel

public static ServerSocketChannel createServerChannel(SocketAddress address,
                                                      int backlog)
                                               throws IOException

Creates and returns a non-blocking TCP server channel bound to the given network address.

If a connection indication arrives when the backlog queue is full, the connection is refused. The backlog argument must be a positive value greater than 0. If the value passed if equal or less than 0, then the default value will be assumed.

Parameters:

address - the address to bind to.

backlog - The listen backlog length.

Returns:

the channel

Throws:

IOException - if the bind operation fails, or if the socket is already bound or if some other I/O error occurs

createClientChannel

public static SocketChannel createClientChannel(String hostName,
                                                int port)
                                         throws IOException

Creates and returns a non-blocking TCP server channel bound to the given network host and port.

Parameters:

hostName - the host to bind to.

port - the port to bind to.

Returns:

the channel

Throws:

IOException - If an I/O error occurs

createClientChannel

public static SocketChannel createClientChannel(SocketAddress address)
                                         throws IOException

Creates and returns a non-blocking TCP client channel bound to the given network address.

Parameters:

address - the address to bind to.

Returns:

the channel

Throws:

IOException - If an I/O error occurs

createDatagramChannel

public static DatagramChannel createDatagramChannel(int port)
                                             throws IOException

Creates and returns a non-blocking UDP datagram channel bound to the given network port.

Parameters:

port - the port to bind to.

Returns:

the channel

Throws:

IOException - If an I/O error occurs

createDatagramChannel

public static DatagramChannel createDatagramChannel(SocketAddress address)
                                             throws IOException

Creates and returns a non-blocking UDP datagram channel bound to the given network address.

Parameters:

address - the address to bind to.

Returns:

the channel

Throws:

IOException - If an I/O error occurs

hasMark

public static boolean hasMark(Buffer buffer)

Returns whether or not a given buffer has the mark defined.

Parameters:

buffer - the buffer to check

Returns:

true if it has a mark

readMany

public static int readMany(ReadableByteChannel channel,
                           ByteBuffer buffer)
                    throws IOException

Efficiently reads (without ever blocking) as many bytes as possible from the given non-blocking channel into the given buffer. Returns the total number of bytes that have been read. The algorithm strongly improves throughput at the expense of somewhat increased latency. This method simply propagates exceptions thrown in the underlying ReadableByteChannel.read(ByteBuffer)NIO code - it never causes an exception itself.

Parameters:

channel - - the channel to read from

buffer - - the buffer to read into

Returns:

the total number of bytes read, possibly zero. If end-of-stream (EOS) is encountered then the number returned is precisely -(total+1). Hence, if EOS is encountered the returned number is always < 0, and else >= 0. In the EOS case, the caller can determine the total number of read bytes with -(readMany(...)+1). (The same trick is used in Arrays.binarySearch(long[], long)to effectively return two return parameters within one parameter).

Example usage:

 
 
 int total = readMany(channel, buffer);
 boolean eos = false;
 if (total < 0) {
 	eos = true;
 	total = -(total + 1);
 }
 
 System.out.println(total + "bytes read");
 
 // some meaningful processing of the read bytes goes here
 
 if (eos) {
 	System.out.println(total + "bytes read, EOS reached, now closing channel");
 	channel.close();
 	System.exit(0);
 }
 
 
 

Throws:

NonReadableChannelException - If this channel was not opened for reading

ClosedChannelException - If this channel is closed

AsynchronousCloseException - If another thread closes this channel while the read operation is in progress

ClosedByInterruptException - If another thread interrupts the current thread while the read operation is in progress, thereby closing the channel and setting the current thread's interrupt status

IOException - If some other I/O error occurs

writeMany

public static int writeMany(WritableByteChannel channel,
                            ByteBuffer buffer)
                     throws IOException

Efficiently writes (without ever blocking) as many bytes as possible from the given buffer to the given non-blocking channel. Returns the total number of bytes that have been written. The algorithm strongly improves throughput at the expense of somewhat increased latency. This method simply propagates exceptions thrown in the underlying WritableByteChannel.write(ByteBuffer)NIO code - it never causes an exception itself.

Parameters:

channel - - the channel to write to

buffer - - the buffer to read from

Returns:

the total number of bytes written, possibly zero.

Throws:

NonWritableChannelException - If this channel was not opened for writing

ClosedChannelException - If this channel is closed

AsynchronousCloseException - If another thread closes this channel while the write operation is in progress

ClosedByInterruptException - If another thread interrupts the current thread while the write operation is in progress, thereby closing the channel and setting the current thread's interrupt status

IOException - If some other I/O error occurs

getRegisteredChannels

public static List getRegisteredChannels(Selector selector)

Returns all selectable channels registered with the given selector, excluding channels of invalid keys.

Parameters:

selector -

Returns:

the channels

getNumberOfReadyOps

public static int getNumberOfReadyOps(SelectionKey key)

Returns the number of ready operations of the given selection key.

Parameters:

key -

Returns:

the number

addInterestBits

public static void addInterestBits(SelectionKey key,
                                   int opBits)

Adds the given operation bits to the interest set of the given key.

Parameters:

key - the selection key to work on.

opBits - the bits to add.

removeInterestBits

public static void removeInterestBits(SelectionKey key,
                                      int opBits)

Removes the given operation bits from the interest set of the given key.

Parameters:

key - the selection key to work on.

opBits - the bits to remove.

toString

public static String toString(SelectionKey key)

Returns a detailed string representation of the given selection key for debugging purposes.

Parameters:

key - the object to represent

Returns:

a string representation

toString

public static String toString(int selectionKeyOps)

Returns a detailed string representation of the given selection key readyOps or interestOps for debugging purposes.

Parameters:

selectionKeyOps - the object to represent

Returns:

a string representation

toString

public static String toString(Set keySet)

Returns a detailed string representation for debugging purposes.

Parameters:

keySet - a selector key set (e.g. selector.keys() or selector.selectedKeys()).

Returns:

a string representation

toString

public static String toString(Selector selector)

Returns a detailed string representation of the given selector for debugging purposes.

Parameters:

selector - the object to represent

Returns:

a string representation