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}