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;
29  
30  import org.apache.http.params.HttpParams;
31  
32  /**
33   * HTTP messages consist of requests from client to server and responses
34   * from server to client.
35   * <pre>
36   *     HTTP-message   = Request | Response     ; HTTP/1.1 messages
37   * </pre>
38   * <p>
39   * HTTP messages use the generic message format of RFC 822 for
40   * transferring entities (the payload of the message). Both types
41   * of message consist of a start-line, zero or more header fields
42   * (also known as "headers"), an empty line (i.e., a line with nothing
43   * preceding the CRLF) indicating the end of the header fields,
44   * and possibly a message-body.
45   * </p>
46   * <pre>
47   *      generic-message = start-line
48   *                        *(message-header CRLF)
49   *                        CRLF
50   *                        [ message-body ]
51   *      start-line      = Request-Line | Status-Line
52   * </pre>
53   *
54   * @since 4.0
55   */
56  @SuppressWarnings("deprecation")
57  public interface HttpMessage {
58  
59      /**
60       * Returns the protocol version this message is compatible with.
61       */
62      ProtocolVersion getProtocolVersion();
63  
64      /**
65       * Checks if a certain header is present in this message. Header values are
66       * ignored.
67       *
68       * @param name the header name to check for.
69       * @return true if at least one header with this name is present.
70       */
71      boolean containsHeader(String name);
72  
73      /**
74       * Returns all the headers with a specified name of this message. Header values
75       * are ignored. Headers are orderd in the sequence they will be sent over a
76       * connection.
77       *
78       * @param name the name of the headers to return.
79       * @return the headers whose name property equals <code>name</code>.
80       */
81      Header[] getHeaders(String name);
82  
83      /**
84       * Returns the first header with a specified name of this message. Header
85       * values are ignored. If there is more than one matching header in the
86       * message the first element of {@link #getHeaders(String)} is returned.
87       * If there is no matching header in the message <code>null</code> is
88       * returned.
89       *
90       * @param name the name of the header to return.
91       * @return the first header whose name property equals <code>name</code>
92       *   or <code>null</code> if no such header could be found.
93       */
94      Header getFirstHeader(String name);
95  
96      /**
97       * Returns the last header with a specified name of this message. Header values
98       * are ignored. If there is more than one matching header in the message the
99       * last element of {@link #getHeaders(String)} is returned. If there is no
100      * matching header in the message <code>null</code> is returned.
101      *
102      * @param name the name of the header to return.
103      * @return the last header whose name property equals <code>name</code>.
104      *   or <code>null</code> if no such header could be found.
105      */
106     Header getLastHeader(String name);
107 
108     /**
109      * Returns all the headers of this message. Headers are orderd in the sequence
110      * they will be sent over a connection.
111      *
112      * @return all the headers of this message
113      */
114     Header[] getAllHeaders();
115 
116     /**
117      * Adds a header to this message. The header will be appended to the end of
118      * the list.
119      *
120      * @param header the header to append.
121      */
122     void addHeader(Header header);
123 
124     /**
125      * Adds a header to this message. The header will be appended to the end of
126      * the list.
127      *
128      * @param name the name of the header.
129      * @param value the value of the header.
130      */
131     void addHeader(String name, String value);
132 
133     /**
134      * Overwrites the first header with the same name. The new header will be appended to
135      * the end of the list, if no header with the given name can be found.
136      *
137      * @param header the header to set.
138      */
139     void setHeader(Header header);
140 
141     /**
142      * Overwrites the first header with the same name. The new header will be appended to
143      * the end of the list, if no header with the given name can be found.
144      *
145      * @param name the name of the header.
146      * @param value the value of the header.
147      */
148     void setHeader(String name, String value);
149 
150     /**
151      * Overwrites all the headers in the message.
152      *
153      * @param headers the array of headers to set.
154      */
155     void setHeaders(Header[] headers);
156 
157     /**
158      * Removes a header from this message.
159      *
160      * @param header the header to remove.
161      */
162     void removeHeader(Header header);
163 
164     /**
165      * Removes all headers with a certain name from this message.
166      *
167      * @param name The name of the headers to remove.
168      */
169     void removeHeaders(String name);
170 
171     /**
172      * Returns an iterator of all the headers.
173      *
174      * @return Iterator that returns Header objects in the sequence they are
175      *         sent over a connection.
176      */
177     HeaderIterator headerIterator();
178 
179     /**
180      * Returns an iterator of the headers with a given name.
181      *
182      * @param name      the name of the headers over which to iterate, or
183      *                  <code>null</code> for all headers
184      *
185      * @return Iterator that returns Header objects with the argument name
186      *         in the sequence they are sent over a connection.
187      */
188     HeaderIterator headerIterator(String name);
189 
190     /**
191      * Returns the parameters effective for this message as set by
192      * {@link #setParams(HttpParams)}.
193      *
194      * @deprecated (4.3) use configuration classes provided 'org.apache.http.config'
195      *  and 'org.apache.http.client.config'
196      */
197     @Deprecated
198     HttpParams getParams();
199 
200     /**
201      * Provides parameters to be used for the processing of this message.
202      * @param params the parameters
203      *
204      * @deprecated (4.3) use configuration classes provided 'org.apache.http.config'
205      *  and 'org.apache.http.client.config'
206      */
207     @Deprecated
208     void setParams(HttpParams params);
209 
210 }