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  public interface HttpMessage {
57  
58      /**
59       * Returns the protocol version this message is compatible with.
60       */
61      ProtocolVersion getProtocolVersion();
62  
63      /**
64       * Checks if a certain header is present in this message. Header values are
65       * ignored.
66       *
67       * @param name the header name to check for.
68       * @return true if at least one header with this name is present.
69       */
70      boolean containsHeader(String name);
71  
72      /**
73       * Returns all the headers with a specified name of this message. Header values
74       * are ignored. Headers are orderd in the sequence they will be sent over a
75       * connection.
76       *
77       * @param name the name of the headers to return.
78       * @return the headers whose name property equals <code>name</code>.
79       */
80      Header[] getHeaders(String name);
81  
82      /**
83       * Returns the first header with a specified name of this message. Header
84       * values are ignored. If there is more than one matching header in the
85       * message the first element of {@link #getHeaders(String)} is returned.
86       * If there is no matching header in the message <code>null</code> is
87       * returned.
88       *
89       * @param name the name of the header to return.
90       * @return the first header whose name property equals <code>name</code>
91       *   or <code>null</code> if no such header could be found.
92       */
93      Header getFirstHeader(String name);
94  
95      /**
96       * Returns the last header with a specified name of this message. Header values
97       * are ignored. If there is more than one matching header in the message the
98       * last element of {@link #getHeaders(String)} is returned. If there is no
99       * matching header in the message <code>null</code> is returned.
100      *
101      * @param name the name of the header to return.
102      * @return the last header whose name property equals <code>name</code>.
103      *   or <code>null</code> if no such header could be found.
104      */
105     Header getLastHeader(String name);
106 
107     /**
108      * Returns all the headers of this message. Headers are orderd in the sequence
109      * they will be sent over a connection.
110      *
111      * @return all the headers of this message
112      */
113     Header[] getAllHeaders();
114 
115     /**
116      * Adds a header to this message. The header will be appended to the end of
117      * the list.
118      *
119      * @param header the header to append.
120      */
121     void addHeader(Header header);
122 
123     /**
124      * Adds a header to this message. The header will be appended to the end of
125      * the list.
126      *
127      * @param name the name of the header.
128      * @param value the value of the header.
129      */
130     void addHeader(String name, String value);
131 
132     /**
133      * Overwrites the first header with the same name. The new header will be appended to
134      * the end of the list, if no header with the given name can be found.
135      *
136      * @param header the header to set.
137      */
138     void setHeader(Header header);
139 
140     /**
141      * Overwrites the first header with the same name. The new header will be appended to
142      * the end of the list, if no header with the given name can be found.
143      *
144      * @param name the name of the header.
145      * @param value the value of the header.
146      */
147     void setHeader(String name, String value);
148 
149     /**
150      * Overwrites all the headers in the message.
151      *
152      * @param headers the array of headers to set.
153      */
154     void setHeaders(Header[] headers);
155 
156     /**
157      * Removes a header from this message.
158      *
159      * @param header the header to remove.
160      */
161     void removeHeader(Header header);
162 
163     /**
164      * Removes all headers with a certain name from this message.
165      *
166      * @param name The name of the headers to remove.
167      */
168     void removeHeaders(String name);
169 
170     /**
171      * Returns an iterator of all the headers.
172      *
173      * @return Iterator that returns Header objects in the sequence they are
174      *         sent over a connection.
175      */
176     HeaderIterator headerIterator();
177 
178     /**
179      * Returns an iterator of the headers with a given name.
180      *
181      * @param name      the name of the headers over which to iterate, or
182      *                  <code>null</code> for all headers
183      *
184      * @return Iterator that returns Header objects with the argument name
185      *         in the sequence they are sent over a connection.
186      */
187     HeaderIterator headerIterator(String name);
188 
189     /**
190      * Returns the parameters effective for this message as set by
191      * {@link #setParams(HttpParams)}.
192      */
193     HttpParams getParams();
194 
195     /**
196      * Provides parameters to be used for the processing of this message.
197      * @param params the parameters
198      */
199     void setParams(HttpParams params);
200 
201 }