org.mortbay.http
Interface HttpListener

All Superinterfaces:

LifeCycle, java.io.Serializable

All Known Implementing Classes:

AJP13Listener, SocketListener

public interface HttpListener

extends LifeCycle, java.io.Serializable

HTTP Listener. This interface describes the methods of a generic request listener for the HttpServer. Once a HttpListener is started, it is responsible for listening for new connections. Once a new connection is accepted it should be handled by creating a HttpConnection instance and calling either the HttpConnection.handle() or HttpConnection.handleNext() methods from a Thread allocated to that connection.

Version:

$Id: HttpListener.java,v 1.11.2.1 2003/11/19 11:37:22 gregwilkins Exp $

Author:

Greg Wilkins (gregw)

See Also:

HttpConnection, HttpServer

Field Summary

static java.lang.String

ATTRIBUTE

Method Summary

void	customizeRequest(HttpConnection connection, HttpRequest request) Customize a request for a listener/connection combination.
int	getBufferReserve() Get the size of the header reserve area.
int	getBufferSize() Get the size of the buffers used by connections from this listener.
int	getConfidentialPort() Get the protocol port to use for confidential redirections.
java.lang.String	getConfidentialScheme() Get the protocol scheme to use for confidential redirections.
java.lang.String	getDefaultScheme() Get the default scheme for requests.
java.lang.String	getHost() Get the host or IP of the interface used by this listener.
HttpServer	getHttpServer() Get the HttpServer instance for this HttpListener.
int	getIntegralPort() Get the protocol port to use for integral redirections.
java.lang.String	getIntegralScheme() Get the protocol scheme to use for integral redirections.
int	getPort() Get the port number of the listener.
boolean	isConfidential(HttpConnection connection) Get the confidential status of a connection.
boolean	isIntegral(HttpConnection connection) Get the integral status of a connection.
boolean	isLowOnResources() Get the low on resources state of the listener.
boolean	isOutOfResources() Get the out of resources state of the listener.
void	persistConnection(HttpConnection connection) Prepare a connection for persistance.
void	setHost(java.lang.String host) Set the host or IP of the interface used by this listener.
void	setHttpServer(HttpServer server) Set the HttpServer instance for this HttpListener.
void	setPort(int port) Set the port number of the listener.

Methods inherited from interface org.mortbay.util.LifeCycle

isStarted, start, stop

Field Detail

ATTRIBUTE

public static final java.lang.String ATTRIBUTE

See Also:

Constant Field Values

Method Detail

setHttpServer

public void setHttpServer(HttpServer server)

Set the HttpServer instance for this HttpListener. This method is called by the HttpServer.addListener method. It should not be called directly.

Parameters:

server - The HttpServer instance this HttpListener has been added to.

getHttpServer

public HttpServer getHttpServer()

Get the HttpServer instance for this HttpListener.

Returns:

The HttpServer instance this HttpListener has been added to, or null if the listener is not added to any HttpServer.

setHost

public void setHost(java.lang.String host)
             throws java.net.UnknownHostException

Set the host or IP of the interface used by this listener.

Parameters:

host - The hostname or IP address of the interface used by this listeners. If null or "0.0.0.0" then all available interfaces are used by this listener.

java.net.UnknownHostException

getHost

public java.lang.String getHost()

Get the host or IP of the interface used by this listener.

Returns:

The hostname or IP address of the interface used by this listeners. If null or "0.0.0.0" then all available interfaces are used by this listener.

setPort

public void setPort(int port)

Set the port number of the listener.

Parameters:

port - The TCP/IP port number to be used by this listener.

getPort

public int getPort()

Get the port number of the listener.

Returns:

The TCP/IP port number used by this listener.

getBufferSize

public int getBufferSize()

Get the size of the buffers used by connections from this listener.

Returns:

The default buffer size in bytes.

getBufferReserve

public int getBufferReserve()

Get the size of the header reserve area. Get the size of the header reserve area within the buffers used by connections from this listener. The header reserve is space reserved in the first buffer of a response to allow a HTTP header to be written in the same packet. The reserve should be large enough to avoid moving data to fit the header, but not too large as to waste memory.

Returns:

The default buffer reserve size in bytes.

getDefaultScheme

public java.lang.String getDefaultScheme()

Get the default scheme for requests. If a request is received from a HttpConnection created by this listener, that does not include a scheme in it's request URL, then this method is used to determine the protocol scheme most likely used to connect to this listener.

Returns:

The protocol scheme name (eg "http" or "https").

customizeRequest

public void customizeRequest(HttpConnection connection,
                             HttpRequest request)

Customize a request for a listener/connection combination. This method is called by HttpConnection after a request has been read from that connection and before processing that request. Implementations may use this callback to add additional listener and/or connection specific attributes to the request (eg SSL attributes).

Parameters:

connection - The connection the request was received on, which must be a HttpConnection created by this listener.

request - The request to customize.

persistConnection

public void persistConnection(HttpConnection connection)

Prepare a connection for persistance. This method is called by the HttpConnection on a persistent connection after each request has been handled and before starting to read for the next connection. Implementations may use this callback to change the parameters or scheduling of the connection.

Parameters:

connection - The perstent connection, which must be a HttpConnection created by this listener.

isLowOnResources

public boolean isLowOnResources()

Get the low on resources state of the listener. For most implementations, Threads are the resource reported on by this method.

Returns:

True if the listener is out of resources.

isOutOfResources

public boolean isOutOfResources()

Get the out of resources state of the listener. For most implementations, Threads are the resource reported on by this method.

Returns:

True if the listener is out of resources.

isIntegral

public boolean isIntegral(HttpConnection connection)

Get the integral status of a connection.

Parameters:

connection - The connection to test.

Returns:

True of the connection checks the integrity of the data. For most implementations this is true for https connections.

getIntegralScheme

public java.lang.String getIntegralScheme()

Get the protocol scheme to use for integral redirections. If an INTEGRAL security constraint is not met for a request, the request is redirected to an integral port. This scheme return by this method is used for that redirection.

Returns:

The integral scheme. For most implementations this is "https"

getIntegralPort

public int getIntegralPort()

Get the protocol port to use for integral redirections. If an INTEGRAL security constraint is not met for a request, the request is redirected to an integral port. This port return by this method is used for that redirection.

Returns:

The integral port. For most implementations this is 443 for https

isConfidential

public boolean isConfidential(HttpConnection connection)

Get the confidential status of a connection.

Parameters:

connection - The connection to test.

Returns:

True of the connection checks the integrity of the data. For most implementations this is true for https connections.

getConfidentialScheme

public java.lang.String getConfidentialScheme()

Get the protocol scheme to use for confidential redirections. If an CONFIDENTIAL security constraint is not met for a request, the request is redirected to an confidential port. This scheme return by this method is used for that redirection.

Returns:

The confidential scheme. For most implementations this is "https"

getConfidentialPort

public int getConfidentialPort()

Get the protocol port to use for confidential redirections. If an CONFIDENTIAL security constraint is not met for a request, the request is redirected to an confidential port. This port return by this method is used for that redirection.

Returns:

The confidential port. For most implementations this is 443 for https