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 * @deprecated Please use {@link java.net.URL#openConnection} instead. 73 * Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a> 74 * for further details. 75 */ 76 @Deprecated 77 public interface LineFormatter { 78 79 80 81 /** 82 * Formats a protocol version. 83 * This method does <i>not</i> follow the general contract for 84 * <code>buffer</code> arguments. 85 * It does <i>not</i> clear the argument buffer, but appends instead. 86 * The returned buffer can always be modified by the caller. 87 * Because of these differing conventions, it is not named 88 * <code>formatProtocolVersion</code>. 89 * 90 * @param buffer a buffer to which to append, or <code>null</code> 91 * @param version the protocol version to format 92 * 93 * @return a buffer with the formatted protocol version appended. 94 * The caller is allowed to modify the result buffer. 95 * If the <code>buffer</code> argument is not <code>null</code>, 96 * the returned buffer is the argument buffer. 97 */ appendProtocolVersion(CharArrayBuffer buffer, ProtocolVersion version)98 CharArrayBuffer appendProtocolVersion(CharArrayBuffer buffer, 99 ProtocolVersion version) 100 ; 101 102 103 /** 104 * Formats a request line. 105 * 106 * @param buffer a buffer available for formatting, or 107 * <code>null</code>. 108 * The buffer will be cleared before use. 109 * @param reqline the request line to format 110 * 111 * @return the formatted request line 112 */ formatRequestLine(CharArrayBuffer buffer, RequestLine reqline)113 CharArrayBuffer formatRequestLine(CharArrayBuffer buffer, 114 RequestLine reqline) 115 ; 116 117 118 /** 119 * Formats a status line. 120 * 121 * @param buffer a buffer available for formatting, or 122 * <code>null</code>. 123 * The buffer will be cleared before use. 124 * @param statline the status line to format 125 * 126 * @return the formatted status line 127 * 128 * @throws ParseException in case of a parse error 129 */ formatStatusLine(CharArrayBuffer buffer, StatusLine statline)130 CharArrayBuffer formatStatusLine(CharArrayBuffer buffer, 131 StatusLine statline) 132 ; 133 134 135 /** 136 * Formats a header. 137 * Due to header continuation, the result may be multiple lines. 138 * In order to generate well-formed HTTP, the lines in the result 139 * must be separated by the HTTP line break sequence CR-LF. 140 * There is <i>no</i> trailing CR-LF in the result. 141 * <br/> 142 * See the class comment for details about the buffer argument. 143 * 144 * @param buffer a buffer available for formatting, or 145 * <code>null</code>. 146 * The buffer will be cleared before use. 147 * @param header the header to format 148 * 149 * @return a buffer holding the formatted header, never <code>null</code>. 150 * The returned buffer may be different from the argument buffer. 151 * 152 * @throws ParseException in case of a parse error 153 */ formatHeader(CharArrayBuffer buffer, Header header)154 CharArrayBuffer formatHeader(CharArrayBuffer buffer, 155 Header header) 156 ; 157 158 } 159