com.sun.sgs.nio.channels
Class AsynchronousServerSocketChannel

java.lang.Object
  com.sun.sgs.nio.channels.AsynchronousChannel
      com.sun.sgs.nio.channels.AsynchronousServerSocketChannel

All Implemented Interfaces:

NetworkChannel, Closeable, Channel

public abstract class AsynchronousServerSocketChannel
extends AsynchronousChannel
implements NetworkChannel

An asynchronous channel for stream-oriented listening sockets.

An asynchronous server-socket channel is created by invoking the open method of this class. A newly-created asynchronous server-socket channel is open but not yet bound. It can be bound to a local address and configured to listen for connections by invoking the bind method. Once bound, the accept method is used to initiate the accepting of connections to the channel's socket. An attempt to invoke the accept method on an unbound channel will cause a NotYetBoundException to be thrown.

Channels of this type are safe for use by multiple concurrent threads though at most one accept operation can be outstanding at any time. If a thread initiates an accept operation before a previous accept operation has completed then an AcceptPendingException will be thrown. Whether or not an operation is pending may be determined by invoking the isAcceptPending method.

Socket options are configured using the setOption method. Channels of this type support the following options:

Option Name	Description
SO_RCVBUF	The size of the socket receive buffer
SO_REUSEADDR	Re-use address

and may support additional (implementation specific) options. The list of options supported is obtained by invoking the options method.

Usage Example:

   final AsynchronousServerSocketChannel listener = 
       AsynchronousServerSocketChannel.open().bind(
           new InetSocketAddress(5000));
 
   listener.accept(
     new CompletionHandler<AsynchronousSocketChannel,Void>() {
       public void completed(IoFuture<AsynchronousSocketChannel,Void> 
                             result) 
       {
           try {
               AsynchronousSocketChannel ch = result.getNow();
               :
           } catch (ExecutionException x) { .. } 
 
           // accept the next connection
           listener.accept(this);
       }
   });
 

Method Summary

abstract <A> IoFuture<AsynchronousSocketChannel,A>	accept(A attachment, CompletionHandler<AsynchronousSocketChannel,? super A> handler) Accepts a connection.
<A> IoFuture<AsynchronousSocketChannel,A>	accept(CompletionHandler<AsynchronousSocketChannel,? super A> handler) Accepts a connection.
AsynchronousServerSocketChannel	bind(SocketAddress local) Binds the channel's socket to a local address and configures the socket to listen for connections.
abstract AsynchronousServerSocketChannel	bind(SocketAddress local, int backlog) Binds the channel's socket to a local address and configures the socket to listen for connections.
abstract boolean	isAcceptPending() Tells whether or not an accept is pending for this channel.
static AsynchronousServerSocketChannel	open() Opens an asynchronous server-socket channel.
static AsynchronousServerSocketChannel	open(AsynchronousChannelGroup group) Opens an asynchronous server-socket channel.
abstract AsynchronousServerSocketChannel	setOption(SocketOption name, Object value) Sets the value of a socket option.

Methods inherited from class com.sun.sgs.nio.channels.AsynchronousChannel

close, provider

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.sun.sgs.nio.channels.NetworkChannel

getLocalAddress, getOption, options

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

open

public static AsynchronousServerSocketChannel open(AsynchronousChannelGroup group)
                                            throws IOException

Opens an asynchronous server-socket channel.

The new channel is created by invoking the openAsynchronousServerSocketChannel method on the AsynchronousChannelProvider object that created the given group. If the group parameter is null then the resulting channel is created by the system-wide default provider, and bound to the default group.

Parameters:

group - the group to which the newly constructed channel should be bound, or null for the default group

Returns:

a new asynchronous server socket channel

Throws:

ShutdownChannelGroupException - the specified group is shutdown

IOException - if an I/O error occurs

open

public static AsynchronousServerSocketChannel open()
                                            throws IOException

Opens an asynchronous server-socket channel.

This method returns an asynchronous server socket channel that is bound to the default group. This method is equivalent to evaluating the expression:

     open((AsynchronousChannelGroup)null);
 

Returns:

a new asynchronous server socket channel

Throws:

IOException - if an I/O error occurs

bind

public final AsynchronousServerSocketChannel bind(SocketAddress local)
                                           throws IOException

Binds the channel's socket to a local address and configures the socket to listen for connections.

This method works as if invoking it were equivalent to evaluating the expression:

         bind(local, 0);
 

Specified by:

bind in interface NetworkChannel

Parameters:

local - the local address to bind the socket, or null to bind to an automatically assigned socket address

Returns:

this channel

Throws:

AlreadyBoundException - if the socket is already bound

UnsupportedAddressTypeException - if the type of the given address is not supported

SecurityException - if a security manager has been installed and its checkListen method denies the operation

ClosedChannelException - if the channel is closed

IOException - if some other I/O error occurs

bind

public abstract AsynchronousServerSocketChannel bind(SocketAddress local,
                                                     int backlog)
                                              throws IOException

Binds the channel's socket to a local address and configures the socket to listen for connections.

This method is used to establish an association between the socket and a local address. Once an association is established then the socket remains bound until the associated channel is closed. An attempt to bind a socket that is already bound throws AlreadyBoundException. If the local parameter has the value null then the socket address is assigned automatically.

The backlog parameter is the maximum number of pending connections on the socket. Its exact semantics are implementation specific. An implementation may impose an implementation specific maximum length or may choose to ignore the parameter. If the backlog parameter has the value 0, or a negative value, then an implementation specific default is used.

Parameters:

local - the local address to bind the socket, or null to bind to an automatically assigned socket address

backlog - the maximum number number of pending connections

Returns:

this channel

Throws:

AlreadyBoundException - if the socket is already bound

UnsupportedAddressTypeException - if the type of the given address is not supported

SecurityException - if a security manager has been installed and its checkListen method denies the operation

ClosedChannelException - if the channel is closed

IOException - if some other I/O error occurs

setOption

public abstract AsynchronousServerSocketChannel setOption(SocketOption name,
                                                          Object value)
                                                   throws IOException

Sets the value of a socket option.

The name parameter is the name of the socket option. The value parameter is the value of the option and is of the type specified by the option. A value of null may be a valid value for some socket options.

Specified by:

setOption in interface NetworkChannel

Parameters:

name - the name of the socket option

value - the value of the socket option

Returns:

this channel

Throws:

ClosedChannelException - if this channel is closed

IOException - if an I/O error occurs

See Also:

SocketOption

accept

public abstract <A> IoFuture<AsynchronousSocketChannel,A> accept(A attachment,
                                                                 CompletionHandler<AsynchronousSocketChannel,? super A> handler)

Accepts a connection.

This method initiates accepting a connection made to this channel's socket, returning an IoFuture representing the pending result of the operation. The IoFuture's get method will return the AsynchronousSocketChannel for the new connection on successful completion.

When a new connection is accepted then the resulting AsynchronousSocketChannel will be bound to the same AsynchronousChannelGroup as this channel.

If a security manager has been installed then it verifies that the address and port number of the connection's remote endpoint are permitted by the security manager's checkAccept method. The permission check is performed with privileges that are restricted by the calling context of this method. If the permission check fails then the operation completes by throwing ExecutionException with cause SecurityException.

Type Parameters:

A - the attachment type

Parameters:

attachment - the object to attach to the returned IoFuture object; can be null

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

AcceptPendingException - if an accept operation is already in progress on this channel

NotYetBoundException - if this channel's socket has not yet been bound

accept

public final <A> IoFuture<AsynchronousSocketChannel,A> accept(CompletionHandler<AsynchronousSocketChannel,? super A> handler)

Accepts a connection.

This method initiates accepting a connection made to this channel's socket, returning an IoFuture representing the pending result of the operation. Its get method will return the AsynchronousSocketChannel for the new connection on successful completion.

This method works as if invoking it were equivalent to evaluating the expression:

     accept((Object)null, handler);
 

When a new connection is accepted then the resulting AsynchronousSocketChannel will be bound to the same AsynchronousChannelGroup as this channel.

Type Parameters:

A - the attachment type

Parameters:

handler - the handler for consuming the result; can be null

Returns:

an IoFuture object representing the pending result

Throws:

ClosedAsynchronousChannelException - if this channel is closed

AcceptPendingException - if an accept operation is already in progress on this channel

NotYetBoundException - if this channel's socket has not yet been bound

isAcceptPending

public abstract boolean isAcceptPending()

Tells whether or not an accept is pending for this channel.

The result of this method is a snapshot of the channel state. It may be invalid when the caller goes to examine the result and should not be used for the purpose of coordination.

Returns:

true if, and only if, an accept is pending for this this channel but has not yet completed.