co.paralleluniverse.fibers.io

Class FiberSocketChannel

java.lang.Object

co.paralleluniverse.fibers.io.FiberSocketChannel

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.nio.channels.ByteChannel, java.nio.channels.Channel, java.nio.channels.GatheringByteChannel, java.nio.channels.NetworkChannel, java.nio.channels.ReadableByteChannel, java.nio.channels.ScatteringByteChannel, java.nio.channels.WritableByteChannel

public abstract class FiberSocketChannel
extends java.lang.Object
implements java.nio.channels.ByteChannel, java.nio.channels.ScatteringByteChannel, java.nio.channels.GatheringByteChannel, java.nio.channels.NetworkChannel

A fiber-blocking version of SocketChannel.

Constructor Summary

Constructors

Constructor and Description
FiberSocketChannel()

Method Summary

Modifier and Type	Method and Description
abstract FiberSocketChannel	bind(java.net.SocketAddress local)
abstract void	close()
abstract void	connect(java.net.SocketAddress remote) Connects this channel.
abstract void	connect(java.net.SocketAddress remote, long timeout, java.util.concurrent.TimeUnit timeUnit) Connects this channel.
abstract java.net.SocketAddress	getLocalAddress()
abstract <T> T	getOption(java.net.SocketOption<T> name)
abstract java.net.SocketAddress	getRemoteAddress() Returns the remote address to which this channel's socket is connected.
abstract boolean	isOpen()
static FiberSocketChannel	open() Opens a socket channel.
static FiberSocketChannel	open(ChannelGroup group) Opens a socket channel.
static FiberSocketChannel	open(ChannelGroup group, java.net.SocketAddress remote) Opens a socket channel and connects it to a remote address.
static FiberSocketChannel	open(java.net.SocketAddress remote) Opens a socket channel and connects it to a remote address.
abstract java.lang.Object	provider() Returns the IO provider that created this channel.
abstract int	read(java.nio.ByteBuffer dst)
abstract long	read(java.nio.ByteBuffer[] dsts)
abstract long	read(java.nio.ByteBuffer[] dsts, int offset, int length)
abstract long	read(java.nio.ByteBuffer[] dsts, int offset, int length, long timeout, java.util.concurrent.TimeUnit unit) Reads a sequence of bytes from this channel into a subsequence of the given buffers.
abstract int	read(java.nio.ByteBuffer dst, long timeout, java.util.concurrent.TimeUnit unit) Reads a sequence of bytes from this channel into the given buffer.
abstract <T> FiberSocketChannel	setOption(java.net.SocketOption<T> name, T value)
abstract FiberSocketChannel	shutdownInput() Shutdown the connection for reading without closing the channel.
abstract FiberSocketChannel	shutdownOutput() Shutdown the connection for writing without closing the channel.
abstract java.util.Set<java.net.SocketOption<?>>	supportedOptions()
abstract int	write(java.nio.ByteBuffer src)
abstract long	write(java.nio.ByteBuffer[] srcs)
abstract long	write(java.nio.ByteBuffer[] srcs, int offset, int length)
abstract long	write(java.nio.ByteBuffer[] srcs, int offset, int length, long timeout, java.util.concurrent.TimeUnit unit) Writes a sequence of bytes to this channel from a subsequence of the given buffers.
abstract int	write(java.nio.ByteBuffer src, long timeout, java.util.concurrent.TimeUnit unit) Writes a sequence of bytes to this channel from the given buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

FiberSocketChannel

public FiberSocketChannel()

Method Detail

open

public static FiberSocketChannel open(ChannelGroup group)
                               throws java.io.IOException,
                                      SuspendExecution

Opens a socket channel.

If the group parameter is null then the resulting channel is 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 socket channel

Throws:

ShutdownChannelGroupException - If the channel group is shutdown

java.io.IOException - If an I/O error occurs

SuspendExecution

open

public static FiberSocketChannel open()
                               throws java.io.IOException,
                                      SuspendExecution

Opens a socket channel. Same as open((AsynchronousChannelGroup) null).

Returns:

A new socket channel

Throws:

java.io.IOException - If an I/O error occurs

SuspendExecution

open

public static FiberSocketChannel open(java.net.SocketAddress remote)
                               throws java.io.IOException,
                                      SuspendExecution

Opens a socket channel and connects it to a remote address.

This convenience method works as if by invoking the open() method, invoking the connect method upon the resulting socket channel, passing it remote, and then returning that channel.

Parameters:

remote - The remote address to which the new channel is to be connected

Returns:

A new socket channel

Throws:

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

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

UnresolvedAddressException - If the given remote address is not fully resolved

UnsupportedAddressTypeException - If the type of the given remote address is not supported

java.lang.SecurityException - If a security manager has been installed and it does not permit access to the given remote endpoint

java.io.IOException - If some other I/O error occurs

SuspendExecution

open

public static FiberSocketChannel open(ChannelGroup group,
                                      java.net.SocketAddress remote)
                               throws java.io.IOException,
                                      SuspendExecution

Opens a socket channel and connects it to a remote address.

This convenience method works as if by invoking the open() method, invoking the connect method upon the resulting socket channel, passing it remote, and then returning that channel.

Parameters:

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

remote - The remote address to which the new channel is to be connected

Returns:

A new socket channel

Throws:

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

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

UnresolvedAddressException - If the given remote address is not fully resolved

UnsupportedAddressTypeException - If the type of the given remote address is not supported

java.lang.SecurityException - If a security manager has been installed and it does not permit access to the given remote endpoint

java.io.IOException - If some other I/O error occurs

SuspendExecution

connect

public abstract void connect(java.net.SocketAddress remote)
                      throws java.io.IOException,
                             SuspendExecution

Connects this channel.

This method initiates an operation to connect this channel. it blocks until the connection is successfully established or connection cannot be established. If the connection cannot be established then the channel is closed.

This method performs exactly the same security checks as the Socket class. That is, if a security manager has been installed then this method verifies that its checkConnect method permits connecting to the address and port number of the given remote endpoint.

Parameters:

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

Throws:

UnresolvedAddressException - If the given remote address is not fully resolved

UnsupportedAddressTypeException - If the type of the given remote address is not supported

AlreadyConnectedException - If this channel is already connected

ConnectionPendingException - If a connection operation is already in progress on this channel

ShutdownChannelGroupException - If the channel group has terminated

java.lang.SecurityException - If a security manager has been installed and it does not permit access to the given remote endpoint

java.io.IOException

SuspendExecution

See Also:

getRemoteAddress()

connect

public abstract void connect(java.net.SocketAddress remote,
                             long timeout,
                             java.util.concurrent.TimeUnit timeUnit)
                      throws java.io.IOException,
                             SuspendExecution,
                             java.util.concurrent.TimeoutException

Connects this channel.

This method initiates an operation to connect this channel. it blocks until the connection is successfully established or connection cannot be established or a timeout occurs while attempting to establish it. If the connection cannot be established then the channel is closed but not so if a timeout occurs (see http://stackoverflow.com/questions/20752756/how-to-set-java-nio-asynchronoussocketchannel-connect-timeout).

This method performs exactly the same security checks as the Socket class. That is, if a security manager has been installed then this method verifies that its checkConnect method permits connecting to the address and port number of the given remote endpoint.

Parameters:

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

timeout - The timeout for the connection attempt

timeUnit - The time unit for the connection attempt timeout

Throws:

UnresolvedAddressException - If the given remote address is not fully resolved

UnsupportedAddressTypeException - If the type of the given remote address is not supported

AlreadyConnectedException - If this channel is already connected

ConnectionPendingException - If a connection operation is already in progress on this channel

ShutdownChannelGroupException - If the channel group has terminated

java.lang.SecurityException - If a security manager has been installed and it does not permit access to the given remote endpoint

java.io.IOException

SuspendExecution

java.util.concurrent.TimeoutException

See Also:

getRemoteAddress()

read

public abstract long read(java.nio.ByteBuffer[] dsts,
                          int offset,
                          int length,
                          long timeout,
                          java.util.concurrent.TimeUnit unit)
                   throws java.io.IOException,
                          SuspendExecution

Reads a sequence of bytes from this channel into a subsequence of the given buffers. This operation, sometimes called a scattering read, is often useful when implementing network protocols that group data into segments consisting of one or more fixed-length headers followed by a variable-length body. This method blocks until the read operation completes or fails. The returned result is the number of bytes read or -1 if no bytes could be read because the channel has reached end-of-stream.

This method initiates a read of up to r bytes from this channel, where r is the total number of bytes remaining in the specified subsequence of the given buffer array, that is,

 dsts[offset].remaining()
     + dsts[offset+1].remaining()
     + ... + dsts[offset+length-1].remaining()

at the moment that the read is attempted.

Suppose that a byte sequence of length n is read, where 0 < n <= r. Up to the first dsts[offset].remaining() bytes of this sequence are transferred into buffer dsts[offset], up to the next dsts[offset+1].remaining() bytes are transferred into buffer dsts[offset+1], and so forth, until the entire byte sequence is transferred into the given buffers. As many bytes as possible are transferred into each buffer, hence the final position of each updated buffer, except the last updated buffer, is guaranteed to be equal to that buffer's limit. The underlying operating system may impose a limit on the number of buffers that may be used in an I/O operation. Where the number of buffers (with bytes remaining), exceeds this limit, then the I/O operation is performed with the maximum number of buffers allowed by the operating system.

If a timeout is specified and the timeout elapses before the operation completes then the method throws exception InterruptedByTimeoutException. Where a timeout occurs, and the implementation cannot guarantee that bytes have not been read, or will not be read from the channel into the given buffers, then further attempts to read from the channel will cause an unspecific runtime exception to be thrown.

Parameters:

dsts - The buffers into which bytes are to be transferred

offset - The offset within the buffer array of the first buffer into which bytes are to be transferred; must be non-negative and no larger than dsts.length

length - The maximum number of buffers to be accessed; must be non-negative and no larger than dsts.length - offset

timeout - The maximum time for the I/O operation to complete

unit - The time unit of the timeout argument

Returns:

the number of bytes read or -1 if no bytes could be read because the channel has reached end-of-stream.

Throws:

java.lang.IndexOutOfBoundsException - If the pre-conditions for the offset and length parameter aren't met

java.lang.IllegalArgumentException - If the buffer is read-only

ReadPendingException - If a read operation is already in progress on this channel

NotYetConnectedException - If this channel is not yet connected

ShutdownChannelGroupException - If the channel group has terminated

java.nio.channels.InterruptedByTimeoutException - If a timeout is specified and the timeout elapses before the operation completes

java.io.IOException

SuspendExecution

read

public abstract int read(java.nio.ByteBuffer dst,
                         long timeout,
                         java.util.concurrent.TimeUnit unit)
                  throws java.io.IOException,
                         SuspendExecution

Reads a sequence of bytes from this channel into the given buffer.

This method reads a sequence of bytes from this channel into the given buffer. The returned result is the number of bytes read or -1 if no bytes could be read because the channel has reached end-of-stream.

If a timeout is specified and the timeout elapses before the method throws InterruptedByTimeoutException. Where a timeout occurs, and the implementation cannot guarantee that bytes have not been read, or will not be read from the channel into the given buffer, then further attempts to read from the channel will cause an unspecific runtime exception to be thrown.

Otherwise this method works in the same manner as the read(ByteBuffer). method.

Parameters:

dst - The buffer into which bytes are to be transferred

timeout - The maximum time for the I/O operation to complete

unit - The time unit of the timeout argument

Returns:

the number of bytes read or -1 if no bytes could be read because the channel has reached end-of-stream.

Throws:

java.lang.IllegalArgumentException - If the buffer is read-only

ReadPendingException - If a read operation is already in progress on this channel

NotYetConnectedException - If this channel is not yet connected

ShutdownChannelGroupException - If the channel group has terminated

java.nio.channels.InterruptedByTimeoutException - If a timeout is specified and the timeout elapses before the operation completes

java.io.IOException

SuspendExecution

write

public abstract long write(java.nio.ByteBuffer[] srcs,
                           int offset,
                           int length,
                           long timeout,
                           java.util.concurrent.TimeUnit unit)
                    throws java.io.IOException,
                           SuspendExecution

Writes a sequence of bytes to this channel from a subsequence of the given buffers. This operation, sometimes called a gathering write, is often useful when implementing network protocols that group data into segments consisting of one or more fixed-length headers followed by a variable-length body. The returned result is the number of bytes written.

This method writes of up to r bytes to this channel, where r is the total number of bytes remaining in the specified subsequence of the given buffer array, that is,

 srcs[offset].remaining()
     + srcs[offset+1].remaining()
     + ... + srcs[offset+length-1].remaining()

at the moment that the write is attempted.

Suppose that a byte sequence of length n is written, where 0 < n <= r. Up to the first srcs[offset].remaining() bytes of this sequence are written from buffer srcs[offset], up to the next srcs[offset+1].remaining() bytes are written from buffer srcs[offset+1], and so forth, until the entire byte sequence is written. As many bytes as possible are written from each buffer, hence the final position of each updated buffer, except the last updated buffer, is guaranteed to be equal to that buffer's limit. The underlying operating system may impose a limit on the number of buffers that may be used in an I/O operation. Where the number of buffers (with bytes remaining), exceeds this limit, then the I/O operation is performed with the maximum number of buffers allowed by the operating system.

If a timeout is specified and the timeout elapses before the operation completes then the method throws the exception InterruptedByTimeoutException. Where a timeout occurs, and the implementation cannot guarantee that bytes have not been written, or will not be written to the channel from the given buffers, then further attempts to write to the channel will cause an unspecific runtime exception to be thrown.

Parameters:

srcs - The buffers from which bytes are to be retrieved

offset - The offset within the buffer array of the first buffer from which bytes are to be retrieved; must be non-negative and no larger than srcs.length

length - The maximum number of buffers to be accessed; must be non-negative and no larger than srcs.length - offset

timeout - The maximum time for the I/O operation to complete

unit - The time unit of the timeout argument

Throws:

java.lang.IndexOutOfBoundsException - If the pre-conditions for the offset and length parameter aren't met

WritePendingException - If a write operation is already in progress on this channel

NotYetConnectedException - If this channel is not yet connected

ShutdownChannelGroupException - If the channel group has terminated

java.nio.channels.InterruptedByTimeoutException - If a timeout is specified and the timeout elapses before the operation completes

java.io.IOException

SuspendExecution

write

public abstract int write(java.nio.ByteBuffer src,
                          long timeout,
                          java.util.concurrent.TimeUnit unit)
                   throws java.io.IOException,
                          SuspendExecution

Writes a sequence of bytes to this channel from the given buffer.

This writes a sequence of bytes to this channel from the given buffer. The returned result is the number of bytes written.

If a timeout is specified and the timeout elapses before the operation completes then the method throws the exception InterruptedByTimeoutException. Where a timeout occurs, and the implementation cannot guarantee that bytes have not been written, or will not be written to the channel from the given buffer, then further attempts to write to the channel will cause an unspecific runtime exception to be thrown.

Otherwise this method works in the same manner as the write(ByteBuffer) method.

Parameters:

src - The buffer from which bytes are to be retrieved

timeout - The maximum time for the I/O operation to complete

unit - The time unit of the timeout argument

Throws:

WritePendingException - If a write operation is already in progress on this channel

NotYetConnectedException - If this channel is not yet connected

ShutdownChannelGroupException - If the channel group has terminated

java.nio.channels.InterruptedByTimeoutException - If a timeout is specified and the timeout elapses before the operation completes

java.io.IOException

SuspendExecution

read

@Suspendable
public abstract long read(java.nio.ByteBuffer[] dsts,
                                       int offset,
                                       int length)
                                throws java.io.IOException

Specified by:

read in interface java.nio.channels.ScatteringByteChannel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.io.IOException

read

@Suspendable
public abstract long read(java.nio.ByteBuffer[] dsts)
                                throws java.io.IOException

Specified by:

read in interface java.nio.channels.ScatteringByteChannel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.io.IOException

read

@Suspendable
public abstract int read(java.nio.ByteBuffer dst)
                               throws java.io.IOException

Specified by:

read in interface java.nio.channels.ReadableByteChannel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.io.IOException

write

@Suspendable
public abstract long write(java.nio.ByteBuffer[] srcs,
                                        int offset,
                                        int length)
                                 throws java.io.IOException

Specified by:

write in interface java.nio.channels.GatheringByteChannel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.io.IOException

write

@Suspendable
public abstract long write(java.nio.ByteBuffer[] srcs)
                                 throws java.io.IOException

Specified by:

write in interface java.nio.channels.GatheringByteChannel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.io.IOException

write

@Suspendable
public abstract int write(java.nio.ByteBuffer src)
                                throws java.io.IOException

Specified by:

write in interface java.nio.channels.WritableByteChannel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.io.IOException

isOpen

public abstract boolean isOpen()

Specified by:

isOpen in interface java.nio.channels.Channel

close

public abstract void close()
                    throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.nio.channels.Channel

Throws:

java.io.IOException

shutdownInput

public abstract FiberSocketChannel shutdownInput()
                                          throws java.io.IOException

Shutdown the connection for reading without closing the channel.

Once shutdown for reading then further reads on the channel will return -1, the end-of-stream indication. If the input side of the connection is already shutdown then invoking this method has no effect. The effect on an outstanding read operation is system dependent and therefore not specified. The effect, if any, when there is data in the socket receive buffer that has not been read, or data arrives subsequently, is also system dependent.

Returns:

The channel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.nio.channels.ClosedChannelException - If this channel is closed

java.io.IOException - If some other I/O error occurs

shutdownOutput

public abstract FiberSocketChannel shutdownOutput()
                                           throws java.io.IOException

Shutdown the connection for writing without closing the channel.

Once shutdown for writing then further attempts to write to the channel will throw ClosedChannelException. If the output side of the connection is already shutdown then invoking this method has no effect. The effect on an outstanding write operation is system dependent and therefore not specified.

Returns:

The channel

Throws:

NotYetConnectedException - If this channel is not yet connected

java.nio.channels.ClosedChannelException - If this channel is closed

java.io.IOException - If some other I/O error occurs

getRemoteAddress

public abstract java.net.SocketAddress getRemoteAddress()
                                                 throws java.io.IOException

Returns the remote address to which this channel's socket is connected.

Where the channel is bound and connected to an Internet Protocol socket address then the return value from this method is of type InetSocketAddress.

Returns:

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

Throws:

java.nio.channels.ClosedChannelException - If the channel is closed

java.io.IOException - If an I/O error occurs

bind

public abstract FiberSocketChannel bind(java.net.SocketAddress local)
                                 throws java.io.IOException

Specified by:

bind in interface java.nio.channels.NetworkChannel

Throws:

ConnectionPendingException - If a connection operation is already in progress on this channel

AlreadyBoundException

UnsupportedAddressTypeException

java.nio.channels.ClosedChannelException

java.io.IOException

setOption

public abstract <T> FiberSocketChannel setOption(java.net.SocketOption<T> name,
                                                 T value)
                                          throws java.io.IOException

Specified by:

setOption in interface java.nio.channels.NetworkChannel

Throws:

java.lang.IllegalArgumentException

java.nio.channels.ClosedChannelException

java.io.IOException

getLocalAddress

public abstract java.net.SocketAddress getLocalAddress()
                                                throws java.io.IOException

Specified by:

getLocalAddress in interface java.nio.channels.NetworkChannel

Throws:

java.io.IOException

getOption

public abstract <T> T getOption(java.net.SocketOption<T> name)
                         throws java.io.IOException

Specified by:

getOption in interface java.nio.channels.NetworkChannel

Throws:

java.io.IOException

supportedOptions

public abstract java.util.Set<java.net.SocketOption<?>> supportedOptions()

Specified by:

supportedOptions in interface java.nio.channels.NetworkChannel

provider

public abstract java.lang.Object provider()

Returns the IO provider that created this channel. The type of the returned value is implementation dependent, and may be null.