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