SecureNioChannel (Apache Tomcat 10.1.14 API Documentation)

Package org.apache.tomcat.util.net

## Class SecureNioChannel

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

- All Implemented Interfaces:
    `Closeable`, `AutoCloseable`, `ByteChannel`, `Channel`, `GatheringByteChannel`, `ReadableByteChannel`, `ScatteringByteChannel`, `WritableByteChannel`

      public class SecureNioChannel
      extends NioChannel

  Implementation of a secure socket channel

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `closed` |
    `protected boolean` | `closing` |
    `protected boolean` | `handshakeComplete` |
    `protected SSLEngineResult.HandshakeStatus` | `handshakeStatus` |
    `protected ByteBuffer` | `netInBuffer` |
    `protected ByteBuffer` | `netOutBuffer` |
    `protected boolean` | `sniComplete` |
    `protected SSLEngine` | `sslEngine` |

    - ### Fields inherited from class org.apache.tomcat.util.net.NioChannel

      `bufHandler, emptyBuf, sc, socketWrapper`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SecureNioChannel​(SocketBufferHandler bufHandler, NioEndpoint endpoint)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Sends an SSL close message, will not physically close the connection here.
    `void` | `close​(boolean force)` | Close the connection.
    `protected boolean` | `flush​(ByteBuffer buf)` | Flushes the buffer to the network, non blocking
    `boolean` | `flushOutbound()` | Return true if the buffer wrote data.
    `void` | `free()` | Free the channel memory
    `ByteBuffer` | `getEmptyBuf()` |
    `int` | `getOutboundRemaining()` |
    `SSLEngine` | `getSslEngine()` |
    `SSLSupport` | `getSSLSupport()` |
    `int` | `handshake​(boolean read, boolean write)` | Performs SSL handshake, non blocking, but performs NEED_TASK on the same thread.
    `protected SSLEngineResult` | `handshakeUnwrap​(boolean doread)` | Perform handshake unwrap
    `protected SSLEngineResult` | `handshakeWrap​(boolean doWrite)` | Performs the WRAP function
    `boolean` | `isClosing()` |
    `boolean` | `isHandshakeComplete()` |
    `int` | `read​(ByteBuffer dst)` | Reads a sequence of bytes from this channel into the given buffer.
    `long` | `read​(ByteBuffer[] dsts, int offset, int length)` |
    `void` | `rehandshake​(long timeout)` | Force a blocking handshake to take place for this key.
    `void` | `reset​(SocketChannel channel, NioEndpoint.NioSocketWrapper socketWrapper)` | Reset the channel
    `protected SSLEngineResult.HandshakeStatus` | `tasks()` | Executes all the tasks needed on the same thread.
    `int` | `write​(ByteBuffer src)` | Writes a sequence of bytes to this channel from the given buffer.
    `long` | `write​(ByteBuffer[] srcs, int offset, int length)` |

    - ### Methods inherited from class org.apache.tomcat.util.net.NioChannel

      `checkInterruptStatus, getAppReadBufHandler, getBufHandler, getIOChannel, isOpen, read, setAppReadBufHandler, toString, write`

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

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

- - ### Field Detail

    - #### netInBuffer

          protected ByteBuffer netInBuffer

    - #### netOutBuffer

          protected ByteBuffer netOutBuffer

    - #### sslEngine

          protected SSLEngine sslEngine

    - #### sniComplete

          protected boolean sniComplete

    - #### handshakeComplete

          protected boolean handshakeComplete

    - #### handshakeStatus

          protected SSLEngineResult.HandshakeStatus handshakeStatus

    - #### closed

          protected boolean closed

    - #### closing

          protected boolean closing

  - ### Constructor Detail

    - #### SecureNioChannel

          public SecureNioChannel​(SocketBufferHandler bufHandler,
                                  NioEndpoint endpoint)

  - ### Method Detail

    - #### reset

          public void reset​(SocketChannel channel,
                            NioEndpoint.NioSocketWrapper socketWrapper)
                     throws IOException

      Description copied from class: `NioChannel`
      Reset the channel
      Overrides:
        `reset` in class `NioChannel`
      Parameters:
        `channel` - the socket channel
        `socketWrapper` - the socket wrapper
      Throws:
        `IOException` - If a problem was encountered resetting the channel

    - #### free

          public void free()

      Description copied from class: `NioChannel`
      Free the channel memory
      Overrides:
        `free` in class `NioChannel`

    - #### flush

          protected boolean flush​(ByteBuffer buf)
                           throws IOException

      Flushes the buffer to the network, non blocking
      Parameters:
        `buf` - ByteBuffer
      Returns:
        boolean true if the buffer has been emptied out, false otherwise
      Throws:
        `IOException` - An IO error occurred writing data

    - #### handshake

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

      Performs SSL handshake, non blocking, but performs NEED_TASK on the same thread. Hence, you should never call this method using your Acceptor thread, as you would slow down your system significantly. If the return value from this method is positive, the selection key should be registered interestOps given by the return value.
      Overrides:
        `handshake` in class `NioChannel`
      Parameters:
        `read` - boolean - true if the underlying channel is readable
        `write` - boolean - true if the underlying channel is writable
      Returns:
        0 if hand shake is complete, -1 if an error (other than an IOException) occurred, otherwise it returns a SelectionKey interestOps value
      Throws:
        `IOException` - If an I/O error occurs during the handshake or if the handshake fails during wrapping or unwrapping

    - #### rehandshake

          public void rehandshake​(long timeout)
                           throws IOException

      Force a blocking handshake to take place for this key. This requires that both network and application buffers have been emptied out prior to this call taking place, or a IOException will be thrown.
      Parameters:
        `timeout` - - timeout in milliseconds for each socket operation
      Throws:
        `IOException` - - if an IO exception occurs or if application or network buffers contain data
        `SocketTimeoutException` - - if a socket operation timed out

    - #### tasks

          protected SSLEngineResult.HandshakeStatus tasks()

      Executes all the tasks needed on the same thread.
      Returns:
        the status

    - #### handshakeWrap

          protected SSLEngineResult handshakeWrap​(boolean doWrite)
                                           throws IOException

      Performs the WRAP function
      Parameters:
        `doWrite` - boolean
      Returns:
        the result
      Throws:
        `IOException` - An IO error occurred

    - #### handshakeUnwrap

          protected SSLEngineResult handshakeUnwrap​(boolean doread)
                                             throws IOException

      Perform handshake unwrap
      Parameters:
        `doread` - boolean
      Returns:
        the result
      Throws:
        `IOException` - An IO error occurred

    - #### getSSLSupport

          public SSLSupport getSSLSupport()

    - #### close

          public void close()
                     throws IOException

      Sends an SSL close message, will not physically close the connection here.
      To close the connection, you could do something like

             close();
             while (isOpen() && !myTimeoutFunction()) Thread.sleep(25);
             if ( isOpen() ) close(true); //forces a close if you timed out

      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Channel`
      Specified by:
        `close` in interface `Closeable`
      Overrides:
        `close` in class `NioChannel`
      Throws:
        `IOException` - if an I/O error occurs
        `IOException` - if there is data on the outgoing network buffer and we are unable to flush it

    - #### close

          public void close​(boolean force)
                     throws IOException

      Description copied from class: `NioChannel`
      Close the connection.
      Overrides:
        `close` in class `NioChannel`
      Parameters:
        `force` - Should the underlying socket be forcibly closed?
      Throws:
        `IOException` - If closing the secure channel fails.

    - #### read

          public int read​(ByteBuffer dst)
                   throws IOException

      Reads a sequence of bytes from this channel into the given buffer.
      Specified by:
        `read` in interface `ReadableByteChannel`
      Overrides:
        `read` in class `NioChannel`
      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:
        `IOException` - If some other I/O error occurs
        `IllegalArgumentException` - if the destination buffer is different than getBufHandler().getReadBuffer()

    - #### read

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

      Specified by:
        `read` in interface `ScatteringByteChannel`
      Overrides:
        `read` in class `NioChannel`
      Throws:
        `IOException`

    - #### write

          public int write​(ByteBuffer src)
                    throws IOException

      Writes a sequence of bytes to this channel from the given buffer.
      Specified by:
        `write` in interface `WritableByteChannel`
      Overrides:
        `write` in class `NioChannel`
      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

    - #### write

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

      Specified by:
        `write` in interface `GatheringByteChannel`
      Overrides:
        `write` in class `NioChannel`
      Throws:
        `IOException`

    - #### getOutboundRemaining

          public int getOutboundRemaining()

      Overrides:
        `getOutboundRemaining` in class `NioChannel`

    - #### flushOutbound

          public boolean flushOutbound()
                                throws IOException

      Description copied from class: `NioChannel`
      Return true if the buffer wrote data. NO-OP for non-secure channel.
      Overrides:
        `flushOutbound` in class `NioChannel`
      Returns:
        Always returns `false` for non-secure channel
      Throws:
        `IOException` - Never for non-secure channel

    - #### isHandshakeComplete

          public boolean isHandshakeComplete()

      Overrides:
        `isHandshakeComplete` in class `NioChannel`

    - #### isClosing

          public boolean isClosing()

      Overrides:
        `isClosing` in class `NioChannel`

    - #### getSslEngine

          public SSLEngine getSslEngine()

    - #### getEmptyBuf

          public ByteBuffer getEmptyBuf()