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 32 package org.apache.http.message; 33 34 35 import org.apache.http.HeaderElement; 36 import org.apache.http.NameValuePair; 37 import org.apache.http.ParseException; 38 import 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 * 52 * @deprecated Please use {@link java.net.URL#openConnection} instead. 53 * Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a> 54 * for further details. 55 */ 56 @Deprecated 57 public interface HeaderValueParser { 58 59 /** 60 * Parses a header value into elements. 61 * Parse errors are indicated as <code>RuntimeException</code>. 62 * <p> 63 * Some HTTP headers (such as the set-cookie header) have values that 64 * can be decomposed into multiple elements. In order to be processed 65 * by this parser, such headers must be in the following form: 66 * </p> 67 * <pre> 68 * header = [ element ] *( "," [ element ] ) 69 * element = name [ "=" [ value ] ] *( ";" [ param ] ) 70 * param = name [ "=" [ value ] ] 71 * 72 * name = token 73 * value = ( token | quoted-string ) 74 * 75 * token = 1*<any char except "=", ",", ";", <"> and 76 * white space> 77 * quoted-string = <"> *( text | quoted-char ) <"> 78 * text = any char except <"> 79 * quoted-char = "\" char 80 * </pre> 81 * <p> 82 * Any amount of white space is allowed between any part of the 83 * header, element or param and is ignored. A missing value in any 84 * element or param will be stored as the empty {@link String}; 85 * if the "=" is also missing <var>null</var> will be stored instead. 86 * </p> 87 * 88 * @param buffer buffer holding the header value to parse 89 * @param cursor the parser cursor containing the current position and 90 * the bounds within the buffer for the parsing operation 91 * 92 * @return an array holding all elements of the header value 93 * 94 * @throws ParseException in case of a parse error 95 */ parseElements( CharArrayBuffer buffer, ParserCursor cursor)96 HeaderElement[] parseElements( 97 CharArrayBuffer buffer, 98 ParserCursor cursor) throws ParseException; 99 100 /** 101 * Parses a single header element. 102 * A header element consist of a semicolon-separate list 103 * of name=value definitions. 104 * 105 * @param buffer buffer holding the element to parse 106 * @param cursor the parser cursor containing the current position and 107 * the bounds within the buffer for the parsing operation 108 * 109 * @return the parsed element 110 * 111 * @throws ParseException in case of a parse error 112 */ parseHeaderElement( CharArrayBuffer buffer, ParserCursor cursor)113 HeaderElement parseHeaderElement( 114 CharArrayBuffer buffer, 115 ParserCursor cursor) throws ParseException; 116 117 /** 118 * Parses a list of name-value pairs. 119 * These lists are used to specify parameters to a header element. 120 * Parse errors are indicated as <code>RuntimeException</code>. 121 * <p> 122 * This method comforms to the generic grammar and formatting rules 123 * outlined in the 124 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2" 125 * >Section 2.2</a> 126 * and 127 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6" 128 * >Section 3.6</a> 129 * of 130 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">RFC 2616</a>. 131 * </p> 132 * <h>2.2 Basic Rules</h> 133 * <p> 134 * The following rules are used throughout this specification to 135 * describe basic parsing constructs. 136 * The US-ASCII coded character set is defined by ANSI X3.4-1986. 137 * </p> 138 * <pre> 139 * OCTET = <any 8-bit sequence of data> 140 * CHAR = <any US-ASCII character (octets 0 - 127)> 141 * UPALPHA = <any US-ASCII uppercase letter "A".."Z"> 142 * LOALPHA = <any US-ASCII lowercase letter "a".."z"> 143 * ALPHA = UPALPHA | LOALPHA 144 * DIGIT = <any US-ASCII digit "0".."9"> 145 * CTL = <any US-ASCII control character 146 * (octets 0 - 31) and DEL (127)> 147 * CR = <US-ASCII CR, carriage return (13)> 148 * LF = <US-ASCII LF, linefeed (10)> 149 * SP = <US-ASCII SP, space (32)> 150 * HT = <US-ASCII HT, horizontal-tab (9)> 151 * <"> = <US-ASCII double-quote mark (34)> 152 * </pre> 153 * <p> 154 * Many HTTP/1.1 header field values consist of words separated 155 * by LWS or special characters. These special characters MUST be 156 * in a quoted string to be used within 157 * a parameter value (as defined in section 3.6). 158 * <p> 159 * <pre> 160 * token = 1*<any CHAR except CTLs or separators> 161 * separators = "(" | ")" | "<" | ">" | "@" 162 * | "," | ";" | ":" | "\" | <"> 163 * | "/" | "[" | "]" | "?" | "=" 164 * | "{" | "}" | SP | HT 165 * </pre> 166 * <p> 167 * A string of text is parsed as a single word if it is quoted using 168 * double-quote marks. 169 * </p> 170 * <pre> 171 * quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) 172 * qdtext = <any TEXT except <">> 173 * </pre> 174 * <p> 175 * The backslash character ("\") MAY be used as a single-character 176 * quoting mechanism only within quoted-string and comment constructs. 177 * </p> 178 * <pre> 179 * quoted-pair = "\" CHAR 180 * </pre> 181 * <h>3.6 Transfer Codings</h> 182 * <p> 183 * Parameters are in the form of attribute/value pairs. 184 * </p> 185 * <pre> 186 * parameter = attribute "=" value 187 * attribute = token 188 * value = token | quoted-string 189 * </pre> 190 * 191 * @param buffer buffer holding the name-value list to parse 192 * @param cursor the parser cursor containing the current position and 193 * the bounds within the buffer for the parsing operation 194 * 195 * @return an array holding all items of the name-value list 196 * 197 * @throws ParseException in case of a parse error 198 */ parseParameters( CharArrayBuffer buffer, ParserCursor cursor)199 NameValuePair[] parseParameters( 200 CharArrayBuffer buffer, 201 ParserCursor cursor) throws ParseException; 202 203 204 /** 205 * Parses a name=value specification, where the = and value are optional. 206 * 207 * @param buffer the buffer holding the name-value pair to parse 208 * @param cursor the parser cursor containing the current position and 209 * the bounds within the buffer for the parsing operation 210 * 211 * @return the name-value pair, where the value is <code>null</code> 212 * if no value is specified 213 */ parseNameValuePair( CharArrayBuffer buffer, ParserCursor cursor)214 NameValuePair parseNameValuePair( 215 CharArrayBuffer buffer, 216 ParserCursor cursor) throws ParseException; 217 218 } 219 220