biz.onixs.util.network

Interface Socket

All Superinterfaces:

AutoCloseable

public interface Socket
extends AutoCloseable

The interface provides methods for configuring sockets and performing IO operations.

Method Summary

Modifier and Type	Method and Description
SocketAddress	getLocalAddress() Returns the local address to which the socket is bound.
SocketAddress	getRemoteAddress() Returns the remote address to which the socket is connected.
boolean	isBlocking() Returns whether every I/O operation on this channel will block until it completes.
int	read(ByteBuffer dst) Reads a sequence of bytes into the given buffer.
void	setBlocking(boolean blocking) Sets whether every I/O operation on this channel will block until it completes.
<T> void	setOption(SocketOption<T> name, T value) Sets the value of the socket option (e.g.
void	setPerformancePreferences(int connectionTime, int latency, int bandwidth) Sets the performance preferences for this socket.
void	waitRead(long timeout, TimeUnit timeUnit) Waits for read I/O operation to be ready.
void	waitWrite(long timeout, TimeUnit timeUnit) Waits for write I/O operation to be ready.
void	wakeupRead() Causes the waitRead(long, TimeUnit) operation that has not yet returned to return immediately.
void	wakeupWrite() Causes the waitWrite(long, TimeUnit) operation that has not yet returned to return immediately.
int	write(ByteBuffer src) Writes a sequence of bytes from the given buffer.

Methods inherited from interface java.lang.AutoCloseable

close

Method Detail

getLocalAddress

SocketAddress getLocalAddress()
                       throws IOException

Returns the local address to which the socket is bound.

Returns:

the local address to which the socket is bound

Throws:

IOException - if an I/O error occurs when getting the local address

getRemoteAddress

SocketAddress getRemoteAddress()
                        throws IOException

Returns the remote address to which the socket is connected.

Returns:

the remote address to which the socket is connected

Throws:

IOException - if an I/O error occurs when getting the remote address

setOption

<T> void setOption(SocketOption<T> name,
                   T value)
            throws IOException

Sets the value of the socket option (e.g. StandardSocketOptions).

Type Parameters:

T - the type of the socket option value

Parameters:

name - the name of the socket option

value - the value of the socket option

Throws:

IOException - if an I/O error occurs when setting the socket option

UnsupportedOperationException - if the socket option is not supported

IllegalArgumentException - if the value is invalid for the socket option

setPerformancePreferences

void setPerformancePreferences(int connectionTime,
                               int latency,
                               int bandwidth)

Sets the performance preferences for this socket.

This method does not have a consistent behavior across different operating systems and platforms.

Parameters:

connectionTime - an int expressing the relative weighting given to a short connection time

latency - an int expressing the relative weighting given to low latency

bandwidth - an int expressing the relative weighting given to high bandwidth

read

int read(ByteBuffer dst)
  throws IOException

Reads a sequence of bytes into the given buffer.

Parameters:

dst - the buffer into which bytes are to be transferred.

Returns:

the number of bytes read, possibly zero, or -1 if the socket has reached end-of-stream.

Throws:

IOException - If some other I/O error occurs.

waitRead

void waitRead(long timeout,
              TimeUnit timeUnit)
       throws IOException

Waits for read I/O operation to be ready. This method performs a blocking operation. It returns only after read operation is ready, wakeupRead() method is invoked, the current thread is interrupted, or the given timeout period expires, whichever comes first.

Parameters:

timeout - if positive, block for up to timeout in specified time unit, more or less, while waiting for a socket to become read ready; if zero, block indefinitely; must not be negative.

timeUnit - time unit of the timeout.

Throws:

IOException - If some other I/O error occurs.

wakeupRead

void wakeupRead()

Causes the waitRead(long, TimeUnit) operation that has not yet returned to return immediately.

write

int write(ByteBuffer src)
   throws IOException

Writes a sequence of bytes from the given buffer.

Parameters:

src - the buffer from which bytes are to be retrieved.

Returns:

the number of bytes written, possibly zero.

Throws:

IOException - If some other I/O error occurs.

waitWrite

void waitWrite(long timeout,
               TimeUnit timeUnit)
        throws IOException

Waits for write I/O operation to be ready. This method performs a blocking operation. It returns only after write operation is ready, wakeupWrite() method is invoked, the current thread is interrupted, or the given timeout period expires, whichever comes first.

Parameters:

timeout - if positive, block for up to timeout in specified time unit, more or less, while waiting for a socket to become write ready; if zero, block indefinitely; must not be negative.

timeUnit - time unit of the timeout.

Throws:

IOException - If some other I/O error occurs.

wakeupWrite

void wakeupWrite()

Causes the waitWrite(long, TimeUnit) operation that has not yet returned to return immediately.

isBlocking

boolean isBlocking()

Returns whether every I/O operation on this channel will block until it completes.

Returns:

true if, and only if, this socket is in blocking mode.

setBlocking

void setBlocking(boolean blocking)
          throws IOException

Sets whether every I/O operation on this channel will block until it completes.

Parameters:

blocking - true for block until I/O operation completes, false otherwise.

Throws:

IOException - If some other I/O error occurs.