org.xlightweb
Interface IHttpExchange

All Superinterfaces:

IDestroyable

public interface IHttpExchange
extends IDestroyable

This class encapsulates a HTTP request received and a response to be generated in one exchange. It provides methods

• to retrieve and forward the request (within the local chain), and
• to send the response

For an example see IHttpRequestHandler

Field Summary

static String	SHOW_DETAILED_ERROR_DEFAULT
static String	SHOW_DETAILED_ERROR_KEY System property key to define if detailed error should been shown in error page

Method Summary

void	destroy() destroy the exchange and the underlying connection
String	encodeURL(String url) Encodes the specified URL by including the session ID in it, or, if encoding is not needed, returns the URL unchanged.
void	forward(IHttpRequest request) forwards a request locally.
BodyDataSink	forward(IHttpRequestHeader requestHeader) forwards the a request.
BodyDataSink	forward(IHttpRequestHeader requestHeader, IHttpResponseHandler responseHandler) forwards the a request.
BodyDataSink	forward(IHttpRequestHeader requestHeader, int contentLength) forwards a request.
BodyDataSink	forward(IHttpRequestHeader requestHeader, int contentLength, IHttpResponseHandler responseHandler) forwards a request.
void	forward(IHttpRequest request, IHttpResponseHandler responseHandler) forwards a request.
IHttpConnection	getConnection() returns the underlying connection
IHttpRequest	getRequest() get the request of this exchange
IHttpSession	getSession(boolean create) Returns the current HttpSession associated with this exchange or, if there is no current session and create is true, returns a new session.
void	send(IHttpResponse response) send the response.
BodyDataSink	send(IHttpResponseHeader header) send the response.
BodyDataSink	send(IHttpResponseHeader header, int contentLength) send the response in a plain body non-blocking mode.
boolean	sendContinueIfRequested() send a 100 Continue response if the request contains a Expect: 100-Continue header.
void	sendError(Exception e) send an error response
void	sendError(int errorCode) send an error response
void	sendError(int errorCode, String msg) send an error response
void	sendRedirect(String location) Sends a temporary redirect response using the specified redirect location URL.

Field Detail

SHOW_DETAILED_ERROR_KEY

static final String SHOW_DETAILED_ERROR_KEY

System property key to define if detailed error should been shown in error page

See Also:

Constant Field Values

SHOW_DETAILED_ERROR_DEFAULT

static final String SHOW_DETAILED_ERROR_DEFAULT

See Also:

Constant Field Values

Method Detail

getRequest

IHttpRequest getRequest()

get the request of this exchange

Returns:

the request

getConnection

IHttpConnection getConnection()

returns the underlying connection

Returns:

the connection

send

BodyDataSink send(IHttpResponseHeader header)
                  throws IOException,
                         IllegalStateException

send the response. If the content-length header is not set, the message will send in chunked mode. This send method will be used if the body size is unknown by sending the header.

By calling the IHttpMessage.getProtocolVersion() method of the request, it can be verified, if the requestor supports a chunked responses (HTTP/1.0 request)

• Connection-LifeCycle support: If the request header contains a 'Connection: close' entry, the connection will be closed after the HTTP transaction

Parameters:

header - the header

Returns:

the body handle to write

Throws:

IOException - if an exception occurs

IllegalStateException - if a response has already been send

send

BodyDataSink send(IHttpResponseHeader header,
                  int contentLength)
                  throws IOException,
                         IllegalStateException

send the response in a plain body non-blocking mode. For performance reasons this is the preferred send method

• Connection-LifeCycle support: If the request header contains a 'Connection: close' entry, the connection will be closed after the HTTP transaction

Parameters:

header - the header

contentLength - the body content length

Returns:

the body handle to write

Throws:

IOException - if an exception occurs

IllegalStateException - if a response has already been send

send

void send(IHttpResponse response)
          throws IOException,
                 IllegalStateException

send the response.

• Connection-LifeCycle support: If the request header contains a 'Connection: close' entry, the connection will be closed after the HTTP transaction

Parameters:

response - the response

Throws:

IOException - if an exception occurs

IllegalStateException - if a response has already been send

sendError

void sendError(int errorCode,
               String msg)
               throws IllegalStateException

send an error response

Parameters:

errorCode - the error code

msg - the error message

Throws:

IllegalStateException - if a response has already been send

sendError

void sendError(int errorCode)
               throws IllegalStateException

send an error response

Parameters:

errorCode - the error code

msg - the error message

Throws:

IllegalStateException - if a response has already been send

sendError

void sendError(Exception e)
               throws IllegalStateException

send an error response

Parameters:

e - the exception

Throws:

IllegalStateException - if a response has already been send

sendRedirect

void sendRedirect(String location)
                  throws IllegalStateException

Sends a temporary redirect response using the specified redirect location URL.

Parameters:

location - the redirect location URL

Throws:

IllegalStateException - if a response has already been send

forward

BodyDataSink forward(IHttpRequestHeader requestHeader,
                     IHttpResponseHandler responseHandler)
                     throws IOException,
                            ConnectException,
                            IllegalStateException

forwards the a request. If the content-length header is not set, the message will send in chunked mode. Forwarding will be used to forward the request to the next handler of the chain. If no successor handler exits an error response will be returned to the client. For an example see RequestHandlerChain This method should only be used if the original request supports chunked responses, which can be check by request.supportsChunkedResponse()

Parameters:

requestHeader - the request header

responseHandler - the response handler or null (supported: IHttpRequestHandler, IHttpSocketTimeoutHandler)

Returns:

the body handle to write

Throws:

ConnectException - if an error occurred while attempting to connect to a remote address and port.

IOException - if an exception occurs

IllegalStateException - if a request has already been forwarded

forward

BodyDataSink forward(IHttpRequestHeader requestHeader)
                     throws IOException,
                            ConnectException,
                            IllegalStateException

forwards the a request. If the content-length header is not set, the message will send in chunked mode. Forwarding will be used to forward the request to the next handler of the chain. If no successor handler exits an error response will be returned to the client. For an example see RequestHandlerChain This method should only be used if the original request supports chunked responses, which can be check by request.supportsChunkedResponse()

Parameters:

requestHeader - the request header

Returns:

the body handle to write

Throws:

ConnectException - if an error occurred while attempting to connect to a remote address and port.

IOException - if an exception occurs

IllegalStateException - if a request has already been forwarded

forward

BodyDataSink forward(IHttpRequestHeader requestHeader,
                     int contentLength,
                     IHttpResponseHandler responseHandler)
                     throws IOException,
                            ConnectException,
                            IllegalStateException

forwards a request. The request will be send in a plain body mode. Forwarding will be used to forward the request to the next handler of the chain. If no successor handler exits an error response will be returned to the client. For an example see RequestHandlerChain

Parameters:

requestHeader - the request header

contentLength - the content length

responseHandler - the response handler or null (supported: IHttpRequestHandler, IHttpSocketTimeoutHandler)

Returns:

the body handle to write

Throws:

ConnectException - if an error occurred while attempting to connect to a remote address and port.

IOException - if an exception occurs

IllegalStateException - if a request has already been forwarded

forward

BodyDataSink forward(IHttpRequestHeader requestHeader,
                     int contentLength)
                     throws IOException,
                            ConnectException,
                            IllegalStateException

forwards a request. The request will be send in a plain body mode. Forwarding will be used to forward the request to the next handler of the chain. If no successor handler exits an error response will be returned to the client. For an example see RequestHandlerChain

Parameters:

requestHeader - the request header

contentLength - the content length

Returns:

the body handle to write

Throws:

ConnectException - if an error occurred while attempting to connect to a remote address and port.

IOException - if an exception occurs

IllegalStateException - if a request has already been forwarded

forward

void forward(IHttpRequest request)
             throws IOException,
                    ConnectException,
                    IllegalStateException

forwards a request locally. Forwarding will be used to forward the request to the next handler of the chain. If no successor handler exits an error response will be returned to the client. For an example see RequestHandlerChain

Parameters:

request - the request

Throws:

ConnectException - if an error occurred while attempting to connect to a remote address and port.

IOException - if an exception occurs

IllegalStateException - if a request has already been forwarded

forward

void forward(IHttpRequest request,
             IHttpResponseHandler responseHandler)
             throws IOException,
                    ConnectException,
                    IllegalStateException

forwards a request. Forwarding will be used to forward the request to the next handler of the chain. If no successor handler exits an error response will be returned to the client. For an example see RequestHandlerChain

Parameters:

request - the request

responseHandler - the response handler or null (supported: IHttpRequestHandler, IHttpSocketTimeoutHandler)

Throws:

ConnectException - if an error occurred while attempting to connect to a remote address and port.

IOException - if an exception occurs

IllegalStateException - if a request has already been forwarded

sendContinueIfRequested

boolean sendContinueIfRequested()
                                throws IOException

send a 100 Continue response if the request contains a Expect: 100-Continue header. The 100 response will be send once, even though in the case of a repeated sendContinue() call

Returns:

true if a 100 Continue response has been sent

Throws:

IOException - if an exception occurs

getSession

IHttpSession getSession(boolean create)

Returns the current HttpSession associated with this exchange or, if there is no current session and create is true, returns a new session. If create is false and the exchange has no valid HttpSession, this method returns null.

Parameters:

create - true to create a new session if necessary; false to return null if there's no current session

Returns:

the HttpSession associated with this exchange or null if create is false and the request has no valid session

encodeURL

String encodeURL(String url)

Encodes the specified URL by including the session ID in it, or, if encoding is not needed, returns the URL unchanged. The implementation of this method includes the logic to determine whether the session ID needs to be encoded in the URL. For example, if the browser supports cookies, or session tracking is turned off, URL encoding is unnecessary.

Parameters:

url - the url to be encoded.

Returns:

the encoded URL if encoding is needed; the unchanged URL otherwise.

destroy

void destroy()

destroy the exchange and the underlying connection

Specified by:

destroy in interface IDestroyable