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