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 java.util.Locale;
031
032/**
033 * After receiving and interpreting a request message, a server responds
034 * with an HTTP response message.
035 * <pre>
036 *     Response      = Status-Line
037 *                     *(( general-header
038 *                      | response-header
039 *                      | entity-header ) CRLF)
040 *                     CRLF
041 *                     [ message-body ]
042 * </pre>
043 *
044 * @since 4.0
045 */
046public interface HttpResponse extends HttpMessage {
047
048    /**
049     * Obtains the status line of this response.
050     * The status line can be set using one of the
051     * {@link #setStatusLine setStatusLine} methods,
052     * or it can be initialized in a constructor.
053     *
054     * @return  the status line, or {@code null} if not yet set
055     */
056    StatusLine getStatusLine();
057
058    /**
059     * Sets the status line of this response.
060     *
061     * @param statusline the status line of this response
062     */
063    void setStatusLine(StatusLine statusline);
064
065    /**
066     * Sets the status line of this response.
067     * The reason phrase will be determined based on the current
068     * {@link #getLocale locale}.
069     *
070     * @param ver       the HTTP version
071     * @param code      the status code
072     */
073    void setStatusLine(ProtocolVersion ver, int code);
074
075    /**
076     * Sets the status line of this response with a reason phrase.
077     *
078     * @param ver       the HTTP version
079     * @param code      the status code
080     * @param reason    the reason phrase, or {@code null} to omit
081     */
082    void setStatusLine(ProtocolVersion ver, int code, String reason);
083
084    /**
085     * Updates the status line of this response with a new status code.
086     *
087     * @param code the HTTP status code.
088     *
089     * @throws IllegalStateException
090     *          if the status line has not be set
091     *
092     * @see HttpStatus
093     * @see #setStatusLine(StatusLine)
094     * @see #setStatusLine(ProtocolVersion,int)
095     */
096    void setStatusCode(int code)
097        throws IllegalStateException;
098
099    /**
100     * Updates the status line of this response with a new reason phrase.
101     *
102     * @param reason    the new reason phrase as a single-line string, or
103     *                  {@code null} to unset the reason phrase
104     *
105     * @throws IllegalStateException
106     *          if the status line has not be set
107     *
108     * @see #setStatusLine(StatusLine)
109     * @see #setStatusLine(ProtocolVersion,int)
110     */
111    void setReasonPhrase(String reason)
112        throws IllegalStateException;
113
114    /**
115     * Obtains the message entity of this response, if any.
116     * The entity is provided by calling {@link #setEntity setEntity}.
117     *
118     * @return  the response entity, or
119     *          {@code null} if there is none
120     */
121    HttpEntity getEntity();
122
123    /**
124     * Associates a response entity with this response.
125     * <p>
126     * Please note that if an entity has already been set for this response and it depends on
127     * an input stream ({@link HttpEntity#isStreaming()} returns {@code true}),
128     * it must be fully consumed in order to ensure release of resources.
129     *
130     * @param entity    the entity to associate with this response, or
131     *                  {@code null} to unset
132     *
133     * @see HttpEntity#isStreaming()
134     * @see org.apache.http.util.EntityUtils#updateEntity(HttpResponse, HttpEntity)
135     */
136    void setEntity(HttpEntity entity);
137
138    /**
139     * Obtains the locale of this response.
140     * The locale is used to determine the reason phrase
141     * for the {@link #setStatusCode status code}.
142     * It can be changed using {@link #setLocale setLocale}.
143     *
144     * @return  the locale of this response, never {@code null}
145     */
146    Locale getLocale();
147
148    /**
149     * Changes the locale of this response.
150     *
151     * @param loc       the new locale
152     */
153    void setLocale(Locale loc);
154
155}