RequestKey.java revision 9c6ac19d4a3d39b7c2992060957920118ff56a65
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 17package com.android.bitmap; 18 19import android.os.ParcelFileDescriptor; 20 21import java.io.IOException; 22import 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 */ 66public 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 * This method must be called from the UI thread. 74 * 75 * @param key The key to create a FileDescriptorFactory for. This key will be passed to the 76 * callback so it can check whether the key has changed. 77 * @param callback The callback to notify once the FileDescriptorFactory has been created. Do 78 * not invoke the callback directly from this method. Instead, create a handler 79 * and post a Runnable. 80 * 81 * @return If the client will attempt to create a FileDescriptorFactory, return a Cancelable 82 * object to cancel the asynchronous task. If the client wants to create an InputStream instead, 83 * return null. The callback must be notified if and only if the client returns a Cancelable 84 * object and not null. 85 */ 86 public Cancelable createFileDescriptorFactoryAsync(RequestKey key, Callback callback); 87 88 /** 89 * Create an {@link InputStream} for the source. This method will be called if 90 * {@link #createFileDescriptorFactoryAsync(RequestKey, Callback)} returns null. 91 * 92 * This method can be called from any thread. 93 */ 94 public InputStream createInputStream() throws IOException; 95 96 /** 97 * Return true if the image source may have be oriented in either portrait or landscape, and 98 * will need to be automatically re-oriented based on accompanying Exif metadata. 99 * 100 * This method can be called from any thread. 101 */ 102 public boolean hasOrientationExif() throws IOException; 103 104 /** 105 * Callback for creating the {@link FileDescriptorFactory} asynchronously. 106 */ 107 public interface Callback { 108 109 /** 110 * Notifies that the {@link FileDescriptorFactory} has been created. This must be called on 111 * the UI thread. 112 * @param key The key that the FileDescriptorFactory was created for. The callback should 113 * check that the key has not changed. 114 * @param factory The FileDescriptorFactory to decode from. 115 */ 116 void fileDescriptorFactoryCreated(RequestKey key, FileDescriptorFactory factory); 117 } 118 119 public interface FileDescriptorFactory { 120 ParcelFileDescriptor createFileDescriptor(); 121 } 122 123 /** 124 * Interface for a background task that is cancelable. 125 */ 126 public interface Cancelable { 127 128 /** 129 * Cancel the background task. This must be called on the UI thread. 130 */ 131 void cancel(); 132 } 133}