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.Header; 031import org.apache.http.ParseException; 032import org.apache.http.ProtocolVersion; 033import org.apache.http.RequestLine; 034import org.apache.http.StatusLine; 035import org.apache.http.util.CharArrayBuffer; 036 037/** 038 * Interface for parsing lines in the HEAD section of an HTTP message. 039 * There are individual methods for parsing a request line, a 040 * status line, or a header line. 041 * The lines to parse are passed in memory, the parser does not depend 042 * on any specific IO mechanism. 043 * Instances of this interface are expected to be stateless and thread-safe. 044 * 045 * @since 4.0 046 */ 047public interface LineParser { 048 049 /** 050 * Parses the textual representation of a protocol version. 051 * This is needed for parsing request lines (last element) 052 * as well as status lines (first element). 053 * 054 * @param buffer a buffer holding the protocol version to parse 055 * @param cursor the parser cursor containing the current position and 056 * the bounds within the buffer for the parsing operation 057 * 058 * @return the parsed protocol version 059 * 060 * @throws ParseException in case of a parse error 061 */ 062 ProtocolVersion parseProtocolVersion( 063 CharArrayBuffer buffer, 064 ParserCursor cursor) throws ParseException; 065 066 /** 067 * Checks whether there likely is a protocol version in a line. 068 * This method implements a <i>heuristic</i> to check for a 069 * likely protocol version specification. It does <i>not</i> 070 * guarantee that {@link #parseProtocolVersion} would not 071 * detect a parse error. 072 * This can be used to detect garbage lines before a request 073 * or status line. 074 * 075 * @param buffer a buffer holding the line to inspect 076 * @param cursor the cursor at which to check for a protocol version, or 077 * negative for "end of line". Whether the check tolerates 078 * whitespace before or after the protocol version is 079 * implementation dependent. 080 * 081 * @return {@code true} if there is a protocol version at the 082 * argument index (possibly ignoring whitespace), 083 * {@code false} otherwise 084 */ 085 boolean hasProtocolVersion( 086 CharArrayBuffer buffer, 087 ParserCursor cursor); 088 089 /** 090 * Parses a request line. 091 * 092 * @param buffer a buffer holding the line to parse 093 * @param cursor the parser cursor containing the current position and 094 * the bounds within the buffer for the parsing operation 095 * 096 * @return the parsed request line 097 * 098 * @throws ParseException in case of a parse error 099 */ 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}