1/*
2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpResponse.java $
3 * $Revision: 652956 $
4 * $Date: 2008-05-02 17:13:05 -0700 (Fri, 02 May 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
34
35import java.util.Locale;
36
37
38/**
39 * An HTTP response.
40 *
41 * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
42 *
43 * @version $Revision: 652956 $
44 *
45 * @since 4.0
46 */
47public interface HttpResponse extends HttpMessage {
48
49    /**
50     * Obtains the status line of this response.
51     * The status line can be set using one of the
52     * {@link #setStatusLine setStatusLine} methods,
53     * or it can be initialized in a constructor.
54     *
55     * @return  the status line, or <code>null</code> if not yet set
56     */
57    StatusLine getStatusLine();
58
59    /**
60     * Sets the status line of this response.
61     *
62     * @param statusline the status line of this response
63     */
64    void setStatusLine(StatusLine statusline);
65
66    /**
67     * Sets the status line of this response.
68     * The reason phrase will be determined based on the current
69     * {@link #getLocale locale}.
70     *
71     * @param ver       the HTTP version
72     * @param code      the status code
73     */
74    void setStatusLine(ProtocolVersion ver, int code);
75
76    /**
77     * Sets the status line of this response with a reason phrase.
78     *
79     * @param ver       the HTTP version
80     * @param code      the status code
81     * @param reason    the reason phrase, or <code>null</code> to omit
82     */
83    void setStatusLine(ProtocolVersion ver, int code, String reason);
84
85    /**
86     * Updates the status line of this response with a new status code.
87     * The status line can only be updated if it is available. It must
88     * have been set either explicitly or in a constructor.
89     * <br/>
90     * The reason phrase will be updated according to the new status code,
91     * based on the current {@link #getLocale locale}. It can be set
92     * explicitly using {@link #setReasonPhrase setReasonPhrase}.
93     *
94     * @param code the HTTP status code.
95     *
96     * @throws IllegalStateException
97     *          if the status line has not be set
98     *
99     * @see HttpStatus
100     * @see #setStatusLine(StatusLine)
101     * @see #setStatusLine(ProtocolVersion,int)
102     */
103    void setStatusCode(int code)
104        throws IllegalStateException;
105
106    /**
107     * Updates the status line of this response with a new reason phrase.
108     * The status line can only be updated if it is available. It must
109     * have been set either explicitly or in a constructor.
110     *
111     * @param reason    the new reason phrase as a single-line string, or
112     *                  <code>null</code> to unset the reason phrase
113     *
114     * @throws IllegalStateException
115     *          if the status line has not be set
116     *
117     * @see #setStatusLine(StatusLine)
118     * @see #setStatusLine(ProtocolVersion,int)
119     */
120    void setReasonPhrase(String reason)
121        throws IllegalStateException;
122
123    /**
124     * Obtains the message entity of this response, if any.
125     * The entity is provided by calling {@link #setEntity setEntity}.
126     *
127     * @return  the response entity, or
128     *          <code>null</code> if there is none
129     */
130    HttpEntity getEntity();
131
132    /**
133     * Associates a response entity with this response.
134     *
135     * @param entity    the entity to associate with this response, or
136     *                  <code>null</code> to unset
137     */
138    void setEntity(HttpEntity entity);
139
140    /**
141     * Obtains the locale of this response.
142     * The locale is used to determine the reason phrase
143     * for the {@link #setStatusCode status code}.
144     * It can be changed using {@link #setLocale setLocale}.
145     *
146     * @return  the locale of this response, never <code>null</code>
147     */
148    Locale getLocale();
149
150    /**
151     * Changes the locale of this response.
152     * If there is a status line, it's reason phrase will be updated
153     * according to the status code and new locale.
154     *
155     * @param loc       the new locale
156     *
157     * @see #getLocale getLocale
158     * @see #setStatusCode setStatusCode
159     */
160    void setLocale(Locale loc);
161}
162