1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
9
====================================================================
10
Licensed to the Apache Software Foundation (ASF) under one
11
or more contributor license agreements. See the NOTICE file
12
distributed with this work for additional information
13
regarding copyright ownership. The ASF licenses this file
14
to you under the Apache License, Version 2.0 (the
15
"License"); you may not use this file except in compliance
16
with the License. You may obtain a copy of the License at
18
http://www.apache.org/licenses/LICENSE-2.0
20
Unless required by applicable law or agreed to in writing,
21
software distributed under the License is distributed on an
22
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
23
KIND, either express or implied. See the License for the
24
specific language governing permissions and limitations
26
====================================================================
29
<chapter id="advanced">
30
<title>Advanced topics</title>
32
<title>HTTP message parsing and formatting framework</title>
34
HTTP message processing framework is designed to be expressive and flexible while remaining
35
memory efficient and fast. HttpCore HTTP message processing code achieves near zero
36
intermediate garbage and near zero-copy buffering for its parsing and formatting
37
operations. The same HTTP message parsing and formatting API and implementations are used
38
by both the blocking and non-blocking transport implementations, which helps ensure a
39
consistent behavior of HTTP services regardless of the I/O model.
42
<title>HTTP line parsing and formatting</title>
44
HttpCore utilizes a number of low level components for all its line parsing and
48
<classname>CharArrayBuffer</classname> represents a sequence of characters, usually a
49
single line in an HTTP message stream such as a request line, a status line or a
50
header. Internally <classname>CharArrayBuffer</classname> is backed by an array of
51
chars, which can be expanded to accommodate more input if needed. <classname>
52
CharArrayBuffer</classname> also provides a number of utility methods for manipulating
53
content of the buffer, storing more data and retrieving subsets of data.
55
<programlisting><![CDATA[
56
CharArrayBuffer buf = new CharArrayBuffer(64);
57
buf.append("header: data ");
58
int i = buf.indexOf(':');
59
String s = buf.substringTrimmed(i + 1, buf.length());
60
System.out.println(s);
61
System.out.println(s.length());
63
<para>stdout ></para>
64
<programlisting><![CDATA[
69
<classname>ParserCursor</classname> represents a context of a parsing operation: the
70
bounds limiting the scope of the parsing operation and the current position the parsing
71
operation is expected to start at.
73
<programlisting><![CDATA[
74
CharArrayBuffer buf = new CharArrayBuffer(64);
75
buf.append("header: data ");
76
int i = buf.indexOf(':');
77
ParserCursor cursor = new ParserCursor(0, buf.length());
78
cursor.updatePos(i + 1);
79
System.out.println(cursor);
81
<para>stdout ></para>
82
<programlisting><![CDATA[
86
<interfacename>LineParser</interfacename> is the interface for parsing lines in the
87
head section of an HTTP message. There are individual methods for parsing a request
88
line, a status line, or a header line. The lines to parse are passed in memory, the
89
parser does not depend on any specific I/O mechanism.
91
<programlisting><![CDATA[
92
CharArrayBuffer buf = new CharArrayBuffer(64);
93
buf.append("HTTP/1.1 200");
94
ParserCursor cursor = new ParserCursor(0, buf.length());
96
LineParser parser = new BasicLineParser();
97
ProtocolVersion ver = parser.parseProtocolVersion(buf, cursor);
98
System.out.println(ver);
99
System.out.println(buf.substringTrimmed(
101
cursor.getUpperBound()));
103
<para>stdout ></para>
104
<programlisting><![CDATA[
108
<programlisting><![CDATA[
109
CharArrayBuffer buf = new CharArrayBuffer(64);
110
buf.append("HTTP/1.1 200 OK");
111
ParserCursor cursor = new ParserCursor(0, buf.length());
112
LineParser parser = new BasicLineParser();
113
StatusLine sl = parser.parseStatusLine(buf, cursor);
114
System.out.println(sl.getReasonPhrase());
116
<para>stdout ></para>
117
<programlisting><![CDATA[
121
<interfacename>LineFormatter</interfacename> for formatting elements of the head
122
section of an HTTP message. This is the complement to <interfacename>LineParser
123
</interfacename>. There are individual methods for formatting a request line, a status
124
line, or a header line.
127
Please note the formatting does not include the trailing line break sequence
128
<literal>CR-LF</literal>.
130
<programlisting><![CDATA[
131
CharArrayBuffer buf = new CharArrayBuffer(64);
132
LineFormatter formatter = new BasicLineFormatter();
133
formatter.formatRequestLine(buf,
134
new BasicRequestLine("GET", "/", HttpVersion.HTTP_1_1));
135
System.out.println(buf.toString());
136
formatter.formatHeader(buf,
137
new BasicHeader("Content-Type", "text/plain"));
138
System.out.println(buf.toString());
140
<para>stdout ></para>
141
<programlisting><![CDATA[
143
Content-Type: text/plain
146
<interfacename>HeaderValueParser</interfacename> is the interface for parsing header
147
values into elements.
149
<programlisting><![CDATA[
150
CharArrayBuffer buf = new CharArrayBuffer(64);
151
HeaderValueParser parser = new BasicHeaderValueParser();
152
buf.append("name1=value1; param1=p1, " +
153
"name2 = \"value2\", name3 = value3");
154
ParserCursor cursor = new ParserCursor(0, buf.length());
155
System.out.println(parser.parseHeaderElement(buf, cursor));
156
System.out.println(parser.parseHeaderElement(buf, cursor));
157
System.out.println(parser.parseHeaderElement(buf, cursor));
159
<para>stdout ></para>
160
<programlisting><![CDATA[
161
name1=value1; param1=p1
166
<interfacename>HeaderValueFormatter</interfacename> is the interface for formatting
167
elements of a header value. This is the complement to <interfacename>HeaderValueParser
170
<programlisting><![CDATA[
171
CharArrayBuffer buf = new CharArrayBuffer(64);
172
HeaderValueFormatter formatter = new BasicHeaderValueFormatter();
173
HeaderElement[] hes = new HeaderElement[] {
174
new BasicHeaderElement("name1", "value1",
175
new NameValuePair[] {
176
new BasicNameValuePair("param1", "p1")} ),
177
new BasicHeaderElement("name2", "value2"),
178
new BasicHeaderElement("name3", "value3"),
180
formatter.formatElements(buf, hes, true);
181
System.out.println(buf.toString());
183
<para>stdout ></para>
184
<programlisting><
added
removed
src/docbkx/advanced.xml
