src/components/cronet/android/java/src/org/chromium/net/HttpUrlRequest.java

   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. Currently can only be
  77      * "POST" or "PUT".
  78      *
  79      * <p>The default when this method is not called is "GET" if the request has
  80      * no body or "POST" if it does.
  81      *
  82      * @param method Either "POST" or "PUT".
  83      */
  84     void setHttpMethod(String method);
  85
  86     /**
  87      * Start executing the request.
  88      * <p>
  89      * If this is a streaming upload request using a ReadableByteChannel, the
  90      * call will block while the request is uploaded.
  91      */
  92     void start();
  93
  94     /**
  95      * Cancel the request in progress.
  96      */
  97     void cancel();
  98
  99     /**
 100      * Returns {@code true} if the request has been canceled.
 101      */
 102     boolean isCanceled();
 103
 104     /**
 105      * Returns the entire response as a ByteBuffer.
 106      */
 107     ByteBuffer getByteBuffer();
 108
 109     /**
 110      * Returns the entire response as a byte array.
 111      */
 112     byte[] getResponseAsBytes();
 113
 114     /**
 115      * Returns the expected content length. It is not guaranteed to be correct
 116      * and may be -1 if the content length is unknown.
 117      */
 118     long getContentLength();
 119
 120     /**
 121      * Returns the content MIME type if known or {@code null} otherwise.
 122      */
 123     String getContentType();
 124
 125     /**
 126      * Returns the HTTP status code. It may be 0 if the request has not started
 127      * or failed before getting the status code from the server. If the status
 128      * code is 206 (partial response) after {@link #setOffset} is called, the
 129      * method returns 200.
 130      */
 131     int getHttpStatusCode();
 132
 133     /**
 134      * Returns the response header value for the given name or {@code null} if
 135      * not found.
 136      */
 137     String getHeader(String name);
 138
 139     /**
 140      * Returns an unmodifiable map of the response-header fields and values.
 141      * The null key is mapped to the HTTP status line for compatibility with
 142      * HttpUrlConnection.
 143      */
 144     Map<String, List<String>> getAllHeaders();
 145
 146     /**
 147      * Returns the exception that occurred while executing the request of null
 148      * if the request was successful.
 149      */
 150     IOException getException();
 151 }