Package org.apache.coyote

Interface ProtocolHandler

All Known Implementing Classes:

AbstractAjpProtocol, AbstractHttp11JsseProtocol, AbstractHttp11Protocol, AbstractProtocol, AjpNio2Protocol, AjpNioProtocol, 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

Modifier and Type	Method	Description
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(String protocol)	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.
Executor	getExecutor()	The executor, provide access to the underlying thread pool.
default String	getId()	The default behavior is to identify connectors uniquely with address and port.
ScheduledExecutorService	getUtilityExecutor()	Get the utility executor that should be used by the protocol handler.
void	init()	Initialise the protocol.
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(Executor executor)	Set the optional executor that will be used by the connector.
void	setUtilityExecutor(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 Details

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

Executor getExecutor()

The executor, provide access to the underlying thread pool.

Returns:

The executor used to process requests

setExecutor

void setExecutor(Executor executor)

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

Parameters:

executor - the executor

getUtilityExecutor

ScheduledExecutorService getUtilityExecutor()

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

Returns:

the executor

setUtilityExecutor

void setUtilityExecutor(ScheduledExecutorService utilityExecutor)

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

Parameters:

utilityExecutor - the executor

init

void init()
   throws Exception

Initialise the protocol.

Throws:

Exception - If the protocol handler fails to initialise

start

void start()
    throws Exception

Start the protocol.

Throws:

Exception - If the protocol handler fails to start

pause

void pause()
    throws Exception

Pause the protocol (optional).

Throws:

Exception - If the protocol handler fails to pause

resume

void resume()
     throws Exception

Resume the protocol (optional).

Throws:

Exception - If the protocol handler fails to resume

stop

void stop()
   throws Exception

Stop the protocol.

Throws:

Exception - If the protocol handler fails to stop

destroy

void destroy()
      throws Exception

Destroy the protocol (optional).

Throws:

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

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:

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 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(String protocol)
                       throws ClassNotFoundException,
InstantiationException,
IllegalAccessException,
IllegalArgumentException,
InvocationTargetException,
NoSuchMethodException,
SecurityException

Create a new ProtocolHandler for the given protocol.

Parameters:

protocol - the protocol

Returns:

the newly instantiated protocol handler

Throws:

ClassNotFoundException - Specified protocol was not found

InstantiationException - Specified protocol could not be instantiated

IllegalAccessException - Exception occurred

IllegalArgumentException - Exception occurred

InvocationTargetException - Exception occurred

NoSuchMethodException - Exception occurred

SecurityException - Exception occurred