mirror of
https://github.com/zhigang1992/RestKit.git
synced 2026-04-23 20:31:13 +08:00
Clean up documentation and organize RKRequestQueue and RKRequestQueueDelegate header and implementation.
* Add appledoc section headers and reorganize methods/properties to fit into the sections. * Fill in missing documentation, parameter definitions, and return values. * Fix documentation formatting, styling, and placement. * Remove appledoc signficant asterisk in implementation comment.
This commit is contained in:
Brian Morton
@@ -24,218 +24,331 @@
|
||||
@protocol RKRequestQueueDelegate;
|
||||
|
||||
/**
|
||||
* A lightweight queue implementation responsible
|
||||
* for dispatching and managing RKRequest objects
|
||||
A lightweight queue implementation responsible for dispatching and managing
|
||||
RKRequest objects.
|
||||
*/
|
||||
@interface RKRequestQueue : NSObject {
|
||||
NSString *_name;
|
||||
NSMutableArray *_requests;
|
||||
NSMutableArray *_requests;
|
||||
NSObject<RKRequestQueueDelegate> *_delegate;
|
||||
NSUInteger _loadingCount;
|
||||
NSUInteger _loadingCount;
|
||||
NSUInteger _concurrentRequestsLimit;
|
||||
NSUInteger _requestTimeout;
|
||||
NSTimer *_queueTimer;
|
||||
BOOL _suspended;
|
||||
NSUInteger _requestTimeout;
|
||||
NSTimer *_queueTimer;
|
||||
BOOL _suspended;
|
||||
BOOL _showsNetworkActivityIndicatorWhenBusy;
|
||||
}
|
||||
|
||||
/**
|
||||
A symbolic name for the queue. Used to return existing queue references
|
||||
via [RKRequestQueue queueWithName:]
|
||||
*/
|
||||
@property (nonatomic, retain, readonly) NSString *name;
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Creating a Request Queue
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* The delegate to inform when the request queue state machine changes
|
||||
*
|
||||
* If the object implements the RKRequestQueueDelegate protocol,
|
||||
* it will receive request lifecycle event messages.
|
||||
*/
|
||||
@property(nonatomic, assign) id<RKRequestQueueDelegate> delegate;
|
||||
|
||||
/**
|
||||
* The number of concurrent requests supported by this queue
|
||||
* Defaults to 5
|
||||
*/
|
||||
@property (nonatomic) NSUInteger concurrentRequestsLimit;
|
||||
|
||||
/**
|
||||
* Request timeout value used by the queue
|
||||
* Defaults to 5 minutes (300 seconds)
|
||||
*/
|
||||
@property (nonatomic, assign) NSUInteger requestTimeout;
|
||||
|
||||
/**
|
||||
* Gets the flag that determines if new load requests are allowed to reach the network.
|
||||
*
|
||||
* Because network requests tend to slow down performance, this property can be used to
|
||||
* temporarily delay them. All requests made while suspended are queued, and when
|
||||
* suspended becomes false again they are executed.
|
||||
*/
|
||||
@property (nonatomic) BOOL suspended;
|
||||
|
||||
/**
|
||||
* Returns the total number of requests that are currently loading
|
||||
*/
|
||||
@property (nonatomic, readonly) NSUInteger loadingCount;
|
||||
|
||||
/**
|
||||
* Returns the number of requests in the queue
|
||||
*/
|
||||
@property (nonatomic, readonly) NSUInteger count;
|
||||
|
||||
#if TARGET_OS_IPHONE
|
||||
/**
|
||||
* When YES, this queue will spin the network activity in the menu bar when it is processing
|
||||
* requests
|
||||
*
|
||||
* *Default*: NO
|
||||
*/
|
||||
@property (nonatomic) BOOL showsNetworkActivityIndicatorWhenBusy;
|
||||
#endif
|
||||
|
||||
/**
|
||||
Return the global queue
|
||||
Creates and returns a new request queue.
|
||||
|
||||
Deprecated. All RKClient instances now own their own individual request queues.
|
||||
|
||||
@see [RKClient requestQueue]
|
||||
*/
|
||||
+ (RKRequestQueue *)sharedQueue DEPRECATED_ATTRIBUTE;
|
||||
|
||||
/**
|
||||
Set the global queue
|
||||
|
||||
Deprecated. All RKClient instances now own their own individual request queues.
|
||||
|
||||
@see [RKClient requestQueue]
|
||||
*/
|
||||
+ (void)setSharedQueue:(RKRequestQueue *)requestQueue DEPRECATED_ATTRIBUTE;
|
||||
|
||||
/**
|
||||
Returns a new auto-released request queue
|
||||
@return An autoreleased RKRequestQueue object.
|
||||
*/
|
||||
+ (id)requestQueue;
|
||||
|
||||
/**
|
||||
Returns a new retained request queue with the given name. If there is already
|
||||
an existing queue with the given name, nil will be returned.
|
||||
|
||||
@param name A symbolic name for the queue.
|
||||
@return A new retained RKRequestQueue with the given name or nil if one already
|
||||
exists with the given name.
|
||||
*/
|
||||
+ (id)newRequestQueueWithName:(NSString *)name;
|
||||
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Retrieving an Existing Queue
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
Returns queue with the specified name. If no queue is found with
|
||||
the name provided, a new queue will be initialized and returned.
|
||||
Returns queue with the specified name. If no queue is found with the name
|
||||
provided, a new queue will be initialized and returned.
|
||||
|
||||
@param name A symbolic name for the queue.
|
||||
@return An existing RKRequestQueue with the given name or a new queue if none
|
||||
currently exist.
|
||||
*/
|
||||
+ (id)requestQueueWithName:(NSString *)name;
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Naming Queues
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
Returns YES when there is a queue with the given name
|
||||
A symbolic name for the queue.
|
||||
|
||||
Used to return existing queue references via
|
||||
[RKRequestQueue requestQueueWithName:]
|
||||
*/
|
||||
@property (nonatomic, retain, readonly) NSString *name;
|
||||
|
||||
/**
|
||||
Determine if a queue exists with a given name.
|
||||
|
||||
@param name The queue name to search against.
|
||||
@return YES when there is a queue with the given name.
|
||||
*/
|
||||
+ (BOOL)requestQueueExistsWithName:(NSString *)name;
|
||||
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Monitoring State Changes
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Add an asynchronous request to the queue and send it as
|
||||
* as soon as possible
|
||||
The delegate to inform when the request queue state machine changes.
|
||||
|
||||
If the object implements the RKRequestQueueDelegate protocol, it will receive
|
||||
request lifecycle event messages.
|
||||
*/
|
||||
@property (nonatomic, assign) id<RKRequestQueueDelegate> delegate;
|
||||
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Managing the Queue
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
The number of concurrent requests supported by this queue.
|
||||
|
||||
**Default**: 5 concurrent requests
|
||||
*/
|
||||
@property (nonatomic) NSUInteger concurrentRequestsLimit;
|
||||
|
||||
/**
|
||||
Request timeout value used by the queue.
|
||||
|
||||
**Default**: 5 minutes (300 seconds)
|
||||
*/
|
||||
@property (nonatomic, assign) NSUInteger requestTimeout;
|
||||
|
||||
/**
|
||||
Returns the total number of requests in the queue.
|
||||
*/
|
||||
@property (nonatomic, readonly) NSUInteger count;
|
||||
|
||||
/**
|
||||
Add an asynchronous request to the queue and send it as as soon as possible.
|
||||
|
||||
@param request The request to be added to the queue.
|
||||
*/
|
||||
- (void)addRequest:(RKRequest *)request;
|
||||
|
||||
/**
|
||||
* Cancel a request that is in progress
|
||||
Cancel a request that is in progress.
|
||||
|
||||
@param request The request to be cancelled.
|
||||
*/
|
||||
- (void)cancelRequest:(RKRequest *)request;
|
||||
|
||||
/**
|
||||
* Cancel all requests with a given delegate
|
||||
Cancel all requests with a given delegate.
|
||||
|
||||
@param delegate The delegate assigned to the requests to be cancelled.
|
||||
*/
|
||||
- (void)cancelRequestsWithDelegate:(NSObject<RKRequestDelegate> *)delegate;
|
||||
|
||||
/**
|
||||
* Cancel all active or pending requests.
|
||||
Cancel all active or pending requests.
|
||||
*/
|
||||
- (void)cancelAllRequests;
|
||||
|
||||
/**
|
||||
* Start checking for and processing requests
|
||||
Determine if a given request is currently in this queue.
|
||||
|
||||
@param request The request to check the queue for.
|
||||
@return YES if the specified request is in this queue.
|
||||
*/
|
||||
- (BOOL)containsRequest:(RKRequest *)request;
|
||||
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Processing Queued Requests
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
Start checking for and processing requests.
|
||||
*/
|
||||
- (void)start;
|
||||
|
||||
/**
|
||||
* Returns YES if the specified request is in this queue
|
||||
Sets the flag that determines if new load requests are allowed to reach the
|
||||
network.
|
||||
|
||||
Because network requests tend to slow down performance, this property can be
|
||||
used to temporarily delay them. All requests made while suspended are queued,
|
||||
and when suspended becomes false again they are executed.
|
||||
*/
|
||||
- (BOOL)containsRequest:(RKRequest *)request;
|
||||
@property (nonatomic) BOOL suspended;
|
||||
|
||||
/**
|
||||
Returns the total number of requests that are currently loading.
|
||||
*/
|
||||
@property (nonatomic, readonly) NSUInteger loadingCount;
|
||||
|
||||
#if TARGET_OS_IPHONE
|
||||
/**
|
||||
Sets the flag for showing the network activity indicatory.
|
||||
|
||||
When YES, this queue will spin the network activity in the menu bar when it is
|
||||
processing requests.
|
||||
|
||||
**Default**: NO
|
||||
*/
|
||||
@property (nonatomic) BOOL showsNetworkActivityIndicatorWhenBusy;
|
||||
#endif
|
||||
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Global Queues (Deprecated)
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
Returns the global queue
|
||||
|
||||
@bug **DEPRECATED** in v0.9.4: All RKClient instances now own their own
|
||||
individual request queues.
|
||||
|
||||
@see [RKClient requestQueue]
|
||||
@return Global request queue.
|
||||
*/
|
||||
+ (RKRequestQueue *)sharedQueue DEPRECATED_ATTRIBUTE;
|
||||
|
||||
/**
|
||||
Sets the global queue
|
||||
|
||||
@bug **DEPRECATED** in v0.9.4: All RKClient instances now own their own
|
||||
individual request queues.
|
||||
|
||||
@see [RKClient requestQueue]
|
||||
@param requestQueue The request queue to assign as the global queue.
|
||||
*/
|
||||
+ (void)setSharedQueue:(RKRequestQueue *)requestQueue DEPRECATED_ATTRIBUTE;
|
||||
|
||||
@end
|
||||
|
||||
|
||||
/**
|
||||
* Lifecycle events for RKRequestQueue
|
||||
*
|
||||
Lifecycle events for an RKRequestQueue
|
||||
*/
|
||||
@protocol RKRequestQueueDelegate <NSObject>
|
||||
@optional
|
||||
|
||||
/**
|
||||
* Sent when the queue has been suspended and request processing has been halted
|
||||
*/
|
||||
- (void)requestQueueWasSuspended:(RKRequestQueue *)queue;
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Starting and Stopping the Queue
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Sent when the queue has been unsuspended and request processing has resumed
|
||||
*/
|
||||
- (void)requestQueueWasUnsuspended:(RKRequestQueue *)queue;
|
||||
|
||||
/**
|
||||
* Sent when the queue transitions from an empty state to processing requests
|
||||
Sent when the queue transitions from an empty state to processing requests.
|
||||
|
||||
@param queue The queue that began processing requests.
|
||||
*/
|
||||
- (void)requestQueueDidBeginLoading:(RKRequestQueue *)queue;
|
||||
|
||||
/**
|
||||
* Sent when queue transitions from a processing state to an empty start
|
||||
Sent when queue transitions from a processing state to an empty start.
|
||||
|
||||
@param queue The queue that finished processing requests.
|
||||
*/
|
||||
- (void)requestQueueDidFinishLoading:(RKRequestQueue *)queue;
|
||||
|
||||
/**
|
||||
* Sent before queue sends a request
|
||||
Sent when the queue has been suspended and request processing has been halted.
|
||||
|
||||
@param queue The request queue that has been suspended.
|
||||
*/
|
||||
- (void)requestQueueWasSuspended:(RKRequestQueue *)queue;
|
||||
|
||||
/**
|
||||
Sent when the queue has been unsuspended and request processing has resumed.
|
||||
|
||||
@param queue The request queue that has resumed processing.
|
||||
*/
|
||||
- (void)requestQueueWasUnsuspended:(RKRequestQueue *)queue;
|
||||
|
||||
|
||||
///-----------------------------------------------------------------------------
|
||||
/// @name Processing Requests
|
||||
///-----------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
Sent before queue sends a request.
|
||||
|
||||
@param queue The queue that will process the request.
|
||||
@param request The request to be processed.
|
||||
*/
|
||||
- (void)requestQueue:(RKRequestQueue *)queue willSendRequest:(RKRequest *)request;
|
||||
|
||||
/**
|
||||
* Sent after queue has sent a request
|
||||
Sent after queue has sent a request.
|
||||
|
||||
@param queue The queue that processed the request.
|
||||
@param request The processed request.
|
||||
*/
|
||||
- (void)requestQueue:(RKRequestQueue *)queue didSendRequest:(RKRequest *)request;
|
||||
|
||||
/**
|
||||
* Sent when queue received a response for a request
|
||||
Sent when queue received a response for a request.
|
||||
|
||||
@param queue The queue that received the response.
|
||||
@param response The response that was received.
|
||||
*/
|
||||
- (void)requestQueue:(RKRequestQueue *)queue didLoadResponse:(RKResponse *)response;
|
||||
|
||||
/**
|
||||
* Sent when queue has canceled a request
|
||||
Sent when queue has canceled a request.
|
||||
|
||||
@param queue The queue that cancelled the request.
|
||||
@param request The cancelled request.
|
||||
*/
|
||||
- (void)requestQueue:(RKRequestQueue *)queue didCancelRequest:(RKRequest *)request;
|
||||
|
||||
/**
|
||||
* Sent when an attempted request fails
|
||||
Sent when an attempted request fails.
|
||||
|
||||
@param queue The queue in which the request failed from.
|
||||
@param request The failed request.
|
||||
@param error An NSError object containing the RKRestKitError that caused the
|
||||
request to fail.
|
||||
*/
|
||||
- (void)requestQueue:(RKRequestQueue *)queue didFailRequest:(RKRequest *)request withError:(NSError *)error;
|
||||
|
||||
@end
|
||||
|
||||
/**
|
||||
* A category on UIApplication to allow for jointly managing of network activity indicator.
|
||||
* Adopted from 'iOS Recipes' book: http://pragprog.com/book/cdirec/ios-recipes
|
||||
*/
|
||||
|
||||
#if TARGET_OS_IPHONE
|
||||
|
||||
/**
|
||||
A category on UIApplication to allow for jointly managing the network activity
|
||||
indicator.
|
||||
|
||||
Adopted from 'iOS Recipes' book: http://pragprog.com/book/cdirec/ios-recipes
|
||||
*/
|
||||
@interface UIApplication (RKNetworkActivity)
|
||||
|
||||
/**
|
||||
Returns the number of network activity requests.
|
||||
*/
|
||||
@property (nonatomic, assign, readonly) NSInteger networkActivityCount;
|
||||
|
||||
/**
|
||||
Push a network activity request onto the stack.
|
||||
*/
|
||||
- (void)pushNetworkActivity;
|
||||
|
||||
/**
|
||||
Pop a network activity request off the stack.
|
||||
*/
|
||||
- (void)popNetworkActivity;
|
||||
|
||||
/**
|
||||
Reset the network activity stack.
|
||||
*/
|
||||
- (void)resetNetworkActivity;
|
||||
|
||||
@end
|
||||
|
||||
#endif
|
||||
|
||||
@@ -435,9 +435,9 @@ static const NSTimeInterval kFlushDelay = 0.3;
|
||||
[self setSuspended:NO];
|
||||
}
|
||||
|
||||
/**
|
||||
* Invoked via observation when a request has loaded a response or failed with an error. Remove
|
||||
* the completed request from the queue and continue processing
|
||||
/*
|
||||
Invoked via observation when a request has loaded a response or failed with an
|
||||
error. Remove the completed request from the queue and continue processing
|
||||
*/
|
||||
- (void)requestFinishedWithNotification:(NSNotification*)notification {
|
||||
NSAssert([notification.object isKindOfClass:[RKRequest class]], @"Notification expected to contain an RKRequest, got a %@", NSStringFromClass([notification.object class]));
|
||||
|
||||
Reference in New Issue
Block a user