michael@0: /*
michael@0:  * Copyright (C) 2013 Square, Inc.
michael@0:  *
michael@0:  * Licensed under the Apache License, Version 2.0 (the "License");
michael@0:  * you may not use this file except in compliance with the License.
michael@0:  * You may obtain a copy of the License at
michael@0:  *
michael@0:  *      http://www.apache.org/licenses/LICENSE-2.0
michael@0:  *
michael@0:  * Unless required by applicable law or agreed to in writing, software
michael@0:  * distributed under the License is distributed on an "AS IS" BASIS,
michael@0:  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
michael@0:  * See the License for the specific language governing permissions and
michael@0:  * limitations under the License.
michael@0:  */
michael@0: package com.squareup.picasso;
michael@0: 
michael@0: import android.graphics.Bitmap;
michael@0: import android.net.Uri;
michael@0: import java.io.IOException;
michael@0: import java.io.InputStream;
michael@0: 
michael@0: /** A mechanism to load images from external resources such as a disk cache and/or the internet. */
michael@0: public interface Downloader {
michael@0:   /**
michael@0:    * Download the specified image {@code url} from the internet.
michael@0:    *
michael@0:    * @param uri Remote image URL.
michael@0:    * @param localCacheOnly If {@code true} the URL should only be loaded if available in a local
michael@0:    * disk cache.
michael@0:    * @return {@link Response} containing either a {@link Bitmap} representation of the request or an
michael@0:    * {@link InputStream} for the image data. {@code null} can be returned to indicate a problem
michael@0:    * loading the bitmap.
michael@0:    * @throws IOException if the requested URL cannot successfully be loaded.
michael@0:    */
michael@0:   Response load(Uri uri, boolean localCacheOnly) throws IOException;
michael@0: 
michael@0:   /** Thrown for non-2XX responses. */
michael@0:   class ResponseException extends IOException {
michael@0:     public ResponseException(String message) {
michael@0:       super(message);
michael@0:     }
michael@0:   }
michael@0: 
michael@0:   /** Response stream or bitmap and info. */
michael@0:   class Response {
michael@0:     final InputStream stream;
michael@0:     final Bitmap bitmap;
michael@0:     final boolean cached;
michael@0: 
michael@0:     /**
michael@0:      * Response image and info.
michael@0:      *
michael@0:      * @param bitmap Image.
michael@0:      * @param loadedFromCache {@code true} if the source of the image is from a local disk cache.
michael@0:      */
michael@0:     public Response(Bitmap bitmap, boolean loadedFromCache) {
michael@0:       if (bitmap == null) {
michael@0:         throw new IllegalArgumentException("Bitmap may not be null.");
michael@0:       }
michael@0:       this.stream = null;
michael@0:       this.bitmap = bitmap;
michael@0:       this.cached = loadedFromCache;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Response stream and info.
michael@0:      *
michael@0:      * @param stream Image data stream.
michael@0:      * @param loadedFromCache {@code true} if the source of the stream is from a local disk cache.
michael@0:      */
michael@0:     public Response(InputStream stream, boolean loadedFromCache) {
michael@0:       if (stream == null) {
michael@0:         throw new IllegalArgumentException("Stream may not be null.");
michael@0:       }
michael@0:       this.stream = stream;
michael@0:       this.bitmap = null;
michael@0:       this.cached = loadedFromCache;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Input stream containing image data.
michael@0:      * <p>
michael@0:      * If this returns {@code null}, image data will be available via {@link #getBitmap()}.
michael@0:      */
michael@0:     public InputStream getInputStream() {
michael@0:       return stream;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Bitmap representing the image.
michael@0:      * <p>
michael@0:      * If this returns {@code null}, image data will be available via {@link #getInputStream()}.
michael@0:      */
michael@0:     public Bitmap getBitmap() {
michael@0:       return bitmap;
michael@0:     }
michael@0:   }
michael@0: }