michael@0: /* michael@0: * ==================================================================== michael@0: * Licensed to the Apache Software Foundation (ASF) under one michael@0: * or more contributor license agreements. See the NOTICE file michael@0: * distributed with this work for additional information michael@0: * regarding copyright ownership. The ASF licenses this file michael@0: * to you under the Apache License, Version 2.0 (the michael@0: * "License"); you may not use this file except in compliance michael@0: * with the License. You may obtain a copy of the License at michael@0: * michael@0: * http://www.apache.org/licenses/LICENSE-2.0 michael@0: * michael@0: * Unless required by applicable law or agreed to in writing, michael@0: * software distributed under the License is distributed on an michael@0: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY michael@0: * KIND, either express or implied. See the License for the michael@0: * specific language governing permissions and limitations michael@0: * under the License. michael@0: * ==================================================================== michael@0: * michael@0: * This software consists of voluntary contributions made by many michael@0: * individuals on behalf of the Apache Software Foundation. For more michael@0: * information on the Apache Software Foundation, please see michael@0: * . michael@0: * michael@0: */ michael@0: michael@0: package ch.boye.httpclientandroidlib.message; michael@0: michael@0: import ch.boye.httpclientandroidlib.ProtocolVersion; michael@0: import ch.boye.httpclientandroidlib.RequestLine; michael@0: import ch.boye.httpclientandroidlib.StatusLine; michael@0: import ch.boye.httpclientandroidlib.Header; michael@0: import ch.boye.httpclientandroidlib.util.CharArrayBuffer; michael@0: michael@0: /** michael@0: * Interface for formatting elements of the HEAD section of an HTTP message. michael@0: * This is the complement to {@link LineParser}. michael@0: * There are individual methods for formatting a request line, a michael@0: * status line, or a header line. The formatting does not include the michael@0: * trailing line break sequence CR-LF. michael@0: * Instances of this interface are expected to be stateless and thread-safe. michael@0: * michael@0: *

michael@0: * The formatted lines are returned in memory, the formatter does not depend michael@0: * on any specific IO mechanism. michael@0: * In order to avoid unnecessary creation of temporary objects, michael@0: * a buffer can be passed as argument to all formatting methods. michael@0: * The implementation may or may not actually use that buffer for formatting. michael@0: * If it is used, the buffer will first be cleared by the michael@0: * formatXXX methods. michael@0: * The argument buffer can always be re-used after the call. The buffer michael@0: * returned as the result, if it is different from the argument buffer, michael@0: * MUST NOT be modified. michael@0: *

michael@0: * michael@0: * @since 4.0 michael@0: */ michael@0: public interface LineFormatter { michael@0: michael@0: /** michael@0: * Formats a protocol version. michael@0: * This method does not follow the general contract for michael@0: * buffer arguments. michael@0: * It does not clear the argument buffer, but appends instead. michael@0: * The returned buffer can always be modified by the caller. michael@0: * Because of these differing conventions, it is not named michael@0: * formatProtocolVersion. michael@0: * michael@0: * @param buffer a buffer to which to append, or null michael@0: * @param version the protocol version to format michael@0: * michael@0: * @return a buffer with the formatted protocol version appended. michael@0: * The caller is allowed to modify the result buffer. michael@0: * If the buffer argument is not null, michael@0: * the returned buffer is the argument buffer. michael@0: */ michael@0: CharArrayBuffer appendProtocolVersion(CharArrayBuffer buffer, michael@0: ProtocolVersion version); michael@0: michael@0: /** michael@0: * Formats a request line. michael@0: * michael@0: * @param buffer a buffer available for formatting, or michael@0: * null. michael@0: * The buffer will be cleared before use. michael@0: * @param reqline the request line to format michael@0: * michael@0: * @return the formatted request line michael@0: */ michael@0: CharArrayBuffer formatRequestLine(CharArrayBuffer buffer, michael@0: RequestLine reqline); michael@0: michael@0: /** michael@0: * Formats a status line. michael@0: * michael@0: * @param buffer a buffer available for formatting, or michael@0: * null. michael@0: * The buffer will be cleared before use. michael@0: * @param statline the status line to format michael@0: * michael@0: * @return the formatted status line michael@0: * michael@0: * @throws ch.boye.httpclientandroidlib.ParseException in case of a parse error michael@0: */ michael@0: CharArrayBuffer formatStatusLine(CharArrayBuffer buffer, michael@0: StatusLine statline); michael@0: michael@0: /** michael@0: * Formats a header. michael@0: * Due to header continuation, the result may be multiple lines. michael@0: * In order to generate well-formed HTTP, the lines in the result michael@0: * must be separated by the HTTP line break sequence CR-LF. michael@0: * There is no trailing CR-LF in the result. michael@0: *
michael@0: * See the class comment for details about the buffer argument. michael@0: * michael@0: * @param buffer a buffer available for formatting, or michael@0: * null. michael@0: * The buffer will be cleared before use. michael@0: * @param header the header to format michael@0: * michael@0: * @return a buffer holding the formatted header, never null. michael@0: * The returned buffer may be different from the argument buffer. michael@0: * michael@0: * @throws ch.boye.httpclientandroidlib.ParseException in case of a parse error michael@0: */ michael@0: CharArrayBuffer formatHeader(CharArrayBuffer buffer, michael@0: Header header); michael@0: michael@0: }