001: /*
002: * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0-beta1/module-main/src/main/java/org/apache/http/message/HeaderValueParser.java $
003: * $Revision: 589325 $
004: * $Date: 2007-10-28 11:37:56 +0100 (Sun, 28 Oct 2007) $
005: *
006: * ====================================================================
007: * Licensed to the Apache Software Foundation (ASF) under one
008: * or more contributor license agreements. See the NOTICE file
009: * distributed with this work for additional information
010: * regarding copyright ownership. The ASF licenses this file
011: * to you under the Apache License, Version 2.0 (the
012: * "License"); you may not use this file except in compliance
013: * with the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing,
018: * software distributed under the License is distributed on an
019: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
020: * KIND, either express or implied. See the License for the
021: * specific language governing permissions and limitations
022: * under the License.
023: * ====================================================================
024: *
025: * This software consists of voluntary contributions made by many
026: * individuals on behalf of the Apache Software Foundation. For more
027: * information on the Apache Software Foundation, please see
028: * <http://www.apache.org/>.
029: *
030: */
031:
032: package org.apache.http.message;
033:
034: import org.apache.http.HeaderElement;
035: import org.apache.http.NameValuePair;
036: import org.apache.http.ParseException;
037: import org.apache.http.util.CharArrayBuffer;
038:
039: /**
040: * Interface for parsing header values into elements.
041: * Instances of this interface are expected to be stateless and thread-safe.
042: *
043: *
044: * <!-- empty lines above to avoid 'svn diff' context problems -->
045: * @version $Revision: 589325 $ $Date: 2007-10-28 11:37:56 +0100 (Sun, 28 Oct 2007) $
046: *
047: * @since 4.0
048: */
049: public interface HeaderValueParser {
050:
051: /**
052: * Parses a header value into elements.
053: * Parse errors are indicated as <code>RuntimeException</code>.
054: * <p>
055: * Some HTTP headers (such as the set-cookie header) have values that
056: * can be decomposed into multiple elements. In order to be processed
057: * by this parser, such headers must be in the following form:
058: * </p>
059: * <pre>
060: * header = [ element ] *( "," [ element ] )
061: * element = name [ "=" [ value ] ] *( ";" [ param ] )
062: * param = name [ "=" [ value ] ]
063: *
064: * name = token
065: * value = ( token | quoted-string )
066: *
067: * token = 1*<any char except "=", ",", ";", <"> and
068: * white space>
069: * quoted-string = <"> *( text | quoted-char ) <">
070: * text = any char except <">
071: * quoted-char = "\" char
072: * </pre>
073: * <p>
074: * Any amount of white space is allowed between any part of the
075: * header, element or param and is ignored. A missing value in any
076: * element or param will be stored as the empty {@link String};
077: * if the "=" is also missing <var>null</var> will be stored instead.
078: * </p>
079: *
080: * @param buffer buffer holding the header value to parse
081: * @param cursor the parser cursor containing the current position and
082: * the bounds within the buffer for the parsing operation
083: *
084: * @return an array holding all elements of the header value
085: *
086: * @throws ParseException in case of a parse error
087: */
088: HeaderElement[] parseElements(CharArrayBuffer buffer,
089: ParserCursor cursor) throws ParseException;
090:
091: /**
092: * Parses a single header element.
093: * A header element consist of a semicolon-separate list
094: * of name=value definitions.
095: *
096: * @param buffer buffer holding the element to parse
097: * @param cursor the parser cursor containing the current position and
098: * the bounds within the buffer for the parsing operation
099: *
100: * @return the parsed element
101: *
102: * @throws ParseException in case of a parse error
103: */
104: HeaderElement parseHeaderElement(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>RuntimeException</code>.
111: * <p>
112: * This method comforms to the generic grammar and formatting rules
113: * outlined in the
114: * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2"
115: * >Section 2.2</a>
116: * and
117: * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6"
118: * >Section 3.6</a>
119: * of
120: * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">RFC 2616</a>.
121: * </p>
122: * <h>2.2 Basic Rules</h>
123: * <p>
124: * The following rules are used throughout this specification to
125: * describe basic parsing constructs.
126: * The US-ASCII coded character set is defined by ANSI X3.4-1986.
127: * </p>
128: * <pre>
129: * OCTET = <any 8-bit sequence of data>
130: * CHAR = <any US-ASCII character (octets 0 - 127)>
131: * UPALPHA = <any US-ASCII uppercase letter "A".."Z">
132: * LOALPHA = <any US-ASCII lowercase letter "a".."z">
133: * ALPHA = UPALPHA | LOALPHA
134: * DIGIT = <any US-ASCII digit "0".."9">
135: * CTL = <any US-ASCII control character
136: * (octets 0 - 31) and DEL (127)>
137: * CR = <US-ASCII CR, carriage return (13)>
138: * LF = <US-ASCII LF, linefeed (10)>
139: * SP = <US-ASCII SP, space (32)>
140: * HT = <US-ASCII HT, horizontal-tab (9)>
141: * <"> = <US-ASCII double-quote mark (34)>
142: * </pre>
143: * <p>
144: * Many HTTP/1.1 header field values consist of words separated
145: * by LWS or special characters. These special characters MUST be
146: * in a quoted string to be used within
147: * a parameter value (as defined in section 3.6).
148: * <p>
149: * <pre>
150: * token = 1*<any CHAR except CTLs or separators>
151: * separators = "(" | ")" | "<" | ">" | "@"
152: * | "," | ";" | ":" | "\" | <">
153: * | "/" | "[" | "]" | "?" | "="
154: * | "{" | "}" | SP | HT
155: * </pre>
156: * <p>
157: * A string of text is parsed as a single word if it is quoted using
158: * double-quote marks.
159: * </p>
160: * <pre>
161: * quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
162: * qdtext = <any TEXT except <">>
163: * </pre>
164: * <p>
165: * The backslash character ("\") MAY be used as a single-character
166: * quoting mechanism only within quoted-string and comment constructs.
167: * </p>
168: * <pre>
169: * quoted-pair = "\" CHAR
170: * </pre>
171: * <h>3.6 Transfer Codings</h>
172: * <p>
173: * Parameters are in the form of attribute/value pairs.
174: * </p>
175: * <pre>
176: * parameter = attribute "=" value
177: * attribute = token
178: * value = token | quoted-string
179: * </pre>
180: *
181: * @param buffer buffer holding the name-value list to parse
182: * @param cursor the parser cursor containing the current position and
183: * the bounds within the buffer for the parsing operation
184: *
185: * @return an array holding all items of the name-value list
186: *
187: * @throws ParseException in case of a parse error
188: */
189: NameValuePair[] parseParameters(CharArrayBuffer buffer,
190: ParserCursor cursor) throws ParseException;
191:
192: /**
193: * Parses a name=value specification, where the = and value are optional.
194: *
195: * @param buffer the buffer holding the name-value pair to parse
196: * @param cursor the parser cursor containing the current position and
197: * the bounds within the buffer for the parsing operation
198: *
199: * @return the name-value pair, where the value is <code>null</code>
200: * if no value is specified
201: */
202: NameValuePair parseNameValuePair(CharArrayBuffer buffer,
203: ParserCursor cursor) throws ParseException;
204:
205: }
|