1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 28 package org.apache.http.message; 29 30 import org.apache.http.Header; 31 import org.apache.http.ParseException; 32 import org.apache.http.ProtocolVersion; 33 import org.apache.http.RequestLine; 34 import org.apache.http.StatusLine; 35 import org.apache.http.util.CharArrayBuffer; 36 37 /** 38 * Interface for parsing lines in the HEAD section of an HTTP message. 39 * There are individual methods for parsing a request line, a 40 * status line, or a header line. 41 * The lines to parse are passed in memory, the parser does not depend 42 * on any specific IO mechanism. 43 * Instances of this interface are expected to be stateless and thread-safe. 44 * 45 * @since 4.0 46 */ 47 public interface LineParser { 48 49 /** 50 * Parses the textual representation of a protocol version. 51 * This is needed for parsing request lines (last element) 52 * as well as status lines (first element). 53 * 54 * @param buffer a buffer holding the protocol version to parse 55 * @param cursor the parser cursor containing the current position and 56 * the bounds within the buffer for the parsing operation 57 * 58 * @return the parsed protocol version 59 * 60 * @throws ParseException in case of a parse error 61 */ 62 ProtocolVersion parseProtocolVersion( 63 CharArrayBuffer buffer, 64 ParserCursor cursor) throws ParseException; 65 66 /** 67 * Checks whether there likely is a protocol version in a line. 68 * This method implements a <i>heuristic</i> to check for a 69 * likely protocol version specification. It does <i>not</i> 70 * guarantee that {@link #parseProtocolVersion} would not 71 * detect a parse error. 72 * This can be used to detect garbage lines before a request 73 * or status line. 74 * 75 * @param buffer a buffer holding the line to inspect 76 * @param cursor the cursor at which to check for a protocol version, or 77 * negative for "end of line". Whether the check tolerates 78 * whitespace before or after the protocol version is 79 * implementation dependent. 80 * 81 * @return {@code true} if there is a protocol version at the 82 * argument index (possibly ignoring whitespace), 83 * {@code false} otherwise 84 */ 85 boolean hasProtocolVersion( 86 CharArrayBuffer buffer, 87 ParserCursor cursor); 88 89 /** 90 * Parses a request line. 91 * 92 * @param buffer a buffer holding the line to parse 93 * @param cursor the parser cursor containing the current position and 94 * the bounds within the buffer for the parsing operation 95 * 96 * @return the parsed request line 97 * 98 * @throws ParseException in case of a parse error 99 */ 100 RequestLine parseRequestLine( 101 CharArrayBuffer buffer, 102 ParserCursor cursor) throws ParseException; 103 104 /** 105 * Parses a status 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 status line 112 * 113 * @throws ParseException in case of a parse error 114 */ 115 StatusLine parseStatusLine( 116 CharArrayBuffer buffer, 117 ParserCursor cursor) throws ParseException; 118 119 /** 120 * Creates a header from a line. 121 * The full header line is expected here. Header continuation lines 122 * must be joined by the caller before invoking this method. 123 * 124 * @param buffer a buffer holding the full header line. 125 * This buffer MUST NOT be re-used afterwards, since 126 * the returned object may reference the contents later. 127 * 128 * @return the header in the argument buffer. 129 * The returned object MAY be a wrapper for the argument buffer. 130 * The argument buffer MUST NOT be re-used or changed afterwards. 131 * 132 * @throws ParseException in case of a parse error 133 */ 134 Header parseHeader(CharArrayBuffer buffer) 135 throws ParseException; 136 137 }