Package org.apache.coyote

# Interface UpgradeProtocol

All Known Implementing Classes:
  `Http2Protocol`

public interface UpgradeProtocol

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `accept(Request request)`
  Allows the implementation to examine the request and accept or reject it based on what it finds.
  `byte[]`
  `getAlpnIdentifier()`
  `String`
  `getAlpnName()`
  `String`
  `getHttpUpgradeName(boolean isSSLEnabled)`
  `InternalHttpUpgradeHandler`
  `getInternalUpgradeHandler(SocketWrapperBase<?> socketWrapper, Adapter adapter, Request request)`
  `Processor`
  `getProcessor(SocketWrapperBase<?> socketWrapper, Adapter adapter)`
  `default void`
  `setHttp11Protocol(AbstractProtocol<?> protocol)`
  Deprecated.
  This will be removed in Tomcat 10.
  `default void`
  `setHttp11Protocol(AbstractHttp11Protocol<?> protocol)`
  Configure the HTTP/1.1 protocol that this UpgradeProcotol is nested under.

- ## Method Details

  - ### getHttpUpgradeName

    String getHttpUpgradeName(boolean isSSLEnabled)
    Parameters:
      `isSSLEnabled` - Is this for a connector that is configured to support TLS. Some protocols (e.g. HTTP/2) only support HTTP upgrade over non-secure connections.
    Returns:
      The name that clients will use to request an upgrade to this protocol via an HTTP/1.1 upgrade request or `null` if upgrade via an HTTP/1.1 upgrade request is not supported.

  - ### getAlpnIdentifier

    byte[] getAlpnIdentifier()
    Returns:
      The byte sequence as listed in the IANA registry for this protocol or `null` if upgrade via ALPN is not supported.

  - ### getAlpnName

    String getAlpnName()
    Returns:
      The name of the protocol as listed in the IANA registry if and only if `getAlpnIdentifier()` returns the UTF-8 encoding of this name. If `getAlpnIdentifier()` returns some other byte sequence, then this method returns the empty string. If upgrade via ALPN is not supported then `null` is returned.

  - ### getProcessor

    Processor getProcessor(SocketWrapperBase<?> socketWrapper, Adapter adapter)
    Parameters:
      `socketWrapper` - The socketWrapper for the connection that requires a processor
      `adapter` - The Adapter instance that provides access to the standard Engine/Host/Context/Wrapper processing chain
    Returns:
      A processor instance for processing a connection using this protocol.

  - ### getInternalUpgradeHandler

    InternalHttpUpgradeHandler getInternalUpgradeHandler(SocketWrapperBase<?> socketWrapper, Adapter adapter, Request request)
    Parameters:
      `socketWrapper` - The socket
      `adapter` - The Adapter to use to configure the new upgrade handler
      `request` - A copy (may be incomplete) of the request that triggered the upgrade
    Returns:
      An instance of the HTTP upgrade handler for this protocol

  - ### accept

    boolean accept(Request request)
    Allows the implementation to examine the request and accept or reject it based on what it finds.
    Parameters:
      `request` - The request that included an upgrade header for this protocol
    Returns:
      `true` if the request is accepted, otherwise `false`

  - ### setHttp11Protocol

    default void setHttp11Protocol(AbstractHttp11Protocol<?> protocol)
    Configure the HTTP/1.1 protocol that this UpgradeProcotol is nested under. Connections passed to this UpgradeProtocol via HTTP upgrade will have been initially handled by this HTTP/1.1 protocol implementation.

    The default implementation is a NO-OP.

    Parameters:
      `protocol` - The HTTP/1.1 protocol implementation that will initially handle any connections passed to this UpgradeProtocol via the HTTP upgrade mechanism

  - ### setHttp11Protocol

    @Deprecated default void setHttp11Protocol(AbstractProtocol<?> protocol)
    Deprecated.
    This will be removed in Tomcat 10. Use `setHttp11Protocol(AbstractHttp11Protocol)` instead
    Configure the HTTP/1.1 protocol that this UpgradeProcotol is nested under. Connections passed to this UpgradeProtocol via HTTP upgrade will have been initially handled by this HTTP/1.1 protocol implementation.

    The default implementation is to call `setHttp11Protocol(AbstractHttp11Protocol)` if protocol is an instance of `AbstractHttp11Protocol` else this is a NO-OP.

    Parameters:
      `protocol` - The HTTP/1.1 protocol implementation that will initially handle any connections passed to this UpgradeProtocol via the HTTP upgrade mechanism