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