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.ProtocolVersion; 32 import org.apache.http.RequestLine; 33 import org.apache.http.StatusLine; 34 import org.apache.http.util.CharArrayBuffer; 35 36 /** 37 * Interface for formatting elements of the HEAD section of an HTTP message. 38 * This is the complement to {@link LineParser}. 39 * There are individual methods for formatting a request line, a 40 * status line, or a header line. The formatting does <i>not</i> include the 41 * trailing line break sequence CR-LF. 42 * Instances of this interface are expected to be stateless and thread-safe. 43 * 44 * <p> 45 * The formatted lines are returned in memory, the formatter does not depend 46 * on any specific IO mechanism. 47 * In order to avoid unnecessary creation of temporary objects, 48 * a buffer can be passed as argument to all formatting methods. 49 * The implementation may or may not actually use that buffer for formatting. 50 * If it is used, the buffer will first be cleared by the 51 * {@code formatXXX} methods. 52 * The argument buffer can always be re-used after the call. The buffer 53 * returned as the result, if it is different from the argument buffer, 54 * MUST NOT be modified. 55 * </p> 56 * 57 * @since 4.0 58 */ 59 public interface LineFormatter { 60 61 /** 62 * Formats a protocol version. 63 * This method does <i>not</i> follow the general contract for 64 * {@code buffer} arguments. 65 * It does <i>not</i> clear the argument buffer, but appends instead. 66 * The returned buffer can always be modified by the caller. 67 * Because of these differing conventions, it is not named 68 * {@code formatProtocolVersion}. 69 * 70 * @param buffer a buffer to which to append, or {@code null} 71 * @param version the protocol version to format 72 * 73 * @return a buffer with the formatted protocol version appended. 74 * The caller is allowed to modify the result buffer. 75 * If the {@code buffer} argument is not {@code null}, 76 * the returned buffer is the argument buffer. 77 */ 78 CharArrayBuffere/http/util/CharArrayBuffer.html#CharArrayBuffer">CharArrayBuffer appendProtocolVersion(CharArrayBuffer buffer, 79 ProtocolVersion version); 80 81 /** 82 * Formats a request line. 83 * 84 * @param buffer a buffer available for formatting, or 85 * {@code null}. 86 * The buffer will be cleared before use. 87 * @param reqline the request line to format 88 * 89 * @return the formatted request line 90 */ 91 CharArrayBufferpache/http/util/CharArrayBuffer.html#CharArrayBuffer">CharArrayBuffer formatRequestLine(CharArrayBuffer buffer, 92 RequestLine reqline); 93 94 /** 95 * Formats a status line. 96 * 97 * @param buffer a buffer available for formatting, or 98 * {@code null}. 99 * 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 CharArrayBufferapache/http/util/CharArrayBuffer.html#CharArrayBuffer">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 CharArrayBufferorg/apache/http/util/CharArrayBuffer.html#CharArrayBuffer">CharArrayBuffer formatHeader(CharArrayBuffer buffer, 130 Header header); 131 132 }