Inherits from NSObject
Declared in RKEntityByAttributeCache.h

Overview

The RKEntityByAttributeCache class provides an in-memory caching mechanism for managed objects instances of an entity in a managed object context with the value of one of the object’s attributes acting as the cache key. When loaded, the cache will retrieve all instances of an entity from the store and build a dictionary mapping values for the given cache key attribute to the managed object ID for all objects matching the value. The cache can then be used to quickly retrieve objects by attribute value for the cache key without executing another fetch request against the managed object context. This can provide a large performance improvement when a large number of objects are being retrieved using a particular attribute as the key.

RKEntityByAttributeCache instances are used by the RKEntityCache to provide caching for multiple entities at once.

Bug: Please note that the RKEntityByAttribute cache is implemented using a NSFetchRequest with a result type of NSDictionaryResultType. This means that the cache cannot load pending object instances via a fetch from the load method. Pending objects must be manually added to the cache via addObject: if it is desirable for the pending objects to be retrieved by subsequent invocations of objectWithAttributeValue:inContext: and objectsWithAttributeValue:inContext: prior to a save.

This is a limitation imposed by Core Data. The dictionary result type implementation is leveraged instead a normal fetch request because it offers very large performance and memory utilization improvements by avoiding construction of managed object instances and faulting.

Tasks

Creating a Cache

Getting Cache Identity

  •   entity

    The Core Data entity description for the managed objects being cached.

    property
  •   attributes

    An array of attribute names specifying attributes of the cached entity that act as the cache key.

    property
  •   managedObjectContext

    The managed object context the receiver fetches cached objects from.

    property
  •   callbackQueue

    The queue on which to dispatch callbacks for asynchronous operations. When nil, the main queue is used.

    property

Loading and Flushing the Cache

  • – load:

    Loads the cache by finding all instances of the configured entity and building an association between the value of the cached attribute’s value and the managed object ID for the object.

  • – flush:

    Flushes the cache by releasing all cache attribute value to managed object ID associations.

Inspecting Cache State

Managing Cached Objects

Properties

attributes

An array of attribute names specifying attributes of the cached entity that act as the cache key.

@property (nonatomic, readonly) NSArray *attributes

Declared In

RKEntityByAttributeCache.h

callbackQueue

The queue on which to dispatch callbacks for asynchronous operations. When nil, the main queue is used.

@property (nonatomic, assign) dispatch_queue_t callbackQueue

Discussion

Default: nil

Declared In

RKEntityByAttributeCache.h

entity

The Core Data entity description for the managed objects being cached.

@property (nonatomic, readonly) NSEntityDescription *entity

Declared In

RKEntityByAttributeCache.h

managedObjectContext

The managed object context the receiver fetches cached objects from.

@property (nonatomic, readonly) NSManagedObjectContext *managedObjectContext

Declared In

RKEntityByAttributeCache.h

Instance Methods

addObjects:completion:

Asynchronously adds a managed object to the cache.

- (void)addObjects:(NSSet *)managedObjects completion:(void ( ^ ) ( void ))completion

Parameters

completion

An optional block to execute once the object has been added to the cache.

object

The managed object to add to the cache.

Discussion

The object must be an instance of the cached entity.

Declared In

RKEntityByAttributeCache.h

containsObject:

Returns a Boolean value that indicates whether a given object is present in the cache.

- (BOOL)containsObject:(NSManagedObject *)object

Parameters

object

An object.

Return Value

YES if object is present in the cache, otherwise NO.

Declared In

RKEntityByAttributeCache.h

containsObjectWithAttributeValues:

Returns a Boolean value that indicates whether one of more objects is present in the cache with a given value of the cache key attribute.

- (BOOL)containsObjectWithAttributeValues:(NSDictionary *)attributeValues

Parameters

attributeValue

The value with which to check the cache for objects with a matching value.

Return Value

YES if one or more objects with the given value for the cache key attribute is present in the cache, otherwise NO.

Declared In

RKEntityByAttributeCache.h

count

Returns a count of the total number of cached objects.

- (NSUInteger)count

Declared In

RKEntityByAttributeCache.h

countOfAttributeValues

Returns the number of unique attribute values contained within the receiver.

- (NSUInteger)countOfAttributeValues

Return Value

The number of unique attribute values within the receiver.

Declared In

RKEntityByAttributeCache.h

countWithAttributeValues:

Returns the total number of cached objects whose attributes match the values in the given dictionary of attribute values.

- (NSUInteger)countWithAttributeValues:(NSDictionary *)attributeValues

Parameters

attributeValues

The value for the cache key attribute to retrieve a count of the objects with a matching value.

Return Value

The number of objects in the cache with the given value for the cache attribute of the receiver.

Declared In

RKEntityByAttributeCache.h

flush:

Flushes the cache by releasing all cache attribute value to managed object ID associations.

- (void)flush:(void ( ^ ) ( void ))completion

Parameters

completion

A block to execute when the cache has finished flushing.

Declared In

RKEntityByAttributeCache.h

initWithEntity:attributes:managedObjectContext:

Initializes the receiver with a given entity, attribute, and managed object context.

- (id)initWithEntity:(NSEntityDescription *)entity attributes:(NSArray *)attributeNames managedObjectContext:(NSManagedObjectContext *)context

Parameters

entity

The Core Data entity description for the managed objects being cached.

attributeNames

An array of attribute names used as the cache keys.

context

The managed object context the cache retrieves the cached objects from.

Return Value

The receiver, initialized with the given entity, attribute, and managed object

context.

Declared In

RKEntityByAttributeCache.h

isLoaded

A Boolean value indicating if the cache has loaded associations between cache attribute values and managed object ID’s.

- (BOOL)isLoaded

Declared In

RKEntityByAttributeCache.h

load:

Loads the cache by finding all instances of the configured entity and building an association between the value of the cached attribute’s value and the managed object ID for the object.

- (void)load:(void ( ^ ) ( void ))completion

Parameters

completion

A block to execute when the cache has finished loading.

Declared In

RKEntityByAttributeCache.h

objectWithAttributeValues:inContext:

Returns the first object with a matching value for the cache key attributes in a given managed object context.

- (NSManagedObject *)objectWithAttributeValues:(NSDictionary *)attributeValues inContext:(NSManagedObjectContext *)context

Parameters

attributeValues

A value for the cache key attribute.

context

The managed object context to retrieve the object from.

Return Value

An object with the value of attribute matching attributeValue or nil.

Declared In

RKEntityByAttributeCache.h

objectsWithAttributeValues:inContext:

Returns the collection of objects with a matching value for the cache key attribute in a given managed object context.

- (NSSet *)objectsWithAttributeValues:(NSDictionary *)attributeValues inContext:(NSManagedObjectContext *)context

Parameters

context

The managed object context to retrieve the objects from.

attributeValue

A value for the cache key attribute.

Return Value

An array of objects with the value of attribute matching attributeValue or an empty array.

Declared In

RKEntityByAttributeCache.h

removeObjects:completion:

Asynchronously removes a managed object from the cache.

- (void)removeObjects:(NSSet *)managedObjects completion:(void ( ^ ) ( void ))completion

Parameters

completion

An optional block to execute once the object has been removed from the cache.

object

The managed object to remove from the cache.

Discussion

The object must be an instance of the cached entity.

Declared In

RKEntityByAttributeCache.h