1 // Copyright 2021 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package com.google.android.downloader; 16 17 import java.io.IOException; 18 import java.nio.channels.WritableByteChannel; 19 20 /** 21 * An abstract "sink" for the stream of bytes produced by a download. A common implementation is 22 * {@link ProtoFileDownloadDestination}, which streams the downloaded bytes to a writeable file on 23 * disk, and serializes {@link DownloadMetadata} as a protocol buffer. 24 * 25 * <p>Persistent destinations may support partial download resumption by implementing {@link 26 * #numExistingBytes} to return a non-zero value. 27 */ 28 public interface DownloadDestination { 29 /** 30 * How many bytes are already present for the destination. Used to avoid re-downloading data by 31 * using HTTP range downloads. 32 */ numExistingBytes()33 long numExistingBytes() throws IOException; 34 35 /** 36 * Reads metadata for the destination. The metadata is used to set request headers as appropriate 37 * to support range downloads and content-aware requests. 38 * 39 * <p>Note that this operation likely needs to read persistent state from disk to retrieve the 40 * metadata (e.g. a database read). An {@link IOException} may be thrown if an error is 41 * encountered. This method will always be called on the {@link java.util.concurrent.Executor} 42 * that is supplied to the downloader via {@link Downloader.Builder#withIOExecutor}. 43 */ readMetadata()44 DownloadMetadata readMetadata() throws IOException; 45 46 /** 47 * Opens the byte channel to write the download data to, with server-provided metadata to control 48 * how the destination should be initialized and stored. The downloader will close the channel 49 * when the download is complete. 50 * 51 * <p>The returned {@link WritableByteChannel} must have its {@code position} set to {@code 52 * byteOffset}. The underlying storage mechanism should also persist the metadata message, so that 53 * future calls to {@link #readMetadata} represent those values. Failure to do so may result in 54 * data corruption. 55 * 56 * @param byteOffset initial byte position for the returned channel. 57 * @param metadata metadata to configure the destination with 58 * @throws IllegalArgumentException if {@code byteOffset} is outside of range [0, {@link 59 * #numExistingBytes}] 60 */ openByteChannel(long byteOffset, DownloadMetadata metadata)61 WritableByteChannel openByteChannel(long byteOffset, DownloadMetadata metadata) 62 throws IOException; 63 64 /** 65 * Erases any existing bytes stored at this destination. 66 * 67 * <p>Implementations can either invalidate any channels previously returned by {@link 68 * #openByteChannel} or have them silently drop subsequent writes. 69 */ clear()70 void clear() throws IOException; 71 } 72