RKObjectManager Class Reference
Inherits from | NSObject |
Conforms to | RKConfigurationDelegate |
Declared in | RKObjectManager.h RKObjectManager.m |
Overview
The object manager is the primary interface for interacting with RESTful resources via HTTP. It is responsible for retrieving remote object representations via HTTP and transforming them into local domain objects via the RKObjectMapper. It is also capable of serializing local objects and sending them to a remote system for processing. The object manager strives to hide the developer from the details of configuring an RKRequest, processing an RKResponse, parsing any data returned by the remote system, and running the parsed data through the object mapper.
Shared Manager Instance
Multiple instances of RKObjectManager may be used in parallel, but the first instance initialized is automatically configured as the sharedManager instance. The shared instance can be changed at runtime if so desired. See sharedManager and setSharedManager for details.
Configuring the Object Manager
The object mapper must be configured before object can be loaded from or transmitted to your remote backend system. Configuration consists of specifying the desired MIME types to be used during loads and serialization, registering object mappings to use for mapping and serialization, registering routes, and optionally configuring an instance of the managed object store (for Core Data).
MIME Types
MIME Types are used for two purposes within RestKit:
- Content Negotiation. RestKit leverages the HTTP Accept header to specify the desired representation of content when contacting a remote web service. You can specify the MIME Type to use via the acceptMIMEType method. The default MIME Type is RKMIMETypeJSON (application/json). If the remote web service responds with content in a different MIME Type than specified, RestKit will attempt to parse it by consulting the [parser registry][RKParserRegistry parserForMIMEType:]. Failure to find a parser for the returned content will result in an unexpected response invocation of [RKObjectLoaderDelegate objectLoaderDidLoadUnexpectedResponse].
- Serialization. RestKit can be used to transport local object representation back to the remote web server for processing by serializing them into an RKRequestSerializable representation. The desired serialization format is configured by setting the serializationMIMEType property. RestKit currently supports serialization to RKMIMETypeFormURLEncoded and RKMIMETypeJSON. The serialization rules themselves are expressed via an instance of RKObjectMapping.
The Mapping Provider
RestKit determines how to map and serialize objects by consulting the mappingProvider. The mapping provider is responsible for providing instances of RKObjectMapper with object mappings that should be used for transforming mappable data into object representations. When you ask the object manager to load or send objects for you, the mappingProvider instance will be used for the object mapping operations constructed for you. In this way, the mappingProvider is the central registry for the knowledge about how objects in your application are mapped.
Mappings are registered by constructing instances of RKObjectMapping and registering them with the provider: `
RKObjectManager* manager = [RKObjectManager managerWithBaseURL:myBaseURL];
RKObjectMapping* articleMapping = [RKObjectMapping mappingForClass:[Article class]];
[mapping mapAttributes:@"title", @"body", @"publishedAt", nil];
[manager.mappingProvider setObjectMapping:articleMapping forKeyPath:@"article"];
// Generate an inverse mapping for transforming Article -> NSMutableDictionary.
[manager.mappingProvider setSerializationMapping:[articleMapping inverseMapping] forClass:[Article class]];`
Configuring Routes
Routing is the process of transforming objects and actions (as defined by HTTP verbs) into resource paths. RestKit ships
Initializing a Core Data Object Store
Loading Remote Objects
Routing & Object Serialization
Default Error Mapping
When an instance of RKObjectManager is configured, the RKObjectMappingProvider instance configured
Provides extensions to RKObjectManager for instantiating RKTableController instances
Tasks
Configuring the Shared Manager Instance
-
+ sharedManager
Return the shared instance of the object manager
-
+ setSharedManager:
Set the shared instance of the object manager
Object Mapping Dispatch Queue
-
+ defaultMappingQueue
Returns the global default Grand Central Dispatch queue used for object mapping operations executed by RKObjectLoaders.
-
+ setDefaultMappingQueue:
Sets a new global default Grand Central Dispatch queue for use in object mapping operations executed by RKObjectLoaders.
Initializing an Object Manager
-
+ managerWithBaseURLString:
Create and initialize a new object manager. If this is the first instance created it will be set as the shared instance
-
– initWithBaseURL:
Initializes a newly created object manager with a specified baseURL.
Network Integration
-
client
The underlying HTTP client for this manager
property -
baseURL
The base URL of the underlying RKClient instance. Object loader and paginator instances built through the object manager are relative to this URL.
property -
requestCache
The request cache used to store and load responses for requests sent through this object manager’s underlying client object
property -
requestQueue
The request queue used to dispatch asynchronous requests sent through this object manager’s underlying client object
property -
networkStatus
Returns the current network status for this object manager as determined by connectivity to the remote backend system
property -
isOnline
Returns YES when we are in online mode
property -
isOffline
Returns YES when we are in offline mode
property
Configuring Object Mapping
-
mappingProvider
The Mapping Provider responsible for returning mappings for various keyPaths.
property -
router
Router object responsible for generating resource paths for HTTP requests
property -
objectStore
A Core Data backed object store for persisting objects that have been fetched from the Web
property -
mappingQueue
The Grand Dispatch Queue to use when performing expensive object mapping operations within RKObjectLoader instances created through this object manager
property -
serializationMIMEType
The Default MIME Type to be used in object serialization.
property -
acceptMIMEType
The value for the HTTP Accept header to specify the preferred format for retrieved data
property
Building Object Loaders
-
– objectLoaderClass
Returns the class of object loader instances built through the manager. When Core Data has been configured, instances of RKManagedObjectLoader will be emitted by the manager. Otherwise RKObjectLoader is used.
-
– loaderWithResourcePath:
Creates and returns an RKObjectLoader or RKManagedObjectLoader instance targeting the specified resourcePath.
-
– loaderWithURL:
Creates and returns an RKObjectLoader or RKManagedObjectLoader instance targeting the specified URL.
-
– loaderForObject:method:
Creates and returns an RKObjectLoader or RKManagedObjectLoader instance for an object instance.
-
– paginatorWithResourcePathPattern:
Creates and returns an RKObjectPaginator instance targeting the specified resource path pattern.
-
– loadObjectsAtResourcePath:delegate:
Create and send an asynchronous GET request to load the objects at the resource path and call back the delegate with the loaded objects. Remote objects will be mapped to local objects by consulting the keyPath registrations set on the mapping provider.
Mappable Object Loaders
-
– getObject:delegate:
Fetch the data for a mappable object by performing an HTTP GET.
-
– postObject:delegate:
Create a remote mappable model by POSTing the attributes to the remote resource and loading the resulting objects from the payload
-
– putObject:delegate:
Update a remote mappable model by PUTing the attributes to the remote resource and loading the resulting objects from the payload
-
– deleteObject:delegate:
Delete the remote instance of a mappable model by performing an HTTP DELETE on the remote resource
-
– loadObjectsAtResourcePath:usingBlock:
Load the objects at the specified resource path and perform object mapping on the response payload. Prior to sending the object loader, the block will be invoked to allow you to configure the object loader as you see fit. This can be used to change the response type, set custom parameters, choose an object mapping, etc.
-
– getObject:usingBlock:
GET a remote object instance and yield the object loader to the block before sending
-
– postObject:usingBlock:
POST a remote object instance and yield the object loader to the block before sending
-
– putObject:usingBlock:
PUT a remote object instance and yield the object loader to the block before sending
-
– deleteObject:usingBlock:
DELETE a remote object instance and yield the object loader to the block before sending
Other Methods
-
– configureObjectLoader:
Configure an object loader before it is utilized
RKTableController Methods
-
– tableControllerForTableViewController:
Creates and returns a table controller object capable of loading remote object representations into a UITableView using the RestKit object mapping engine for a given table view controller.
-
– tableControllerWithTableView:forViewController:
Creates and returns a table controller object capable of loading remote object representations into a UITableView using the RestKit object mapping engine for a given table view and view controller.
-
– fetchedResultsTableControllerForTableViewController:
Creates and returns a fetched results table controller object capable of loading remote object representations stored in Core Data into a UITableView using the RestKit object mapping engine for a given table view controller.
-
– fetchedResultsTableControllerWithTableView:forViewController:
Creates and returns a table controller object capable of loading remote object representations stored in Core Data into a UITableView using the RestKit object mapping engine for a given table view and view controller.
Properties
acceptMIMEType
The value for the HTTP Accept header to specify the preferred format for retrieved data
@property (nonatomic, assign) NSString *acceptMIMEType
Declared In
RKObjectManager.h
baseURL
The base URL of the underlying RKClient instance. Object loader and paginator instances built through the object manager are relative to this URL.
@property (nonatomic, readonly) RKURL *baseURL
Return Value
The baseURL of the client.
See Also
Declared In
RKObjectManager.h
client
The underlying HTTP client for this manager
@property (nonatomic, retain) RKClient *client
Declared In
RKObjectManager.h
isOffline
Returns YES when we are in offline mode
@property (nonatomic, readonly) BOOL isOffline
Declared In
RKObjectManager.h
isOnline
Returns YES when we are in online mode
@property (nonatomic, readonly) BOOL isOnline
Declared In
RKObjectManager.h
mappingProvider
The Mapping Provider responsible for returning mappings for various keyPaths.
@property (nonatomic, retain) RKObjectMappingProvider *mappingProvider
Declared In
RKObjectManager.h
mappingQueue
The Grand Dispatch Queue to use when performing expensive object mapping operations within RKObjectLoader instances created through this object manager
@property (nonatomic, assign) dispatch_queue_t mappingQueue
Declared In
RKObjectManager.h
networkStatus
Returns the current network status for this object manager as determined by connectivity to the remote backend system
@property (nonatomic, readonly) RKObjectManagerNetworkStatus networkStatus
Declared In
RKObjectManager.h
objectStore
A Core Data backed object store for persisting objects that have been fetched from the Web
@property (nonatomic, retain) RKManagedObjectStore *objectStore
Declared In
RKObjectManager.h
requestCache
The request cache used to store and load responses for requests sent through this object manager’s underlying client object
@property (nonatomic, readonly) RKRequestCache *requestCache
Declared In
RKObjectManager.h
requestQueue
The request queue used to dispatch asynchronous requests sent through this object manager’s underlying client object
@property (nonatomic, readonly) RKRequestQueue *requestQueue
Declared In
RKObjectManager.h
Class Methods
defaultMappingQueue
Returns the global default Grand Central Dispatch queue used for object mapping operations executed by RKObjectLoaders.
+ (dispatch_queue_t)defaultMappingQueue
Discussion
All object loaders perform their loading within a Grand Central Dispatch queue. This provides control over the number of loaders that are performing expensive operations such as JSON parsing, object mapping, and accessing Core Data concurrently. The defaultMappingQueue is configured as the mappingQueue for all RKObjectManager’s created by RestKit, but can be overridden on a per manager and per object loader basis.
By default, the defaultMappingQueue is configured as serial GCD queue.
Declared In
RKObjectManager.h
managerWithBaseURLString:
Create and initialize a new object manager. If this is the first instance created it will be set as the shared instance
+ (id)managerWithBaseURLString:(NSString *)baseURLString
Declared In
RKObjectManager.h
setDefaultMappingQueue:
Sets a new global default Grand Central Dispatch queue for use in object mapping operations executed by RKObjectLoaders.
+ (void)setDefaultMappingQueue:(dispatch_queue_t)defaultMappingQueue
Declared In
RKObjectManager.h
Instance Methods
configureObjectLoader:
Configure an object loader before it is utilized
- (void)configureObjectLoader:(RKObjectLoader *)objectLoader
Parameters
- request
An object loader being configured for dispatch
Declared In
RKConfigurationDelegate.h
deleteObject:delegate:
Delete the remote instance of a mappable model by performing an HTTP DELETE on the remote resource
- (void)deleteObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate
Declared In
RKObjectManager.h
deleteObject:usingBlock:
DELETE a remote object instance and yield the object loader to the block before sending
- (void)deleteObject:(id<NSObject>)object usingBlock:(RKObjectLoaderBlock)block
Declared In
RKObjectManager.h
fetchedResultsTableControllerForTableViewController:
Creates and returns a fetched results table controller object capable of loading remote object representations stored in Core Data into a UITableView using the RestKit object mapping engine for a given table view controller.
- (RKFetchedResultsTableController *)fetchedResultsTableControllerForTableViewController:(UITableViewController *)tableViewController
Parameters
- tableViewController
A UITableViewController to instantiate a table controller for
Return Value
An RKFetchedResultsTableController instance ready to drive the table view for the provided tableViewController.
Declared In
RKObjectManager+RKTableController.h
fetchedResultsTableControllerWithTableView:forViewController:
Creates and returns a table controller object capable of loading remote object representations stored in Core Data into a UITableView using the RestKit object mapping engine for a given table view and view controller.
- (RKFetchedResultsTableController *)fetchedResultsTableControllerWithTableView:(UITableView *)tableView forViewController:(UIViewController *)viewController
Parameters
- tableView
The UITableView object that table controller with acts as the delegate and data source for.
- viewController
The UIViewController that owns the specified tableView.
Return Value
An RKFetchedResultsTableController instance ready to drive the table view for the provided tableViewController.
Declared In
RKObjectManager+RKTableController.h
getObject:delegate:
Fetch the data for a mappable object by performing an HTTP GET.
- (void)getObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate
Declared In
RKObjectManager.h
getObject:usingBlock:
GET a remote object instance and yield the object loader to the block before sending
- (void)getObject:(id<NSObject>)object usingBlock:(RKObjectLoaderBlock)block
Declared In
RKObjectManager.h
initWithBaseURL:
Initializes a newly created object manager with a specified baseURL.
- (id)initWithBaseURL:(RKURL *)baseURL
Return Value
The newly initialized RKObjectManager object
Declared In
RKObjectManager.h
loadObjectsAtResourcePath:delegate:
Create and send an asynchronous GET request to load the objects at the resource path and call back the delegate with the loaded objects. Remote objects will be mapped to local objects by consulting the keyPath registrations set on the mapping provider.
- (void)loadObjectsAtResourcePath:(NSString *)resourcePath delegate:(id<RKObjectLoaderDelegate>)delegate
Declared In
RKObjectManager.h
loadObjectsAtResourcePath:usingBlock:
Load the objects at the specified resource path and perform object mapping on the response payload. Prior to sending the object loader, the block will be invoked to allow you to configure the object loader as you see fit. This can be used to change the response type, set custom parameters, choose an object mapping, etc.
- (void)loadObjectsAtResourcePath:(NSString *)resourcePath usingBlock:(RKObjectLoaderBlock)block
Discussion
For example:
- (void)loadObjectUsingBlockExample {
[[RKObjectManager sharedManager] loadObjectsAtResourcePath:@"/monkeys.json" usingBlock:^(RKObjectLoader* loader) {
loader.objectMapping = [[RKObjectManager sharedManager].mappingProvider objectMappingForClass:[Monkey class]];
}];
}
Declared In
RKObjectManager.h
loaderForObject:method:
Creates and returns an RKObjectLoader or RKManagedObjectLoader instance for an object instance.
- (id)loaderForObject:(id<NSObject>)object method:(RKRequestMethod)method
Parameters
- object
The object with which to initialize the object loader.
Return Value
The newly created object loader instance.
Discussion
The object loader instantiated will be initialized with a URL built by evaluating the object with the router to construct a resource path and then appending that resource path to the baseURL of the client. The loader will then be configured with object mapping configuration from the manager and request configuration from the client. The specified object will be the target of the object loader and will have any returned content mapped back onto the instance.
See Also
Declared In
RKObjectManager.h
loaderWithResourcePath:
Creates and returns an RKObjectLoader or RKManagedObjectLoader instance targeting the specified resourcePath.
- (id)loaderWithResourcePath:(NSString *)resourcePath
Parameters
- resourcePath
A resource to use when building the URL to initialize the object loader instance.
Return Value
The newly created object loader instance.
Discussion
The object loader instantiated will be initialized with an RKURL built by appending the resourcePath to the baseURL of the client. The loader will then be configured with object mapping configuration from the manager and request configuration from the client.
Declared In
RKObjectManager.h
loaderWithURL:
Creates and returns an RKObjectLoader or RKManagedObjectLoader instance targeting the specified URL.
- (id)loaderWithURL:(NSURL *)URL
Parameters
- URL
The URL with which to initialize the object loader.
Return Value
The newly created object loader instance.
Discussion
The object loader instantiated will be initialized with URL and will then be configured with object mapping configuration from the manager and request configuration from the client.
Declared In
RKObjectManager.h
objectLoaderClass
Returns the class of object loader instances built through the manager. When Core Data has been configured, instances of RKManagedObjectLoader will be emitted by the manager. Otherwise RKObjectLoader is used.
- (Class)objectLoaderClass
Return Value
Declared In
RKObjectManager.h
paginatorWithResourcePathPattern:
Creates and returns an RKObjectPaginator instance targeting the specified resource path pattern.
- (RKObjectPaginator *)paginatorWithResourcePathPattern:(NSString *)resourcePathPattern
Return Value
The newly created paginator instance.
Discussion
The paginator instantiated will be initialized with an RKURL built by appending the resourcePathPattern to the baseURL of the client.
See Also
Declared In
RKObjectManager.h
postObject:delegate:
Create a remote mappable model by POSTing the attributes to the remote resource and loading the resulting objects from the payload
- (void)postObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate
Declared In
RKObjectManager.h
postObject:usingBlock:
POST a remote object instance and yield the object loader to the block before sending
- (void)postObject:(id<NSObject>)object usingBlock:(RKObjectLoaderBlock)block
Declared In
RKObjectManager.h
putObject:delegate:
Update a remote mappable model by PUTing the attributes to the remote resource and loading the resulting objects from the payload
- (void)putObject:(id<NSObject>)object delegate:(id<RKObjectLoaderDelegate>)delegate
Declared In
RKObjectManager.h
putObject:usingBlock:
PUT a remote object instance and yield the object loader to the block before sending
- (void)putObject:(id<NSObject>)object usingBlock:(RKObjectLoaderBlock)block
Declared In
RKObjectManager.h
tableControllerForTableViewController:
Creates and returns a table controller object capable of loading remote object representations into a UITableView using the RestKit object mapping engine for a given table view controller.
- (RKTableController *)tableControllerForTableViewController:(UITableViewController *)tableViewController
Parameters
- tableViewController
A UITableViewController to instantiate a table controller for
Return Value
An RKTableController instance ready to drive the table view for the provided tableViewController.
Declared In
RKObjectManager+RKTableController.h
tableControllerWithTableView:forViewController:
Creates and returns a table controller object capable of loading remote object representations into a UITableView using the RestKit object mapping engine for a given table view and view controller.
- (RKTableController *)tableControllerWithTableView:(UITableView *)tableView forViewController:(UIViewController *)viewController
Parameters
- tableView
The UITableView object that table controller with acts as the delegate and data source for.
- viewController
The UIViewController that owns the specified tableView.
Return Value
An RKTableController instance ready to drive the table view for the provided tableViewController.
Declared In
RKObjectManager+RKTableController.h