Home | History | Annotate | Download | only in net 
      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