1/*
2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpMessage.java $
3 * $Revision: 610823 $
4 * $Date: 2008-01-10 07:53:53 -0800 (Thu, 10 Jan 2008) $
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
32package org.apache.http;
33
34import org.apache.http.params.HttpParams;
35
36/**
37 * A generic HTTP message.
38 * Holds what is common between requests and responses.
39 *
40 * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
41 *
42 * @version $Revision: 610823 $
43 *
44 * @since 4.0
45 */
46public interface HttpMessage {
47
48    /**
49     * Returns the protocol version this message is compatible with.
50     */
51    ProtocolVersion getProtocolVersion();
52
53    /**
54     * Checks if a certain header is present in this message. Header values are
55     * ignored.
56     *
57     * @param name the header name to check for.
58     * @return true if at least one header with this name is present.
59     */
60    boolean containsHeader(String name);
61
62    /**
63     * Returns all the headers with a specified name of this message. Header values
64     * are ignored. Headers are orderd in the sequence they will be sent over a
65     * connection.
66     *
67     * @param name the name of the headers to return.
68     * @return the headers whose name property equals <code>name</code>.
69     */
70    Header[] getHeaders(String name);
71
72    /**
73     * Returns the first header with a specified name of this message. Header
74     * values are ignored. If there is more than one matching header in the
75     * message the first element of {@link #getHeaders(String)} is returned.
76     * If there is no matching header in the message <code>null</code> is
77     * returned.
78     *
79     * @param name the name of the header to return.
80     * @return the first header whose name property equals <code>name</code>
81     *   or <code>null</code> if no such header could be found.
82     */
83    Header getFirstHeader(String name);
84
85    /**
86     * Returns the last header with a specified name of this message. Header values
87     * are ignored. If there is more than one matching header in the message the
88     * last element of {@link #getHeaders(String)} is returned. If there is no
89     * matching header in the message <code>null</code> is returned.
90     *
91     * @param name the name of the header to return.
92     * @return the last header whose name property equals <code>name</code>.
93     *   or <code>null</code> if no such header could be found.
94     */
95    Header getLastHeader(String name);
96
97    /**
98     * Returns all the headers of this message. Headers are orderd in the sequence
99     * they will be sent over a connection.
100     *
101     * @return all the headers of this message
102     */
103    Header[] getAllHeaders();
104
105    /**
106     * Adds a header to this message. The header will be appended to the end of
107     * the list.
108     *
109     * @param header the header to append.
110     */
111    void addHeader(Header header);
112
113    /**
114     * Adds a header to this message. The header will be appended to the end of
115     * the list.
116     *
117     * @param name the name of the header.
118     * @param value the value of the header.
119     */
120    void addHeader(String name, String value);
121
122    /**
123     * Overwrites the first header with the same name. The new header will be appended to
124     * the end of the list, if no header with the given name can be found.
125     *
126     * @param header the header to set.
127     */
128    void setHeader(Header header);
129
130    /**
131     * Overwrites the first header with the same name. The new header will be appended to
132     * the end of the list, if no header with the given name can be found.
133     *
134     * @param name the name of the header.
135     * @param value the value of the header.
136     */
137    void setHeader(String name, String value);
138
139    /**
140     * Overwrites all the headers in the message.
141     *
142     * @param headers the array of headers to set.
143     */
144    void setHeaders(Header[] headers);
145
146    /**
147     * Removes a header from this message.
148     *
149     * @param header the header to remove.
150     */
151    void removeHeader(Header header);
152
153    /**
154     * Removes all headers with a certain name from this message.
155     *
156     * @param name The name of the headers to remove.
157     */
158    void removeHeaders(String name);
159
160    /**
161     * Returns an iterator of all the headers.
162     *
163     * @return Iterator that returns Header objects in the sequence they are
164     *         sent over a connection.
165     */
166    HeaderIterator headerIterator();
167
168    /**
169     * Returns an iterator of the headers with a given name.
170     *
171     * @param name      the name of the headers over which to iterate, or
172     *                  <code>null</code> for all headers
173     *
174     * @return Iterator that returns Header objects with the argument name
175     *         in the sequence they are sent over a connection.
176     */
177    HeaderIterator headerIterator(String name);
178
179    /**
180     * Returns the parameters effective for this message as set by
181     * {@link #setParams(HttpParams)}.
182     */
183    HttpParams getParams();
184
185    /**
186     * Provides parameters to be used for the processing of this message.
187     * @param params the parameters
188     */
189    void setParams(HttpParams params);
190
191}
192