HttpCore Tutorial
Oleg Kalnichevski
ii
Preface ................................................................................................................................... iv
1. HttpCore Scope ........................................................................................................... iv
2. HttpCore Goals ........................................................................................................... iv
3. What HttpCore is NOT ............................................................................................... iv
1. Fundamentals ....................................................................................................................... 1
1.1. HTTP messages ........................................................................................................ 1
1.1.1. Structure ........................................................................................................ 1
1.1.2. Basic operations ............................................................................................. 1
1.1.3. HTTP entity ................................................................................................... 3
1.1.4. Creating entities .............................................................................................. 5
1.2. Blocking HTTP connections ...................................................................................... 7
1.2.1. Working with blocking HTTP connections ....................................................... 8
1.2.2. Content transfer with blocking I/O ................................................................... 9
1.2.3. Supported content transfer mechanisms ............................................................ 9
1.2.4. Terminating HTTP connections ....................................................................... 9
1.3. HTTP exception handling ........................................................................................ 10
1.3.1. Protocol exception ........................................................................................ 10
1.4. HTTP protocol processors ........................................................................................ 10
1.4.1. Standard protocol interceptors ........................................................................ 10
1.4.2. Working with protocol processors .................................................................. 11
1.4.3. HTTP context ............................................................................................... 12
1.5. HTTP parameters .................................................................................................... 13
1.5.1. HTTP parameter beans .................................................................................. 14
1.6. Blocking HTTP protocol handlers ............................................................................ 14
1.6.1. HTTP service ............................................................................................... 14
1.6.2. HTTP request executor .................................................................................. 16
1.6.3. Connection persistence / re-use ...................................................................... 16
2. NIO extensions .................................................................................................................. 18
2.1. Benefits and shortcomings of the non-blocking I/O model .......................................... 18
2.2. Differences from other NIO frameworks ................................................................... 18
2.3. I/O reactor .............................................................................................................. 18
2.3.1. I/O dispatchers .............................................................................................. 18
2.3.2. I/O reactor shutdown ..................................................................................... 19
2.3.3. I/O sessions .................................................................................................. 19
2.3.4. I/O session state management ........................................................................ 19
2.3.5. I/O session event mask .................................................................................. 20
2.3.6. I/O session buffers ........................................................................................ 20
2.3.7. I/O session shutdown .................................................................................... 20
2.3.8. Listening I/O reactors .................................................................................... 20
2.3.9. Connecting I/O reactors ................................................................................. 21
2.3.10. Queuing of I/O interest set operations .......................................................... 22
2.4. I/O reactor exception handling ................................................................................. 23
2.4.1. I/O reactor audit log ...................................................................................... 23
2.5. Non-blocking HTTP connections .............................................................................. 24
2.5.1. Execution context of non-blocking HTTP connections ..................................... 24
2.5.2. Working with non-blocking HTTP connections ............................................... 24
2.5.3. HTTP I/O control ......................................................................................... 25
2.5.4. Non-blocking content transfer ........................................................................ 26
2.5.5. Supported non-blocking content transfer mechanisms ...................................... 27
HttpCore Tutorial
iii
2.5.6. Direct channel I/O ........................................................................................ 27
2.6. HTTP I/O event dispatchers ..................................................................................... 28
2.7. Non-blocking HTTP entities ..................................................................................... 30
2.7.1. Content consuming non-blocking HTTP entity ................................................ 30
2.7.2. Content producing non-blocking HTTP entity ................................................. 31
2.8. Non-blocking HTTP protocol handlers ...................................................................... 32
2.8.1. Asynchronous HTTP service handler ............................................................. 32
2.8.2. Asynchronous HTTP client handler ................................................................ 35
2.8.3. Compatibility with blocking I/O .................................................................... 37
2.8.4. Connection event listener .............................................................................. 38
2.9. Non-blocking TLS/SSL ............................................................................................ 38
2.9.1. SSL I/O session ............................................................................................ 38
2.9.2. SSL I/O event dispatches .............................................................................. 39
3. Advanced topics ................................................................................................................. 40
3.1. HTTP message parsing and formatting framework ..................................................... 40
3.1.1. HTTP line parsing and formatting .................................................................. 40
3.1.2. HTTP message streams and session I/O buffers .............................................. 42
3.1.3. HTTP message parsers and formatter ............................................................. 43
3.1.4. HTTP header parsing on demand ................................................................... 44
3.2. Customizing HTTP connections ............................................................................... 45
iv
Preface
HttpCore is a set of components implementing the most fundamental aspects of the HTTP protocol
that are nonetheless sufficient to develop full-featured client-side and server-side HTTP services with
a minimal footprint.
HttpCore has the following scope and goals:
1. HttpCore Scope
• A consistent API for building client / proxy / server side HTTP services
• A consistent API for building both synchronous and asynchronous HTTP services
• A set of low level components based on blocking (classic) and non-blocking (NIO) I/O models
2. HttpCore Goals
• Implementation of the most fundamental HTTP transport aspects
• Balance between good performance and the clarity & expressiveness of API
• Small (predictable) memory footprint
• Self contained library (no external dependencies beyond JRE)
3. What HttpCore is NOT
• A replacement for HttpClient
• A replacement for a Servlet container or a competitor to the Servlet API
1
Chapter 1. Fundamentals
1.1. HTTP messages
1.1.1. Structure
A HTTP message consists of a head and an optional body. The message head of an HTTP request
consists of a request line and a collection of header fields. The message head of an HTTP response
consists of a status line and a collection of header fields. All HTTP messages must include the protocol
version. Some HTTP messages can optionally enclose a content body.
HttpCore defines the HTTP message object model that closely follows the definition and provides
an extensive support for serialization (formatting) and deserialization (parsing) of HTTP message
elements.
1.1.2. Basic operations
1.1.2.1. HTTP request message
HTTP request is a message sent from the client to the server. The first line of that message includes
the method to be applied to the resource, the identifier of the resource, and the protocol version in use.
HttpRequest request = new BasicHttpRequest("GET", "/",
HttpVersion.HTTP_1_1);
System.out.println(request.getRequestLine().getMethod());
System.out.println(request.getRequestLine().getUri());
System.out.println(request.getProtocolVersion());
System.out.println(request.getRequestLine().toString());
stdout >
GET
/
HTTP/1.1
GET / HTTP/1.1
1.1.2.2. HTTP response message
HTTP response is a message sent by the server back to the client after having received and interpreted
a request message. The first line of that message consists of the protocol version followed by a numeric
status code and its associated textual phrase.
HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1,
HttpStatus.SC_OK, "OK");
System.out.println(response.getProtocolVersion());
System.out.println(response.getStatusLine().getStatusCode());
System.out.println(response.getStatusLine().getReasonPhrase());
System.out.println(response.getStatusLine().toString());
stdout >
