1 // Copyright 2015 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 5 package android.net.http; 6 7 import androidx.annotation.NonNull; 8 9 import java.io.Closeable; 10 import java.io.IOException; 11 import java.nio.ByteBuffer; 12 13 /** 14 * Abstract class allowing the embedder to provide an upload body to {@link UrlRequest}. It supports 15 * both non-chunked (size known in advanced) and chunked (size not known in advance) uploads. Be 16 * aware that not all servers support chunked uploads. 17 * 18 * <p>An upload is either always chunked, across multiple uploads if the data 19 * ends up being sent more than once, or never chunked. 20 */ 21 public abstract class UploadDataProvider implements Closeable { 22 /** 23 * If this is a non-chunked upload, returns the length of the upload. Must always return -1 if 24 * this is a chunked upload. 25 * 26 * @return the length of the upload for non-chunked uploads, -1 otherwise. 27 * @throws IOException if any IOException occurred during the process. 28 */ getLength()29 public abstract long getLength() throws IOException; 30 31 /** 32 * Reads upload data into {@code byteBuffer}. Upon completion, the buffer's position is updated 33 * to the end of the bytes that were read. The buffer's limit is not changed. Each call of this 34 * method must be followed be a single call, either synchronous or asynchronous, to {@code 35 * uploadDataSink}: {@link UploadDataSink#onReadSucceeded} on success or {@link 36 * UploadDataSink#onReadError} on failure. Neither read nor rewind will be called until one of 37 * those methods or the other is called. Even if the associated {@link UrlRequest} is canceled, 38 * one or the other must still be called before resources can be safely freed. Throwing an 39 * exception will also result in resources being freed and the request being errored out. 40 * 41 * @param uploadDataSink The object to notify when the read has completed, successfully or 42 * otherwise. 43 * @param byteBuffer The buffer to copy the read bytes into. Do not change byteBuffer's limit. 44 * @throws IOException if any IOException occurred during the process. {@link 45 * UrlRequest.Callback#onFailed} will be called with the thrown exception set as the cause of 46 * the 47 * {@link CallbackException}. 48 */ read(@onNull UploadDataSink uploadDataSink, @NonNull ByteBuffer byteBuffer)49 public abstract void read(@NonNull UploadDataSink uploadDataSink, 50 @NonNull ByteBuffer byteBuffer) throws IOException; 51 52 /** 53 * Rewinds upload data. Each call must be followed be a single call, either synchronous or 54 * asynchronous, to {@code uploadDataSink}: {@link UploadDataSink#onRewindSucceeded} on success 55 * or 56 * {@link UploadDataSink#onRewindError} on failure. Neither read nor rewind will be called until 57 * one of those methods or the other is called. Even if the associated {@link UrlRequest} is 58 * canceled, one or the other must still be called before resources can be safely freed. 59 * Throwing an exception will also result in resources being freed and the request being errored 60 * out. 61 * 62 * <p>If rewinding is not supported, this should call 63 * {@link UploadDataSink#onRewindError}. Note that rewinding is required to follow redirects 64 * that preserve the upload body, and for retrying when the server times out stale sockets. 65 * 66 * @param uploadDataSink The object to notify when the rewind operation has completed, 67 * successfully or otherwise. 68 * @throws IOException if any IOException occurred during the process. {@link 69 * UrlRequest.Callback#onFailed} will be called with the thrown exception set as the cause of 70 * the 71 * {@link CallbackException}. 72 */ rewind(@onNull UploadDataSink uploadDataSink)73 public abstract void rewind(@NonNull UploadDataSink uploadDataSink) throws IOException; 74 75 /** 76 * Called when this UploadDataProvider is no longer needed by a request, so that resources (like 77 * a file) can be explicitly released. 78 * 79 * @throws IOException if any IOException occurred during the process. This will cause the 80 * request 81 * to fail if it is not yet complete; otherwise it will be logged. 82 */ 83 @Override close()84 public void close() throws IOException {} 85 } 86