001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.message;
029
030import org.apache.http.HeaderElement;
031import org.apache.http.NameValuePair;
032import org.apache.http.ParseException;
033import org.apache.http.util.CharArrayBuffer;
034
035/**
036 * Interface for parsing header values into elements.
037 * Instances of this interface are expected to be stateless and thread-safe.
038 *
039 * @since 4.0
040 */
041public interface HeaderValueParser {
042
043    /**
044     * Parses a header value into elements.
045     * Parse errors are indicated as {@code RuntimeException}.
046     * <p>
047     * Some HTTP headers (such as the set-cookie header) have values that
048     * can be decomposed into multiple elements. In order to be processed
049     * by this parser, such headers must be in the following form:
050     * </p>
051     * <pre>
052     * header  = [ element ] *( "," [ element ] )
053     * element = name [ "=" [ value ] ] *( ";" [ param ] )
054     * param   = name [ "=" [ value ] ]
055     *
056     * name    = token
057     * value   = ( token | quoted-string )
058     *
059     * token         = 1*&lt;any char except "=", ",", ";", &lt;"&gt; and
060     *                       white space&gt;
061     * quoted-string = &lt;"&gt; *( text | quoted-char ) &lt;"&gt;
062     * text          = any char except &lt;"&gt;
063     * quoted-char   = "\" char
064     * </pre>
065     * <p>
066     * Any amount of white space is allowed between any part of the
067     * header, element or param and is ignored. A missing value in any
068     * element or param will be stored as the empty {@link String};
069     * if the "=" is also missing <var>null</var> will be stored instead.
070     * </p>
071     *
072     * @param buffer    buffer holding the header value to parse
073     * @param cursor    the parser cursor containing the current position and
074     *                  the bounds within the buffer for the parsing operation
075     *
076     * @return  an array holding all elements of the header value
077     *
078     * @throws ParseException        in case of a parsing error
079     */
080    HeaderElement[] parseElements(
081            CharArrayBuffer buffer,
082            ParserCursor cursor) throws ParseException;
083
084    /**
085     * Parses a single header element.
086     * A header element consist of a semicolon-separate list
087     * of name=value definitions.
088     *
089     * @param buffer    buffer holding the element to parse
090     * @param cursor    the parser cursor containing the current position and
091     *                  the bounds within the buffer for the parsing operation
092     *
093     * @return  the parsed element
094     *
095     * @throws ParseException        in case of a parse error
096     */
097    HeaderElement parseHeaderElement(
098            CharArrayBuffer buffer,
099            ParserCursor cursor) throws ParseException;
100
101    /**
102     * Parses a list of name-value pairs.
103     * These lists are used to specify parameters to a header element.
104     * Parse errors are indicated as {@code ParseException}.
105     *
106     * @param buffer    buffer holding the name-value list to parse
107     * @param cursor    the parser cursor containing the current position and
108     *                  the bounds within the buffer for the parsing operation
109     *
110     * @return  an array holding all items of the name-value list
111     *
112     * @throws ParseException        in case of a parse error
113     */
114    NameValuePair[] parseParameters(
115            CharArrayBuffer buffer,
116            ParserCursor cursor) throws ParseException;
117
118
119    /**
120     * Parses a name=value specification, where the = and value are optional.
121     *
122     * @param buffer    the buffer holding the name-value pair to parse
123     * @param cursor    the parser cursor containing the current position and
124     *                  the bounds within the buffer for the parsing operation
125     *
126     * @return  the name-value pair, where the value is {@code null}
127     *          if no value is specified
128     */
129    NameValuePair parseNameValuePair(
130            CharArrayBuffer buffer,
131            ParserCursor cursor) throws ParseException;
132
133}
134