001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http;
029
030import org.apache.http.params.HttpParams;
031
032/**
033 * HTTP messages consist of requests from client to server and responses
034 * from server to client.
035 * <pre>
036 *     HTTP-message   = Request | Response     ; HTTP/1.1 messages
037 * </pre>
038 * <p>
039 * HTTP messages use the generic message format of RFC 822 for
040 * transferring entities (the payload of the message). Both types
041 * of message consist of a start-line, zero or more header fields
042 * (also known as "headers"), an empty line (i.e., a line with nothing
043 * preceding the CRLF) indicating the end of the header fields,
044 * and possibly a message-body.
045 * </p>
046 * <pre>
047 *      generic-message = start-line
048 *                        *(message-header CRLF)
049 *                        CRLF
050 *                        [ message-body ]
051 *      start-line      = Request-Line | Status-Line
052 * </pre>
053 *
054 * @since 4.0
055 */
056@SuppressWarnings("deprecation")
057public interface HttpMessage {
058
059    /**
060     * Returns the protocol version this message is compatible with.
061     */
062    ProtocolVersion getProtocolVersion();
063
064    /**
065     * Checks if a certain header is present in this message. Header values are
066     * ignored.
067     *
068     * @param name the header name to check for.
069     * @return true if at least one header with this name is present.
070     */
071    boolean containsHeader(String name);
072
073    /**
074     * Returns all the headers with a specified name of this message. Header values
075     * are ignored. Headers are orderd in the sequence they will be sent over a
076     * connection.
077     *
078     * @param name the name of the headers to return.
079     * @return the headers whose name property equals {@code name}.
080     */
081    Header[] getHeaders(String name);
082
083    /**
084     * Returns the first header with a specified name of this message. Header
085     * values are ignored. If there is more than one matching header in the
086     * message the first element of {@link #getHeaders(String)} is returned.
087     * If there is no matching header in the message {@code null} is
088     * returned.
089     *
090     * @param name the name of the header to return.
091     * @return the first header whose name property equals {@code name}
092     *   or {@code null} if no such header could be found.
093     */
094    Header getFirstHeader(String name);
095
096    /**
097     * Returns the last header with a specified name of this message. Header values
098     * are ignored. If there is more than one matching header in the message the
099     * last element of {@link #getHeaders(String)} is returned. If there is no
100     * matching header in the message {@code null} is returned.
101     *
102     * @param name the name of the header to return.
103     * @return the last header whose name property equals {@code name}.
104     *   or {@code null} 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} 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}