View Javadoc

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      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      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     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 }