1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.bitmap; 18 19 import android.os.ParcelFileDescriptor; 20 21 import java.io.IOException; 22 import java.io.InputStream; 23 24 /** 25 * The decode task uses this class to get input to decode. You must implement at least one of 26 * {@link #createFileDescriptorFactoryAsync(RequestKey, Callback)} or {@link #createInputStream()}. 27 * {@link DecodeTask} will prioritize 28 * {@link #createFileDescriptorFactoryAsync(RequestKey, Callback)} before falling back to 29 * {@link #createInputStream()}. 30 * 31 * <p> 32 * Clients of this interface must also implement {@link #equals(Object)} and {@link #hashCode()} as 33 * this object will be used as a cache key. 34 * 35 * <p> 36 * The following is a high level view of the interactions between RequestKey and the rest of the 37 * system. 38 * 39 * BasicBitmapDrawable 40 * UI Thread 41 * ++ 42 * bind() || Background Thread 43 * |+-------------------->+ 44 * || createFDFasync() || 45 * || || Download from url 46 * || || Cache on disk 47 * || || 48 * || vv 49 * |<--------------------+x 50 * || FDFcreated() 51 * || 52 * || 53 * || DecodeTask 54 * || AsyncTask Thread 55 * |+-------------------->+ 56 * || new().execute() || 57 * || || Decode from FDF 58 * || || or createInputStream() 59 * || || 60 * || vv 61 * |<--------------------+x 62 * || onDecodeComplete() 63 * vv 64 * invalidate() xx 65 */ 66 public interface RequestKey { 67 68 /** 69 * Create an {@link FileDescriptorFactory} for a local file stored on the device and pass it to 70 * the given callback. This method will be called first; if it returns null, 71 * {@link #createInputStream()} will be called. 72 * 73 * Clients should implement this method if files are in the local cache folder, or if files must 74 * be downloaded and cached. 75 * 76 * This method must be called from the UI thread. 77 * 78 * @param key The key to create a FileDescriptorFactory for. This key will be passed to the 79 * callback so it can check whether the key has changed. 80 * @param callback The callback to notify once the FileDescriptorFactory has been created. Do 81 * not invoke the callback directly from this method. Instead, create a handler 82 * and post a Runnable. 83 * 84 * @return If the client will attempt to create a FileDescriptorFactory, return a Cancelable 85 * object to cancel the asynchronous task. If the client wants to create an InputStream instead, 86 * return null. The callback must be notified if and only if the client returns a Cancelable 87 * object and not null. 88 */ 89 public Cancelable createFileDescriptorFactoryAsync(RequestKey key, Callback callback); 90 91 /** 92 * Create an {@link InputStream} for the source. This method will be called if 93 * {@link #createFileDescriptorFactoryAsync(RequestKey, Callback)} returns null. 94 * 95 * Clients should implement this method if files exist in the assets/ folder, or for prototypes 96 * that open a connection directly on a URL (be warned that this will cause GCs). 97 * 98 * This method can be called from any thread. 99 */ 100 public InputStream createInputStream() throws IOException; 101 102 /** 103 * Return true if the image source may have be oriented in either portrait or landscape, and 104 * will need to be automatically re-oriented based on accompanying Exif metadata. 105 * 106 * This method can be called from any thread. 107 */ 108 public boolean hasOrientationExif() throws IOException; 109 110 /** 111 * Callback for creating the {@link FileDescriptorFactory} asynchronously. 112 */ 113 public interface Callback { 114 115 /** 116 * Notifies that the {@link FileDescriptorFactory} has been created. This must be called on 117 * the UI thread. 118 * @param key The key that the FileDescriptorFactory was created for. The callback should 119 * check that the key has not changed. 120 * @param factory The FileDescriptorFactory to decode from. 121 */ 122 void fileDescriptorFactoryCreated(RequestKey key, FileDescriptorFactory factory); 123 } 124 125 public interface FileDescriptorFactory { 126 ParcelFileDescriptor createFileDescriptor(); 127 } 128 129 /** 130 * Interface for a background task that is cancelable. 131 */ 132 public interface Cancelable { 133 134 /** 135 * Cancel the background task. This must be called on the UI thread. 136 */ 137 void cancel(); 138 } 139 }