1/* 2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/HeaderValueParser.java $ 3 * $Revision: 589325 $ 4 * $Date: 2007-10-28 03:37:56 -0700 (Sun, 28 Oct 2007) $ 5 * 6 * ==================================================================== 7 * Licensed to the Apache Software Foundation (ASF) under one 8 * or more contributor license agreements. See the NOTICE file 9 * distributed with this work for additional information 10 * regarding copyright ownership. The ASF licenses this file 11 * to you under the Apache License, Version 2.0 (the 12 * "License"); you may not use this file except in compliance 13 * with the License. You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * 17 * Unless required by applicable law or agreed to in writing, 18 * software distributed under the License is distributed on an 19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 20 * KIND, either express or implied. See the License for the 21 * specific language governing permissions and limitations 22 * under the License. 23 * ==================================================================== 24 * 25 * This software consists of voluntary contributions made by many 26 * individuals on behalf of the Apache Software Foundation. For more 27 * information on the Apache Software Foundation, please see 28 * <http://www.apache.org/>. 29 * 30 */ 31 32package org.apache.http.message; 33 34 35import org.apache.http.HeaderElement; 36import org.apache.http.NameValuePair; 37import org.apache.http.ParseException; 38import org.apache.http.util.CharArrayBuffer; 39 40 41 42/** 43 * Interface for parsing header values into elements. 44 * Instances of this interface are expected to be stateless and thread-safe. 45 * 46 * 47 * <!-- empty lines above to avoid 'svn diff' context problems --> 48 * @version $Revision: 589325 $ $Date: 2007-10-28 03:37:56 -0700 (Sun, 28 Oct 2007) $ 49 * 50 * @since 4.0 51 */ 52public interface HeaderValueParser { 53 54 /** 55 * Parses a header value into elements. 56 * Parse errors are indicated as <code>RuntimeException</code>. 57 * <p> 58 * Some HTTP headers (such as the set-cookie header) have values that 59 * can be decomposed into multiple elements. In order to be processed 60 * by this parser, such headers must be in the following form: 61 * </p> 62 * <pre> 63 * header = [ element ] *( "," [ element ] ) 64 * element = name [ "=" [ value ] ] *( ";" [ param ] ) 65 * param = name [ "=" [ value ] ] 66 * 67 * name = token 68 * value = ( token | quoted-string ) 69 * 70 * token = 1*<any char except "=", ",", ";", <"> and 71 * white space> 72 * quoted-string = <"> *( text | quoted-char ) <"> 73 * text = any char except <"> 74 * quoted-char = "\" char 75 * </pre> 76 * <p> 77 * Any amount of white space is allowed between any part of the 78 * header, element or param and is ignored. A missing value in any 79 * element or param will be stored as the empty {@link String}; 80 * if the "=" is also missing <var>null</var> will be stored instead. 81 * </p> 82 * 83 * @param buffer buffer holding the header value 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 an array holding all elements of the header value 88 * 89 * @throws ParseException in case of a parse error 90 */ 91 HeaderElement[] parseElements( 92 CharArrayBuffer buffer, 93 ParserCursor cursor) throws ParseException; 94 95 /** 96 * Parses a single header element. 97 * A header element consist of a semicolon-separate list 98 * of name=value definitions. 99 * 100 * @param buffer buffer holding the element to parse 101 * @param cursor the parser cursor containing the current position and 102 * the bounds within the buffer for the parsing operation 103 * 104 * @return the parsed element 105 * 106 * @throws ParseException in case of a parse error 107 */ 108 HeaderElement parseHeaderElement( 109 CharArrayBuffer buffer, 110 ParserCursor cursor) throws ParseException; 111 112 /** 113 * Parses a list of name-value pairs. 114 * These lists are used to specify parameters to a header element. 115 * Parse errors are indicated as <code>RuntimeException</code>. 116 * <p> 117 * This method comforms to the generic grammar and formatting rules 118 * outlined in the 119 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2" 120 * >Section 2.2</a> 121 * and 122 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6" 123 * >Section 3.6</a> 124 * of 125 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">RFC 2616</a>. 126 * </p> 127 * <h>2.2 Basic Rules</h> 128 * <p> 129 * The following rules are used throughout this specification to 130 * describe basic parsing constructs. 131 * The US-ASCII coded character set is defined by ANSI X3.4-1986. 132 * </p> 133 * <pre> 134 * OCTET = <any 8-bit sequence of data> 135 * CHAR = <any US-ASCII character (octets 0 - 127)> 136 * UPALPHA = <any US-ASCII uppercase letter "A".."Z"> 137 * LOALPHA = <any US-ASCII lowercase letter "a".."z"> 138 * ALPHA = UPALPHA | LOALPHA 139 * DIGIT = <any US-ASCII digit "0".."9"> 140 * CTL = <any US-ASCII control character 141 * (octets 0 - 31) and DEL (127)> 142 * CR = <US-ASCII CR, carriage return (13)> 143 * LF = <US-ASCII LF, linefeed (10)> 144 * SP = <US-ASCII SP, space (32)> 145 * HT = <US-ASCII HT, horizontal-tab (9)> 146 * <"> = <US-ASCII double-quote mark (34)> 147 * </pre> 148 * <p> 149 * Many HTTP/1.1 header field values consist of words separated 150 * by LWS or special characters. These special characters MUST be 151 * in a quoted string to be used within 152 * a parameter value (as defined in section 3.6). 153 * <p> 154 * <pre> 155 * token = 1*<any CHAR except CTLs or separators> 156 * separators = "(" | ")" | "<" | ">" | "@" 157 * | "," | ";" | ":" | "\" | <"> 158 * | "/" | "[" | "]" | "?" | "=" 159 * | "{" | "}" | SP | HT 160 * </pre> 161 * <p> 162 * A string of text is parsed as a single word if it is quoted using 163 * double-quote marks. 164 * </p> 165 * <pre> 166 * quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) 167 * qdtext = <any TEXT except <">> 168 * </pre> 169 * <p> 170 * The backslash character ("\") MAY be used as a single-character 171 * quoting mechanism only within quoted-string and comment constructs. 172 * </p> 173 * <pre> 174 * quoted-pair = "\" CHAR 175 * </pre> 176 * <h>3.6 Transfer Codings</h> 177 * <p> 178 * Parameters are in the form of attribute/value pairs. 179 * </p> 180 * <pre> 181 * parameter = attribute "=" value 182 * attribute = token 183 * value = token | quoted-string 184 * </pre> 185 * 186 * @param buffer buffer holding the name-value list to parse 187 * @param cursor the parser cursor containing the current position and 188 * the bounds within the buffer for the parsing operation 189 * 190 * @return an array holding all items of the name-value list 191 * 192 * @throws ParseException in case of a parse error 193 */ 194 NameValuePair[] parseParameters( 195 CharArrayBuffer buffer, 196 ParserCursor cursor) throws ParseException; 197 198 199 /** 200 * Parses a name=value specification, where the = and value are optional. 201 * 202 * @param buffer the buffer holding the name-value pair to parse 203 * @param cursor the parser cursor containing the current position and 204 * the bounds within the buffer for the parsing operation 205 * 206 * @return the name-value pair, where the value is <code>null</code> 207 * if no value is specified 208 */ 209 NameValuePair parseNameValuePair( 210 CharArrayBuffer buffer, 211 ParserCursor cursor) throws ParseException; 212 213} 214 215