1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.webkit; 18 19 import android.annotation.NonNull; 20 import android.annotation.SystemApi; 21 import android.annotation.UnsupportedAppUsage; 22 23 import java.io.InputStream; 24 import java.io.StringBufferInputStream; 25 import java.util.Map; 26 27 /** 28 * Encapsulates a resource response. Applications can return an instance of this 29 * class from {@link WebViewClient#shouldInterceptRequest} to provide a custom 30 * response when the WebView requests a particular resource. 31 */ 32 public class WebResourceResponse { 33 @UnsupportedAppUsage 34 private boolean mImmutable; 35 private String mMimeType; 36 private String mEncoding; 37 @UnsupportedAppUsage 38 private int mStatusCode; 39 private String mReasonPhrase; 40 private Map<String, String> mResponseHeaders; 41 private InputStream mInputStream; 42 43 /** 44 * Constructs a resource response with the given MIME type, character encoding, 45 * and input stream. Callers must implement {@link InputStream#read(byte[])} for 46 * the input stream. {@link InputStream#close()} will be called after the WebView 47 * has finished with the response. 48 * 49 * <p class="note"><b>Note:</b> The MIME type and character encoding must 50 * be specified as separate parameters (for example {@code "text/html"} and 51 * {@code "utf-8"}), not a single value like the {@code "text/html; charset=utf-8"} 52 * format used in the HTTP Content-Type header. Do not use the value of a HTTP 53 * Content-Encoding header for {@code encoding}, as that header does not specify a 54 * character encoding. Content without a defined character encoding (for example 55 * image resources) should pass {@code null} for {@code encoding}. 56 * 57 * @param mimeType the resource response's MIME type, for example {@code "text/html"}. 58 * @param encoding the resource response's character encoding, for example {@code "utf-8"}. 59 * @param data the input stream that provides the resource response's data. Must not be a 60 * StringBufferInputStream. 61 */ 62 public WebResourceResponse(String mimeType, String encoding, 63 InputStream data) { 64 mMimeType = mimeType; 65 mEncoding = encoding; 66 setData(data); 67 } 68 69 /** 70 * Constructs a resource response with the given parameters. Callers must implement 71 * {@link InputStream#read(byte[])} for the input stream. {@link InputStream#close()} will be 72 * called after the WebView has finished with the response. 73 * 74 * 75 * <p class="note"><b>Note:</b> See {@link #WebResourceResponse(String,String,InputStream)} 76 * for details on what should be specified for {@code mimeType} and {@code encoding}. 77 * 78 * @param mimeType the resource response's MIME type, for example {@code "text/html"}. 79 * @param encoding the resource response's character encoding, for example {@code "utf-8"}. 80 * @param statusCode the status code needs to be in the ranges [100, 299], [400, 599]. 81 * Causing a redirect by specifying a 3xx code is not supported. 82 * @param reasonPhrase the phrase describing the status code, for example "OK". Must be 83 * non-empty. 84 * @param responseHeaders the resource response's headers represented as a mapping of header 85 * name -> header value. 86 * @param data the input stream that provides the resource response's data. Must not be a 87 * StringBufferInputStream. 88 */ 89 public WebResourceResponse(String mimeType, String encoding, int statusCode, 90 @NonNull String reasonPhrase, Map<String, String> responseHeaders, InputStream data) { 91 this(mimeType, encoding, data); 92 setStatusCodeAndReasonPhrase(statusCode, reasonPhrase); 93 setResponseHeaders(responseHeaders); 94 } 95 96 /** 97 * Sets the resource response's MIME type, for example "text/html". 98 * 99 * @param mimeType The resource response's MIME type 100 */ 101 public void setMimeType(String mimeType) { 102 checkImmutable(); 103 mMimeType = mimeType; 104 } 105 106 /** 107 * Gets the resource response's MIME type. 108 * 109 * @return The resource response's MIME type 110 */ 111 public String getMimeType() { 112 return mMimeType; 113 } 114 115 /** 116 * Sets the resource response's encoding, for example "UTF-8". This is used 117 * to decode the data from the input stream. 118 * 119 * @param encoding The resource response's encoding 120 */ 121 public void setEncoding(String encoding) { 122 checkImmutable(); 123 mEncoding = encoding; 124 } 125 126 /** 127 * Gets the resource response's encoding. 128 * 129 * @return The resource response's encoding 130 */ 131 public String getEncoding() { 132 return mEncoding; 133 } 134 135 /** 136 * Sets the resource response's status code and reason phrase. 137 * 138 * @param statusCode the status code needs to be in the ranges [100, 299], [400, 599]. 139 * Causing a redirect by specifying a 3xx code is not supported. 140 * @param reasonPhrase the phrase describing the status code, for example "OK". Must be 141 * non-empty. 142 */ 143 public void setStatusCodeAndReasonPhrase(int statusCode, @NonNull String reasonPhrase) { 144 checkImmutable(); 145 if (statusCode < 100) 146 throw new IllegalArgumentException("statusCode can't be less than 100."); 147 if (statusCode > 599) 148 throw new IllegalArgumentException("statusCode can't be greater than 599."); 149 if (statusCode > 299 && statusCode < 400) 150 throw new IllegalArgumentException("statusCode can't be in the [300, 399] range."); 151 if (reasonPhrase == null) 152 throw new IllegalArgumentException("reasonPhrase can't be null."); 153 if (reasonPhrase.trim().isEmpty()) 154 throw new IllegalArgumentException("reasonPhrase can't be empty."); 155 for (int i = 0; i < reasonPhrase.length(); i++) { 156 int c = reasonPhrase.charAt(i); 157 if (c > 0x7F) { 158 throw new IllegalArgumentException( 159 "reasonPhrase can't contain non-ASCII characters."); 160 } 161 } 162 mStatusCode = statusCode; 163 mReasonPhrase = reasonPhrase; 164 } 165 166 /** 167 * Gets the resource response's status code. 168 * 169 * @return The resource response's status code. 170 */ 171 public int getStatusCode() { 172 return mStatusCode; 173 } 174 175 /** 176 * Gets the description of the resource response's status code. 177 * 178 * @return The description of the resource response's status code. 179 */ 180 public String getReasonPhrase() { 181 return mReasonPhrase; 182 } 183 184 /** 185 * Sets the headers for the resource response. 186 * 187 * @param headers Mapping of header name -> header value. 188 */ 189 public void setResponseHeaders(Map<String, String> headers) { 190 checkImmutable(); 191 mResponseHeaders = headers; 192 } 193 194 /** 195 * Gets the headers for the resource response. 196 * 197 * @return The headers for the resource response. 198 */ 199 public Map<String, String> getResponseHeaders() { 200 return mResponseHeaders; 201 } 202 203 /** 204 * Sets the input stream that provides the resource response's data. Callers 205 * must implement {@link InputStream#read(byte[])}. {@link InputStream#close()} 206 * will be called after the WebView has finished with the response. 207 * 208 * @param data the input stream that provides the resource response's data. Must not be a 209 * StringBufferInputStream. 210 */ 211 public void setData(InputStream data) { 212 checkImmutable(); 213 // If data is (or is a subclass of) StringBufferInputStream 214 if (data != null && StringBufferInputStream.class.isAssignableFrom(data.getClass())) { 215 throw new IllegalArgumentException("StringBufferInputStream is deprecated and must " + 216 "not be passed to a WebResourceResponse"); 217 } 218 mInputStream = data; 219 } 220 221 /** 222 * Gets the input stream that provides the resource response's data. 223 * 224 * @return The input stream that provides the resource response's data 225 */ 226 public InputStream getData() { 227 return mInputStream; 228 } 229 230 /** 231 * The internal version of the constructor that doesn't perform arguments checks. 232 * @hide 233 */ 234 @SystemApi 235 public WebResourceResponse(boolean immutable, String mimeType, String encoding, int statusCode, 236 String reasonPhrase, Map<String, String> responseHeaders, InputStream data) { 237 mImmutable = immutable; 238 mMimeType = mimeType; 239 mEncoding = encoding; 240 mStatusCode = statusCode; 241 mReasonPhrase = reasonPhrase; 242 mResponseHeaders = responseHeaders; 243 mInputStream = data; 244 } 245 246 private void checkImmutable() { 247 if (mImmutable) 248 throw new IllegalStateException("This WebResourceResponse instance is immutable"); 249 } 250 } 251
