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;
10import java.util.List;
11import java.util.Map;
12
13/**
14 * HTTP request (GET or POST).
15 */
16public 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