kylefang/RestKit
1
0
Fork 0
mirror of https://github.com/zhigang1992/RestKit.git synced 2026-04-24 04:46:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

Touch up docs for batched object request operations

Browse Source
This commit is contained in:
Blake Watters
2012-09-30 19:29:51 -04:00
parent 8c34f0996b
commit 2280674f5a
5 changed files with 72 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
Code/Network/RKObjectManager.h
View File

@@ -406,23 +406,24 @@ RKMappingResult, RKRequestDescriptor, RKResponseDescriptor;
*/
- (void)cancelAllObjectRequestOperationsWithMethod:(RKRequestMethod)method matchingPathPattern:(NSString *)pathPattern;
///--------------------------------------------------
/// @name Managing Batches of Enqueued Object Request Operations
///--------------------------------------------------
///-----------------------------------------
/// @name Batching Object Request Operations
///-----------------------------------------
/**
Enqueues a set of `RKObjectRequestOperation`, derived from the provided RKRoute and objects, to the object manager's operation queue.
Creates and enqueues an `RKObjectRequestOperation` to the object manager's operation queue for each specified object into a batch. Each object request operation is built by evaluating the object against the given route to construct a request path and then invoking `appropriateObjectRequestOperationWithObject:method:path:parameters:`. When each object request operation finishes, the specified progress block is executed, until all of the request operations have finished, at which point the completion block also executes.
@param route The RKRoute to apply to all provided objects.
@param objects The set of objects that should be turned into operations using the provided route.
@param route The route specifying the request method and the path pattern with which to construct the request for each object object request operation in the batch.
@param objects The set of objects for which to enqueue a batch of object request operations.
@param progress A block object to be executed when an object request operation completes. This block has no return value and takes two arguments: the number of finished operations and the total number of operations initially executed.
@param completion A block object to be executed when the object request operations complete. This block has no return value and takes one argument: the list of operations executed.
@see [RKObjectManager enqueueBatchOfObjectRequestOperations:progress:completion]
@see `[RKObjectManager enqueueBatchOfObjectRequestOperations:progress:completion]`
*/
- (void)enqueueBatchOfObjectRequestOperationsWithRoute:(RKRoute *)route
objects:(NSArray *)objects
progress:(void (^)(NSUInteger numberOfFinishedOperations, NSUInteger totalNumberOfOperations))progress
progress:(void (^)(NSUInteger numberOfFinishedOperations,
NSUInteger totalNumberOfOperations))progress
completion:(void (^)(NSArray *operations))completion;
/**
@@ -434,7 +435,8 @@ RKMappingResult, RKRequestDescriptor, RKResponseDescriptor;
*/
- (void)enqueueBatchOfObjectRequestOperations:(NSArray *)operations
progress:(void (^)(NSUInteger numberOfFinishedOperations, NSUInteger totalNumberOfOperations))progress
progress:(void (^)(NSUInteger numberOfFinishedOperations,
NSUInteger totalNumberOfOperations))progress
completion:(void (^)(NSArray *operations))completion;
///-------------------------------------

9
Code/Network/RKObjectManager.m
View File

@@ -517,17 +517,18 @@ static BOOL RKDoesArrayOfResponseDescriptorsContainEntityMapping(NSArray *respon
- (void)enqueueBatchOfObjectRequestOperationsWithRoute:(RKRoute *)route
objects:(NSArray *)objects
progress:(void (^)(NSUInteger numberOfFinishedOperations, NSUInteger totalNumberOfOperations))progress
progress:(void (^)(NSUInteger numberOfFinishedOperations,
NSUInteger totalNumberOfOperations))progress
completion:(void (^)(NSArray *operations))completion {
NSMutableArray *operations = [[NSMutableArray alloc] initWithCapacity:objects.count];
for (id object in objects) {
RKObjectRequestOperation *operation = nil;
NSURL *URL = [self.router URLForRoute:route object:object];
NSURL *URL = [self.router URLWithRoute:route object:object];
NSAssert(URL, @"Failed to generate URL for route %@ with object %@", route, object);
if ([route isClassRoute]) {
operation = [self appropriateObjectRequestOperationWithObject:object method:RKRequestMethodGET path:[URL relativeString] parameters:nil];
operation = [self appropriateObjectRequestOperationWithObject:object method:route.method path:[URL relativeString] parameters:nil];
} else {
operation = [self appropriateObjectRequestOperationWithObject:nil method:RKRequestMethodGET path:[URL relativeString] parameters:nil];
operation = [self appropriateObjectRequestOperationWithObject:nil method:route.method path:[URL relativeString] parameters:nil];
}
[operations addObject:operation];
}

1
Code/Network/RKRoute.m
View File

@@ -38,7 +38,6 @@
@implementation RKRoute
+ (id)routeWithName:(NSString *)name pathPattern:(NSString *)pathPattern method:(RKRequestMethod)method
{
NSParameterAssert(name);

80
Code/Network/RKRouter.h
View File

@@ -23,9 +23,6 @@
@class RKRouteSet;
@class RKRoute;
void RKAssociateBaseURLWithURL(NSURL *baseURL, NSURL *URL);
NSURL *RKBaseURLAssociatedWithURL(NSURL *URL);
/**
An `RKRouter` instance is responsible for generating `NSURL` objects with a given base URL and a route set. It is used to centralize the knowledge about the URL's that are used by the application.
@@ -61,56 +58,46 @@ NSURL *RKBaseURLAssociatedWithURL(NSURL *URL);
/**
Generates a URL for the route with the given name.
The route set is searched for a route with the given name and a new `NSURL` object is instantiated
with the baseURL of the receiver and the path pattern of the route, optionally interpolated
with a given object. If a pointer to an `RKRequestMethod` variable is provided, the HTTP method
for the route will be assigned to the reference.
The route set is searched for a route with the given name and a new `NSURL` object is instantiated with the baseURL of the receiver and the path pattern of the route, optionally interpolated with a given object. If a pointer to an `RKRequestMethod` variable is provided, the HTTP method for the route will be assigned to the reference.
@param routeName The name of the route for which a URL is to be generated.
@param method A pointer to an `RKRequestMethod` variable in which to store the HTTP method associated
with the named route. May be nil.
@param method A pointer to an `RKRequestMethod` variable in which to store the HTTP method associated with the named route. May be nil.
@param object An optional object against which to interpolate the path pattern.
@return A new `NSURL` object constructed by appending the path pattern to the baseURL of the
receiver and interpolating against a given object; or nil if no route was found with the given
name.
@return A new `NSURL` object constructed by appending the path pattern to the baseURL of the receiver and interpolating against a given object; or nil if no route was found with the given name.
*/
- (NSURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method object:(id)object;
/**
Generates a URL for a given object and HTTP method.
The route set is searched for a route that matches the HTTP method and class of
the object being routed. If there is not an exact match for the object's class, the inheritance
hierarchy is searched until a match is found or all possible routes are exhausted. Exact HTTP request
matches are favored over the wildcard method (`RKRequestMethodAny`). Once the appropriate route is identified,
a new `NSURL` object is instantiated with the baseURL of the receiver and the path pattern of the route,
interpolated against the object being routed.
The route set is searched for a route that matches the HTTP method and class of the object being routed. If there is not an exact match for the object's class, the inheritance hierarchy is searched until a match is found or all possible routes are exhausted. Exact HTTP request matches are favored over the wildcard method (`RKRequestMethodAny`). Once the appropriate route is identified, a new `NSURL` object is instantiated with the baseURL of the receiver and the path pattern of the route, interpolated against the object being routed.
@param object The object for which a URL is to be generated.
@param method The HTTP method for which the URL is to be generated.
@return A new URL object constructed by appending the path pattern of the route for the object and
HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no route was found
for the given object and HTTP method.
@return A new URL object constructed by appending the path pattern of the route for the object an HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no route was found for the given object and HTTP method.
*/
- (NSURL *)URLForObject:(id)object method:(RKRequestMethod)method;
/**
Generates a URL for a relationship of a given object with a given HTTP method.
The route set is searched for a route that matches the relationship of the given object's class and the given
HTTP method. If a matching route is found, a new `NSURL` object is instantiated with the baseURL of the receiver
and the path pattern of the route, interpolated against the object being routed.
The route set is searched for a route that matches the relationship of the given object's class and the given HTTP method. If a matching route is found, a new `NSURL` object is instantiated with the baseURL of the receiver and the path pattern of the route, interpolated against the object being routed.
@param relationshipName The name of the relationship for which a URL is to be generated.
@param object The object for which the URL is to be generated.
@param method The HTTP method for which the URL is to be generated.
@return A new URL object constructed by appending the path pattern of the route for the given object's
relationship and HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no
route was found for the given relationship, object and HTTP method.
@return A new URL object constructed by appending the path pattern of the route for the given object's relationship and HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no route was found for the given relationship, object and HTTP method.
*/
- (NSURL *)URLForRelationship:(NSString *)relationshipName ofObject:(id)object method:(RKRequestMethod)method;
- (NSURL *)URLForRoute:(RKRoute *)route object:(id)object;
/**
Generates a URL with a given route and object.
@param route The route to generate the URL with.
@param object The object with which to interpolate the path pattern of the given route.
@return A new URL object constructed by interpolating the path pattern of the given route with the given object to construct a path and constructing an `NSURL` object relative to the `baseURL` of the receiver.
*/
- (NSURL *)URLWithRoute:(RKRoute *)route object:(id)object;
///---------------------------------------------
/// @name Configuring the Base URL and Route Set
@@ -127,3 +114,40 @@ NSURL *RKBaseURLAssociatedWithURL(NSURL *URL);
@property (nonatomic, strong, readonly) RKRouteSet *routeSet;
@end
///----------------
/// @name Functions
///----------------
/**
## An Important Note about Base URL's Containing a Path
When a `NSURL` object that was created relative to another URL via `[NSURL URLWithString:relativeToURL:` is used to create an `NSURLRequest`, the `URL` property of the request object is no longer relative to the original base URL. The `relativeString` and `relativePath` methods will return the complete URL path, rather than the expected relative path. This presents a problem for applications in which the `baseURL` contains a path (i.e. the `baseURL` is a value such as 'http://restkit.org/api/v1'), as path patterns used in routing and response descriptors will unexpectedly return the complete path, rather than the relative portion.
To work around this issue, RestKit provides baseURL association functions that can be used to associate a base URL with the URL of a `NSURLRequest` object. The `RKResponseMapperOperation` class is aware of this associated object and will attempt to use it when evaluating response descriptors.
@see `RKRouter`
@see `RKObjectManager`
@see `RKResponseDescriptor`
@see `RKResponseMapperOperation`
*/
//--------------------------------------
/// @name Base URL Association Functions
//--------------------------------------
/**
Associates a base URL with a given URL.
@param baseURL The base URL to associate with another URL.
@param URL The URL that is associated with the base URL.
*/
void RKAssociateBaseURLWithURL(NSURL *baseURL, NSURL *URL);
/**
Retrieves the base URL associated with the given URL.
@param URL The URL to retrieve the associated base URL for.
@return The base URL associated with the given URL.
*/
NSURL *RKBaseURLAssociatedWithURL(NSURL *URL);

13
Code/Network/RKRouter.m
View File

@@ -24,7 +24,6 @@
#import "RKPathMatcher.h"
#import <objc/runtime.h>
@interface RKRouter ()
@property (nonatomic, strong, readwrite) NSURL *baseURL;
@property (nonatomic, strong, readwrite) RKRouteSet *routeSet;
@@ -73,29 +72,25 @@ NSURL *RKBaseURLAssociatedWithURL(NSURL *URL)
{
RKRoute *route = [self.routeSet routeForName:routeName];
if (method) *method = route.method;
return [self URLForRoute:route object:object];
return [self URLWithRoute:route object:object];
}
- (NSURL *)URLForObject:(id)object method:(RKRequestMethod)method
{
RKRoute *route = [self.routeSet routeForObject:object method:method];
return [self URLForRoute:route object:object];
return [self URLWithRoute:route object:object];
}
- (NSURL *)URLForRelationship:(NSString *)relationshipName ofObject:(id)object method:(RKRequestMethod)method
{
RKRoute *route = [self.routeSet routeForRelationship:relationshipName ofClass:[object class] method:method];
return [self URLForRoute:route object:object];
return [self URLWithRoute:route object:object];
}
- (NSURL *)URLForRoute:(RKRoute *)route object:(id)object
- (NSURL *)URLWithRoute:(RKRoute *)route object:(id)object
{
NSParameterAssert(route);
NSURL *URL = [NSURL URLWithString:[self pathFromRoute:route forObject:object] relativeToURL:self.baseURL];
/**
Associate our baseURL with the URL of the `NSURLRequest` object. This enables us to match response descriptors by path.
*/
RKAssociateBaseURLWithURL(self.baseURL, URL);
return URL;
}