[jetty-dev] HttpParser javadoc

[Greg Wilkins <gregw@xxxxxxxxxxx>]

In response to Simone asking some questions, I've improved the javadoc of the HTTP Parser and associated classes (see below).  Feedback to further improve is welcome:

org.eclipse.jetty.http.HttpParser

A Parser for HTTP 0.9, 1.0 and 1.1

The is parser parses HTTP client and server messages from buffers passed in the parseNext(ByteBuffer) method. The parsed elements of the HTTP message are passed as event calls to the HttpHandler instance the parser is constructed with. If the passed handler is a RequestHandler then server side parsing is performed and if it is a ResponseHandler, then client side parsing is done.

The contract of the HttpHandler API is that if a call returns true then the call to parseNext(ByteBuffer) will return as soon as possible also with a true response. Typically this indicates that the parsing has reached a stage where the caller should process the events accumulated by the handler. It is the preferred calling style that handling such as calling a servlet to process a request, should be done after a true return fromparseNext(ByteBuffer) rather than from within the scope of a call like RequestHandler.messageComplete()

For performance, the parse is heavily dependent on the Trie.getBest(ByteBuffer, int, int) method to look ahead in a single pass for both the structure ( : and CRLF ) and semantic (which header and value) of a header. Specifically the static HttpField.CACHE is used to lookup common combinations of headers and values (eg. "Connection: close"), or just header names (eg. "Connection:" ). For headers who's value is not known statically (eg. Host, COOKIE) then a per parser dynamic Trie of HttpFields from previous parsed messages is used to help the parsing of subsequent messages.

Trie<HttpField> org.eclipse.jetty.http.HttpField.CACHE

Cache of common HttpFields including:

• Common static combinations such as:
  • Connection: close
  • Accept-Encoding: gzip
  • Content-Length: 0
• Combinations of Content-Type header for common mime types by common charsets
• Most common headers with null values so that a lookup will at least determine the header name even if the name:value combination is not cached

org.eclipse.jetty.util.ArrayTernaryTrie<V>

A Ternary Trie String lookup data structure. This Trie is of a fixed size and cannot grow (which can be a good thing with regards to DOS when used as a cache).

The Trie is stored in 3 arrays:

char[] _tree

This is semantically 2 dimensional array flattened into a 1 dimensional char array. The second dimension is that every 4 sequential elements represents a row of: character; hi index; eq index; low index, used to build a ternary trie of key strings.

String[] _key

An array of key values where each element matches a row in the _tree array. A non zero key element indicates that the _tree row is a complete key rather than an intermediate character of a longer key.

V[] _value

An array of values corresponding to the _key array

The lookup of a value will iterate through the _tree array matching characters. If the equal tree branch is followed, then the _key array is looked up to see if this is a complete match. If a match is found then the _value array is looked up to return the matching value.

--
Greg Wilkins <gregw@xxxxxxxxxxx>
http://www.webtide.com
Developer advice and support from the Jetty & CometD experts.
Intalio, the modern way to build business applications.