1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.http.message;
29
30 import org.apache.http.Header;
31 import org.apache.http.ParseException;
32 import org.apache.http.ProtocolVersion;
33 import org.apache.http.RequestLine;
34 import org.apache.http.StatusLine;
35 import org.apache.http.util.CharArrayBuffer;
36
37 /**
38 * Interface for parsing lines in the HEAD section of an HTTP message.
39 * There are individual methods for parsing a request line, a
40 * status line, or a header line.
41 * The lines to parse are passed in memory, the parser does not depend
42 * on any specific IO mechanism.
43 * Instances of this interface are expected to be stateless and thread-safe.
44 *
45 * @since 4.0
46 */
47 public interface LineParser {
48
49 /**
50 * Parses the textual representation of a protocol version.
51 * This is needed for parsing request lines (last element)
52 * as well as status lines (first element).
53 *
54 * @param buffer a buffer holding the protocol version to parse
55 * @param cursor the parser cursor containing the current position and
56 * the bounds within the buffer for the parsing operation
57 *
58 * @return the parsed protocol version
59 *
60 * @throws ParseException in case of a parse error
61 */
62 ProtocolVersion parseProtocolVersion(
63 CharArrayBuffer buffer,
64 ParserCursor cursor) throws ParseException;
65
66 /**
67 * Checks whether there likely is a protocol version in a line.
68 * This method implements a <i>heuristic</i> to check for a
69 * likely protocol version specification. It does <i>not</i>
70 * guarantee that {@link #parseProtocolVersion} would not
71 * detect a parse error.
72 * This can be used to detect garbage lines before a request
73 * or status line.
74 *
75 * @param buffer a buffer holding the line to inspect
76 * @param cursor the cursor at which to check for a protocol version, or
77 * negative for "end of line". Whether the check tolerates
78 * whitespace before or after the protocol version is
79 * implementation dependent.
80 *
81 * @return {@code true} if there is a protocol version at the
82 * argument index (possibly ignoring whitespace),
83 * {@code false} otherwise
84 */
85 boolean hasProtocolVersion(
86 CharArrayBuffer buffer,
87 ParserCursor cursor);
88
89 /**
90 * Parses a request line.
91 *
92 * @param buffer a buffer holding the line to parse
93 * @param cursor the parser cursor containing the current position and
94 * the bounds within the buffer for the parsing operation
95 *
96 * @return the parsed request line
97 *
98 * @throws ParseException in case of a parse error
99 */
100 RequestLine parseRequestLine(
101 CharArrayBuffer buffer,
102 ParserCursor cursor) throws ParseException;
103
104 /**
105 * Parses a status line.
106 *
107 * @param buffer a buffer holding the line to parse
108 * @param cursor the parser cursor containing the current position and
109 * the bounds within the buffer for the parsing operation
110 *
111 * @return the parsed status line
112 *
113 * @throws ParseException in case of a parse error
114 */
115 StatusLine parseStatusLine(
116 CharArrayBuffer buffer,
117 ParserCursor cursor) throws ParseException;
118
119 /**
120 * Creates a header from a line.
121 * The full header line is expected here. Header continuation lines
122 * must be joined by the caller before invoking this method.
123 *
124 * @param buffer a buffer holding the full header line.
125 * This buffer MUST NOT be re-used afterwards, since
126 * the returned object may reference the contents later.
127 *
128 * @return the header in the argument buffer.
129 * The returned object MAY be a wrapper for the argument buffer.
130 * The argument buffer MUST NOT be re-used or changed afterwards.
131 *
132 * @throws ParseException in case of a parse error
133 */
134 Header parseHeader(CharArrayBuffer buffer)
135 throws ParseException;
136
137 }