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