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

Deprecations Methods

Properties

attributes

@property (nonatomic, readonly) NSArray *attributes
Discussion

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

Declared In

RKEntityByAttributeCache.h

callbackQueue

@property (nonatomic, assign) dispatch_queue_t callbackQueue
Discussion

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

Default: nil

Declared In

RKEntityByAttributeCache.h

count

@property (nonatomic, readonly) NSUInteger count
Discussion

Returns a count of the total number of cached objects.

Declared In

RKEntityByAttributeCache.h

countOfAttributeValues

@property (nonatomic, readonly) NSUInteger countOfAttributeValues
Discussion

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

Return Value

The number of unique attribute values within the receiver.

Declared In

RKEntityByAttributeCache.h

entity

@property (nonatomic, readonly) NSEntityDescription *entity
Discussion

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

Declared In

RKEntityByAttributeCache.h

loaded

@property (nonatomic, getter=isLoaded, readonly) BOOL loaded
Discussion

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

Declared In

RKEntityByAttributeCache.h

managedObjectContext

@property (nonatomic, readonly) NSManagedObjectContext *managedObjectContext
Discussion

The managed object context the receiver fetches cached objects from.

Declared In

RKEntityByAttributeCache.h

monitorsContextForChanges

@property (nonatomic, assign) BOOL monitorsContextForChanges

Instance Methods

addObject:

- (void)addObject:(NSManagedObject *)object

addObjects:completion:

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

Asynchronously adds a managed object to the cache.

The object must be an instance of the cached entity.

Parameters

managedObjects

The managed object to add to the cache.

completion

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

Declared In

RKEntityByAttributeCache.h

containsObject:

- (BOOL)containsObject:(NSManagedObject *)object
Discussion

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

Parameters

object

An object.

Return Value

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

Declared In

RKEntityByAttributeCache.h

containsObjectWithAttributeValues:

- (BOOL)containsObjectWithAttributeValues:(NSDictionary *)attributeValues
Discussion

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.

Parameters

attributeValues

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

countWithAttributeValues:

- (NSUInteger)countWithAttributeValues:(NSDictionary *)attributeValues
Discussion

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

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

- (void)flush

flush:

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

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

Parameters

completion

A block to execute when the cache has finished flushing.

Declared In

RKEntityByAttributeCache.h

initWithEntity:attributes:managedObjectContext:

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

Initializes the receiver with a given entity, attribute, and managed object 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

load

- (void)load

load:

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

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.

Parameters

completion

A block to execute when the cache has finished loading.

Declared In

RKEntityByAttributeCache.h

objectWithAttributeValues:inContext:

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

Returns the first object with a matching value for the cache key attributes in a given managed object 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:

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

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

Parameters

attributeValues

A value for the cache key attribute.

context

The managed object context to retrieve the objects from.

Return Value

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

Declared In

RKEntityByAttributeCache.h

removeObject:

- (void)removeObject:(NSManagedObject *)object

removeObjects:completion:

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

Asynchronously removes a managed object from the cache.

The object must be an instance of the cached entity.

Parameters

managedObjects

The managed object to remove from the cache.

completion

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

Declared In

RKEntityByAttributeCache.h