michael@0: /* michael@0: * ==================================================================== michael@0: * Licensed to the Apache Software Foundation (ASF) under one michael@0: * or more contributor license agreements. See the NOTICE file michael@0: * distributed with this work for additional information michael@0: * regarding copyright ownership. The ASF licenses this file michael@0: * to you under the Apache License, Version 2.0 (the michael@0: * "License"); you may not use this file except in compliance michael@0: * with the License. You may obtain a copy of the License at michael@0: * michael@0: * http://www.apache.org/licenses/LICENSE-2.0 michael@0: * michael@0: * Unless required by applicable law or agreed to in writing, michael@0: * software distributed under the License is distributed on an michael@0: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY michael@0: * KIND, either express or implied. See the License for the michael@0: * specific language governing permissions and limitations michael@0: * under the License. michael@0: * ==================================================================== michael@0: * michael@0: * This software consists of voluntary contributions made by many michael@0: * individuals on behalf of the Apache Software Foundation. For more michael@0: * information on the Apache Software Foundation, please see michael@0: * . michael@0: * michael@0: */ michael@0: michael@0: package ch.boye.httpclientandroidlib.message; michael@0: michael@0: import ch.boye.httpclientandroidlib.HeaderElement; michael@0: import ch.boye.httpclientandroidlib.NameValuePair; michael@0: import ch.boye.httpclientandroidlib.ParseException; michael@0: import ch.boye.httpclientandroidlib.util.CharArrayBuffer; michael@0: michael@0: /** michael@0: * Interface for parsing header values into elements. michael@0: * Instances of this interface are expected to be stateless and thread-safe. michael@0: * michael@0: * @since 4.0 michael@0: */ michael@0: public interface HeaderValueParser { michael@0: michael@0: /** michael@0: * Parses a header value into elements. michael@0: * Parse errors are indicated as RuntimeException. michael@0: *

michael@0: * Some HTTP headers (such as the set-cookie header) have values that michael@0: * can be decomposed into multiple elements. In order to be processed michael@0: * by this parser, such headers must be in the following form: michael@0: *

michael@0: * 
michael@0:      * header  = [ element ] *( "," [ element ] )
michael@0:      * element = name [ "=" [ value ] ] *( ";" [ param ] )
michael@0:      * param   = name [ "=" [ value ] ]
michael@0:      *
michael@0:      * name    = token
michael@0:      * value   = ( token | quoted-string )
michael@0:      *
michael@0:      * token         = 1*<any char except "=", ",", ";", <"> and
michael@0:      *                       white space>
michael@0:      * quoted-string = <"> *( text | quoted-char ) <">
michael@0:      * text          = any char except <">
michael@0:      * quoted-char   = "\" char
michael@0:      *
michael@0: *

michael@0: * Any amount of white space is allowed between any part of the michael@0: * header, element or param and is ignored. A missing value in any michael@0: * element or param will be stored as the empty {@link String}; michael@0: * if the "=" is also missing null will be stored instead. michael@0: *

michael@0: * michael@0: * @param buffer buffer holding the header value to parse michael@0: * @param cursor the parser cursor containing the current position and michael@0: * the bounds within the buffer for the parsing operation michael@0: * michael@0: * @return an array holding all elements of the header value michael@0: * michael@0: * @throws ParseException in case of a parse error michael@0: */ michael@0: HeaderElement[] parseElements( michael@0: CharArrayBuffer buffer, michael@0: ParserCursor cursor) throws ParseException; michael@0: michael@0: /** michael@0: * Parses a single header element. michael@0: * A header element consist of a semicolon-separate list michael@0: * of name=value definitions. michael@0: * michael@0: * @param buffer buffer holding the element to parse michael@0: * @param cursor the parser cursor containing the current position and michael@0: * the bounds within the buffer for the parsing operation michael@0: * michael@0: * @return the parsed element michael@0: * michael@0: * @throws ParseException in case of a parse error michael@0: */ michael@0: HeaderElement parseHeaderElement( michael@0: CharArrayBuffer buffer, michael@0: ParserCursor cursor) throws ParseException; michael@0: michael@0: /** michael@0: * Parses a list of name-value pairs. michael@0: * These lists are used to specify parameters to a header element. michael@0: * Parse errors are indicated as ParseException. michael@0: * michael@0: * @param buffer buffer holding the name-value list to parse michael@0: * @param cursor the parser cursor containing the current position and michael@0: * the bounds within the buffer for the parsing operation michael@0: * michael@0: * @return an array holding all items of the name-value list michael@0: * michael@0: * @throws ParseException in case of a parse error michael@0: */ michael@0: NameValuePair[] parseParameters( michael@0: CharArrayBuffer buffer, michael@0: ParserCursor cursor) throws ParseException; michael@0: michael@0: michael@0: /** michael@0: * Parses a name=value specification, where the = and value are optional. michael@0: * michael@0: * @param buffer the buffer holding the name-value pair to parse michael@0: * @param cursor the parser cursor containing the current position and michael@0: * the bounds within the buffer for the parsing operation michael@0: * michael@0: * @return the name-value pair, where the value is null michael@0: * if no value is specified michael@0: */ michael@0: NameValuePair parseNameValuePair( michael@0: CharArrayBuffer buffer, michael@0: ParserCursor cursor) throws ParseException; michael@0: michael@0: } michael@0: