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.HeaderElement;
31 import org.apache.http.NameValuePair;
32 import org.apache.http.ParseException;
33 import org.apache.http.util.CharArrayBuffer;
34
35 /**
36 * Interface for parsing header values into elements.
37 * Instances of this interface are expected to be stateless and thread-safe.
38 *
39 * @since 4.0
40 */
41 public interface HeaderValueParser {
42
43 /**
44 * Parses a header value into elements.
45 * Parse errors are indicated as {@code RuntimeException}.
46 * <p>
47 * Some HTTP headers (such as the set-cookie header) have values that
48 * can be decomposed into multiple elements. In order to be processed
49 * by this parser, such headers must be in the following form:
50 * </p>
51 * <pre>
52 * header = [ element ] *( "," [ element ] )
53 * element = name [ "=" [ value ] ] *( ";" [ param ] )
54 * param = name [ "=" [ value ] ]
55 *
56 * name = token
57 * value = ( token | quoted-string )
58 *
59 * token = 1*<any char except "=", ",", ";", <"> and
60 * white space>
61 * quoted-string = <"> *( text | quoted-char ) <">
62 * text = any char except <">
63 * quoted-char = "\" char
64 * </pre>
65 * <p>
66 * Any amount of white space is allowed between any part of the
67 * header, element or param and is ignored. A missing value in any
68 * element or param will be stored as the empty {@link String};
69 * if the "=" is also missing <var>null</var> will be stored instead.
70 * </p>
71 * <p>
72 * Note that this parser does not apply to list-typed HTTP header fields in
73 * general; it is only suitable for fields that use the syntax described
74 * above. Counter-examples are "Link" (RFC 8288), "If-None-Match" (RFC 7232)
75 * or "Dav" (RFC 4918).
76 * </p>
77 *
78 * @param buffer buffer holding the header value to parse
79 * @param cursor the parser cursor containing the current position and
80 * the bounds within the buffer for the parsing operation
81 *
82 * @return an array holding all elements of the header value
83 *
84 * @throws ParseException in case of a parsing error
85 */
86 HeaderElement[] parseElements(
87 CharArrayBuffer buffer,
88 ParserCursor cursor) throws ParseException;
89
90 /**
91 * Parses a single header element.
92 * A header element consist of a semicolon-separate list
93 * of name=value definitions.
94 *
95 * @param buffer buffer holding the element to parse
96 * @param cursor the parser cursor containing the current position and
97 * the bounds within the buffer for the parsing operation
98 *
99 * @return the parsed element
100 *
101 * @throws ParseException in case of a parse error
102 */
103 HeaderElement parseHeaderElement(
104 CharArrayBuffer buffer,
105 ParserCursor cursor) throws ParseException;
106
107 /**
108 * Parses a list of name-value pairs.
109 * These lists are used to specify parameters to a header element.
110 * Parse errors are indicated as {@code ParseException}.
111 *
112 * @param buffer buffer holding the name-value list to parse
113 * @param cursor the parser cursor containing the current position and
114 * the bounds within the buffer for the parsing operation
115 *
116 * @return an array holding all items of the name-value list
117 *
118 * @throws ParseException in case of a parse error
119 */
120 NameValuePair[] parseParameters(
121 CharArrayBuffer buffer,
122 ParserCursor cursor) throws ParseException;
123
124
125 /**
126 * Parses a name=value specification, where the = and value are optional.
127 *
128 * @param buffer the buffer holding the name-value pair to parse
129 * @param cursor the parser cursor containing the current position and
130 * the bounds within the buffer for the parsing operation
131 *
132 * @return the name-value pair, where the value is {@code null}
133 * if no value is specified
134 */
135 NameValuePair parseNameValuePair(
136 CharArrayBuffer buffer,
137 ParserCursor cursor) throws ParseException;
138
139 }
140