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 }