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 }