1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
# Quick Start Guide to Using Cronet
Cronet offers its own Java asynchronous API as well as support for the
[java.net.HttpURLConnection] API. This document gives a brief introduction to
using these two Java APIs.
## Using Cronet's Java asynchronous API
First you will need to extend `UrlRequest.Callback` to handle
events during the lifetime of a request. For example:
class MyCallback extends UrlRequest.Callback {
@Override
public void onRedirectReceived(UrlRequest request,
UrlResponseInfo responseInfo, String newLocationUrl) {
if (followRedirect) {
// Let's tell Cronet to follow the redirect!
request.followRedirect();
} else {
// Not worth following the redirect? Abandon the request.
request.cancel();
}
}
@Override
public void onResponseStarted(UrlRequest request,
UrlResponseInfo responseInfo) {
// Now we have response headers!
int httpStatusCode = responseInfo.getHttpStatusCode();
if (httpStatusCode == 200) {
// Success! Let's tell Cronet to read the response body.
request.read(myBuffer);
} else if (httpStatusCode == 503) {
// Do something. Note that 4XX and 5XX are not considered
// errors from Cronet's perspective since the response is
// successfully read.
}
mResponseHeaders = responseInfo.getAllHeaders();
}
@Override
public void onReadCompleted(UrlRequest request,
UrlResponseInfo responseInfo, ByteBuffer byteBuffer) {
// Response body is available.
doSomethingWithResponseData(byteBuffer);
// Let's tell Cronet to continue reading the response body or
// inform us that the response is complete!
request.read(mBuffer);
}
@Override
public void onSucceeded(UrlRequest request,
UrlResponseInfo responseInfo) {
// Request has completed successfully!
}
@Override
public void onFailed(UrlRequest request,
UrlResponseInfo responseInfo, CronetException error) {
// Request has failed. responseInfo might be null.
Log.e("MyCallback", "Request failed. " + error.getMessage());
// Maybe handle error here. Typical errors include hostname
// not resolved, connection to server refused, etc.
}
}
Make a request like this:
CronetEngine.Builder engineBuilder = new CronetEngine.Builder(getContext());
CronetEngine engine = engineBuilder.build();
Executor executor = Executors.newSingleThreadExecutor();
MyCallback callback = new MyCallback();
UrlRequest.Builder requestBuilder = engine.newUrlRequestBuilder(
"https://www.example.com", callback, executor);
UrlRequest request = requestBuilder.build();
request.start();
In the above example, `MyCallback` extends `UrlRequest.Callback`. The request
is started asynchronously. When the response is ready (fully or partially), and
in the event of failures or redirects, `callback`'s methods will be invoked on
`executor`'s thread to inform the client of the request state and/or response
information.
### Downloading Data
When Cronet fetches response headers from the server or gets them from the
cache, `UrlRequest.Callback.onResponseStarted` will be invoked. To read the
response body, the client should call `UrlRequest.read` and supply a
[ByteBuffer] for Cronet to fill. Once a portion or all of
the response body is read, `UrlRequest.Callback.onReadCompleted` will be invoked.
The client may then read and consume the data within `byteBuffer`.
Once the client is ready to consume more data, the client should call
`UrlRequest.read` again. The process continues until
`UrlRequest.Callback.onSucceeded` or `UrlRequest.Callback.onFailed` is invoked,
which signals the completion of the request.
### Uploading Data
MyUploadDataProvider myUploadDataProvider = new MyUploadDataProvider();
requestBuilder.setHttpMethod("POST");
requestBuilder.setUploadDataProvider(myUploadDataProvider, executor);
In the above example, `MyUploadDataProvider` extends `UploadDataProvider`.
When Cronet is ready to send the request body,
`myUploadDataProvider.read(UploadDataSink uploadDataSink,
ByteBuffer byteBuffer)` will be invoked. The client will need to write the
request body into `byteBuffer`. Once the client is done writing into
`byteBuffer`, the client can let Cronet know by calling
`uploadDataSink.onReadSucceeded`. If the request body doesn't fit into
`byteBuffer`, the client can continue writing when `UploadDataProvider.read` is
invoked again. For more details, please see the API reference.
### <a id=configuring-cronet></a> Configuring Cronet
Various configuration options are available via the `CronetEngine.Builder`
object.
Enabling HTTP/2 and QUIC:
- For Example:
engineBuilder.enableHttp2(true).enableQuic(true);
Controlling the cache:
- Use a 100KiB in-memory cache:
engineBuilder.enableHttpCache(
CronetEngine.Builder.HttpCache.IN_MEMORY, 100 * 1024);
- or use a 1MiB disk cache:
engineBuilder.setStoragePath(storagePathString);
engineBuilder.enableHttpCache(CronetEngine.Builder.HttpCache.DISK,
1024 * 1024);
### Debugging
To get more information about how Cronet is processing network
requests, you can start and stop **NetLog** logging by calling
`CronetEngine.startNetLogToFile` and `CronetEngine.stopNetLog`.
Bear in mind that logs may contain sensitive data. You may analyze the
generated log by navigating to [chrome://net-internals#import] using a
Chrome browser.
## Using the java.net.HttpURLConnection API
Cronet offers an implementation of the [java.net.HttpURLConnection] API to make
it easier for apps which rely on this API to use Cronet.
To open individual connections using Cronet's implementation, do the following:
HttpURLConnection connection =
(HttpURLConnection)engine.openConnection(url);
To use Cronet's implementation instead of the system's default implementation
for all connections established using `URL.openConnection()` do the following:
URL.setURLStreamHandlerFactory(engine.createURLStreamHandlerFactory());
Cronet's
HttpURLConnection implementation has some limitations as compared to the system
implementation, including not utilizing the default system HTTP cache (Please
see {@link org.chromium.net.CronetEngine#createURLStreamHandlerFactory} for
more information).
You can configure Cronet and control caching through the
`CronetEngine.Builder` instance, `engineBuilder`
(See [Configuring Cronet](#configuring-cronet) section), before you build the
`CronetEngine` and then call `CronetEngine.createURLStreamHandlerFactory()`.
[ByteBuffer]: https://developer.android.com/reference/java/nio/ByteBuffer.html
[chrome://net-internals#import]: chrome://net-internals#import
[java.net.HttpURLConnection]: https://developer.android.com/reference/java/net/HttpURLConnection.html
|
