Skip to content

Commit 3a86d17

Browse files
author
Mallory Paine
committed
Fast Image Cache 1.0
0 parents  commit 3a86d17

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+4831
-0
lines changed

‎.gitignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Mac OS X Finder
2+
.DS_Store
3+
4+
# Xcode
5+
build/*
6+
*.pbxuser
7+
!default.pbxuser
8+
*.mode1v3
9+
!default.mode1v3
10+
*.mode2v3
11+
!default.mode2v3
12+
*.perspectivev3
13+
!default.perspectivev3
14+
*.xcworkspace
15+
!default.xcworkspace
16+
xcuserdata
17+
profile
18+
*.moved-aside
19+
DerivedData
20+
21+
# Demo Images
22+
FastImageCacheDemo/Demo Images/*.jpg

‎FastImageCache/FICEntity.h‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
//
2+
// FICEntity.h
3+
// FastImageCache
4+
//
5+
// Copyright (c) 2013 Path, Inc.
6+
// See LICENSE for full license agreement.
7+
//
8+
9+
#import "FICImports.h"
10+
11+
typedef void (^FICEntityImageDrawingBlock)(CGContextRef context, CGSize contextSize);
12+
13+
/**
14+
`FICEntity` is a protocol that classes interacting with the image cache must conform to. An entity uniquely identifies entries in image tables, which are instances of `<FICImageTable>`.
15+
*/
16+
@protocol FICEntity <NSObject>
17+
18+
@required
19+
20+
/**
21+
A string that uniquely identifies this entity.
22+
23+
@discussion Within each image table, each entry is identified by an entity's UUID. Ideally, this value should never change for an entity. For example, if your entity class is a person
24+
model, its UUID might be an API-assigned, unchanging, unique user ID. No matter how the properties of the person change, its user ID should never change.
25+
*/
26+
@property (nonatomic, copy, readonly) NSString *UUID;
27+
28+
/**
29+
A string that uniquely identifies an entity's source image.
30+
31+
@discussion While `<UUID>` should be unchanging, a source image UUID might change. For example, if your entity class is a person model, its source image UUID might change every time the
32+
person changes their profile photo. In this case, the source image UUID might be a hash of the profile photo URL (assuming each image is given a unique URL).
33+
*/
34+
@property (nonatomic, copy, readonly) NSString *sourceImageUUID;
35+
36+
/**
37+
Returns the source image URL associated with a specific format name.
38+
39+
@param formatName The name of the image format that identifies which image table is requesting the source image.
40+
41+
@return A URL representing the requested source image.
42+
43+
@discussion Fast Image Cache operates on URLs when requesting source images. Typically, these URLs will point to remote image resources that must be downloaded from the Internet. While the
44+
URL returned by this method must be a valid instance of `NSURL`, it does not need to point to an actual remote resource. The URL might point to a file path on disk or be composed of a custom
45+
URL scheme of your choosing. The image cache's delegate is prompted to provide a source image for a particular entity and format name when it cannot find the requested image. It only uses the
46+
URL returned by this method to key image cache requests. No network or file operations are performed by the image cache.
47+
48+
An example of when this method might return different source image URLs for the same entity is if you have defined several image formats for different thumbnail sizes and styles. For very
49+
large thumbnails, the source image URL might be the original image. For smaller thumbnails, the source image URL might point to a downscaled version of the original image.
50+
51+
@see FICImageFormat
52+
@see [FICImageCacheDelegate imageCache:wantsSourceImageForEntity:withFormatName:completionBlock:]
53+
*/
54+
- (NSURL *)sourceImageURLWithFormatName:(NSString *)formatName;
55+
56+
/**
57+
Returns the drawing block for a specific image and format name.
58+
59+
@param image The cached image that represents this entity.
60+
61+
@param formatName The name of the image format that identifies which image table is requesting the source image.
62+
63+
@return The drawing block used to draw the image data to be stored in the image table.
64+
65+
The drawing block's type is defined as follows:
66+
67+
typedef void (^FICEntityImageDrawingBlock)(CGContextRef context, CGSize contextSize)
68+
69+
@discussion Each entity is responsible for drawing its own source image into the bitmap context provided by the image table that will store the image data. Often it is sufficient to simply
70+
draw the image into the bitmap context. However, if you wish to apply any additional graphics processing to the source image before it is stored (such as clipping the image to a roundect rect),
71+
you may use this block to do so.
72+
73+
@note This block will always be called from the serial dispatch queue used by the image cache.
74+
*/
75+
- (FICEntityImageDrawingBlock)drawingBlockForImage:(UIImage *)image withFormatName:(NSString *)formatName;
76+
77+
@end

‎FastImageCache/FICImageCache+FICErrorLogging.h‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
//
2+
// FICImageCache+FICErrorLogging.h
3+
// FastImageCache
4+
//
5+
// Copyright (c) 2013 Path, Inc.
6+
// See LICENSE for full license agreement.
7+
//
8+
9+
#import "FICImageCache.h"
10+
11+
/**
12+
This category on `<FICImageCache>` simply exposes its private logging mechanism to other classes.
13+
*/
14+
@interface FICImageCache (FICErrorLogging)
15+
16+
///-----------------------------
17+
/// @name Logging Error Messages
18+
///-----------------------------
19+
20+
/**
21+
Passes an error message to the image cache.
22+
23+
@param message A string representing the error message.
24+
25+
@discussion Rather than logging directly to standard output, Fast Image Cache classes pass all error logging to the shared `<FICImageCache>` instance. `<FICImageCache>` then allows its delegate to handle the
26+
message.
27+
28+
@see [FICImageCacheDelegate imageCache:errorDidOccurWithMessage:]
29+
*/
30+
- (void)_logMessage:(NSString *)message;
31+
32+
@end

‎FastImageCache/FICImageCache.h‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
//
2+
// FICImageCache.h
3+
// FastImageCache
4+
//
5+
// Copyright (c) 2013 Path, Inc.
6+
// See LICENSE for full license agreement.
7+
//
8+
9+
#import "FICImports.h"
10+
#import "FICImageFormat.h"
11+
#import "FICEntity.h"
12+
13+
@protocol FICEntity;
14+
@protocol FICImageCacheDelegate;
15+
16+
typedef void (^FICImageCacheCompletionBlock)(id <FICEntity> entity, NSString *formatName, UIImage *image);
17+
typedef void (^FICImageRequestCompletionBlock)(UIImage *sourceImage);
18+
19+
/**
20+
`FICImageCache` is the primary class for managing and interacting with the image cache. Applications using the image cache create one or more `<FICImageFormat>`
21+
objects. These formats effectively act as logical groupings for image data stored in the image cache. An `<FICImageTable>` object is created for each format defined by
22+
your application to allow for efficient storage and retrieval of image data. Image data is keyed off of objects conforming to the `<FICEntity>` protocol as well as an
23+
image format name.
24+
*/
25+
@interface FICImageCache : NSObject
26+
27+
///----------------------------
28+
/// @name Managing the Delegate
29+
///----------------------------
30+
31+
/**
32+
The delegate of the image cache.
33+
34+
@discussion The delegate is responsible for asynchronously providing the source image for an entity. Optionally, the delegate can require that all formats in a format
35+
family for a particular entity be processed. Any errors that occur in the image cache are also communicated back to the delegate.
36+
*/
37+
@property(nonatomic, assign) id <FICImageCacheDelegate> delegate;
38+
39+
///---------------------------------------
40+
/// @name Accessing the Shared Image Cache
41+
///---------------------------------------
42+
43+
/**
44+
Convenience accessor to retrieve a shared image cache instance.
45+
*/
46+
+ (instancetype)sharedImageCache;
47+
48+
///---------------------------------
49+
/// @name Working with Image Formats
50+
///---------------------------------
51+
52+
/**
53+
Sets the image formats to be used by the image cache.
54+
55+
@param formats An array of `<FICImageFormat>` objects.
56+
57+
@note Once the image formats have been set, subsequent calls to this method will do nothing.
58+
*/
59+
- (void)setFormats:(NSArray *)formats;
60+
61+
/**
62+
Returns an image format previously associated with the image cache.
63+
64+
@param formatName The name of the image format to return.
65+
66+
@return An image format with the name `formatName` or `nil` if no format with that name exists.
67+
*/
68+
- (FICImageFormat *)formatWithName:(NSString *)formatName;
69+
70+
/**
71+
Returns all the image formats of the same family previously associated with the image cache.
72+
73+
@param family The name of the family of image formats to return.
74+
75+
@return An array of `<FICImageFormat>` objects whose family is `family` or `nil` if no format belongs to that family.
76+
*/
77+
- (NSArray *)formatsWithFamily:(NSString *)family;
78+
79+
///-----------------------------------------------
80+
/// @name Storing, Retrieving, and Deleting Images
81+
///-----------------------------------------------
82+
83+
/**
84+
Manually sets the the image to be used by the image cache for a particular entity and format name.
85+
86+
@discussion Usually the image cache's delegate is responsible for lazily providing the source image for a given entity. This source image is then processed according
87+
to the drawing block defined by an entity for a given image format. This method allows the sender to explicitly set the image data to be stored in the image cache.
88+
After the image has been processed by the image cache, the completion block is called asynchronously on the main queue.
89+
90+
@param image The image to store in the image cache.
91+
92+
@param entity The entity that uniquely identifies the source image.
93+
94+
@param formatName The format name that uniquely identifies which image table to look in for the cached image.
95+
96+
@param completionBlock The completion block that is called after the image has been processed or if an error occurs.
97+
98+
The completion block's type is defined as follows:
99+
100+
typedef void (^FICImageCacheCompletionBlock)(id <FICEntity> entity, NSString *formatName, UIImage *image)
101+
*/
102+
- (void)setImage:(UIImage *)image forEntity:(id <FICEntity>)entity withFormatName:(NSString *)formatName completionBlock:(FICImageCacheCompletionBlock)completionBlock;
103+
104+
/**
105+
Attempts to synchronously retrieve an image from the image cache.
106+
107+
@param entity The entity that uniquely identifies the source image.
108+
109+
@param formatName The format name that uniquely identifies which image table to look in for the cached image.
110+
111+
@param completionBlock The completion block that is called when the requested image is available or if an error occurs.
112+
113+
The completion block's type is defined as follows:
114+
115+
typedef void (^FICImageCacheCompletionBlock)(id <FICEntity> entity, NSString *formatName, UIImage *image)
116+
117+
If the requested image already exists in the image cache, then the completion block is immediately called synchronously on the current thread. If the requested image
118+
does not already exist in the image cache, then the completion block will be called asynchronously on the main thread as soon as the requested image is available.
119+
120+
@return `YES` if the requested image already exists in the image case, `NO` if the image needs to be provided to the image cache by its delegate.
121+
122+
@discussion Even if you make a synchronous image retrieval request, if the image does not yet exist in the image cache, the delegate will be asked to provide a source
123+
image, and it will be processed. This always occurs asynchronously. In this case, the return value from this method will be `NO`, and the image will be available in the
124+
completion block.
125+
126+
@note You can always rely on the completion block being called. If an error occurs for any reason, the `image` parameter of the completion block will be `nil`. See
127+
<[FICImageCacheDelegate imageCache:errorDidOccurWithMessage:]> for information about being notified when errors occur.
128+
*/
129+
- (BOOL)retrieveImageForEntity:(id <FICEntity>)entity withFormatName:(NSString *)formatName completionBlock:(FICImageCacheCompletionBlock)completionBlock;
130+
131+
/**
132+
Asynchronously retrieves an image from the image cache.
133+
134+
@param entity The entity that uniquely identifies the source image.
135+
136+
@param formatName The format name that uniquely identifies which image table to look in for the cached image.
137+
138+
@param completionBlock The completion block that is called when the requested image is available or if an error occurs.
139+
140+
The completion block's type is defined as follows:
141+
142+
typedef void (^FICImageCacheCompletionBlock)(id <FICEntity> entity, NSString *formatName, UIImage *image)
143+
144+
Unlike its synchronous counterpart, this method will always call its completion block asynchronously on the main thread, even if the request image is already in the
145+
image cache.
146+
147+
@return `YES` if the requested image already exists in the image case, `NO` if the image needs to be provided to the image cache by its delegate.
148+
149+
@note You can always rely on the completion block being called. If an error occurs for any reason, the `image` parameter of the completion block will be `nil`. See
150+
<[FICImageCacheDelegate imageCache:errorDidOccurWithMessage:]> for information about being notified when errors occur.
151+
152+
@see [FICImageCache retrieveImageForEntity:withFormatName:completionBlock:]
153+
*/
154+
- (BOOL)asynchronouslyRetrieveImageForEntity:(id <FICEntity>)entity withFormatName:(NSString *)formatName completionBlock:(FICImageCacheCompletionBlock)completionBlock;
155+
156+
/**
157+
Deletes an image from the image cache.
158+
159+
@param entity The entity that uniquely identifies the source image.
160+
161+
@param formatName The format name that uniquely identifies which image table to look in for the cached image.
162+
*/
163+
- (void)deleteImageForEntity:(id <FICEntity>)entity withFormatName:(NSString *)formatName;
164+
165+
///-----------------------------------
166+
/// @name Checking for Image Existence
167+
///-----------------------------------
168+
169+
/**
170+
Returns whether or not an image exists in the image cache.
171+
172+
@param entity The entity that uniquely identifies the source image.
173+
174+
@param formatName The format name that uniquely identifies which image table to look in for the cached image.
175+
176+
@return `YES` if an image exists in the image cache for a given entity and format name. Otherwise, `NO`.
177+
*/
178+
- (BOOL)imageExistsForEntity:(id <FICEntity>)entity withFormatName:(NSString *)formatName;
179+
180+
///--------------------------------
181+
/// @name Resetting the Image Cache
182+
///--------------------------------
183+
184+
/**
185+
Resets the image cache by deleting all image tables and their contents.
186+
187+
@note Resetting an image cache does not reset its image formats.
188+
*/
189+
- (void)reset;
190+
191+
@end
192+
193+
/**
194+
`FICImageCacheDelegate` defines the required and optional actions that an image cache's delegate can perform.
195+
*/
196+
@protocol FICImageCacheDelegate <NSObject>
197+
198+
@required
199+
200+
/**
201+
This method is called on the delegate when the image cache needs a source image.
202+
203+
@param imageCache The image cache that is requesting the source image.
204+
205+
@param entity The entity that uniquely identifies the source image.
206+
207+
@param formatName The format name that uniquely identifies which image table to look in for the cached image.
208+
209+
@param completionBlock The completion block that the receiver must call when it has a source image ready.
210+
211+
The completion block's type is defined as follows:
212+
213+
typedef void (^FICImageRequestCompletionBlock)(UIImage *sourceImage)
214+
215+
The completion block must always be called on the main thread.
216+
217+
@discussion A source image is usually the original, full-size image that represents an entity. This source image is processed for every unique format to create the
218+
actual image data to be stored in the image cache. This method is an asynchronous data provider, so nothing is actually returned to the sender. Instead, the delegate's
219+
implementation is expected to call the completion block once an image is available.
220+
221+
Fast Image Cache is architected under the typical design pattern whereby model objects provide a URL to certain image assets and allow the client to actually retrieve
222+
the images via network requests only when needed. As a result, the implementation of this method will usually involve creating an asynchronous network request using
223+
the URL returned by <[FICEntity sourceImageURLWithFormatName:]>, deserializing the image data when the request completes, and finally calling this method's completion
224+
block to provide the image cache with the source image.
225+
*/
226+
- (void)imageCache:(FICImageCache *)imageCache wantsSourceImageForEntity:(id <FICEntity>)entity withFormatName:(NSString *)formatName completionBlock:(FICImageRequestCompletionBlock)completionBlock;
227+
228+
@optional
229+
230+
/**
231+
This method is called on the delegate to determine whether or not all formats in a family should be processed right now.
232+
233+
@note If this method is not implemented by the delegate, the default value is `YES`.
234+
235+
@param imageCache The image cache that is requesting the source image.
236+
237+
@param formatFamily The name of a format family.
238+
239+
@param entity The entity that uniquely identifies the source image.
240+
241+
@return `YES` if all formats in a format family should be processed. Otherwise, `NO`.
242+
243+
@discussion This method is called whenever new image data is stored in the image cache. Because format families are used to group multiple different formats together,
244+
typically the delegate will want to return `YES` here so that other formats in the same family can be processed.
245+
246+
For example, if your image cache has defined several different thumbnail sizes and styles for a person model, and if a person changes their profile photo, you would
247+
want every thumbnail size and style is updated with the new source image.
248+
*/
249+
- (BOOL)imageCache:(FICImageCache *)imageCache shouldProcessAllFormatsInFamily:(NSString *)formatFamily forEntity:(id <FICEntity>)entity;
250+
251+
/**
252+
This method is called on the delegate whenever the image cache has an error message to log.
253+
254+
@param imageCache The image cache that is requesting the source image.
255+
256+
@param errorMessage The error message generated by the image cache.
257+
258+
@discussion Fast Image Cache will not explicitly log any messages to standard output. Instead, it allows the delegate to handle (or ignore) any error output.
259+
*/
260+
- (void)imageCache:(FICImageCache *)imageCache errorDidOccurWithMessage:(NSString *)errorMessage;
261+
262+
@end

0 commit comments

Comments
 (0)