Provides classes for parsing the stream of bytes comprising an HTTP request or response into HttpMessage (and subsidary) objects.

If you want to parse a message, you will want to use the Http1xRequestParser and Http1xResponseParser. These are the only classes from this package which you will need to interface with. For examples of using the classes, see the corresponding unit tests.

If you need to maintain/modify the parsing logic, you should first consult the UML diagrams for an overview of the class hierarchy. The next thing you will need to know is that these parsers are developed with two overriding goals:

1. minimize memory allocations when reading and writing messages
2. be robust when parsing messages that do not follow the spec

• use ByteBuffers for moving data into the parser - for an easy transition to the Java New I/O classes (java.nio)
• preservation of the raw content - to allow previously-recorded data to be re-parsed by new parser version for transparent error correction
• all I/O and parsing work should be performed on byte[]s. This is slightly more difficult to code and debug, but MUCH more efficient for I/O. Tranforming headers into Strings, for example, requires many memory allocations.
• pluggable parsers for different versions - for implementing new (HTTP/1.2?) and old (HTTP/1.0) parsers
• follow the HTTP spec as closely as possible, including naming conventions - for ease of understanding for future developers
• modularize the parser - this greatly eases readability and unit testing

The basic flow of parsing a message goes like this:

1. Instantiate a parser (Http1xRequestParser or Http1xResponseParser) - a more generic parser seemed unnecessary, since the context of browser/server/proxy applications imply that you KNOW if the message you to be parsed from a given source is a request or a response.
2. These two classes extend the Http1xParser - which will parse incoming bytes looking for the end of the start-line.
3. When the end of the start-line is found, the Http1xParser will instantiate the appropriate type of start-line object (RequestLine or StatusLine). This function is delegated to the subclasses.
4. After the start-line has been received, the version can be determined and the appropriate parser instantiated. All further incoming bytes will be passed to these more-specific parsers (Http11RequestParser and Http11ResponseParser, for example). The job of Http1xParser is done.
5. Since the process of parsing of the rest of the message is identical for requests and responses, a superclass, Http11MessageParser, performs most of the work. The version-specific request/response parsers (Http11RequestParser and Http11ResponseParser) primarily serve as factories for the correct object type (HttpRequest or HttpResponse) after the parsing is complete.
6. When Http11MessageParser receives it's first bytes, it will be looking for headers. The task of parsing bytes that makeup the header (and looking for the end of the header) is delegated to a HeaderParser. If the HeaderParser finds terminators immeditately, then the response does not contain any headers (or body) and it's job (and the message) is complete.
7. After the HeaderParser indicates that the headers have been parsed, the Http11MessageParser will use the BodyParserFactory to determine if the message contains a body and, if so, what parser class is appropriate. The BodyParserFactory should provide a mechanism for caching/reusing body parsers - to eliminate the need for continuously allocating new ones. This functionality is not yet complete.
8. Any incoming bytes will now be passed to the BodyParser until it reports that the entire body has been received.
9. After the body parsing is complete, the message may be retrieved from the parser.
10. Prior to re-using the primary parser object to parse another message, it should be reset(), which will return it to it's initial state. This will also reset all of the delegate parsers.

Miscellaneous notes and concepts:

• TerminationDetector is a stateful class used by the Http1xParser and HeaderParser for detecting ASCII line terminations.
• Most of the parser classes maintain state so that messages can be parsed byte-by-byte as they arrive.
• Certain parsers do not need to be stateful, because they parse a small amount of data at a time - these include the RequestLineParser, StatusLineParser and VersionParser. Since these parsers do not need to maintain state, their parsing methods are static, to reduce memory consumption.