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