Merge pull request #95 from onevcat/feature/resource-based-api

Resource based api

Kingfisher-Demo/ViewController.swift

@@ -58,7 +58,9 @@ extension ViewController: UICollectionViewDataSource {
     override func collectionView(collectionView: UICollectionView, cellForItemAtIndexPath indexPath: NSIndexPath) -> UICollectionViewCell {
         let cell = collectionView.dequeueReusableCellWithReuseIdentifier("collectionViewCell", forIndexPath: indexPath) as! CollectionViewCell
         cell.cellImageView.kf_showIndicatorWhenLoading = true
-        cell.cellImageView.kf_setImageWithURL(NSURL(string: "https://raw.githubusercontent.com/onevcat/Kingfisher/master/images/kingfisher-\(indexPath.row + 1).jpg")!, placeholderImage: nil, optionsInfo: nil, progressBlock: { (receivedSize, totalSize) -> () in
+
+        let URL = NSURL(string: "https://raw.githubusercontent.com/onevcat/Kingfisher/master/images/kingfisher-\(indexPath.row + 1).jpg")!
+        cell.cellImageView.kf_setImageWithResource(Resource(downloadURL: URL), placeholderImage: nil, optionsInfo: nil, progressBlock: { (receivedSize, totalSize) -> () in
             println("\(indexPath.row + 1): \(receivedSize)/\(totalSize)")
         }) { (image, error, cacheType, imageURL) -> () in
             println("\(indexPath.row + 1): Finished")

Kingfisher.xcodeproj/project.pbxproj

@@ -8,6 +8,7 @@
 
 /* Begin PBXBuildFile section */
 		0D9C68098E20AB4F19D7C313 /* libPods-KingfisherTests.a in Frameworks */ = {isa = PBXBuildFile; fileRef = A9E621E297FEFAD35D39C34E /* libPods-KingfisherTests.a */; };
+		4B2C4DF81B7D7ACD000912CA /* Resource.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4B2C4DF71B7D7ACD000912CA /* Resource.swift */; };
 		4B3E714F1B02005900F5AAED /* WatchKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 4B3E714D1B01FEB200F5AAED /* WatchKit.framework */; settings = {ATTRIBUTES = (Weak, ); }; };
 		4B412CA51AE8A2F9008D530A /* KingfisherOptionsInfo.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4B412CA41AE8A2F9008D530A /* KingfisherOptionsInfo.swift */; };
 		4B6D4F651AE0A46D0084D15B /* UIImageViewExtensionTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4B6D4F641AE0A46D0084D15B /* UIImageViewExtensionTests.swift */; };
@@ -107,6 +108,7 @@
 /* End PBXCopyFilesBuildPhase section */
 
 /* Begin PBXFileReference section */
+		4B2C4DF71B7D7ACD000912CA /* Resource.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Resource.swift; sourceTree = "<group>"; };
 		4B3E714D1B01FEB200F5AAED /* WatchKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = WatchKit.framework; path = System/Library/Frameworks/WatchKit.framework; sourceTree = SDKROOT; };
 		4B412CA41AE8A2F9008D530A /* KingfisherOptionsInfo.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = KingfisherOptionsInfo.swift; sourceTree = "<group>"; };
 		4B6D4F641AE0A46D0084D15B /* UIImageViewExtensionTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = UIImageViewExtensionTests.swift; sourceTree = "<group>"; };
@@ -295,6 +297,7 @@
 				D1ED2D591AD2D0F900CFC3EB /* KingfisherManager.swift */,
 				D1ED2D5A1AD2D0F900CFC3EB /* KingfisherOptions.swift */,
 				4B412CA41AE8A2F9008D530A /* KingfisherOptionsInfo.swift */,
+				4B2C4DF71B7D7ACD000912CA /* Resource.swift */,
 				D1ED2D371AD2D09F00CFC3EB /* Supporting Files */,
 			);
 			path = Kingfisher;
@@ -605,6 +608,7 @@
 				4BD352F31AF36A0700B18A40 /* WKInterfaceImage+Kingfisher.swift in Sources */,
 				D1ED2D5E1AD2D0F900CFC3EB /* ImageDownloader.swift in Sources */,
 				4B412CA51AE8A2F9008D530A /* KingfisherOptionsInfo.swift in Sources */,
+				4B2C4DF81B7D7ACD000912CA /* Resource.swift in Sources */,
 				D1ED2D601AD2D0F900CFC3EB /* KingfisherOptions.swift in Sources */,
 				D151E72B1AD3C48D004FD4AE /* UIImage+Decode.swift in Sources */,
 			);

Kingfisher/KingfisherManager.swift

@@ -95,24 +95,24 @@ public class KingfisherManager {
         cache = ImageCache.defaultCache
         downloader = ImageDownloader.defaultDownloader
     }
-
+    
     /**
-    Get an image with URL as the key.
+    Get an image with resource.
     If KingfisherOptions.None is used as `options`, Kingfisher will seek the image in memory and disk first.
-    If not found, it will download the image at URL and cache it.
+    If not found, it will download the image at `resource.downloadURL` and cache it with `resource.cacheKey`.
     These default behaviors could be adjusted by passing different options. See `KingfisherOptions` for more.
 
-    :param: URL               The image URL.
+    :param: resource          Resource object contains information such as `cacheKey` and `downloadURL`.
     :param: optionsInfo       A dictionary could control some behaviors. See `KingfisherOptionsInfo` for more.
     :param: progressBlock     Called every time downloaded data changed. This could be used as a progress UI.
     :param: completionHandler Called when the whole retriving process finished.
 
     :returns: A `RetrieveImageTask` task object. You can use this object to cancel the task.
     */
-    public func retrieveImageWithURL(URL: NSURL,
-                             optionsInfo: KingfisherOptionsInfo?,
-                           progressBlock: DownloadProgressBlock?,
-                       completionHandler: CompletionHandler?) -> RetrieveImageTask
+    public func retrieveImageWithResource(resource: Resource,
+        optionsInfo: KingfisherOptionsInfo?,
+        progressBlock: DownloadProgressBlock?,
+        completionHandler: CompletionHandler?) -> RetrieveImageTask
     {
         func parseOptionsInfo(optionsInfo: KingfisherOptionsInfo?) -> (Options, ImageCache, ImageDownloader) {
             let options: Options
@@ -142,42 +142,64 @@ public class KingfisherManager {
         let parsedOptions = parseOptionsInfo(optionsInfo)
         let (options, targetCache, downloader) = (parsedOptions.0, parsedOptions.1, parsedOptions.2)
 
-        if let key = URL.absoluteString {
-            if options.forceRefresh {
-                downloadAndCacheImageWithURL(URL,
-                    forKey: key,
-                    retrieveImageTask: task,
-                    progressBlock: progressBlock,
-                    completionHandler: completionHandler,
-                    options: options,
-                    targetCache: targetCache,
-                    downloader: downloader)
-            } else {
-                let diskTaskCompletionHandler: CompletionHandler = { (image, error, cacheType, imageURL) -> () in
-                    // Break retain cycle created inside diskTask closure below
-                    task.diskRetrieveTask = nil
-                    completionHandler?(image: image, error: error, cacheType: cacheType, imageURL: imageURL)
-                }
-                let diskTask = targetCache.retrieveImageForKey(key, options: options, completionHandler: { (image, cacheType) -> () in
-                    if image != nil {
-                        diskTaskCompletionHandler(image: image, error: nil, cacheType:cacheType, imageURL: URL)
-                    } else {
-                        self.downloadAndCacheImageWithURL(URL,
-                            forKey: key,
-                            retrieveImageTask: task,
-                            progressBlock: progressBlock,
-                            completionHandler: diskTaskCompletionHandler,
-                            options: options,
-                            targetCache: targetCache,
-                            downloader: downloader)
-                    }
-                })
-                task.diskRetrieveTask = diskTask
+        if options.forceRefresh {
+            downloadAndCacheImageWithURL(resource.downloadURL,
+                forKey: resource.cacheKey,
+                retrieveImageTask: task,
+                progressBlock: progressBlock,
+                completionHandler: completionHandler,
+                options: options,
+                targetCache: targetCache,
+                downloader: downloader)
+        } else {
+            let diskTaskCompletionHandler: CompletionHandler = { (image, error, cacheType, imageURL) -> () in
+                // Break retain cycle created inside diskTask closure below
+                task.diskRetrieveTask = nil
+                completionHandler?(image: image, error: error, cacheType: cacheType, imageURL: imageURL)
             }
+            let diskTask = targetCache.retrieveImageForKey(resource.cacheKey, options: options, completionHandler: { (image, cacheType) -> () in
+                if image != nil {
+                    diskTaskCompletionHandler(image: image, error: nil, cacheType:cacheType, imageURL: resource.downloadURL)
+                } else {
+                    self.downloadAndCacheImageWithURL(resource.downloadURL,
+                        forKey: resource.cacheKey,
+                        retrieveImageTask: task,
+                        progressBlock: progressBlock,
+                        completionHandler: diskTaskCompletionHandler,
+                        options: options,
+                        targetCache: targetCache,
+                        downloader: downloader)
+                }
+            })
+            task.diskRetrieveTask = diskTask
         }
 
         return task
     }
+
+    /**
+    Get an image with `URL.absoluteString` as the key.
+    If KingfisherOptions.None is used as `options`, Kingfisher will seek the image in memory and disk first.
+    If not found, it will download the image at URL and cache it with `URL.absoluteString` value as its key.
+
+    If you need to specify the key other than `URL.absoluteString`, please use resource version of this API with `resource.cacheKey` set to what you want.
+
+    These default behaviors could be adjusted by passing different options. See `KingfisherOptions` for more.
+
+    :param: URL               The image URL.
+    :param: optionsInfo       A dictionary could control some behaviors. See `KingfisherOptionsInfo` for more.
+    :param: progressBlock     Called every time downloaded data changed. This could be used as a progress UI.
+    :param: completionHandler Called when the whole retriving process finished.
+
+    :returns: A `RetrieveImageTask` task object. You can use this object to cancel the task.
+    */
+    public func retrieveImageWithURL(URL: NSURL,
+                             optionsInfo: KingfisherOptionsInfo?,
+                           progressBlock: DownloadProgressBlock?,
+                       completionHandler: CompletionHandler?) -> RetrieveImageTask
+    {
+        return retrieveImageWithResource(Resource(downloadURL: URL), optionsInfo: optionsInfo, progressBlock: progressBlock, completionHandler: completionHandler)
+    }
 
     func downloadAndCacheImageWithURL(URL: NSURL,
                                forKey key: String,

Kingfisher/Resource.swift

@@ -0,0 +1,37 @@
+//
+//  Resource.swift
+//  Kingfisher
+//
+//  Created by Wei Wang on 15/4/6.
+//
+//  Copyright (c) 2015 Wei Wang <[email protected]>
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to deal
+//  in the Software without restriction, including without limitation the rights
+//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//  copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+
+import Foundation
+
+public struct Resource {
+    public let cacheKey: String
+    public let downloadURL: NSURL
+
+    public init(downloadURL: NSURL, cacheKey: String? = nil) {
+        self.downloadURL = downloadURL
+        self.cacheKey = cacheKey ?? downloadURL.absoluteString!
+    }
+}