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 in favor of {@link #createInputStream()}}, 71 * which will only be called if null is returned from this method, 72 * or {@link Callback#fileDescriptorFactoryCreated(RequestKey, FileDescriptorFactory)} is called 73 * with a null FileDescriptorFactory. 74 * 75 * Clients should implement this method if files are in the local cache folder, or if files must 76 * be downloaded and cached. 77 * 78 * This method must be called from the UI thread. 79 * 80 * @param key The key to create a FileDescriptorFactory for. This key will be passed to the 81 * callback so it can check whether the key has changed. 82 * @param callback The callback to notify once the FileDescriptorFactory is created or has failed 83 * to be created. 84 * Do not invoke the callback directly from this method. Instead, create a handler 85 * and post a Runnable. 86 * 87 * @return If the client will attempt to create a FileDescriptorFactory, return a Cancelable 88 * object to cancel the asynchronous task. If the client wants to create an InputStream instead, 89 * return null. The callback must be notified if and only if the client returns a Cancelable 90 * object and not null. 91 */ createFileDescriptorFactoryAsync(RequestKey key, Callback callback)92 public Cancelable createFileDescriptorFactoryAsync(RequestKey key, Callback callback); 93 94 /** 95 * Create an {@link InputStream} for the source. This method will be called if 96 * {@link #createFileDescriptorFactoryAsync(RequestKey, Callback)} returns null. 97 * 98 * Clients should implement this method if files exist in the assets/ folder, or for prototypes 99 * that open a connection directly on a URL (be warned that this will cause GCs). 100 * 101 * This method can be called from any thread. 102 */ createInputStream()103 public InputStream createInputStream() throws IOException; 104 105 /** 106 * Return true if the image source may have be oriented in either portrait or landscape, and 107 * will need to be automatically re-oriented based on accompanying Exif metadata. 108 * 109 * This method can be called from any thread. 110 */ hasOrientationExif()111 public boolean hasOrientationExif() throws IOException; 112 113 /** 114 * Callback for creating the {@link FileDescriptorFactory} asynchronously. 115 */ 116 public interface Callback { 117 118 /** 119 * Notifies that the {@link FileDescriptorFactory} has been created. This must be called on 120 * the UI thread. 121 * @param key The key that the FileDescriptorFactory was created for. The callback should 122 * check that the key has not changed. 123 * @param factory The FileDescriptorFactory to decode from. Pass null to cancel decode. 124 */ fileDescriptorFactoryCreated(RequestKey key, FileDescriptorFactory factory)125 void fileDescriptorFactoryCreated(RequestKey key, FileDescriptorFactory factory); 126 } 127 128 public interface FileDescriptorFactory { createFileDescriptor()129 ParcelFileDescriptor createFileDescriptor(); 130 } 131 132 /** 133 * Interface for a background task that is cancelable. 134 */ 135 public interface Cancelable { 136 137 /** 138 * Cancel the background task. This must be called on the UI thread. 139 */ cancel()140 void cancel(); 141 } 142 } 143