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.ProtocolVersion; 032import org.apache.http.RequestLine; 033import org.apache.http.StatusLine; 034import org.apache.http.util.CharArrayBuffer; 035 036/** 037 * Interface for formatting elements of the HEAD section of an HTTP message. 038 * This is the complement to {@link LineParser}. 039 * There are individual methods for formatting a request line, a 040 * status line, or a header line. The formatting does <i>not</i> include the 041 * trailing line break sequence CR-LF. 042 * Instances of this interface are expected to be stateless and thread-safe. 043 * 044 * <p> 045 * The formatted lines are returned in memory, the formatter does not depend 046 * on any specific IO mechanism. 047 * In order to avoid unnecessary creation of temporary objects, 048 * a buffer can be passed as argument to all formatting methods. 049 * The implementation may or may not actually use that buffer for formatting. 050 * If it is used, the buffer will first be cleared by the 051 * {@code formatXXX} methods. 052 * The argument buffer can always be re-used after the call. The buffer 053 * returned as the result, if it is different from the argument buffer, 054 * MUST NOT be modified. 055 * </p> 056 * 057 * @since 4.0 058 */ 059public interface LineFormatter { 060 061 /** 062 * Formats a protocol version. 063 * This method does <i>not</i> follow the general contract for 064 * {@code buffer} arguments. 065 * It does <i>not</i> clear the argument buffer, but appends instead. 066 * The returned buffer can always be modified by the caller. 067 * Because of these differing conventions, it is not named 068 * {@code formatProtocolVersion}. 069 * 070 * @param buffer a buffer to which to append, or {@code null} 071 * @param version the protocol version to format 072 * 073 * @return a buffer with the formatted protocol version appended. 074 * The caller is allowed to modify the result buffer. 075 * If the {@code buffer} argument is not {@code null}, 076 * the returned buffer is the argument buffer. 077 */ 078 CharArrayBuffer appendProtocolVersion(CharArrayBuffer buffer, 079 ProtocolVersion version); 080 081 /** 082 * Formats a request line. 083 * 084 * @param buffer a buffer available for formatting, or 085 * {@code null}. 086 * The buffer will be cleared before use. 087 * @param reqline the request line to format 088 * 089 * @return the formatted request line 090 */ 091 CharArrayBuffer formatRequestLine(CharArrayBuffer buffer, 092 RequestLine reqline); 093 094 /** 095 * Formats a status line. 096 * 097 * @param buffer a buffer available for formatting, or 098 * {@code null}. 099 * The buffer will be cleared before use. 100 * @param statline the status line to format 101 * 102 * @return the formatted status line 103 * 104 * @throws org.apache.http.ParseException in case of a parse error 105 */ 106 CharArrayBuffer formatStatusLine(CharArrayBuffer buffer, 107 StatusLine statline); 108 109 /** 110 * Formats a header. 111 * Due to header continuation, the result may be multiple lines. 112 * In order to generate well-formed HTTP, the lines in the result 113 * must be separated by the HTTP line break sequence CR-LF. 114 * There is <i>no</i> trailing CR-LF in the result. 115 * <p> 116 * See the class comment for details about the buffer argument. 117 * </p> 118 * 119 * @param buffer a buffer available for formatting, or 120 * {@code null}. 121 * The buffer will be cleared before use. 122 * @param header the header to format 123 * 124 * @return a buffer holding the formatted header, never {@code null}. 125 * The returned buffer may be different from the argument buffer. 126 * 127 * @throws org.apache.http.ParseException in case of a parse error 128 */ 129 CharArrayBuffer formatHeader(CharArrayBuffer buffer, 130 Header header); 131 132}