1package com.bumptech.glide.load.data;
2
3import com.bumptech.glide.Priority;
4import com.bumptech.glide.load.ResourceDecoder;
5import com.bumptech.glide.load.model.ModelLoader;
6
7/**
8 * A base class for lazily and retrieving data that can be used to load a resource. A new instance is created per image
9 * load by {@link ModelLoader}. {@link #loadData(Priority)} may or may not be called for any given load depending on
10 * whether or not the corresponding image is cached. Cancel also may or may not be called. If
11 * {@link #loadData(Priority)} is called, then so {@link #cleanup()} will be called.
12 *
13 * @param <T> The type of data to be loaded.
14 */
15public interface DataFetcher<T> {
16
17    /**
18     * Asynchronously fetch data from which a resource can be decoded. This will always be called on
19     * background thread so it is safe to perform long running tasks here. Any third party libraries called
20     * must be thread safe since this method will be called from a thread in a
21     * {@link java.util.concurrent.ExecutorService} that may have more than one background thread.
22     *
23     * This method will only be called when the corresponding image is not in the cache.
24     *
25     * @param priority The priority with which the request should be completed.
26     */
27    public T loadData(Priority priority) throws Exception;
28
29    /**
30     * Cleanup or recycle any resources used by this data fetcher. This method will be called in a finally block
31     * after the data returned by {@link #loadData(Priority)} has been decoded by the {@link ResourceDecoder}.
32     */
33    public void cleanup();
34
35    /**
36     * Returns a string uniquely identifying the data that this fetcher will fetch including the specific size.
37     *
38     * <p>
39     *     A hash of the bytes of the data that will be fetched is the ideal id but since that is in many cases
40     *     impractical and not performant, urls, file paths, and uris are normally sufficient.
41     * </p>
42     */
43    public String getId();
44
45    /**
46     * A method that will be called when a load is no longer relevant and has been cancelled. This method does not need
47     * to guarantee that any in process loads do not finish. It also may be called before a load starts or after it
48     * finishes.
49     *
50     * <p>
51     *  The best way to use this method is to cancel any loads that have not yet started, but allow those that are in
52     *  process to finish since its we typically will want to display the same image in a different view in
53     *  the near future.
54     * </p>
55     */
56    public void cancel();
57}
58