1 // Copyright 2014 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 package org.chromium.net; 6 7 import java.io.IOException; 8 import java.nio.ByteBuffer; 9 import java.nio.channels.ReadableByteChannel; 10 import java.util.List; 11 import java.util.Map; 12 13 /** 14 * HTTP request (GET or POST). 15 */ 16 public interface HttpUrlRequest { 17 18 public static final int REQUEST_PRIORITY_IDLE = 0; 19 20 public static final int REQUEST_PRIORITY_LOWEST = 1; 21 22 public static final int REQUEST_PRIORITY_LOW = 2; 23 24 public static final int REQUEST_PRIORITY_MEDIUM = 3; 25 26 public static final int REQUEST_PRIORITY_HIGHEST = 4; 27 28 /** 29 * Returns the URL associated with this request. 30 */ 31 String getUrl(); 32 33 /** 34 * Requests a range starting at the given offset to the end of the resource. 35 * The server may or may not honor the offset request. The client must check 36 * the HTTP status code before processing the response. 37 */ 38 void setOffset(long offset); 39 40 /** 41 * Limits the size of the download. 42 * 43 * @param limit Maximum size of the downloaded response (post gzip) 44 * @param cancelEarly If true, cancel the download as soon as the size of 45 * the response is known. If false, download {@code responseSize} 46 * bytes and then cancel. 47 */ 48 void setContentLengthLimit(long limit, boolean cancelEarly); 49 50 /** 51 * Sets data to upload as part of a POST request. 52 * 53 * @param contentType MIME type of the post content or null if this is not a 54 * POST. 55 * @param data The content that needs to be uploaded if this is a POST 56 * request. 57 */ 58 void setUploadData(String contentType, byte[] data); 59 60 /** 61 * Sets a readable byte channel to upload as part of a POST request. 62 * 63 * <p>Once {@link #start()} is called, this channel is guaranteed to be 64 * closed, either when the upload completes, or when it is canceled. 65 * 66 * @param contentType MIME type of the post content or null if this is not a 67 * POST. 68 * @param channel The channel to read to read upload data from if this is a 69 * POST request. 70 * @param contentLength The length of data to upload. 71 */ 72 void setUploadChannel(String contentType, ReadableByteChannel channel, 73 long contentLength); 74 75 /** 76 * Sets the HTTP method verb to use for this request. 77 * 78 * <p>The default when this method is not called is "GET" if the request has 79 * no body or "POST" if it does. 80 * 81 * @param method "GET", "POST", etc. Must be all uppercase. 82 */ 83 void setHttpMethod(String method); 84 85 /** 86 * Start executing the request. 87 * <p> 88 * If this is a streaming upload request using a ReadableByteChannel, the 89 * call will block while the request is uploaded. 90 */ 91 void start(); 92 93 /** 94 * Cancel the request in progress. 95 */ 96 void cancel(); 97 98 /** 99 * Returns {@code true} if the request has been canceled. 100 */ 101 boolean isCanceled(); 102 103 /** 104 * Returns protocol (e.g. "quic/1+spdy/3") negotiated with server. Returns 105 * empty string if no protocol was negotiated, or the protocol is not known. 106 * Returns empty when using plain http or https. Must be called after 107 * onResponseStarted but before request is recycled. 108 */ 109 String getNegotiatedProtocol(); 110 111 /** 112 * Returns the entire response as a ByteBuffer. 113 */ 114 ByteBuffer getByteBuffer(); 115 116 /** 117 * Returns the entire response as a byte array. 118 */ 119 byte[] getResponseAsBytes(); 120 121 /** 122 * Returns the expected content length. It is not guaranteed to be correct 123 * and may be -1 if the content length is unknown. 124 */ 125 long getContentLength(); 126 127 /** 128 * Returns the content MIME type if known or {@code null} otherwise. 129 */ 130 String getContentType(); 131 132 /** 133 * Returns the HTTP status code. It may be 0 if the request has not started 134 * or failed before getting the status code from the server. If the status 135 * code is 206 (partial response) after {@link #setOffset} is called, the 136 * method returns 200. 137 */ 138 int getHttpStatusCode(); 139 140 /** 141 * Returns the response header value for the given name or {@code null} if 142 * not found. 143 */ 144 String getHeader(String name); 145 146 /** 147 * Returns an unmodifiable map of the response-header fields and values. 148 * The null key is mapped to the HTTP status line for compatibility with 149 * HttpUrlConnection. 150 */ 151 Map<String, List<String>> getAllHeaders(); 152 153 /** 154 * Returns the exception that occurred while executing the request of null 155 * if the request was successful. 156 */ 157 IOException getException(); 158 } 159