001: /*
002: * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0-beta1/module-main/src/main/java/org/apache/http/message/LineParser.java $
003: * $Revision: 589374 $
004: * $Date: 2007-10-28 17:25:07 +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.ProtocolVersion;
035: import org.apache.http.ParseException;
036: import org.apache.http.RequestLine;
037: import org.apache.http.StatusLine;
038: import org.apache.http.Header;
039: import org.apache.http.util.CharArrayBuffer;
040:
041: /**
042: * Interface for parsing lines in the HEAD section of an HTTP message.
043: * There are individual methods for parsing a request line, a
044: * status line, or a header line.
045: * The lines to parse are passed in memory, the parser does not depend
046: * on any specific IO mechanism.
047: * Instances of this interface are expected to be stateless and thread-safe.
048: *
049: * @author <a href="mailto:rolandw AT apache.org">Roland Weber</a>
050: *
051: *
052: * <!-- empty lines above to avoid 'svn diff' context problems -->
053: * @version $Revision: 589374 $ $Date: 2007-10-28 17:25:07 +0100 (Sun, 28 Oct 2007) $
054: *
055: * @since 4.0
056: */
057: public interface LineParser {
058:
059: /**
060: * Parses the textual representation of a protocol version.
061: * This is needed for parsing request lines (last element)
062: * as well as status lines (first element).
063: *
064: * @param buffer a buffer holding the protocol version to parse
065: * @param cursor the parser cursor containing the current position and
066: * the bounds within the buffer for the parsing operation
067: *
068: * @return the parsed protocol version
069: *
070: * @throws ParseException in case of a parse error
071: */
072: ProtocolVersion parseProtocolVersion(CharArrayBuffer buffer,
073: ParserCursor cursor) throws ParseException;
074:
075: /**
076: * Checks whether there likely is a protocol version in a line.
077: * This method implements a <i>heuristic</i> to check for a
078: * likely protocol version specification. It does <i>not</i>
079: * guarantee that {@link #parseProtocolVersion} would not
080: * detect a parse error.
081: * This can be used to detect garbage lines before a request
082: * or status line.
083: *
084: * @param buffer a buffer holding the line to inspect
085: * @param cursor the cursor at which to check for a protocol version, or
086: * negative for "end of line". Whether the check tolerates
087: * whitespace before or after the protocol version is
088: * implementation dependent.
089: *
090: * @return <code>true</code> if there is a protocol version at the
091: * argument index (possibly ignoring whitespace),
092: * <code>false</code> otherwise
093: */
094: boolean hasProtocolVersion(CharArrayBuffer buffer,
095: ParserCursor cursor);
096:
097: /**
098: * Parses a request line.
099: *
100: * @param buffer a buffer holding the line 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 request line
105: *
106: * @throws ParseException in case of a parse error
107: */
108: RequestLine parseRequestLine(CharArrayBuffer buffer,
109: ParserCursor cursor) throws ParseException;
110:
111: /**
112: * Parses a status line.
113: *
114: * @param buffer a buffer holding the line to parse
115: * @param cursor the parser cursor containing the current position and
116: * the bounds within the buffer for the parsing operation
117: *
118: * @return the parsed status line
119: *
120: * @throws ParseException in case of a parse error
121: */
122: StatusLine parseStatusLine(CharArrayBuffer buffer,
123: ParserCursor cursor) throws ParseException;
124:
125: /**
126: * Creates a header from a line.
127: * The full header line is expected here. Header continuation lines
128: * must be joined by the caller before invoking this method.
129: *
130: * @param buffer a buffer holding the full header line.
131: * This buffer MUST NOT be re-used afterwards, since
132: * the returned object may reference the contents later.
133: *
134: * @return the header in the argument buffer.
135: * The returned object MAY be a wrapper for the argument buffer.
136: * The argument buffer MUST NOT be re-used or changed afterwards.
137: *
138: * @throws ParseException in case of a parse error
139: */
140: Header parseHeader(CharArrayBuffer buffer) throws ParseException;
141:
142: }
|