org.simpleframework.http.core
Class Conversation

java.lang.Object
  org.simpleframework.http.core.Conversation

public class Conversation
extends Object

The Conversation object is used to set and interpret the semantics of the HTTP headers with regard to the encoding used for the response. This will ensure the the correct headers are used so that if chunked encoding or a connection close is needed that the headers are set accordingly. This allows both the server and client to agree on the best semantics to use.

Author:

Niall Gallagher

See Also:

ResponseBuffer, ResponseEncoder

Constructor Summary

Conversation(RequestHeader request, ResponseHeader response)
Constructor for the Conversation object.

Method Summary

long	getContentLength() This is used to acquire the content length for the response.
RequestHeader	getRequest() This provides the Request object.
ResponseHeader	getResponse() This provides the Response object.
boolean	isChunkable() The isChunkable method is used to determine if the client supports chunked encoding.
boolean	isChunkedEncoded() The isChunkedEncoded is used to determine whether the chunked encoding scheme is desired.
boolean	isConnect() This is used to determine if the method was a CONNECT.
boolean	isEmpty() This is used to determine if the Response has a message body.
boolean	isHead() This is used to determine if the request method was HEAD.
boolean	isKeepAlive() The isKeepAlive method is used to determine if the connection semantics are set to maintain the connection.
boolean	isPersistent() This checks the protocol version used in the request to check whether it supports persistent HTTP connections.
boolean	isTunnel() This is used to determine if a tunnel should be established.
boolean	isWebSocket() This is used to determine if a WebSocket upgrade was requested and established.
void	setChunkedEncoded() This is used when the output is encoded in the chunked encoding.
void	setConnectionUpgrade() This is used to set the response to a connection upgrade.
void	setContentLength(long length) This is used to set the content length for the response.
void	setIdentityEncoded() This will remove all explicit transfer encoding headers from the response header.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Conversation

public Conversation(RequestHeader request,
                    ResponseHeader response)

Constructor for the Conversation object. This is used to create an object that makes use of both the request and response HTTP headers to determine how best to deliver the response body. Depending on the protocol version and the existing response headers suitable semantics are determined.

Parameters:

request - this is the request from the client

response - this is the response that is to be sent

Method Detail

getRequest

public RequestHeader getRequest()

This provides the Request object. This can be used to acquire the request HTTP headers and protocl version used by the client. Typically the conversation provides all the data needed to determine the type of response required.

Returns:

this returns the request object for the conversation

getResponse

public ResponseHeader getResponse()

This provides the Response object. This is used when the commit is required on the response. By committing the response the HTTP header is generated and delivered to the underlying transport.

Returns:

this returns the response for the conversation

getContentLength

public long getContentLength()

This is used to acquire the content length for the response. The content length is acquired fromt he Content-Length header if it has been set. If not then this will return a -1 value.

Returns:

this returns the value for the content length header

isEmpty

public boolean isEmpty()

This is used to determine if the Response has a message body. If this does not have a message body then true is returned. This is determined as of RFC 2616 rules for the presence of a message body. A message body must not be included with a HEAD request or with a 304 or a 204 response. If when this is called there is no message length delimiter as specified by section RFC 2616 4.4, then there is no body.

Returns:

true if there is no response body, false otherwise

isHead

public boolean isHead()

This is used to determine if the request method was HEAD. This is of particular interest in a HTTP conversation as it tells the response whether a response body is to be sent or not. If the method is head the delimeters for the response should be as they would be for a similar GET, however no body is sent.

Returns:

true if the request method was a HEAD method

isConnect

public boolean isConnect()

This is used to determine if the method was a CONNECT. The connect method is typically used when a client wishes to establish a connection directly with an origin server. Such a direct connection is useful when using TLS as it ensures there is not man in the middle with respect to key exchanges.

Returns:

this returns true if the method was a CONNECT method

setContentLength

public void setContentLength(long length)

This is used to set the content length for the response. If the HTTP version is HTTP/1.1 then the Content-Length header is used, if an earlier protocol version is used then connection close semantics are also used to ensure client compatibility.

Parameters:

length - this is the length to set HTTP header to

isPersistent

public boolean isPersistent()

This checks the protocol version used in the request to check whether it supports persistent HTTP connections. By default the HTTP/1.1 protocol supports persistent connnections, this can onlyy be overridden with a Connection header with the close token. Earlier protocol versions are connection close.

Returns:

this returns true if the protocol is HTTP/1.1 or above

isKeepAlive

public boolean isKeepAlive()

The isKeepAlive method is used to determine if the connection semantics are set to maintain the connection. This checks to see if there is a Connection header with the keep-alive token, if so then the connection is keep alive, if however there is no connection header the version is used.

Returns:

true if the response connection is to be maintained

isChunkable

public boolean isChunkable()

The isChunkable method is used to determine if the client supports chunked encoding. If the client does not support chunked encoding then a connection close should be used instead, this allows HTTP/1.0 clients to be supported properly.

Returns:

true if the client supports chunked transfer encoding

setChunkedEncoded

public void setChunkedEncoded()

This is used when the output is encoded in the chunked encoding. This should only be used if the protocol version is HTTP/1.1 or above. If the protocol version supports chunked encoding then it will encode the data as specified in RFC 2616 section 3.6.1.

setConnectionUpgrade

public void setConnectionUpgrade()

This is used to set the response to a connection upgrade. The response for an upgrade contains no payload delimeter such as content length or transfer encoding. It is typically used when establishing a web socket connection or a HTTP tunnel.

setIdentityEncoded

public void setIdentityEncoded()

This will remove all explicit transfer encoding headers from the response header. By default the identity encoding is used for all connections, it basically means no encoding. So if the response uses a Content-Length it implicitly assumes tha the encoding of the response is identity encoding.

isChunkedEncoded

public boolean isChunkedEncoded()

The isChunkedEncoded is used to determine whether the chunked encoding scheme is desired. This is enables data to be encoded in such a way that a connection can be maintained without a Content-Length header. If the output is chunked then the connection is keep alive.

Returns:

true if the response output is chunked encoded

isWebSocket

public boolean isWebSocket()

This is used to determine if a WebSocket upgrade was requested and established. An upgrade to use a WebSocket is done when the client requests the upgrade and the server responds with an upgrade confirmation, this is the basic handshake required.

Returns:

this returns true if a WebSocket handshake succeeded

isTunnel

public boolean isTunnel()

This is used to determine if a tunnel should be established. A tunnel is where the the HTTP server no longer processes any HTTP requests, it simply forms a byte stream with the client. Scenarios where tunnels are useful are when WebSockets are required or when a client wants a TLS connection to an origin server through a proxy server.

Returns:

this returns true if a tunnel has been established