| 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 |