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 java.util.Locale;
31  
32  /**
33   * After receiving and interpreting a request message, a server responds
34   * with an HTTP response message.
35   * <pre>
36   *     Response      = Status-Line
37   *                     *(( general-header
38   *                      | response-header
39   *                      | entity-header ) CRLF)
40   *                     CRLF
41   *                     [ message-body ]
42   * </pre>
43   *
44   * @since 4.0
45   */
46  public interface HttpResponse extends HttpMessage {
47  
48      /**
49       * Obtains the status line of this response.
50       * The status line can be set using one of the
51       * {@link #setStatusLine setStatusLine} methods,
52       * or it can be initialized in a constructor.
53       *
54       * @return  the status line, or {@code null} if not yet set
55       */
56      StatusLine getStatusLine();
57  
58      /**
59       * Sets the status line of this response.
60       *
61       * @param statusline the status line of this response
62       */
63      void setStatusLine(StatusLine statusline);
64  
65      /**
66       * Sets the status line of this response.
67       * The reason phrase will be determined based on the current
68       * {@link #getLocale locale}.
69       *
70       * @param ver       the HTTP version
71       * @param code      the status code
72       */
73      void setStatusLine(ProtocolVersion ver, int code);
74  
75      /**
76       * Sets the status line of this response with a reason phrase.
77       *
78       * @param ver       the HTTP version
79       * @param code      the status code
80       * @param reason    the reason phrase, or {@code null} to omit
81       */
82      void setStatusLine(ProtocolVersion ver, int code, String reason);
83  
84      /**
85       * Updates the status line of this response with a new status code.
86       *
87       * @param code the HTTP status code.
88       *
89       * @throws IllegalStateException
90       *          if the status line has not be set
91       *
92       * @see HttpStatus
93       * @see #setStatusLine(StatusLine)
94       * @see #setStatusLine(ProtocolVersion,int)
95       */
96      void setStatusCode(int code)
97          throws IllegalStateException;
98  
99      /**
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 }