OLD | NEW |
1 # Quick Start Guide to Using Cronet | 1 # Quick Start Guide to Using Cronet |
2 Cronet is the networking stack of Chromium put into a library for use on | 2 Cronet is the networking stack of Chromium put into a library for use on |
3 mobile. This is the same networking stack that is used in the Chrome browser | 3 mobile. This is the same networking stack that is used in the Chrome browser |
4 by over a billion people. It offers an easy-to-use, high performance, | 4 by over a billion people. It offers an easy-to-use, high performance, |
5 standards-compliant, and secure way to perform HTTP requests. Cronet has support | 5 standards-compliant, and secure way to perform HTTP requests. Cronet has support |
6 for both Android and iOS. On Android, Cronet offers its own Java asynchronous | 6 for both Android and iOS. On Android, Cronet offers its own Java asynchronous |
7 API as well as support for the [java.net.HttpURLConnection] API. | 7 API as well as support for the [java.net.HttpURLConnection] API. |
8 This document gives a brief introduction to using these two Java APIs. | 8 This document gives a brief introduction to using these two Java APIs. |
9 | 9 |
10 ### Basics | 10 ### Basics |
11 First you will need to implement the `UrlRequestListener` interface to handle | 11 First you will need to extend `UrlRequestListener` to handle |
12 events during the lifetime of a request. For example: | 12 events during the lifetime of a request. For example: |
13 | 13 |
14 class MyListener implements UrlRequestListener { | 14 class MyListener extends UrlRequestListener { |
15 @Override | 15 @Override |
16 public void onReceivedRedirect(UrlRequest request, | 16 public void onReceivedRedirect(UrlRequest request, |
17 ResponseInfo responseInfo, String newLocationUrl) { | 17 ResponseInfo responseInfo, String newLocationUrl) { |
18 if (followRedirect) { | 18 if (followRedirect) { |
19 // Let's tell Cronet to follow the redirect! | 19 // Let's tell Cronet to follow the redirect! |
20 mRequest.followRedirect(); | 20 mRequest.followRedirect(); |
21 } else { | 21 } else { |
22 // Not worth following the redirect? Abandon the request. | 22 // Not worth following the redirect? Abandon the request. |
23 mRequest.cancel(); | 23 mRequest.cancel(); |
24 } | 24 } |
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
70 | 70 |
71 UrlRequestContextConfig myConfig = new UrlRequestContextConfig(); | 71 UrlRequestContextConfig myConfig = new UrlRequestContextConfig(); |
72 CronetUrlRequestContext myRequestContext = | 72 CronetUrlRequestContext myRequestContext = |
73 new CronetUrlRequestContext(getContext(), myConfig); | 73 new CronetUrlRequestContext(getContext(), myConfig); |
74 Executor executor = Executors.newSingleThreadExecutor(); | 74 Executor executor = Executors.newSingleThreadExecutor(); |
75 MyListener listener = new MyListener(); | 75 MyListener listener = new MyListener(); |
76 UrlRequest request = myRequestContext.createRequest( | 76 UrlRequest request = myRequestContext.createRequest( |
77 "https://www.example.com", listener, executor); | 77 "https://www.example.com", listener, executor); |
78 request.start(); | 78 request.start(); |
79 | 79 |
80 In the above example, `MyListener` implements the `UrlRequestListener` | 80 In the above example, `MyListener` extends `UrlRequestListener`. The request |
81 interface. The request is started asynchronously. When the response is ready | 81 is started asynchronously. When the response is ready (fully or partially), and |
82 (fully or partially), and in the event of failures or redirects, | 82 in the event of failures or redirects, `listener`'s methods will be invoked on |
83 `listener`'s methods will be invoked on `executor`'s thread to inform the | 83 `executor`'s thread to inform the client of the request state and/or response |
84 client of the request state and/or response information. | 84 information. |
85 | 85 |
86 ### Downloading Data | 86 ### Downloading Data |
87 When Cronet fetches response headers from the server or gets them from the | 87 When Cronet fetches response headers from the server or gets them from the |
88 cache, `UrlRequestListener.onResponseStarted` will be invoked. To read the | 88 cache, `UrlRequestListener.onResponseStarted` will be invoked. To read the |
89 response body, the client should call `UrlRequest.read` and supply a | 89 response body, the client should call `UrlRequest.read` and supply a |
90 [ByteBuffer] for Cronet to fill. Once a portion or all of | 90 [ByteBuffer] for Cronet to fill. Once a portion or all of |
91 the response body is read, `UrlRequestListener.onReadCompleted` will be invoked. | 91 the response body is read, `UrlRequestListener.onReadCompleted` will be invoked. |
92 The client may consume the data, or copy the contents of the `byteBuffer` | 92 The client may then read and consume the data within `byteBuffer`. |
93 elsewhere for use later. The data in `byteBuffer` is only guaranteed to be | |
94 valid for the duration of the `UrlRequestListener.onReadCompleted` callback. | |
95 Once the client is ready to consume more data, the client should call | 93 Once the client is ready to consume more data, the client should call |
96 `UrlRequest.read` again. The process continues until | 94 `UrlRequest.read` again. The process continues until |
97 `UrlRequestListener.onSucceeded` or `UrlRequestListener.onFailed` is invoked, | 95 `UrlRequestListener.onSucceeded` or `UrlRequestListener.onFailed` is invoked, |
98 which signals the completion of the request. | 96 which signals the completion of the request. |
99 | 97 |
100 ### Uploading Data | 98 ### Uploading Data |
101 MyUploadDataProvider myUploadDataProvider = new MyUploadDataProvider(); | 99 MyUploadDataProvider myUploadDataProvider = new MyUploadDataProvider(); |
102 request.setHttpMethod("POST"); | 100 request.setHttpMethod("POST"); |
103 request.setUploadDataProvider(myUploadDataProvider, executor); | 101 request.setUploadDataProvider(myUploadDataProvider, executor); |
104 request.start(); | 102 request.start(); |
105 | 103 |
106 In the above example, `MyUploadDataProvider` implements the | 104 In the above example, `MyUploadDataProvider` extends `UploadDataProvider`. |
107 `UploadDataProvider` interface. When Cronet is ready to send the request body, | 105 When Cronet is ready to send the request body, |
108 `myUploadDataProvider.read(UploadDataSink uploadDataSink, | 106 `myUploadDataProvider.read(UploadDataSink uploadDataSink, |
109 ByteBuffer byteBuffer)` will be invoked. The client will need to write the | 107 ByteBuffer byteBuffer)` will be invoked. The client will need to write the |
110 request body into `byteBuffer`. Once the client is done writing into | 108 request body into `byteBuffer`. Once the client is done writing into |
111 `byteBuffer`, the client can let Cronet know by calling | 109 `byteBuffer`, the client can let Cronet know by calling |
112 `uploadDataSink.onReadSucceeded`. If the request body doesn't fit into | 110 `uploadDataSink.onReadSucceeded`. If the request body doesn't fit into |
113 `byteBuffer`, the client can continue writing when `UploadDataProvider.read` is | 111 `byteBuffer`, the client can continue writing when `UploadDataProvider.read` is |
114 invoked again. For more details, please see the API reference. | 112 invoked again. For more details, please see the API reference. |
115 | 113 |
116 ### <a id=configuring-cronet></a> Configuring Cronet | 114 ### <a id=configuring-cronet></a> Configuring Cronet |
117 Various configuration options are available via the `UrlRequestContextConfig` | 115 Various configuration options are available via the `UrlRequestContextConfig` |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
160 see {@link org.chromium.net.urlconnection.CronetURLStreamHandlerFactory} for | 158 see {@link org.chromium.net.urlconnection.CronetURLStreamHandlerFactory} for |
161 more information). | 159 more information). |
162 You can configure Cronet and control caching through the | 160 You can configure Cronet and control caching through the |
163 `UrlRequestContextConfig` instance, `myConfig` | 161 `UrlRequestContextConfig` instance, `myConfig` |
164 (See [Configuring Cronet](#configuring-cronet) section), before you pass it | 162 (See [Configuring Cronet](#configuring-cronet) section), before you pass it |
165 into the `CronetURLStreamHandlerFactory` constructor. | 163 into the `CronetURLStreamHandlerFactory` constructor. |
166 | 164 |
167 [ByteBuffer]: https://developer.android.com/reference/java/nio/ByteBuffer.html | 165 [ByteBuffer]: https://developer.android.com/reference/java/nio/ByteBuffer.html |
168 [chrome://net-internals#import]: chrome://net-internals#import | 166 [chrome://net-internals#import]: chrome://net-internals#import |
169 [java.net.HttpURLConnection]: https://developer.android.com/reference/java/net/H
ttpURLConnection.html | 167 [java.net.HttpURLConnection]: https://developer.android.com/reference/java/net/H
ttpURLConnection.html |
OLD | NEW |