com.internationalnetwork.net
Class ServerSockets

Object
  extended by com.internationalnetwork.net.ServerSockets

public class ServerSockets
extends Object

ServerSockets (plural) has many similarities to the java.net.ServerSocket (singular) class, but it also facilitates binding to multiple endpoints and provides a simple way to accept() inbound connections simulatenously without resorting to inefficient CPU/resource-intensive approaches such as polling or creating an additional thread per binding, etc., each of which have not been found to scale very well.

Example

ServerSockets sS = new ServerSockets("127.0.0.1 port=49152");
SocketChannel sC = sS.accept();
Socket s = sC.socket();
// Deal with I/O with client here
s.close();
sC.close();

Socket v. SocketChannel notes

The methods that return SocketChannel class objects are providing you with access to an important method so that you can avoid memory leaks which result from closing the socket but not the socket channel.  After calling the Socket.close() method, the SocketChannel resources won't be freed by the garbage collector until you call the SocketChannel.close() method.

The SocketChannel.socket() method provides the Socket object you'll need for communicating with your client.

Make sure you call the SocketChannel.close() method only after calling the Socket.close() method to prevent unexpected and intermittent problems on certain Operating Systems.


Field Summary
static String VERSION
          Version number of this Package (read-only).
 
Constructor Summary
ServerSockets()
          Creates a new ServerSockets object, without any addresses bound to it.
ServerSockets(java.net.SocketAddress... endpoints)
          Creates a ServerSockets object, and binds all optionally specified IP addresses to it.
ServerSockets(String... addresses)
          Creates a ServerSockets object, and binds all optionally specified IP addresses to it.
 
Method Summary
 java.nio.channels.SocketChannel accept()
          Listens for a connection to be made on any of the sockets, accepts one connection, and returns the Socket associated with it.
 java.nio.channels.SocketChannel accept(int timeout)
          Listens for a connection to be made on any of the sockets, accepts one connection, and returns the Socket associated with it.
 java.nio.channels.SocketChannel[] acceptMultiple()
          Listens for connections to be made on any of the sockets, and returns a Socket[] array.
 java.nio.channels.SocketChannel[] acceptMultiple(int maximumSockets)
          Listens for connections to be made on any of the sockets, accepts up to the specified number of connections, and returns a Socket[] array.
 java.nio.channels.SocketChannel[] acceptMultiple(int maximumSockets, int timeout)
          Listens for connections to be made on any of the sockets, accepts up to the specified number of connections, and returns a Socket[] array.
 void bind(java.net.SocketAddress... endpoints)
          Binds to any number of endpoints.
 void bind(java.net.SocketAddress endpoint, int backlog)
          Binds to one endpoint using a specific backlog limit.
 void bind(String... addresses)
          Binds to any number of endpoints.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
Version number of this Package (read-only).

See Also:
Constant Field Values
Constructor Detail

ServerSockets

public ServerSockets()
              throws java.io.IOException
Creates a new ServerSockets object, without any addresses bound to it.

Throws:
java.io.IOException - if an I/O error occurs when initializing the socket

ServerSockets

public ServerSockets(java.net.SocketAddress... endpoints)
              throws java.net.BindException,
                     java.io.IOException
Creates a ServerSockets object, and binds all optionally specified IP addresses to it.

Usually java.net.InetSocketAddress is the easiest class to work with when creating a socket address, and can be used in place of SocketAddress.

Parameters:
endpoints - See the documentation for bind() for complete details
Throws:
java.net.BindException - if the binding fails (usually when the IP address is not available for binding)
java.io.IOException - if an I/O error occurs when opening or binding the socket

ServerSockets

public ServerSockets(String... addresses)
              throws java.io.IOException
Creates a ServerSockets object, and binds all optionally specified IP addresses to it.

Parameters:
addresses - See the documentation for bind() for complete details
Throws:
java.io.IOException - if an I/O error occurs when opening the socket
IndexOutOfBoundsException - if the port number is out of range
NumberFormatException - if the port number or the backlog number is not a valid number
UnsupportedOperationException - the IP address or the port number is missing or empty (the backlog parameter is optional)
Method Detail

accept

public java.nio.channels.SocketChannel accept()
                                       throws java.io.IOException
Listens for a connection to be made on any of the sockets, accepts one connection, and returns the Socket associated with it.

Returns:
The new SocketChannel
Throws:
java.io.IOException - if an I/O error occurs when opening the socket or if something goes wrong (such as the OS losing its IP address, which should never happen)

accept

public java.nio.channels.SocketChannel accept(int timeout)
                                       throws java.io.IOException
Listens for a connection to be made on any of the sockets, accepts one connection, and returns the Socket associated with it.

Parameters:
timeout - If positive, block for up to specified number of milliseconds, more or less, while waiting for an inbound connection. If zero, block indefinitely. Must not be a negative value.
Returns:
The new SocketChannel, or null if a timeout occurred
Throws:
java.io.IOException - if an I/O error occurs when opening the socket

acceptMultiple

public java.nio.channels.SocketChannel[] acceptMultiple()
                                                 throws java.io.IOException
Listens for connections to be made on any of the sockets, and returns a Socket[] array.

By returning multiple sockets, the caller can more efficiently handle them sequentially in a loop while also minimizing repeated calls to this method, thus consuming fewer CPU cycles to reduce some system overhead. Smaller loops may also perform better on newer processors due to advanced features such as caching and branch prediction.

The number of accepted Socket connections returned will probably be less than the maximum number specified in most situations since the priority is to ensure faster response time for clients. For this reason, one should take a great deal of care in choosing this maximum limit.

Returns:
SocketChannel[] (will never be null)
Throws:
java.io.IOException - if an I/O error occurs when opening the socket

acceptMultiple

public java.nio.channels.SocketChannel[] acceptMultiple(int maximumSockets)
                                                 throws java.io.IOException
Listens for connections to be made on any of the sockets, accepts up to the specified number of connections, and returns a Socket[] array.

By returning multiple sockets, the caller can more efficiently handle them sequentially in a loop while also minimizing repeated calls to this method, thus consuming fewer CPU cycles to reduce some system overhead. Smaller loops may also perform better on newer processors due to advanced features such as caching and branch prediction.

The number of accepted Socket connections returned will probably be less than the maximum number specified in most situations since the priority is to ensure faster response time for clients. For this reason, one should take a great deal of care in choosing this maximum limit.

Parameters:
maximumSockets - The maximum number of Socket connections to accept, or to accept an unlimited number just specify 0
Returns:
SocketChannel[] (will never be null)
Throws:
java.io.IOException - if an I/O error occurs when opening the socket

acceptMultiple

public java.nio.channels.SocketChannel[] acceptMultiple(int maximumSockets,
                                                        int timeout)
                                                 throws java.io.IOException
Listens for connections to be made on any of the sockets, accepts up to the specified number of connections, and returns a Socket[] array.

By returning multiple sockets, the caller can more efficiently handle them sequentially in a loop while also minimizing repeated calls to this method, thus consuming fewer CPU cycles to reduce some system overhead. Smaller loops may also perform better on newer processors due to advanced features such as caching and branch prediction.

The number of accepted Socket connections returned will probably be less than the maximum number specified in most situations since the priority is to ensure faster response time for clients. For this reason, one should take a great deal of care in choosing this maximum limit.

Parameters:
maximumSockets - The maximum number of Socket connections to accept, or to accept an unlimited number just specify 0
timeout - If positive, block for up to specified number of milliseconds, more or less, while waiting for an inbound connection. If zero, block indefinitely. Must not be a negative value.
Returns:
SocketChannel[] (will never be null)
Throws:
java.io.IOException - if an I/O error occurs when opening the socket

bind

public void bind(java.net.SocketAddress... endpoints)
          throws java.net.BindException,
                 java.io.IOException
Binds to any number of endpoints. Successive calls to this method are also permitted.

Usually java.net.InetSocketAddress is the easiest class to work with when creating a socket address, and can be used in place of SocketAddress.

Parameters:
endpoints - One or more IP addresses and TCP port numbers to bind to
Throws:
java.net.BindException - if the binding fails (usually when the IP address is not available for binding)
java.io.IOException - if an I/O error occurs when binding to a socket

bind

public void bind(java.net.SocketAddress endpoint,
                 int backlog)
          throws java.net.BindException,
                 java.io.IOException
Binds to one endpoint using a specific backlog limit.

Usually java.net.InetSocketAddress is the easiest class to work with when creating a socket address, and can be used in place of SocketAddress.

Parameters:
endpoint - The IP address and TCP port number to bind to
backlog - The maximum backlog limit of unprocessed connections (all additional connections will be rejected)
Throws:
java.net.BindException - if the binding fails (usually when the IP address is not available for binding)
java.io.IOException - if an I/O error occurs when binding to a socket

bind

public void bind(String... addresses)
          throws java.net.BindException,
                 java.io.IOException
Binds to any number of endpoints. Each endpoint is specified as one or more Strings (or in a String[] array), in the following format:

"10.88.88.88 port=8 backlog=128"

The first argument is the IPv4 or IPv6 address of the endpoint to bind to.

The remaining case-insensitive arguments can be specified in any order:

In the above example, the String "10.88.88.88 port=8 backlog=128" specifies a binding to an IPv4 address of 10.88.88.88 using TCP port 8 with a maximum backlog limit of 128 unprocessed inbound connections.

Parameters:
addresses - One or more Strings, or a String[] array, each specifying which IP addresses and port numbers to bind to
Throws:
java.net.BindException - if the binding fails (usually when the IP address is not available for binding)
java.io.IOException - if an I/O error occurs when binding to a socket