Package org.apache.coyote

## Interface ProtocolHandler

All Known Implementing Classes:
  `AbstractAjpProtocol`, `AbstractHttp11JsseProtocol`, `AbstractHttp11Protocol`, `AbstractProtocol`, `AjpAprProtocol`, `AjpNio2Protocol`, `AjpNioProtocol`, `Http11AprProtocol`, `Http11Nio2Protocol`, `Http11NioProtocol`

    public interface ProtocolHandler

Abstract the protocol implementation, including threading, etc. This is the main interface to be implemented by a coyote protocol. Adapter is the main interface to be implemented by a coyote servlet container.

Author:
  Remy Maucherat, Costin Manolache
See Also:
  `Adapter`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
`void` `addSslHostConfig​(SSLHostConfig sslHostConfig)` Add a new SSL configuration for a virtual host.
`void` `addSslHostConfig​(SSLHostConfig sslHostConfig, boolean replace)` Add a new SSL configuration for a virtual host.
`void` `addUpgradeProtocol​(UpgradeProtocol upgradeProtocol)` Add a new protocol for used by HTTP/1.1 upgrade or ALPN.
`long` `awaitConnectionsClose​(long waitMillis)` Wait for the client connections to the server to close gracefully.
`void` `closeServerSocketGraceful()` Close the server socket (to prevent further connections) if the server socket was bound on `start()` (rather than on `init()` but do not perform any further shutdown.
`static ProtocolHandler` `create​(java.lang.String protocol, boolean apr)` Create a new ProtocolHandler for the given protocol.
`void` `destroy()` Destroy the protocol (optional).
`SSLHostConfig[]` `findSslHostConfigs()` Find all configured SSL virtual host configurations which will be used by SNI.
`UpgradeProtocol[]` `findUpgradeProtocols()` Return all configured upgrade protocols.
`Adapter` `getAdapter()` Return the adapter associated with the protocol handler.
`default int` `getDesiredBufferSize()` Some protocols, like AJP, have a packet length that shouldn't be exceeded, and this can be used to adjust the buffering used by the application layer.
`java.util.concurrent.Executor` `getExecutor()` The executor, provide access to the underlying thread pool.
`default java.lang.String` `getId()` The default behavior is to identify connectors uniquely with address and port.
`java.util.concurrent.ScheduledExecutorService` `getUtilityExecutor()` Get the utility executor that should be used by the protocol handler.
`void` `init()` Initialise the protocol.
`boolean` `isAprRequired()` Deprecated. This method will be removed in Tomcat 10.1.x onwards
`boolean` `isSendfileSupported()` Does this ProtocolHandler support sendfile?
`void` `pause()` Pause the protocol (optional).
`void` `resume()` Resume the protocol (optional).
`void` `setAdapter​(Adapter adapter)` The adapter, used to call the connector.
`void` `setExecutor​(java.util.concurrent.Executor executor)` Set the optional executor that will be used by the connector.
`void` `setUtilityExecutor​(java.util.concurrent.ScheduledExecutorService utilityExecutor)` Set the utility executor that should be used by the protocol handler.
`void` `start()` Start the protocol.
`void` `stop()` Stop the protocol.

### Method Detail

#### getAdapter

    Adapter getAdapter()

Return the adapter associated with the protocol handler.

Returns:
  the adapter

#### setAdapter

    void setAdapter​(Adapter adapter)

The adapter, used to call the connector.

Parameters:
  `adapter` - The adapter to associate

#### getExecutor

    java.util.concurrent.Executor getExecutor()

The executor, provide access to the underlying thread pool.

Returns:
  The executor used to process requests

#### setExecutor

    void setExecutor​(java.util.concurrent.Executor executor)

Set the optional executor that will be used by the connector.

Parameters:
  `executor` - the executor

#### getUtilityExecutor

    java.util.concurrent.ScheduledExecutorService getUtilityExecutor()

Get the utility executor that should be used by the protocol handler.

Returns:
  the executor

#### setUtilityExecutor

    void setUtilityExecutor​(java.util.concurrent.ScheduledExecutorService utilityExecutor)

Set the utility executor that should be used by the protocol handler.

Parameters:
  `utilityExecutor` - the executor

#### init

    void init()
       throws java.lang.Exception

Initialise the protocol.

Throws:
  `java.lang.Exception` - If the protocol handler fails to initialise

#### start

    void start()
        throws java.lang.Exception

Start the protocol.

Throws:
  `java.lang.Exception` - If the protocol handler fails to start

#### pause

    void pause()
        throws java.lang.Exception

Pause the protocol (optional).

Throws:
  `java.lang.Exception` - If the protocol handler fails to pause

#### resume

    void resume()
         throws java.lang.Exception

Resume the protocol (optional).

Throws:
  `java.lang.Exception` - If the protocol handler fails to resume

#### stop

    void stop()
       throws java.lang.Exception

Stop the protocol.

Throws:
  `java.lang.Exception` - If the protocol handler fails to stop

#### destroy

    void destroy()
          throws java.lang.Exception

Destroy the protocol (optional).

Throws:
  `java.lang.Exception` - If the protocol handler fails to destroy

#### closeServerSocketGraceful

    void closeServerSocketGraceful()

Close the server socket (to prevent further connections) if the server socket was bound on `start()` (rather than on `init()` but do not perform any further shutdown.

#### awaitConnectionsClose

    long awaitConnectionsClose​(long waitMillis)

Wait for the client connections to the server to close gracefully. The method will return when all of the client connections have closed or the method has been waiting for `waitTimeMillis`.

Parameters:
  `waitMillis` - The maximum time to wait in milliseconds for the client connections to close.
Returns:
  The wait time, if any remaining when the method returned

#### isAprRequired

    @Deprecated
    boolean isAprRequired()

Deprecated.
This method will be removed in Tomcat 10.1.x onwards
Requires APR/native library

Returns:
  `true` if this Protocol Handler requires the APR/native library, otherwise `false`

#### isSendfileSupported

    boolean isSendfileSupported()

Does this ProtocolHandler support sendfile?

Returns:
  `true` if this Protocol Handler supports sendfile, otherwise `false`

#### addSslHostConfig

    void addSslHostConfig​(SSLHostConfig sslHostConfig)

Add a new SSL configuration for a virtual host.

Parameters:
  `sslHostConfig` - the configuration

#### addSslHostConfig

    void addSslHostConfig​(SSLHostConfig sslHostConfig,
                          boolean replace)

Add a new SSL configuration for a virtual host.

Parameters:
  `sslHostConfig` - the configuration
  `replace` - If `true` replacement of an existing configuration is permitted, otherwise any such attempted replacement will trigger an exception
Throws:
  `java.lang.IllegalArgumentException` - If the host name is not valid or if a configuration has already been provided for that host and replacement is not allowed

#### findSslHostConfigs

    SSLHostConfig[] findSslHostConfigs()

Find all configured SSL virtual host configurations which will be used by SNI.

Returns:
  the configurations

#### addUpgradeProtocol

    void addUpgradeProtocol​(UpgradeProtocol upgradeProtocol)

Add a new protocol for used by HTTP/1.1 upgrade or ALPN.

Parameters:
  `upgradeProtocol` - the protocol

#### findUpgradeProtocols

    UpgradeProtocol[] findUpgradeProtocols()

Return all configured upgrade protocols.

Returns:
  the protocols

#### getDesiredBufferSize

    default int getDesiredBufferSize()

Some protocols, like AJP, have a packet length that shouldn't be exceeded, and this can be used to adjust the buffering used by the application layer.

Returns:
  the desired buffer size, or -1 if not relevant

#### getId

    default java.lang.String getId()

The default behavior is to identify connectors uniquely with address and port. However, certain connectors are not using that and need some other identifier, which then can be used as a replacement.

Returns:
  the id

#### create

    static ProtocolHandler create​(java.lang.String protocol,
                                  boolean apr)
                           throws java.lang.ClassNotFoundException,
                                  java.lang.InstantiationException,
                                  java.lang.IllegalAccessException,
                                  java.lang.IllegalArgumentException,
                                  java.lang.reflect.InvocationTargetException,
                                  java.lang.NoSuchMethodException,
                                  java.lang.SecurityException

Create a new ProtocolHandler for the given protocol.

Parameters:
  `protocol` - the protocol
  `apr` - if `true` the APR protcol handler will be used
Returns:
  the newly instantiated protocol handler
Throws:
  `java.lang.ClassNotFoundException` - Specified protocol was not found
  `java.lang.InstantiationException` - Specified protocol could not be instantiated
  `java.lang.IllegalAccessException` - Exception occurred
  `java.lang.IllegalArgumentException` - Exception occurred
  `java.lang.reflect.InvocationTargetException` - Exception occurred
  `java.lang.NoSuchMethodException` - Exception occurred
  `java.lang.SecurityException` - Exception occurred