RKSearchIndexer Class Reference
Inherits from | NSObject |
Declared in | RKSearchIndexer.h |
Overview
The RKSearchIndexer
class provides support for adding full text searching to Core Data entities and managing the indexing of managed object instances of searchable entities.
Tasks
Adding Indexing to an Entity
-
+ addSearchIndexingToEntity:onAttributes:
Adds search indexing to the given entity for a given list of attributes identified by name. The entity will have a to-many relationship to the
RKSearchWordEntity
added and the list of searchable attributes stored into the user info dictionary.
Configuring Indexing
-
stopWords
An optional set of stop words to be removed from the set of tokens used to create the search words for indexed entities.
property -
indexingContext
An optional
propertyNSManagedObjectContext
in which to perform indexing operations. -
delegate
The delegate of the search indexer.
property
Indexing Changes in a Managed Object Context
-
– startObservingManagedObjectContext:
Tells the receiver to start monitoring the given managed object context for save notifications and to index any changed objects in response to the save.
-
– stopObservingManagedObjectContext:
Tells the receiver to stop monitoring the given managed object context for save notifications and cease indexing changed objects in response to the save.
-
– indexChangedObjectsInManagedObjectContext:waitUntilFinished:
Tells the receiver to build a list of all inserted or updated managed objects in the given context and index each one. Objects for entities that are not indexed are silently ignored.
Indexing a Managed Object
-
– indexManagedObject:
Tells the receiver to index a given managed object instance.
Managing Indexing Operations
-
– cancelAllIndexingOperations
Tells the indexer to cancel all indexing operations in progress.
-
– waitUntilAllIndexingOperationsAreFinished
Blocks the current thread until all of the receiver’s queued and executing indexing operations finish executing.
Properties
delegate
The delegate of the search indexer.
@property (nonatomic, weak) id<RKSearchIndexerDelegate> delegate
Declared In
RKSearchIndexer.h
indexingContext
An optional NSManagedObjectContext
in which to perform indexing operations.
@property (nonatomic, strong) NSManagedObjectContext *indexingContext
Discussion
Default: nil
Warning: It is recommended that the indexing context be configured with a direct connection to the persistent store coordinator and a merge policy of NSMergeByPropertyObjectTrumpMergePolicy
.
Declared In
RKSearchIndexer.h
Class Methods
addSearchIndexingToEntity:onAttributes:
Adds search indexing to the given entity for a given list of attributes identified by name. The entity will have a to-many relationship to the RKSearchWordEntity
added and the list of searchable attributes stored into the user info dictionary.
+ (void)addSearchIndexingToEntity:(NSEntityDescription *)entity onAttributes:(NSArray *)attributes
Parameters
- entity
The entity to which search indexing support is to be added.
- attributes
An array of NSAttributeDescription objects or NSString attribute names specifying the
NSStringAttributeType
attributes that are to be indexed for searching.
Discussion
Managed objects for entities that have had indexing added to them can be indexed by instances of RKSearchIndexer
and searched via an RKSearchPredicate
used with an NSFetchRequest
object.
The given entity must exist in a mutable managed object model (that is, one that has not been used to create an object graph in a managed object context). The given list of attributes must identify attributes of the given entity with the attribute type of NSStringAttributeType
.
Declared In
RKSearchIndexer.h
Instance Methods
cancelAllIndexingOperations
Tells the indexer to cancel all indexing operations in progress.
- (void)cancelAllIndexingOperations
Discussion
When a managed object context that is being observed is saved, the indexer enqueues an indexing operation for each indexable object that was inserted or updated during the save event. This method provides support for cancelling all in indexing operations that have not yet been processed.
Declared In
RKSearchIndexer.h
indexChangedObjectsInManagedObjectContext:waitUntilFinished:
Tells the receiver to build a list of all inserted or updated managed objects in the given context and index each one. Objects for entities that are not indexed are silently ignored.
- (void)indexChangedObjectsInManagedObjectContext:(NSManagedObjectContext *)managedObjectContext waitUntilFinished:(BOOL)wait
Parameters
- managedObjectContext
The managed object context that is to be indexed.
- wait
A Boolean value that determines if the current thread will be blocked until all indexing operations have completed.
Discussion
The value of the wait
parameter is significant in the determination of the indexing strategy. When YES
, indexing is perform synchronously. When NO
, indexing operations are enqueued and the method returns to the caller immediately. Enqueued indexing operations can later be cancelled by invoking cancelAllIndexingOperations
.
This method is called by the indexer in response to a NSManagedObjectContextWillSaveNotification
for contexts observed with startObservingManagedObjectContext:
.
Warning: Indexing all changed objects in a managed object context does not utilize the indexingContext
as unsaved objects in the graph would not be visible to that context.
Please beware that indexing changed objects in a context with the NSMainQueueConcurrencyType
asynchronously (where wait == NO
) and then invoking waitUntilAllIndexingOperationsAreFinished
will result in a deadlock if called from the main thread. It is highly recommended that indexing be performed in contexts with the NSPrivateQueueConcurrencyType
to take advantage of queueing and avoid blocking the main thread.
Declared In
RKSearchIndexer.h
indexManagedObject:
Tells the receiver to index a given managed object instance.
- (NSUInteger)indexManagedObject:(NSManagedObject *)managedObject
Parameters
- managedObject
The managed object that is to be indexed.
Return Value
A count of the number of search words that were indexed from the given object’s searchable attributes.
@raises NSInvalidArgumentException
Raised if the given managed object is not for a searchable entity.
Declared In
RKSearchIndexer.h
startObservingManagedObjectContext:
Tells the receiver to start monitoring the given managed object context for save notifications and to index any changed objects in response to the save.
- (void)startObservingManagedObjectContext:(NSManagedObjectContext *)managedObjectContext
Parameters
- managedObjectContext
The managed object context to be monitored for save notifications.
Discussion
Warning: The behavior of this method changes based on the availability of an indexingContext
. When the indexing context is nil
, this method will register the receiver as an observer for the NSManagedObjectContextWillSaveNotification
. At save time, the indexer will scan the set of changed objects in the save notification and synchronously index each changed object prior to the completion of the save. This is simple, but introduces a performance penalty that may not be unacceptable.
When an indexing context is provided, invoking startObservingManagedObjectContext:
will cause the receiver to register for the NSManagedObjectContextDidSaveNotification
instead. After a save completes, the indexer will reset the indexing context and enqueue an indexing operation for each changed object in the notification. Once all the indexing operations have completed, the indexing context will be saved and its contents should be merged into other contexts.
Declared In
RKSearchIndexer.h
stopObservingManagedObjectContext:
Tells the receiver to stop monitoring the given managed object context for save notifications and cease indexing changed objects in response to the save.
- (void)stopObservingManagedObjectContext:(NSManagedObjectContext *)managedObjectContext
Parameters
- managedObjectContext
The managed object context that is no longer to be monitored for save notifications.
Declared In
RKSearchIndexer.h
waitUntilAllIndexingOperationsAreFinished
Blocks the current thread until all of the receiver’s queued and executing indexing operations finish executing.
- (void)waitUntilAllIndexingOperationsAreFinished
Discussion
When called, this method blocks the current thread and waits for the receiver’s current and queued indexing operations to finish executing. While the current thread is blocked, the receiver continues to launch already queued operations and monitor those that are executing. During this time, the current thread cannot add operations to the queue, but other threads may. Once all of the pending operations are finished, this method returns.
If there are no indexing operations in the queue, this method returns immediately.
Warning: Invoking this method may cause a deadlock if indexing operations have been enqueued for a managed object context with the NSMainQueueConcurrencyType
and the method is called from the main thread.
Declared In
RKSearchIndexer.h