1 /* 2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/message/LineFormatter.java $ 3 * $Revision: 573864 $ 4 * $Date: 2007-09-08 08:53:25 -0700 (Sat, 08 Sep 2007) $ 5 * 6 * ==================================================================== 7 * Licensed to the Apache Software Foundation (ASF) under one 8 * or more contributor license agreements. See the NOTICE file 9 * distributed with this work for additional information 10 * regarding copyright ownership. The ASF licenses this file 11 * to you under the Apache License, Version 2.0 (the 12 * "License"); you may not use this file except in compliance 13 * with the License. You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * 17 * Unless required by applicable law or agreed to in writing, 18 * software distributed under the License is distributed on an 19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 20 * KIND, either express or implied. See the License for the 21 * specific language governing permissions and limitations 22 * under the License. 23 * ==================================================================== 24 * 25 * This software consists of voluntary contributions made by many 26 * individuals on behalf of the Apache Software Foundation. For more 27 * information on the Apache Software Foundation, please see 28 * <http://www.apache.org/>. 29 * 30 */ 31 32 package org.apache.http.message; 33 34 35 import org.apache.http.ProtocolVersion; 36 import org.apache.http.RequestLine; 37 import org.apache.http.StatusLine; 38 import org.apache.http.Header; 39 import org.apache.http.util.CharArrayBuffer; 40 41 42 /** 43 * Interface for formatting elements of the HEAD section of an HTTP message. 44 * This is the complement to {@link LineParser}. 45 * There are individual methods for formatting a request line, a 46 * status line, or a header line. The formatting does <i>not</i> include the 47 * trailing line break sequence CR-LF. 48 * Instances of this interface are expected to be stateless and thread-safe. 49 * 50 * <p> 51 * The formatted lines are returned in memory, the formatter does not depend 52 * on any specific IO mechanism. 53 * In order to avoid unnecessary creation of temporary objects, 54 * a buffer can be passed as argument to all formatting methods. 55 * The implementation may or may not actually use that buffer for formatting. 56 * If it is used, the buffer will first be cleared by the 57 * <code>formatXXX</code> methods. 58 * The argument buffer can always be re-used after the call. The buffer 59 * returned as the result, if it is different from the argument buffer, 60 * MUST NOT be modified. 61 * </p> 62 * 63 * 64 * @author <a href="mailto:rolandw AT apache.org">Roland Weber</a> 65 * 66 * 67 * <!-- empty lines above to avoid 'svn diff' context problems --> 68 * @version $Revision: 573864 $ $Date: 2007-09-08 08:53:25 -0700 (Sat, 08 Sep 2007) $ 69 * 70 * @since 4.0 71 */ 72 public interface LineFormatter { 73 74 75 76 /** 77 * Formats a protocol version. 78 * This method does <i>not</i> follow the general contract for 79 * <code>buffer</code> arguments. 80 * It does <i>not</i> clear the argument buffer, but appends instead. 81 * The returned buffer can always be modified by the caller. 82 * Because of these differing conventions, it is not named 83 * <code>formatProtocolVersion</code>. 84 * 85 * @param buffer a buffer to which to append, or <code>null</code> 86 * @param version the protocol version to format 87 * 88 * @return a buffer with the formatted protocol version appended. 89 * The caller is allowed to modify the result buffer. 90 * If the <code>buffer</code> argument is not <code>null</code>, 91 * the returned buffer is the argument buffer. 92 */ 93 CharArrayBuffer appendProtocolVersion(CharArrayBuffer buffer, 94 ProtocolVersion version) 95 ; 96 97 98 /** 99 * Formats a request line. 100 * 101 * @param buffer a buffer available for formatting, or 102 * <code>null</code>. 103 * The buffer will be cleared before use. 104 * @param reqline the request line to format 105 * 106 * @return the formatted request line 107 */ 108 CharArrayBuffer formatRequestLine(CharArrayBuffer buffer, 109 RequestLine reqline) 110 ; 111 112 113 /** 114 * Formats a status line. 115 * 116 * @param buffer a buffer available for formatting, or 117 * <code>null</code>. 118 * The buffer will be cleared before use. 119 * @param statline the status line to format 120 * 121 * @return the formatted status line 122 * 123 * @throws ParseException in case of a parse error 124 */ 125 CharArrayBuffer formatStatusLine(CharArrayBuffer buffer, 126 StatusLine statline) 127 ; 128 129 130 /** 131 * Formats a header. 132 * Due to header continuation, the result may be multiple lines. 133 * In order to generate well-formed HTTP, the lines in the result 134 * must be separated by the HTTP line break sequence CR-LF. 135 * There is <i>no</i> trailing CR-LF in the result. 136 * <br/> 137 * See the class comment for details about the buffer argument. 138 * 139 * @param buffer a buffer available for formatting, or 140 * <code>null</code>. 141 * The buffer will be cleared before use. 142 * @param header the header to format 143 * 144 * @return a buffer holding the formatted header, never <code>null</code>. 145 * The returned buffer may be different from the argument buffer. 146 * 147 * @throws ParseException in case of a parse error 148 */ 149 CharArrayBuffer formatHeader(CharArrayBuffer buffer, 150 Header header) 151 ; 152 153 } 154
