naga
Class NIOService

java.lang.Object
  extended by naga.NIOService

public class NIOService
extends java.lang.Object

This class forms the basis of the NIO handling in Naga.

Common usage is to create a single instance of this service and then run one other the select methods in a loop.

Use openSocket(String, int) to open a socket to a remote server, and openServerSocket(int) to open a server socket locally.

Note that the NIOServerSocket by default opens in a "refuse connections" state. To start accepting players, the socket's acceptor must first be set to accept connections. See documentation for openServerSocket for more details.

Example use:

Using the server socket:

 NIOService service = new NIOService;
 NIOServerSocket serverSocket = service.openServerSocket(1234);
 serverSocket.setConnectionAcceptor(myAcceptor);
 serverSocket.listen(myObserver);
 
Using regular sockets:
 NIOService service = new NIOService;
 NIOSocket socket = service.openSocket("www.google.com", 1234);
 socket.listen(myObserver);
 // Asynchronous write by default:
 socket.write("Some message".getBytes());
 

Author:
Christoffer Lerno

Constructor Summary
NIOService()
          Create a new nio service.
 
Method Summary
 void close()
          Close the entire service.
 java.util.Queue<java.lang.Runnable> getQueue()
          Returns a copy of the internal event queue.
 boolean isOpen()
          Determine if this service is open.
 NIOServerSocket openServerSocket(java.net.InetSocketAddress address, int backlog)
          Open a server socket on the address.
 NIOServerSocket openServerSocket(int port)
          Open a server socket on the given port with the default connection backlog.
 NIOServerSocket openServerSocket(int port, int backlog)
          Open a server socket on the given port.
 NIOSocket openSocket(java.net.InetAddress inetAddress, int port)
          Open a normal socket to the host on the given port returning a NIOSocket.
 NIOSocket openSocket(java.lang.String host, int port)
          Open a normal socket to the host on the given port returning a NIOSocket.
 void queue(java.lang.Runnable event)
          Queues an event on the NIOService queue.
 void selectBlocking()
          Run all waiting NIO requests, blocking indefinitely until at least one request is handled.
 void selectBlocking(long timeout)
          Run all waiting NIO requests, blocking until at least one request is found, or the method has blocked for the time given by the timeout value, whatever comes first.
 void selectNonBlocking()
          Run all waiting NIO requests, returning immediately if no requests are found.
 void wakeup()
          Runs wakeup on the selector, causing any blocking select to be released.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NIOService

public NIOService()
           throws java.io.IOException
Create a new nio service.

Throws:
java.io.IOException - if we failed to open the underlying selector used by the service.
Method Detail

selectBlocking

public void selectBlocking()
                    throws java.io.IOException
Run all waiting NIO requests, blocking indefinitely until at least one request is handled.

Throws:
java.io.IOException - if there is an IO error waiting for requests.
java.nio.channels.ClosedSelectorException - if the underlying selector is closed (in this case, NIOService#isOpen will return false)

selectNonBlocking

public void selectNonBlocking()
                       throws java.io.IOException
Run all waiting NIO requests, returning immediately if no requests are found.

Throws:
java.io.IOException - if there is an IO error waiting for requests.
java.nio.channels.ClosedSelectorException - if the underlying selector is closed. (in this case, NIOService#isOpen will return false)

selectBlocking

public void selectBlocking(long timeout)
                    throws java.io.IOException
Run all waiting NIO requests, blocking until at least one request is found, or the method has blocked for the time given by the timeout value, whatever comes first.

Parameters:
timeout - the maximum time to wait for requests.
Throws:
java.lang.IllegalArgumentException - If the value of the timeout argument is negative.
java.io.IOException - if there is an IO error waiting for requests.
java.nio.channels.ClosedSelectorException - if the underlying selector is closed. (in this case, NIOService#isOpen will return false)

openSocket

public NIOSocket openSocket(java.lang.String host,
                            int port)
                     throws java.io.IOException
Open a normal socket to the host on the given port returning a NIOSocket.

This roughly corresponds to creating a regular socket using new Socket(host, port).

This method is thread-safe.

Parameters:
host - the host we want to connect to.
port - the port to use for the connection.
Returns:
a NIOSocket object for asynchronous communication.
Throws:
java.io.IOException - if registering the new socket failed.

openSocket

public NIOSocket openSocket(java.net.InetAddress inetAddress,
                            int port)
                     throws java.io.IOException
Open a normal socket to the host on the given port returning a NIOSocket.

This roughly corresponds to creating a regular socket using new Socket(inetAddress, port).

This method is thread-safe.

Parameters:
inetAddress - the address we want to connect to.
port - the port to use for the connection.
Returns:
a NIOSocket object for asynchronous communication.
Throws:
java.io.IOException - if registering the new socket failed.

openServerSocket

public NIOServerSocket openServerSocket(int port,
                                        int backlog)
                                 throws java.io.IOException
Open a server socket on the given port.

This roughly corresponds to using new ServerSocket(port, backlog);

This method is thread-safe.

Parameters:
port - the port to open.
backlog - the maximum connection backlog (i.e. connections pending accept)
Returns:
a NIOServerSocket for asynchronous connection to the server socket.
Throws:
java.io.IOException - if registering the socket fails.

openServerSocket

public NIOServerSocket openServerSocket(int port)
                                 throws java.io.IOException
Open a server socket on the given port with the default connection backlog.

This roughly corresponds to using new ServerSocket(port);

This method is thread-safe.

Parameters:
port - the port to open.
Returns:
a NIOServerSocket for asynchronous connection to the server socket.
Throws:
java.io.IOException - if registering the socket fails.

openServerSocket

public NIOServerSocket openServerSocket(java.net.InetSocketAddress address,
                                        int backlog)
                                 throws java.io.IOException
Open a server socket on the address.

This method is thread-safe.

Parameters:
address - the address to open.
backlog - the maximum connection backlog (i.e. connections pending accept)
Returns:
a NIOServerSocket for asynchronous connection to the server socket.
Throws:
java.io.IOException - if registering the socket fails.

close

public void close()
Close the entire service.

This will disconnect all sockets associated with this service.

It is not possible to restart the service once closed.

This method is thread-safe.


isOpen

public boolean isOpen()
Determine if this service is open.

This method is thread-safe.

Returns:
true if the service is open, false otherwise.

queue

public void queue(java.lang.Runnable event)
Queues an event on the NIOService queue.

This method is thread-safe, but should in general not be used by other applications.

Parameters:
event - the event to run on the NIOService-thread.

getQueue

public java.util.Queue<java.lang.Runnable> getQueue()
Returns a copy of the internal event queue.

Returns:
a copy of the internal event queue.

wakeup

public void wakeup()
Runs wakeup on the selector, causing any blocking select to be released.