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.hc.core5.http.message;
29
30 import org.apache.hc.core5.http.HeaderElement;
31 import org.apache.hc.core5.http.NameValuePair;
32
33 /**
34 * Interface for parsing header values into elements.
35 * Instances of this interface are expected to be stateless and thread-safe.
36 *
37 * @since 4.0
38 */
39 public interface HeaderValueParser {
40
41 /**
42 * Parses a header value into elements.
43 * Parse errors are indicated as {@code RuntimeException}.
44 *
45 * @param buffer buffer holding the header value to parse
46 * @param cursor the parser cursor containing the current position and
47 * the bounds within the buffer for the parsing operation
48 *
49 * @return an array holding all elements of the header value
50 */
51 HeaderElement[] parseElements(CharSequence buffer, ParserCursor cursor);
52
53 /**
54 * Parses a single header element.
55 * A header element consist of a semicolon-separate list
56 * of name=value definitions.
57 *
58 * @param buffer buffer holding the element to parse
59 * @param cursor the parser cursor containing the current position and
60 * the bounds within the buffer for the parsing operation
61 *
62 * @return the parsed element
63 */
64 HeaderElement parseHeaderElement(CharSequence buffer, ParserCursor cursor);
65
66 /**
67 * Parses a list of name-value pairs.
68 * These lists are used to specify parameters to a header element.
69 * Parse errors are indicated as {@code ParseException}.
70 *
71 * @param buffer buffer holding the name-value list to parse
72 * @param cursor the parser cursor containing the current position and
73 * the bounds within the buffer for the parsing operation
74 *
75 * @return an array holding all items of the name-value list
76 */
77 NameValuePair[] parseParameters(CharSequence buffer, ParserCursor cursor);
78
79
80 /**
81 * Parses a name=value specification, where the = and value are optional.
82 *
83 * @param buffer the buffer holding the name-value pair to parse
84 * @param cursor the parser cursor containing the current position and
85 * the bounds within the buffer for the parsing operation
86 *
87 * @return the name-value pair, where the value is {@code null}
88 * if no value is specified
89 */
90 NameValuePair parseNameValuePair(CharSequence buffer, ParserCursor cursor);
91
92 }
93