10.2.5: AGSRequestOperation Class Reference
10.2.5
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Pages
AGSRequestOperation Class Reference

Description

This is a concurrent operation.

The request will be asynchronously kicked off from the thread that the operation was created on. The request will execute in the background. If the response size is above a certain threshold, then the operation may decide to parse the response in a child operation that it kicks off. Once the response has been parsed the action selectors will called from the thread that the operation was created on.

  • This class encapsulates the logic for accessing secured (token or basic) resources. Including refreshing a token if it has expired. It also has the ability to perform the parsing of the response in a child operation so that the main thread of the application is not bogged down.
  • This class, or a subclass thereof, is used by all the tasks execute requests across the wire.
  • This class, or a subclass thereof, is also used by most of the layers for retrieving images or tiles.
  • This class can be used directly, but you will probably use a subclass of it for getting back the response data in the format that you are looking for.
Since
1.0
Inheritance diagram for AGSRequestOperation:
AGSRunLoopOperation <AGSPausable> <AGSCancellable> <AGSCancellable> AGSImageDataRequestOperation AGSImageRequestOperation AGSJSONRequestOperation

Instance Methods

(void) - cancel
 
(void) - finishWithResult:
 
(id) - initWithRequest:
 
(id) - initWithURL:
 
(id) - initWithURL:queryParameters:
 
(id) - initWithURL:resource:queryParameters:
 
(id) - initWithURL:resource:queryParameters:doPOST:
 
(id) - initWithURL:resource:queryParameters:method:
 
(BOOL) - isCancelled
 
(BOOL) - isPaused
 
(void) - operationDidStart
 
(void) - operationWillFinish
 
(BOOL) - pause
 
(NSError *) - processError:
 
(id) - processResultData:
 
(void) - resume
 
(BOOL) - shouldProcessResultDataInBackground:
 
(BOOL) - supportsPause
 

Class Methods

(NSOperationQueue *) + sharedOperationQueue
 

Properties

SEL action
 
BOOL cancelSessionWhenOperationIsCancelled
 
AGSIdBlock completionHandler
 
AGSCredentialcredential
 
AGSCredentialCachecredentialCache
 
SEL errorAction
 
AGSErrorBlock errorHandler
 
AGSRequestHTTPMethod method
 
NSString * outputPath
 
BOOL post
 
void(^ progressHandler )(long long totalBytesDownloaded, long long totalBytesExpected)
 
NSDictionary * query
 
NSURLRequest * request
 
NSURLRequestCachePolicy requestCachePolicy
 
NSString * resource
 
NSURLResponse * response
 
id result
 
NSThread * runLoopThread
 
id< AGSSecuredResourcesecuredResource
 
NSString * sessionID
 
BOOL shouldCacheResponse
 
NSMutableDictionary * state
 
id target
 
NSTimeInterval timeoutInterval
 
long long totalBytesDownloaded
 
long long totalBytesExpected
 
NSURL * URL
 
NSDictionary * userHeaders
 
BOOL waitUntilActionSelectorIsDone
 

Method Documentation

- (void) cancel

Cancel the operation

Since
10.2
- (void) finishWithResult: (id)  result

A subclass should call finishWithError: when the operation is complete, passing the desired result. If an error ocurred, pass an NSError object and the errorAction selector will be called. Any other type of result will cause the action selector to be fired.

Note that this will call -operationWillFinish before returning.

Since
2.1
- (id) initWithRequest: (NSURLRequest *)  req

Initialize an AGSRequestOperation with the specified request.

Parameters
reqRequest to initialize the operation with.
Returns
Initialized AGSRequestOperation.
Since
1.0
- (id) initWithURL: (NSURL *)  url

Initialize an AGSRequestOperation with the specified url.

Parameters
urlURL to initialize the request operation.
Returns
Initialized AGSRequestOperation.
Since
1.0
- (id) initWithURL: (NSURL *)  url
queryParameters: (NSDictionary *)  query 

Initialize an AGSRequestOperation with the specified url and query parameters.

Parameters
urlURL to initialize the request operation.
queryQuery parameters to submit along with the request.
Returns
Initialized AGSRequestOperation.
Since
1.0
- (id) initWithURL: (NSURL *)  url
resource: (NSString *)  resource
queryParameters: (NSDictionary *)  query 

Initialize an AGSRequestOperation with the specified url, resource, and query parameters.

Parameters
urlURL to initialize the request operation.
resourceResource to access off of the url.
queryQuery parameters to submit along with the request to the resource.
Returns
Initialized AGSRequestOperation
Since
1.0
- (id) initWithURL: (NSURL *)  url
resource: (NSString *)  resource
queryParameters: (NSDictionary *)  query
doPOST: (BOOL)  post 

Designated initializer. Initialize an AGSRequestOperation with the specified url, resource, query parameters, and post flag.

Parameters
urlURL to initialize the request operation.
resourceResource to access off of the url.
queryQuery parameters to submit along with the request to the resource.
postPost flag to determine whether or not to use a GET or POST,
Returns
Initialized AGSRequestOperation
Since
1.0
Deprecated:
Deprecated at 10.2. Please use initWithURL:resource:queryParameters:method: instead.
- (id) initWithURL: (NSURL *)  url
resource: (NSString *)  resource
queryParameters: (NSDictionary *)  query
method: (AGSRequestHTTPMethod method 

Designated initializer. Initialize an AGSRequestOperation with the specified url, resource, query parameters, and post flag.

Parameters
urlURL to initialize the request operation.
resourceResource to access off of the url.
queryQuery parameters to submit along with the request to the resource.
methodThe method by which the request will be made.
Returns
Initialized AGSRequestOperation
Since
10.2
- (BOOL) isCancelled

Indicates whether the operation has been cancelled

Since
10.2
- (BOOL) isPaused

Indicates whether the job or operation is paused.

Since
10.2.3
- (void) operationDidStart

A function that can be overridden by subclasses to start actual operation work.

Since
2.1
- (void) operationWillFinish

A function that can be overridden by subclasses to know when the operation was finished. This may get called even if operationDidStart was never called.

Since
2.1
- (BOOL) pause

Pause the job or operation. Returns YES if it isPaused is YES after calling this. If the job/operation is in a state where it cannot be paused, it will return NO. For example if the job/operation is cancelled it may return YES for supportsPause, but for example you can't pause it if it's cancelled or done. If supportsPause is NO, this method also returns NO.

Since
10.2.3
- (NSError *) processError: (NSError *)  error

Method to override to process the error that results, if any, from a request

Since
1.0
- (id) processResultData: (NSData *)  data

Methods to override to process results and errors before sending them to the callbacks

Parameters
datato be processed from the request
Since
1.0
- (void) resume

Resumes a job or operation after it's been paused. Only valid to be called when isPaused is YES.

Since
10.2.3
+ (NSOperationQueue *) sharedOperationQueue

Class method to retrieve the shared operation queue that is handling all operations. This is where all AGSRequestOperations will be queued.

Since
1.0
- (BOOL) shouldProcessResultDataInBackground: (NSData *)  data

Subclasses can override this if processing the data will take a long time and the superclass should call the process method on a bg thread.

Parameters
datato be processed in the background
Since
1.0
- (BOOL) supportsPause

Some jobs/operations may conform to this protocol, but depending on how they were set up or what they are doing they may not support pausing. For example AGSRequestOperations supports pause if they are downloading a file, but only on certain operating systems that support it (ie, at least iOS 7.0). One use case for this method is if you only wanted to show a pause button when you are using an operation that supports pause.

Since
10.2.3

Property Documentation

- (SEL) action
readwritenonatomicassigninherited

Selector to be called if the operation succeeds. The method must accept two parameters. The first parameter will be an instance of this class, the second will be the result. The result will of type NSDictionary for json, AGSImage for image, and NSData for anything else.

An example of a selector is (operation:didSucceedWithResponse:) The corresponding method signature would be -(void) operation:(NSOperation*)op didSucceedWithResponse:(id)result

Since
2.1
See also
completionHandler for block-based alternative
- (BOOL) cancelSessionWhenOperationIsCancelled
readwritenonatomicassign

Defaults to YES. Specifies whether or not the download session used to download the file is cancelled when the operation is cancelled. Otherwise the session stays in the state that it was in. The value of occasionally being able to set this to NO is that you can cancel the operation, which is taking the spot in the queue and have the download continue out of process, or remain paused, if you wish.

Since
10.2.3
- (AGSIdBlock) completionHandler
readwritenonatomiccopyinherited

Completion handler that will be called when the operation is completed successfully. This handler will only be called when a target is not specified. The AGSIdBlock is called with an object of type id passed as the parameter.

Since
2.3
- (AGSCredential*) credential
readwritenonatomicstrong

Credentials to access a secured resource.

Since
1.0
- (AGSCredentialCache*) credentialCache
readwritenonatomicstrong

Credential cache used to access a secured resources.

Since
10.1.1
- (SEL) errorAction
readwritenonatomicassigninherited

Selector to be called if the operation fails.The method must accept two parameters. The first parameter will be an instance of this class, the second will be the error.

An example of a selector is (operation:didFailWithError:) The corresponding method signature would be -(void) operation:(NSOperation*)op didFailWithError:(NSError*)error

Since
2.1
See also
errorHandler for block-based alternative
- (AGSErrorBlock) errorHandler
readwritenonatomiccopyinherited

Error handler that will be called when an error is returned by the operation. This handler will only be called when a target is not specified. The AGSErrorBlock is called with an object of type NSError passed as the parameter.

Since
2.3
- (AGSRequestHTTPMethod) method
readatomicassign

Flag to determine whether or not the request is a GET or a POST and if it is a post how it's parameters are encoded.

Since
10.2
- (NSString*) outputPath
readwritenonatomicstrong

If this is set then the data is saved to this file as it is retrieved.

Since
10.2
- (BOOL) post
readatomicassign

Flag to determine whether or not the request is a GET or POST.

Since
1.0
Deprecated:
Deprecated at 10.2. use AGSRequestOperation::method instead.
- (void(^ progressHandler)(long long totalBytesDownloaded, long long totalBytesExpected))
readwritenonatomiccopy

If provided, the operation will call this block with the progress of the request. If the content length is unknown or not specified in the request, totalBytesExpected will return -1.

Since
10.2.2
- (NSDictionary*) query
readatomiccopy

Query parameters to be used in the request to URL.

Since
1.0
- (NSURLRequest*) request
readatomicstrong

Request object to be used instead of generating one on the fly.

Since
1.0
- (NSURLRequestCachePolicy) requestCachePolicy
readwritenonatomicassign

The cache policy that should be used for making the web request. Default value is NSURLRequestUseProtocolCachePolicy

Since
10.1.1
- (NSString*) resource
readatomiccopy

String to append to the end of a url to access a specific resource, such as when exporting an image.

Since
1.0
- (NSURLResponse*) response
readnonatomicstrong

The response of the request.

Since
2.2
- (id) result
readnonatomicstronginherited

The results of an operation. It will be of type NSDictionary when the result is json, AGSImage when the result is an image, and NSData when anything else.

Since
2.1
- (NSThread*) runLoopThread
readwritenonatomicstronginherited

The thread that this concurrent operation should start it's work on. This can only be set before the operation starts executing. After that, setting it will be ignored.

Since
2.1
- (id<AGSSecuredResource>) securedResource
readwritenonatomicweak

The secure resource, if applicable, that is making the request.

Since
10.1.1
- (NSString*) sessionID
readwritenonatomiccopy

If provided, the operation will use NSURLSession to allow for downloading in the background. This requires that outputPath is also specified. NOTE: This has a runtime requirement of iOS 7/OS X 10.9

Since
10.2.2
- (BOOL) shouldCacheResponse
readwritenonatomicassign

Whether the response should be cached. Default is YES

Since
10.1.1
- (NSMutableDictionary*) state
readnonatomicstrong

A dictionary that can be filled with objects that need to be retrieved upon completion of an operation and are not passed back as results.

Since
1.0
- (id) target
readwritenonatomicweakinherited

Target class to perform the operation from.

Since
2.1
- (NSTimeInterval) timeoutInterval
readwritenonatomicassign

The timeout interval (in seconds) for this request. Default value is 60.

Since
10.1.1
- (long long) totalBytesDownloaded
readnonatomicassign

The number of bytes currently downloaded for this request.

Since
10.2.2
- (long long) totalBytesExpected
readnonatomicassign

The total number of bytes expected to be downloaded. Will be -1 if unknown.

Since
10.2.2
- (NSURL*) URL
readatomiccopy

URL of the resource to make a request from.

Since
1.0
- (NSDictionary*) userHeaders
readwritenonatomiccopy

Any custom headers you would like to set on the request with the exception of User-Agent, Referer, and Content-Type. If you need to add info to the User-Agent header use setAdditionalUserAgentInfo: (AGSRequest) .

Since
10.2
- (BOOL) waitUntilActionSelectorIsDone
readwritenonatomicassigninherited

Defaults to NO, but it is helpful if this operation is a dependency for another operation and the action selector processes some results that the dependent operation needs before it can start.

Since
2.1