com.sun.sgs.impl.nio
Class AsyncDatagramChannelImpl

java.lang.Object
  com.sun.sgs.nio.channels.AsynchronousChannel
      com.sun.sgs.nio.channels.AsynchronousDatagramChannel
          com.sun.sgs.impl.nio.AsyncDatagramChannelImpl

All Implemented Interfaces:

AsynchronousByteChannel, MulticastChannel, NetworkChannel, Closeable, Channel

 class AsyncDatagramChannelImpl
extends AsynchronousDatagramChannel

An implementation of AsynchronousDatagramChannel. Most interesting methods are delegated to the AsyncKey returned by this channel's channel group.

Also implements the creation and management of multicast MembershipKeys for this channel.

Nested Class Summary

(package private) class

AsyncDatagramChannelImpl.MembershipKeyImpl A simple multicast membership key for datagram channels.

Field Summary

(package private) DatagramChannel	channel The underlying DatagramChannel.
(package private) AtomicBoolean	connectionPending Indicates whether a connect operation is pending on this channel.
(package private) static ProtocolFamily	DEFAULT_PROTOCOL_FAMILY The default protocol family if none is specified: StandardProtocolFamily.INET
(package private) AsyncKey	key The AsyncKey for the underlying channel.
(package private) ConcurrentHashMap<AsyncDatagramChannelImpl.MembershipKeyImpl,AsyncDatagramChannelImpl.MembershipKeyImpl>	mcastKeys The set of multicast membership keys for this channel.
(package private) ProtocolFamily	protocolFamily The ProtocolFamily for this channel.

Constructor Summary

AsyncDatagramChannelImpl(ProtocolFamily pf, AsyncGroupImpl group)
Creates a new instance registered with the given channel group.

Method Summary

AsynchronousDatagramChannel	bind(SocketAddress local) Binds the channel's socket to a local address.
void	close() Closes this channel.
<A> IoFuture<Void,A>	connect(SocketAddress remote, A attachment, CompletionHandler<Void,? super A> handler) Connects this channel.
<A> IoFuture<Void,A>	disconnect(A attachment, CompletionHandler<Void,? super A> handler) Disconnects this channel.
SocketAddress	getConnectedAddress() Returns the remote address to which this channel is connected, or null if the channel is not connected.
SocketAddress	getLocalAddress() Returns the socket address that this channel's socket is bound to, or null if the socket is not bound.
Object	getOption(SocketOption name) Returns the value of a socket option.
boolean	isOpen()
boolean	isReadPending() Tells whether or not a read is pending for this channel.
boolean	isWritePending() Tells whether or not a write is pending for this channel.
MembershipKey	join(InetAddress group, NetworkInterface interf) Joins a multicast group to begin receiving all datagrams sent to the group, returning a membership key.
MembershipKey	join(InetAddress group, NetworkInterface interf, InetAddress source) Joins a multicast group to begin receiving datagrams sent to the group from a given source address.
Set<SocketOption>	options() Returns a set of the socket options supported by this channel.
<A> IoFuture<Integer,A>	read(ByteBuffer dst, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Receives a datagram via this channel.
<A> IoFuture<SocketAddress,A>	receive(ByteBuffer dst, long timeout, TimeUnit unit, A attachment, CompletionHandler<SocketAddress,? super A> handler) Receives a datagram via this channel.
<A> IoFuture<Integer,A>	send(ByteBuffer src, SocketAddress target, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Sends a datagram via this channel.
AsyncDatagramChannelImpl	setOption(SocketOption name, Object value) Sets the value of a socket option.
String	toString()
<A> IoFuture<Integer,A>	write(ByteBuffer src, long timeout, TimeUnit unit, A attachment, CompletionHandler<Integer,? super A> handler) Writes a datagram to this channel.

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

connect, disconnect, open, open, read, read, receive, receive, send, send, write, write

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

provider

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_PROTOCOL_FAMILY

static final ProtocolFamily DEFAULT_PROTOCOL_FAMILY

The default protocol family if none is specified: StandardProtocolFamily.INET

channel

final DatagramChannel channel

The underlying DatagramChannel.

key

final AsyncKey key

The AsyncKey for the underlying channel.

protocolFamily

final ProtocolFamily protocolFamily

The ProtocolFamily for this channel.

mcastKeys

final ConcurrentHashMap<AsyncDatagramChannelImpl.MembershipKeyImpl,AsyncDatagramChannelImpl.MembershipKeyImpl> mcastKeys

The set of multicast membership keys for this channel.

connectionPending

final AtomicBoolean connectionPending

Indicates whether a connect operation is pending on this channel.

Constructor Detail

AsyncDatagramChannelImpl

AsyncDatagramChannelImpl(ProtocolFamily pf,
                         AsyncGroupImpl group)
                   throws IOException

Creates a new instance registered with the given channel group. If this channel is used for multicast, the protocol family should be specified to match that of the multicast group. If null is specified as the protocol family, the default family is used.

Parameters:

group - the channel group

pf - the protocol family, or null for the default protocol family

Throws:

IOException - if an I/O error occurs

Method Detail

toString

public String toString()

Overrides:

toString in class Object

isOpen

public boolean isOpen()

close

public void close()
           throws IOException

Closes this channel.

Any outstanding asynchronous operations upon this channel will complete by throwing ExecutionException with cause AsynchronousCloseException.

This method otherwise behaves exactly as specified by the Channel interface.

Specified by:

close in interface Closeable

Specified by:

close in interface Channel

Specified by:

close in class AsynchronousChannel

Throws:

IOException - if an I/O error occurs

bind

public AsynchronousDatagramChannel bind(SocketAddress local)
                                 throws IOException

Binds the channel's socket to a local address.

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 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 will be bound to an address that is assigned automatically.

An implementation of this interface should specify if a permission is required when a security manager is installed.

This method performs exactly the same security checks as the bind method of the DatagramSocket class. That is, if a security manager has been installed then this method verifies that its checkListen method permits waiting for a connection request on the specified local port number.

Specified by:

bind in interface NetworkChannel

Specified by:

bind in class AsynchronousDatagramChannel

Parameters:

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

Returns:

this channel

Throws:

SecurityException - if a security manager exists and its checkListen method doesn't allow the operation.

ClosedChannelException - if the channel is closed

IOException - if some other I/O error occurs

getLocalAddress

public SocketAddress getLocalAddress()
                              throws IOException

Returns the socket address that this channel's socket is bound to, or null if the socket is not bound.

Returns:

the socket address that the socket is bound to, or null if the channel is not open or the channel's socket is not bound

Throws:

IOException - if an I/O error occurs

setOption

public AsyncDatagramChannelImpl 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

Specified by:

setOption in class AsynchronousDatagramChannel

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

getOption

public Object getOption(SocketOption name)
                 throws IOException

Returns the value of a socket option.

The return type is specific to the socket option and null may be a valid value for some socket options.

Parameters:

name - the socket option

Returns:

the value of the socket option

Throws:

ClosedChannelException - if this channel is closed

IOException - if an I/O error occurs

See Also:

SocketOption

options

public Set<SocketOption> options()

Returns a set of the socket options supported by this channel.

This method will continue to return the set of options even after the channel has been closed.

Returns:

a set of the socket options supported by this channel

join

public MembershipKey join(InetAddress group,
                          NetworkInterface interf)
                   throws IOException

Joins a multicast group to begin receiving all datagrams sent to the group, returning a membership key.

If this channel is currently a member of the group on the given interface to receive all datagrams then the membership key, representing that membership, is returned. Otherwise this channel joins the group and the resulting new membership key is returned. The resulting membership key is not source-specific.

A multicast channel may join several multicast groups, including the same group on more than one interface. An implementation may impose a limit on the number of groups that may be joined at the same time.

Parameters:

group - the multicast address to join

interf - the network interface on which to join the group

Returns:

the membership key

Throws:

ClosedChannelException - if this channel is closed

IOException - if an I/O error occurs

join

public MembershipKey join(InetAddress group,
                          NetworkInterface interf,
                          InetAddress source)
                   throws IOException

Joins a multicast group to begin receiving datagrams sent to the group from a given source address.

If this channel is currently a member of the group on the given interface to receive datagrams from the given source address then the membership key, representing that membership, is returned. Otherwise this channel joins the group and the resulting new membership key is returned. The resulting membership key is source-specific.

Membership is accumulative and this method may be invoked again with the same group and interface to allow receiving datagrams sent by other source addresses to the group. This method fails, by throwing IllegalStateException, if the channel is currently a member to receive all datagrams sent to the group on the interface.

This implementation always throws UnsupportedOperationException.

Parameters:

group - the multicast address to join

interf - the network interface on which to join the group

source - the source address

Returns:

the membership key

Throws:

ClosedChannelException - if this channel is closed

IOException - if an I/O error occurs

getConnectedAddress

public SocketAddress getConnectedAddress()
                                  throws IOException

Returns the remote address to which this channel is connected, or null if the channel is not connected.

Specified by:

getConnectedAddress in class AsynchronousDatagramChannel

Returns:

the remote address; null if the channel is not open or the channel's socket is not connected

Throws:

IOException - if an I/O error occurs

connect

public <A> IoFuture<Void,A> connect(SocketAddress remote,
                                    A attachment,
                                    CompletionHandler<Void,? super A> handler)

Connects this channel.

This method initiates an operation to configure the channel so that it only receives datagrams from, and sends datagrams to, the given remote peer address. Once connected, datagrams may not be received from or sent to any other address. The channel remains connected until it is disconnected or until it is closed. This method returns an IoFuture representing the pending result of the operation. The get method returns null upon successful completion.

This method performs exactly the same security checks as the connect method of the DatagramSocket class. That is, if a security manager has been installed then this method verifies that its checkAccept and checkConnect methods permit datagrams to be received from and sent to, respectively, the given remote address.

This method may be invoked at any time and may thus affect read or write operations that are already in progress at the moment that the socket is connected.

Specified by:

connect in class AsynchronousDatagramChannel

Type Parameters:

A - the attachment type

Parameters:

remote - the remote address to which this channel is to be connected

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

disconnect

public <A> IoFuture<Void,A> disconnect(A attachment,
                                       CompletionHandler<Void,? super A> handler)

Disconnects this channel.

This method initiates an operation to configure the channel so that it can receive datagrams from, and sends datagrams to, any remote address so long as the security manager, if installed, permits it. This method returns an IoFuture representing the pending result of the operation. The get method returns null upon successful completion.

This method may be invoked at any time and may thus affect read or write operations that are already in progress at the moment that the socket is disconnected.

If this channel's is not connected then the operation completes succesfully (meaning that the completion handler is invoked, and the IoFuture's get method returns null).

Specified by:

disconnect in class AsynchronousDatagramChannel

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

isReadPending

public boolean isReadPending()

Tells whether or not a read 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 purposes of coordination.

Specified by:

isReadPending in class AsynchronousDatagramChannel

Returns:

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

See Also:

ReadPendingException

isWritePending

public boolean isWritePending()

Tells whether or not a write 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 purposes of coordination.

Specified by:

isWritePending in class AsynchronousDatagramChannel

Returns:

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

See Also:

WritePendingException

receive

public <A> IoFuture<SocketAddress,A> receive(ByteBuffer dst,
                                             long timeout,
                                             TimeUnit unit,
                                             A attachment,
                                             CompletionHandler<SocketAddress,? super A> handler)

Receives a datagram via this channel.

This method initiates the receiving of a datagram, returning an IoFuture representing the pending result of the operation. The IoFuture's get method returns the source address of the datagram upon successful completion.

The datagram is transferred into the given byte buffer starting at its current position, as if by a regular read operation. If there are fewer bytes remaining in the buffer than are required to hold the datagram then the remainder of the datagram is silently discarded.

When a security manager has been installed and the channel is not connected, then it verifies that the source's address and port number 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. The overhead of this security check can be avoided by first connecting the socket via the connect method.

Specified by:

receive in class AsynchronousDatagramChannel

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which the datagram is to be transferred

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

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

send

public <A> IoFuture<Integer,A> send(ByteBuffer src,
                                    SocketAddress target,
                                    long timeout,
                                    TimeUnit unit,
                                    A attachment,
                                    CompletionHandler<Integer,? super A> handler)

Sends a datagram via this channel.

This method initiates sending of a datagram, returning an IoFuture representing the pending result of the operation. The operation sends the remaining bytes in the given buffer as a single datagram to the given target address. The result of the operation, obtained by invoking the IoFuture's get method, is the number of bytes sent. The number of bytes sent is either the number of bytes that were remaining in the buffer or zero if there was insufficient room for the datagram in the underlying output buffer.

The datagram is transferred from the byte buffer as if by a regular write operation.

If there is a security manager installed and the the channel is not connected then this method verifies that the target address and port number are permitted by the security manager's checkConnect method. The overhead of this security check can be avoided by first connecting the socket via the connect method.

Specified by:

send in class AsynchronousDatagramChannel

Type Parameters:

A - the attachment type

Parameters:

src - the buffer containing the datagram to be sent

target - the address to which the datagram is to be sent

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

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

read

public <A> IoFuture<Integer,A> read(ByteBuffer dst,
                                    long timeout,
                                    TimeUnit unit,
                                    A attachment,
                                    CompletionHandler<Integer,? super A> handler)

Receives a datagram via this channel.

This method initiates the receiving of a datagram, returning an IoFuture representing the pending result of the operation. The IoFuture's get method returns the the number of bytes transferred upon successful completion.

This method may only be invoked if this channel is connected, and it only accepts datagrams from the peer that the channel is connected too. The datagram is transferred into the given byte buffer starting at its current position and exactly as specified in the AsynchronousByteChannel interface. If there are fewer bytes remaining in the buffer than are required to hold the datagram then the remainder of the datagram is silently discarded.

Specified by:

read in class AsynchronousDatagramChannel

Type Parameters:

A - the attachment type

Parameters:

dst - the buffer into which the datagram is to be transferred

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

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

write

public <A> IoFuture<Integer,A> write(ByteBuffer src,
                                     long timeout,
                                     TimeUnit unit,
                                     A attachment,
                                     CompletionHandler<Integer,? super A> handler)

Writes a datagram to this channel.

This method initiates sending of a datagram, returning an IoFuture representing the pending result of the operation. The operation sends the remaining bytes in the given buffer as a single datagram. The result of the operation, obtained by invoking the IoFuture's get method, is the number of bytes sent. The number of bytes sent is either the number of bytes that were remaining in the buffer or zero if there was insufficient room for the datagram in the underlying output buffer.

The datagram is transferred from the byte buffer as if by a regular write operation.

This method may only be invoked if this channel is connected, in which case it sends datagrams directly to the socket's peer. Otherwise it behaves exactly as specified in the AsynchronousByteChannel interface.

Specified by:

write in class AsynchronousDatagramChannel

Type Parameters:

A - the attachment type

Parameters:

src - the buffer containing the datagram to be sent

timeout - the timeout, or 0L for no timeout

unit - the time unit of the timeout argument

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