{"title":"Introducing: JMImageCache","html_url":"https://deallocatedobjects.com/posts/jmimagecache","source_url":"","markdown_content":"Today I'm open-sourcing a small project I use to do remote image downloading and caching on iOS called `JMImageCache`. It uses an `NSCache` based remote-image caching mechanism that can be easily integrated into any project.  It is very light weight and isn't meant to be a replacement for `UIImageView` or anything like that. Just drop it into your project, grab a reference to it and start using it where ever it makes sense.\r\n\r\n### How It Works (Logically)\r\n\r\n\r\nThere are three states an image can be in:\r\n\r\n* Cached In Memory\r\n* Cached On Disk\r\n* Not Cached\r\n\r\nIf an image is requested from cache, and it has never been cached, it is downloaded, stored on disk, put into memory and returned via a delegate callback.\r\n\r\nIf an image is requested from cache, and it has been cached, but hasn't been requested this session, it is read from disk, brought into memory and returned immediately.\r\n\r\nIf an image is requested from cache, and it has been cached and it is already in memory, it is simply returned immediately.\r\n\r\nThe idea behind `JMImageCache` is to always return images the **fastest** way possible, thus the in-memory caching. Reading from disk can be expensive, and should only be done if it has to be.\r\n\r\n### How It Works (Code)\r\n\r\n\r\nRequest an image like so:\r\n\r\n``` objc\r\n\tUIImage *mScott = [[JMImageCache sharedCache] imageForURL:@\"http://dundermifflin.com/i/MichaelScott.png\" delegate:self];\r\n```\r\n\r\n`imageForURL:delegate:` will return either a `UIImage` object, or `nil`. If it returns `nil`, then that means the image needs to be downloaded.\r\n\r\nIf the image needs to be downloaded, you'll be notified via a callback to the delegate object you specified in `imageForURL:delegate:`:\r\n\r\n``` objc\r\n- (void) cache:(JMImageCache *)c didDownloadImage:(UIImage *)i forURL:(NSString *)url {\r\n\tNSLog(@\"Downloaded (And Cached) Image From URL: %@\", url);\r\n}\r\n```\r\n\r\n### Clearing The Cache\r\n\r\n\r\nThe beauty of building on top of `NSCache` is that`JMImageCache` handles low memory situations gracefully. It will evict objects on its own when memory gets tight, you don't need to worry about it.\r\n\r\nHowever, if you really need to, clearing the cache manually is this simple:\r\n\r\n``` objc\r\n[[JMImageCache sharedCache] removeAllObjects];\r\n```\r\n\r\nIf you'd like to remove a specific image from the cache, you can do this:\r\n\r\n``` objc\r\n[[JMImageCache sharedCache] removeImageForURL:@\"http://dundermifflin.com/i/MichaelScott.png\"];\r\n```\r\n\r\n### Demo App\r\n\r\n\r\nThe [Github repository](https://github.com/jakemarsh/JMImageCache) includes a demo project. Just a simple `UITableViewController` app that loads a few images. It does so by calling `imageForURL:delegate:` and passing in the `UITableViewCell` as the `JMImageCacheDelegate` to respond to when an image is downloaded. Then we simply set the `image` of the cell's `imageView` and then call `setNeedsLayout` on the cell to refresh the view. Nothing too fancy, but it should give you a good idea of a standard usage of `JMImageCache`.\r\n\r\n### Using JMImageCache In Your App\r\n\r\nAll you need to do is copy `JMImageCache.h` and `JMImageCache.m` into your project, `#import` the header where you need it, and start using it.\r\n\r\n### Notes\r\n\r\n\r\n`JMImageCache` purposefully uses `NSString` objects instead of `NSURL`'s to make things easier and cut down on `[NSURL URLWithString:@\"...\"]` bits everywhere. Just something to notice in case you see any strange `EXC_BAD_ACCESS` exceptions, make sure you're passing in `NSString`'s and not `NSURL`'s.","html_content":"<p>Today I’m open-sourcing a small project I use to do remote image downloading and caching on iOS called <code>JMImageCache</code>. It uses an <code>NSCache</code> based remote-image caching mechanism that can be easily integrated into any project.  It is very light weight and isn’t meant to be a replacement for <code>UIImageView</code> or anything like that. Just drop it into your project, grab a reference to it and start using it where ever it makes sense.</p>\n\n<h2 id=\"how-it-works-logically\" data-level=\"3\">How It Works (Logically)</h2>\n\n<p>There are three states an image can be in:</p>\n\n<ul>\n<li>Cached In Memory</li>\n<li>Cached On Disk</li>\n<li>Not Cached</li>\n</ul>\n\n<p>If an image is requested from cache, and it has never been cached, it is downloaded, stored on disk, put into memory and returned via a delegate callback.</p>\n\n<p>If an image is requested from cache, and it has been cached, but hasn’t been requested this session, it is read from disk, brought into memory and returned immediately.</p>\n\n<p>If an image is requested from cache, and it has been cached and it is already in memory, it is simply returned immediately.</p>\n\n<p>The idea behind <code>JMImageCache</code> is to always return images the <strong>fastest</strong> way possible, thus the in-memory caching. Reading from disk can be expensive, and should only be done if it has to be.</p>\n\n<h2 id=\"how-it-works-code\" data-level=\"3\">How It Works (Code)</h2>\n\n<p>Request an image like so:</p>\n<figure class=\"code\" data-lang=\"objective-c\"><figcaption><span class=\"lang\">Objective-C</span></figcaption><pre class=\"shiki shiki-themes github-light github-dark\" style=\"--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">    UIImage </span><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\">*</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">mScott </span><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\"> [[JMImageCache </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">sharedCache</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">] </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">imageForURL:</span><span style=\"--shiki-light:#032F62;--shiki-dark:#9ECBFF\">@\"http://dundermifflin.com/i/MichaelScott.png\"</span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\"> delegate:self</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">];</span></span></code></pre></figure>\n<p><code>imageForURL:delegate:</code> will return either a <code>UIImage</code> object, or <code>nil</code>. If it returns <code>nil</code>, then that means the image needs to be downloaded.</p>\n\n<p>If the image needs to be downloaded, you’ll be notified via a callback to the delegate object you specified in <code>imageForURL:delegate:</code>:</p>\n<figure class=\"code\" data-lang=\"objective-c\"><figcaption><span class=\"lang\">Objective-C</span></figcaption><pre class=\"shiki shiki-themes github-light github-dark\" style=\"--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\">-</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\"> (</span><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\">void</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">) cache:(JMImageCache </span><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\">*</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">)c didDownloadImage:(UIImage </span><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\">*</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">)i forURL:(</span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">NSString</span><span style=\"--shiki-light:#D73A49;--shiki-dark:#F97583\"> *</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">)url {</span></span>\n<span class=\"line\"><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">    NSLog</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">(</span><span style=\"--shiki-light:#032F62;--shiki-dark:#9ECBFF\">@\"Downloaded (And Cached) Image From URL: </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">%@</span><span style=\"--shiki-light:#032F62;--shiki-dark:#9ECBFF\">\"</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">, url);</span></span>\n<span class=\"line\"><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">}</span></span></code></pre></figure>\n<h2 id=\"clearing-the-cache\" data-level=\"3\">Clearing The Cache</h2>\n\n<p>The beauty of building on top of <code>NSCache</code> is that<code>JMImageCache</code> handles low memory situations gracefully. It will evict objects on its own when memory gets tight, you don’t need to worry about it.</p>\n\n<p>However, if you really need to, clearing the cache manually is this simple:</p>\n<figure class=\"code\" data-lang=\"objective-c\"><figcaption><span class=\"lang\">Objective-C</span></figcaption><pre class=\"shiki shiki-themes github-light github-dark\" style=\"--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">[[JMImageCache </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">sharedCache</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">] </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">removeAllObjects</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">];</span></span></code></pre></figure>\n<p>If you’d like to remove a specific image from the cache, you can do this:</p>\n<figure class=\"code\" data-lang=\"objective-c\"><figcaption><span class=\"lang\">Objective-C</span></figcaption><pre class=\"shiki shiki-themes github-light github-dark\" style=\"--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e\" tabindex=\"0\"><code><span class=\"line\"><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">[[JMImageCache </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">sharedCache</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">] </span><span style=\"--shiki-light:#005CC5;--shiki-dark:#79B8FF\">removeImageForURL:</span><span style=\"--shiki-light:#032F62;--shiki-dark:#9ECBFF\">@\"http://dundermifflin.com/i/MichaelScott.png\"</span><span style=\"--shiki-light:#24292E;--shiki-dark:#E1E4E8\">];</span></span></code></pre></figure>\n<h2 id=\"demo-app\" data-level=\"3\">Demo App</h2>\n\n<p>The <a href=\"https://github.com/jakemarsh/JMImageCache\">Github repository</a> includes a demo project. Just a simple <code>UITableViewController</code> app that loads a few images. It does so by calling <code>imageForURL:delegate:</code> and passing in the <code>UITableViewCell</code> as the <code>JMImageCacheDelegate</code> to respond to when an image is downloaded. Then we simply set the <code>image</code> of the cell’s <code>imageView</code> and then call <code>setNeedsLayout</code> on the cell to refresh the view. Nothing too fancy, but it should give you a good idea of a standard usage of <code>JMImageCache</code>.</p>\n\n<h2 id=\"using-jmimagecache-in-your-app\" data-level=\"3\">Using JMImageCache In Your App</h2>\n\n<p>All you need to do is copy <code>JMImageCache.h</code> and <code>JMImageCache.m</code> into your project, <code>#import</code> the header where you need it, and start using it.</p>\n\n<h2 id=\"notes\" data-level=\"3\">Notes</h2>\n\n<p><code>JMImageCache</code> purposefully uses <code>NSString</code> objects instead of <code>NSURL</code>‘s to make things easier and cut down on <code>[NSURL URLWithString:@&quot;...&quot;]</code> bits everywhere. Just something to notice in case you see any strange <code>EXC_BAD_ACCESS</code> exceptions, make sure you’re passing in <code>NSString</code>‘s and not <code>NSURL</code>‘s.</p>","created_at":"2013-11-16T05:10:25.692Z","updated_at":"2013-11-16T05:10:25.692Z"}