NioChannel (Apache Tomcat 9.0.75 API Documentation)

Package org.apache.tomcat.util.net

## Class NioChannel

- java.lang.Object
- - org.apache.tomcat.util.net.NioChannel

- All Implemented Interfaces:
    `java.io.Closeable`, `java.lang.AutoCloseable`, `java.nio.channels.ByteChannel`, `java.nio.channels.Channel`, `java.nio.channels.GatheringByteChannel`, `java.nio.channels.ReadableByteChannel`, `java.nio.channels.ScatteringByteChannel`, `java.nio.channels.WritableByteChannel`
  Direct Known Subclasses:
    `SecureNioChannel`

      public class NioChannel
      extends java.lang.Object
      implements java.nio.channels.ByteChannel, java.nio.channels.ScatteringByteChannel, java.nio.channels.GatheringByteChannel

  Base class for a SocketChannel wrapper used by the endpoint. This way, logic for an SSL socket channel remains the same as for a non SSL, making sure we don't need to code for any exception cases.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected SocketBufferHandler` | `bufHandler` |
    `protected static java.nio.ByteBuffer` | `emptyBuf` |
    `protected java.nio.channels.SocketChannel` | `sc` |
    `protected static StringManager` | `sm` |
    `protected NioEndpoint.NioSocketWrapper` | `socketWrapper` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NioChannel​(SocketBufferHandler bufHandler)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `checkInterruptStatus()` | This method should be used to check the interrupt status before attempting a write.
    `void` | `close()` | Closes this channel.
    `void` | `close​(boolean force)` | Close the connection.
    `boolean` | `flush​(boolean block, java.nio.channels.Selector s, long timeout)` | Returns true if the network buffer has been flushed out and is empty.
    `boolean` | `flushOutbound()` | Return true if the buffer wrote data.
    `void` | `free()` | Free the channel memory
    `protected ApplicationBufferHandler` | `getAppReadBufHandler()` |
    `SocketBufferHandler` | `getBufHandler()` |
    `java.nio.channels.SocketChannel` | `getIOChannel()` |
    `int` | `getOutboundRemaining()` |
    `int` | `handshake​(boolean read, boolean write)` | Performs SSL handshake hence is a no-op for the non-secure implementation.
    `boolean` | `isClosing()` |
    `boolean` | `isHandshakeComplete()` |
    `boolean` | `isOpen()` | Tells whether or not this channel is open.
    `int` | `read​(java.nio.ByteBuffer dst)` | Reads a sequence of bytes from this channel into the given buffer.
    `long` | `read​(java.nio.ByteBuffer[] dsts)` |
    `long` | `read​(java.nio.ByteBuffer[] dsts, int offset, int length)` |
    `void` | `reset​(java.nio.channels.SocketChannel channel, NioEndpoint.NioSocketWrapper socketWrapper)` | Reset the channel
    `void` | `setAppReadBufHandler​(ApplicationBufferHandler handler)` |
    `java.lang.String` | `toString()` |
    `int` | `write​(java.nio.ByteBuffer src)` | Writes a sequence of bytes to this channel from the given buffer.
    `long` | `write​(java.nio.ByteBuffer[] srcs)` |
    `long` | `write​(java.nio.ByteBuffer[] srcs, int offset, int length)` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### sm

          protected static final StringManager sm

    - #### emptyBuf

          protected static final java.nio.ByteBuffer emptyBuf

    - #### bufHandler

          protected final SocketBufferHandler bufHandler

    - #### sc

          protected java.nio.channels.SocketChannel sc

    - #### socketWrapper

          protected NioEndpoint.NioSocketWrapper socketWrapper

  - ### Constructor Detail

    - #### NioChannel

          public NioChannel​(SocketBufferHandler bufHandler)

  - ### Method Detail

    - #### reset

          public void reset​(java.nio.channels.SocketChannel channel,
                            NioEndpoint.NioSocketWrapper socketWrapper)
                     throws java.io.IOException

      Reset the channel
      Parameters:
        `channel` - the socket channel
        `socketWrapper` - the socket wrapper
      Throws:
        `java.io.IOException` - If a problem was encountered resetting the channel

    - #### free

          public void free()

      Free the channel memory

    - #### flush

          public boolean flush​(boolean block,
                               java.nio.channels.Selector s,
                               long timeout)
                        throws java.io.IOException

      Returns true if the network buffer has been flushed out and is empty.
      Parameters:
        `block` - Unused. May be used when overridden
        `s` - Unused. May be used when overridden
        `timeout` - Unused. May be used when overridden
      Returns:
        Always returns `true` since there is no network buffer in the regular channel
      Throws:
        `java.io.IOException` - Never for non-secure channel

    - #### close

          public void close()
                     throws java.io.IOException

      Closes this channel.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.nio.channels.Channel`
      Specified by:
        `close` in interface `java.io.Closeable`
      Throws:
        `java.io.IOException` - If an I/O error occurs

    - #### close

          public void close​(boolean force)
                     throws java.io.IOException

      Close the connection.
      Parameters:
        `force` - Should the underlying socket be forcibly closed?
      Throws:
        `java.io.IOException` - If closing the secure channel fails.

    - #### isOpen

          public boolean isOpen()

      Tells whether or not this channel is open.
      Specified by:
        `isOpen` in interface `java.nio.channels.Channel`
      Returns:
        `true` if, and only if, this channel is open

    - #### write

          public int write​(java.nio.ByteBuffer src)
                    throws java.io.IOException

      Writes a sequence of bytes to this channel from the given buffer.
      Specified by:
        `write` in interface `java.nio.channels.WritableByteChannel`
      Parameters:
        `src` - The buffer from which bytes are to be retrieved
      Returns:
        The number of bytes written, possibly zero
      Throws:
        `java.io.IOException` - If some other I/O error occurs

    - #### write

          public long write​(java.nio.ByteBuffer[] srcs)
                     throws java.io.IOException

      Specified by:
        `write` in interface `java.nio.channels.GatheringByteChannel`
      Throws:
        `java.io.IOException`

    - #### write

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

      Specified by:
        `write` in interface `java.nio.channels.GatheringByteChannel`
      Throws:
        `java.io.IOException`

    - #### read

          public int read​(java.nio.ByteBuffer dst)
                   throws java.io.IOException

      Reads a sequence of bytes from this channel into the given buffer.
      Specified by:
        `read` in interface `java.nio.channels.ReadableByteChannel`
      Parameters:
        `dst` - The buffer into which bytes are to be transferred
      Returns:
        The number of bytes read, possibly zero, or `-1` if the channel has reached end-of-stream
      Throws:
        `java.io.IOException` - If some other I/O error occurs

    - #### read

          public long read​(java.nio.ByteBuffer[] dsts)
                    throws java.io.IOException

      Specified by:
        `read` in interface `java.nio.channels.ScatteringByteChannel`
      Throws:
        `java.io.IOException`

    - #### read

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

      Specified by:
        `read` in interface `java.nio.channels.ScatteringByteChannel`
      Throws:
        `java.io.IOException`

    - #### getBufHandler

          public SocketBufferHandler getBufHandler()

    - #### getIOChannel

          public java.nio.channels.SocketChannel getIOChannel()

    - #### isClosing

          public boolean isClosing()

    - #### isHandshakeComplete

          public boolean isHandshakeComplete()

    - #### handshake

          public int handshake​(boolean read,
                               boolean write)
                        throws java.io.IOException

      Performs SSL handshake hence is a no-op for the non-secure implementation.
      Parameters:
        `read` - Unused in non-secure implementation
        `write` - Unused in non-secure implementation
      Returns:
        Always returns zero
      Throws:
        `java.io.IOException` - Never for non-secure channel

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getOutboundRemaining

          public int getOutboundRemaining()

    - #### flushOutbound

          public boolean flushOutbound()
                                throws java.io.IOException

      Return true if the buffer wrote data. NO-OP for non-secure channel.
      Returns:
        Always returns `false` for non-secure channel
      Throws:
        `java.io.IOException` - Never for non-secure channel

    - #### checkInterruptStatus

          protected void checkInterruptStatus()
                                       throws java.io.IOException

      This method should be used to check the interrupt status before attempting a write. If a thread has been interrupted and the interrupt has not been cleared then an attempt to write to the socket will fail. When this happens the socket is removed from the poller without the socket being selected. This results in a connection limit leak for NIO as the endpoint expects the socket to be selected even in error conditions.
      Throws:
        `java.io.IOException` - If the current thread was interrupted

    - #### setAppReadBufHandler

          public void setAppReadBufHandler​(ApplicationBufferHandler handler)

    - #### getAppReadBufHandler

          protected ApplicationBufferHandler getAppReadBufHandler()