1 /* 2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/LineParser.java $ 3 * $Revision: 589374 $ 4 * $Date: 2007-10-28 09:25:07 -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.ProtocolVersion; 36 import org.apache.http.ParseException; 37 import org.apache.http.RequestLine; 38 import org.apache.http.StatusLine; 39 import org.apache.http.Header; 40 import org.apache.http.util.CharArrayBuffer; 41 42 43 /** 44 * Interface for parsing lines in the HEAD section of an HTTP message. 45 * There are individual methods for parsing a request line, a 46 * status line, or a header line. 47 * The lines to parse are passed in memory, the parser does not depend 48 * on any specific IO mechanism. 49 * Instances of this interface are expected to be stateless and thread-safe. 50 * 51 * @author <a href="mailto:rolandw AT apache.org">Roland Weber</a> 52 * 53 * 54 * <!-- empty lines above to avoid 'svn diff' context problems --> 55 * @version $Revision: 589374 $ $Date: 2007-10-28 09:25:07 -0700 (Sun, 28 Oct 2007) $ 56 * 57 * @since 4.0 58 */ 59 public interface LineParser { 60 61 62 /** 63 * Parses the textual representation of a protocol version. 64 * This is needed for parsing request lines (last element) 65 * as well as status lines (first element). 66 * 67 * @param buffer a buffer holding the protocol version to parse 68 * @param cursor the parser cursor containing the current position and 69 * the bounds within the buffer for the parsing operation 70 * 71 * @return the parsed protocol version 72 * 73 * @throws ParseException in case of a parse error 74 */ parseProtocolVersion( CharArrayBuffer buffer, ParserCursor cursor)75 ProtocolVersion parseProtocolVersion( 76 CharArrayBuffer buffer, 77 ParserCursor cursor) throws ParseException; 78 79 80 /** 81 * Checks whether there likely is a protocol version in a line. 82 * This method implements a <i>heuristic</i> to check for a 83 * likely protocol version specification. It does <i>not</i> 84 * guarantee that {@link #parseProtocolVersion} would not 85 * detect a parse error. 86 * This can be used to detect garbage lines before a request 87 * or status line. 88 * 89 * @param buffer a buffer holding the line to inspect 90 * @param cursor the cursor at which to check for a protocol version, or 91 * negative for "end of line". Whether the check tolerates 92 * whitespace before or after the protocol version is 93 * implementation dependent. 94 * 95 * @return <code>true</code> if there is a protocol version at the 96 * argument index (possibly ignoring whitespace), 97 * <code>false</code> otherwise 98 */ hasProtocolVersion( CharArrayBuffer buffer, ParserCursor cursor)99 boolean hasProtocolVersion( 100 CharArrayBuffer buffer, 101 ParserCursor cursor); 102 103 104 /** 105 * Parses a request line. 106 * 107 * @param buffer a buffer holding the line to parse 108 * @param cursor the parser cursor containing the current position and 109 * the bounds within the buffer for the parsing operation 110 * 111 * @return the parsed request line 112 * 113 * @throws ParseException in case of a parse error 114 */ parseRequestLine( CharArrayBuffer buffer, ParserCursor cursor)115 RequestLine parseRequestLine( 116 CharArrayBuffer buffer, 117 ParserCursor cursor) throws ParseException; 118 119 120 /** 121 * Parses a status line. 122 * 123 * @param buffer a buffer holding the line to parse 124 * @param cursor the parser cursor containing the current position and 125 * the bounds within the buffer for the parsing operation 126 * 127 * @return the parsed status line 128 * 129 * @throws ParseException in case of a parse error 130 */ parseStatusLine( CharArrayBuffer buffer, ParserCursor cursor)131 StatusLine parseStatusLine( 132 CharArrayBuffer buffer, 133 ParserCursor cursor) throws ParseException; 134 135 136 /** 137 * Creates a header from a line. 138 * The full header line is expected here. Header continuation lines 139 * must be joined by the caller before invoking this method. 140 * 141 * @param buffer a buffer holding the full header line. 142 * This buffer MUST NOT be re-used afterwards, since 143 * the returned object may reference the contents later. 144 * 145 * @return the header in the argument buffer. 146 * The returned object MAY be a wrapper for the argument buffer. 147 * The argument buffer MUST NOT be re-used or changed afterwards. 148 * 149 * @throws ParseException in case of a parse error 150 */ parseHeader(CharArrayBuffer buffer)151 Header parseHeader(CharArrayBuffer buffer) 152 throws ParseException 153 ; 154 155 156 } 157