1 // Copyright 2016 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 package org.chromium.net.impl; 5 6 import androidx.annotation.IntDef; 7 import androidx.annotation.Nullable; 8 9 import org.chromium.net.BidirectionalStream; 10 import org.chromium.net.ExperimentalBidirectionalStream; 11 import org.chromium.net.ExperimentalCronetEngine; 12 import org.chromium.net.ExperimentalUrlRequest; 13 import org.chromium.net.RequestFinishedInfo; 14 import org.chromium.net.UrlRequest; 15 16 import java.lang.annotation.Retention; 17 import java.lang.annotation.RetentionPolicy; 18 import java.net.URL; 19 import java.util.Collection; 20 import java.util.List; 21 import java.util.Map; 22 import java.util.concurrent.Executor; 23 24 /** 25 * Base class of {@link CronetUrlRequestContext} and {@link JavaCronetEngine} that contains 26 * shared logic. 27 */ 28 public abstract class CronetEngineBase extends ExperimentalCronetEngine { 29 /* 30 * Network handle representing the default network. To be used when a network has not been 31 * explicitly set. 32 */ 33 protected static final long DEFAULT_NETWORK_HANDLE = -1; 34 35 /** 36 * Creates a {@link UrlRequest} object. All callbacks will 37 * be called on {@code executor}'s thread. {@code executor} must not run 38 * tasks on the current thread to prevent blocking networking operations 39 * and causing exceptions during shutdown. 40 * 41 * @param url {@link URL} for the request. 42 * @param callback callback object that gets invoked on different events. 43 * @param executor {@link Executor} on which all callbacks will be invoked. 44 * @param priority priority of the request which should be one of the 45 * {@link UrlRequest.Builder#REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} 46 * values. 47 * @param requestAnnotations Objects to pass on to 48 * {@link org.chromium.net.RequestFinishedInfo.Listener}. 49 * @param disableCache disables cache for the request. 50 * If context is not set up to use cache this param has no effect. 51 * @param disableConnectionMigration disables connection migration for this 52 * request if it is enabled for the session. 53 * @param allowDirectExecutor whether executors used by this request are permitted 54 * to execute submitted tasks inline. 55 * @param trafficStatsTagSet {@code true} if {@code trafficStatsTag} represents a TrafficStats 56 * tag to apply to sockets used to perform this request. 57 * @param trafficStatsTag TrafficStats tag to apply to sockets used to perform this request. 58 * @param trafficStatsUidSet {@code true} if {@code trafficStatsUid} represents a UID to 59 * attribute traffic used to perform this request. 60 * @param trafficStatsUid UID to attribute traffic used to perform this request. 61 * @param requestFinishedListener callback to get invoked with metrics when request is finished. 62 * Set to {@code null} if not used. 63 * @param idempotency idempotency of the request which should be one of the 64 * {@link ExperimentalUrlRequest.Builder#DEFAULT_IDEMPOTENCY IDEMPOTENT NOT_IDEMPOTENT} 65 * values. 66 * @param network network to be used to send this request. Set to {@code null} if not specified. 67 * @return new request. 68 */ createRequest( String url, UrlRequest.Callback callback, Executor executor, @RequestPriority int priority, Collection<Object> requestAnnotations, boolean disableCache, boolean disableConnectionMigration, boolean allowDirectExecutor, boolean trafficStatsTagSet, int trafficStatsTag, boolean trafficStatsUidSet, int trafficStatsUid, @Nullable RequestFinishedInfo.Listener requestFinishedListener, @Idempotency int idempotency, long networkHandle)69 protected abstract UrlRequestBase createRequest( 70 String url, 71 UrlRequest.Callback callback, 72 Executor executor, 73 @RequestPriority int priority, 74 Collection<Object> requestAnnotations, 75 boolean disableCache, 76 boolean disableConnectionMigration, 77 boolean allowDirectExecutor, 78 boolean trafficStatsTagSet, 79 int trafficStatsTag, 80 boolean trafficStatsUidSet, 81 int trafficStatsUid, 82 @Nullable RequestFinishedInfo.Listener requestFinishedListener, 83 @Idempotency int idempotency, 84 long networkHandle); 85 86 /** 87 * Creates a {@link BidirectionalStream} object. {@code callback} methods will 88 * be invoked on {@code executor}. {@code executor} must not run 89 * tasks on the current thread to prevent blocking networking operations 90 * and causing exceptions during shutdown. 91 * 92 * @param url the URL for the stream 93 * @param callback the object whose methods get invoked upon different events 94 * @param executor the {@link Executor} on which all callbacks will be called 95 * @param httpMethod the HTTP method to use for the stream 96 * @param requestHeaders the list of request headers 97 * @param priority priority of the stream which should be one of the 98 * {@link BidirectionalStream.Builder#STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} 99 * values. 100 * @param delayRequestHeadersUntilFirstFlush whether to delay sending request 101 * headers until flush() is called, and try to combine them 102 * with the next data frame. 103 * @param requestAnnotations Objects to pass on to 104 * {@link org.chromium.net.RequestFinishedInfo.Listener}. 105 * @param trafficStatsTagSet {@code true} if {@code trafficStatsTag} represents a TrafficStats 106 * tag to apply to sockets used to perform this request. 107 * @param trafficStatsTag TrafficStats tag to apply to sockets used to perform this request. 108 * @param trafficStatsUidSet {@code true} if {@code trafficStatsUid} represents a UID to 109 * attribute traffic used to perform this request. 110 * @param trafficStatsUid UID to attribute traffic used to perform this request. 111 * @param network network to be used to send this request. Set to {@code null} if not specified. 112 * @return a new stream. 113 */ createBidirectionalStream( String url, BidirectionalStream.Callback callback, Executor executor, String httpMethod, List<Map.Entry<String, String>> requestHeaders, @StreamPriority int priority, boolean delayRequestHeadersUntilFirstFlush, Collection<Object> requestAnnotations, boolean trafficStatsTagSet, int trafficStatsTag, boolean trafficStatsUidSet, int trafficStatsUid, long networkHandle)114 protected abstract ExperimentalBidirectionalStream createBidirectionalStream( 115 String url, 116 BidirectionalStream.Callback callback, 117 Executor executor, 118 String httpMethod, 119 List<Map.Entry<String, String>> requestHeaders, 120 @StreamPriority int priority, 121 boolean delayRequestHeadersUntilFirstFlush, 122 Collection<Object> requestAnnotations, 123 boolean trafficStatsTagSet, 124 int trafficStatsTag, 125 boolean trafficStatsUidSet, 126 int trafficStatsUid, 127 long networkHandle); 128 129 @Override newUrlRequestBuilder( String url, UrlRequest.Callback callback, Executor executor)130 public ExperimentalUrlRequest.Builder newUrlRequestBuilder( 131 String url, UrlRequest.Callback callback, Executor executor) { 132 return new UrlRequestBuilderImpl(url, callback, executor, this); 133 } 134 135 @IntDef({ 136 UrlRequest.Builder.REQUEST_PRIORITY_IDLE, 137 UrlRequest.Builder.REQUEST_PRIORITY_LOWEST, 138 UrlRequest.Builder.REQUEST_PRIORITY_LOW, 139 UrlRequest.Builder.REQUEST_PRIORITY_MEDIUM, 140 UrlRequest.Builder.REQUEST_PRIORITY_HIGHEST 141 }) 142 @Retention(RetentionPolicy.SOURCE) 143 public @interface RequestPriority {} 144 145 @IntDef({ 146 BidirectionalStream.Builder.STREAM_PRIORITY_IDLE, 147 BidirectionalStream.Builder.STREAM_PRIORITY_LOWEST, 148 BidirectionalStream.Builder.STREAM_PRIORITY_LOW, 149 BidirectionalStream.Builder.STREAM_PRIORITY_MEDIUM, 150 BidirectionalStream.Builder.STREAM_PRIORITY_HIGHEST, 151 }) 152 @Retention(RetentionPolicy.SOURCE) 153 public @interface StreamPriority {} 154 155 @IntDef({ 156 ExperimentalUrlRequest.Builder.DEFAULT_IDEMPOTENCY, 157 ExperimentalUrlRequest.Builder.IDEMPOTENT, 158 ExperimentalUrlRequest.Builder.NOT_IDEMPOTENT 159 }) 160 @Retention(RetentionPolicy.SOURCE) 161 public @interface Idempotency {} 162 } 163