ROAsyncRequest
Overview
ROAsyncRequest objects present an ongoing or completed asynchronous request that is executing after one of the begin* messages is set to an Asynchronous Proxy. The ROAsyncRequest can be used to check the status of the request, assign a delegate (of type ROAsyncRequestDelegate to be informed of progress, success and failures. It also needs to be referenced when sending the end* message to receive any result or outgoing parameters, after the request has completed.
The asynchronous proxies provide overloads of the begin* methods that take a BOOL start parameter. When passing in YES, they will return a request that is already started, as do the overloads without this start parameter. When passing in NO, the returned ROAsyncRequest has not been started yet and can be started by sending a start or startInBackground message.
Please also refer to Asynchronous Requests for a more general overview of asynchronous requests.
This class is considered abstract and defines the common interface to interact with asynchronous request object. Every client channel is accompanied with a concrete ROAsyncRequest descendant to use with a corresponding channel class.
Location
- Reference: ROAsyncRequest.h
- Namespace: RemObjectsSDK
- Ancestry: NSObject | ROAsyncRequest
backgroundTasksEnabled
Returns YES if OS supports background tasks, NO othervise.
+ (BOOL) backgroundTasksEnabled
cancel
Aborts the currently running request.
Note: because the status of the current request may be indeterminate and the request may already have been dispatched and executed on the server, sending this message is no guarantee that the requested action will not be performed. Depending on the underlying communication channel, it might also not be possible to skip retrieval of a (possibly large) response message. Sending the cancel message merely indicates that the caller is no longer interested in this request being completed.
- (void) cancel
canceled
Boolean property shows was asynchonous request canceled or not.
@property (readonly) BOOL canceled
channel
The client channel that the request is being executed for. Read-only and mainly for reference and internal use.
@property (readonly) ROClientChannel *channel
checkActivityForThread:
- (void) checkActivityForThread:(NSThread *)aThread
Parameters:
- aThread:
context retain
represents the context of given asynchronous request. It can be any object you need to pass along with async request.
For example:
if ([[request context] isKindOfClass:[MyTest class]]) {
[(MyTest *)[request context] performSomeTests];
}
@property (retain) id context
delegate assign
The delegate to send messages to for updates on progress, success or failure of the request.
@property (assign) id delegate
done
The message that is being sent. Read-only and mainly for reference and internal use.
@property (readonly) BOOL done
exception
This property stores the exception instance from the last run of the asynchronous request
@property (readonly) NSException *exception
failureBlock copy
given block of code will be executed if asynchronous request will fail with any exception. For example:
NSString *sql = [NSString stringWithFormat:@"SELECT TOP %ld * FROM [%@]", limit, tableName];
[self setBusy:YES];
DAAsyncRequest *ar = [[self adapter] beginGetDataTable:tableName withSQL:sql start:NO];
[ar setDelegate:self];
[ar setFailureBlock:^(NSException *exception){
[self setBusy:NO];
[tableView setEnabled:NO];
[tables selectItem:nil];
[Helpers showAlertSheetForException:exception inWindow:self.view.window];
}];
[ar startWithBlock:^{
[self setBusy:NO];
previewTable = [[ar tables] objectAtIndex:0];
[Helpers prepareTableView:tableView
forTable:previewTable];
[tableView setEnabled:YES];
[previewDataSource setArray:[previewTable rows]];
}];
@property (copy) void(^)(NSException *) failureBlock
failWithException:
- (void) failWithException:(NSException *)exception
Parameters:
- exception:
intCancel
- (void) intCancel
message
Represents reference to request message
@property (readonly) ROMessage *message
messageName
Represents the request name. It can be used for particular request identification when handling requests by delegate methods. For example:
- (void)asyncRequestDidComplete:(ROAsyncRequest *)request {
@try {
if ([@"GetDbSchemaNames" compare:[request messageName]] == NSOrderedSame) {
StringArray *names = [[domain asyncSchemaModelerService] endGetDbSchemaNames:request];
[self setDbSchemaNames:[names array]];
}
else if ([@"GetTableNames" compare:[request messageName]] == NSOrderedSame) {
StringArray *names = [[domain asyncSchemaModelerService] endGetTableNames:request];
[self setTableNames:[names array]];
}
else if ([@"GetViewNames" compare:[request messageName]] == NSOrderedSame) {
StringArray *names = [[domain asyncSchemaModelerService] endGetViewNames:request];
[self setViewNames:[names array]];
}
}
}
@property (readonly) NSString *messageName
originatingQueue
@property (readonly) dispatch_queue_t originatingQueue
originatingThread
Keeps the reference to NSThread object on which given request was started.
If asynchronous request was started in usual way (not startOnMainThread/startOnMainThreadWithBlock:) then completion block, as well and failure block will be executed at the originating thread
@property (readonly) NSThread *originatingThread
proxy retain
Keeps the reference to the service proxy instance.
In most of cases it set automatically in auto-generated code for the service interface.
@property (retain) id proxy
requestDidComplete
- (void) requestDidComplete
requestDidFailWithException:
- (void) requestDidFailWithException:(NSException *)exception
Parameters:
- exception:
responseData
The data that is being received. Read-only and mainly for reference and internal use.
@property (readonly) NSData *responseData
responseMessage
Represents a response message (a message that contains the request result that came from the server-side)
@property (readonly) ROMessage *responseMessage
restart
- (void) restart
retried assign
@property (assign) BOOL retried
setBackgroundTasksEnabled:
Set YES if given OS supports background tasks, NO othervise.
+ (void) setBackgroundTasksEnabled:(BOOL)value
Parameters:
- value:
setChannel:
- (void) setChannel:(ROClientChannel *)channel
Parameters:
- channel:
setMessage:
- (void) setMessage:(ROMessage *)message
Parameters:
- message:
start
Starts the request, if it is not already running. While the request itself will be executed in the background, the current thread will be considered the request's context and any callbacks to the delegate will happen on the thread that sent the start message.
If start is sent to a request that is already running, then ROAsyncRequestActiveException will be thrown.
- (void) start
startInBackground
Starts the request, if it is not already running. The request itself will be executed in the background, regardless how it was started. However, any callbacks to the delegate will happen on a background thread and not the thread that started the request. The identity of this background thread is undefined and may depend on the underlying communication structure.
If startInBackground is sent to a request that is already running, a ROAsyncRequestActiveException will be thrown.
- (void) startInBackground
startInBackgroundWithBlock:
Starts the request with given completion block. The request itself will be executed in the background, regardless how it was started. However, any callbacks to the delegate and the completion block itself will happen on a background thread and not the thread that started the request.
The identity of this background thread is undefined and may depend on the underlying communication structure.
If startInBackground is sent to a request that is already running, an ROAsyncRequestActiveException will be thrown.
- (void) startInBackgroundWithBlock:(void(^)(ROAsyncRequest *))block
Parameters:
- block: Completion block. Will be executed in the caller (background) thread.
startOnDispatchQueue:
This method is not implemented yet. Calling it will raise an exception.
- (void) startOnDispatchQueue:(dispatch_queue_t)queue
Parameters:
- queue:
startOnMainThread
Starts the request with instruction to execute any callbacks to the delegate in the the main UI thread, regardless from what thread given request was started.
- (void) startOnMainThread
startOnMainThreadWithBlock:
Starts the request with given completion block with instruction to execute this block, as well any callbacks to the delegate in the the main UI thread, regardless from what thread given request was started
- (void) startOnMainThreadWithBlock:(void(^)(ROAsyncRequest *))block
Parameters:
- block: Completion block. Will be called after async request ends
startWithBlock:
Starts the request whith given completion block. While the request itself will be executed in the background, the current thread will be considered the request's context and any callbacks to the delegate will happen on the thread that sent the start message.
If we apply this method to already running request, then ROAsyncRequestActiveException will be thrown.
- (void) startWithBlock:(void(^)(ROAsyncRequest *))block
Parameters:
- block: Completion block. Will be called after async request ends
canceled
Boolean property shows was asynchonous request canceled or not.
@property (readonly) BOOL canceled
channel
The client channel that the request is being executed for. Read-only and mainly for reference and internal use.
@property (readonly) ROClientChannel *channel
context retain
represents the context of given asynchronous request. It can be any object you need to pass along with async request.
For example:
if ([[request context] isKindOfClass:[MyTest class]]) {
[(MyTest *)[request context] performSomeTests];
}
@property (retain) id context
delegate assign
The delegate to send messages to for updates on progress, success or failure of the request.
@property (assign) id delegate
done
The message that is being sent. Read-only and mainly for reference and internal use.
@property (readonly) BOOL done
exception
This property stores the exception instance from the last run of the asynchronous request
@property (readonly) NSException *exception
failureBlock copy
given block of code will be executed if asynchronous request will fail with any exception. For example:
NSString *sql = [NSString stringWithFormat:@"SELECT TOP %ld * FROM [%@]", limit, tableName];
[self setBusy:YES];
DAAsyncRequest *ar = [[self adapter] beginGetDataTable:tableName withSQL:sql start:NO];
[ar setDelegate:self];
[ar setFailureBlock:^(NSException *exception){
[self setBusy:NO];
[tableView setEnabled:NO];
[tables selectItem:nil];
[Helpers showAlertSheetForException:exception inWindow:self.view.window];
}];
[ar startWithBlock:^{
[self setBusy:NO];
previewTable = [[ar tables] objectAtIndex:0];
[Helpers prepareTableView:tableView
forTable:previewTable];
[tableView setEnabled:YES];
[previewDataSource setArray:[previewTable rows]];
}];
@property (copy) void(^)(NSException *) failureBlock
message
Represents reference to request message
@property (readonly) ROMessage *message
messageName
Represents the request name. It can be used for particular request identification when handling requests by delegate methods. For example:
- (void)asyncRequestDidComplete:(ROAsyncRequest *)request {
@try {
if ([@"GetDbSchemaNames" compare:[request messageName]] == NSOrderedSame) {
StringArray *names = [[domain asyncSchemaModelerService] endGetDbSchemaNames:request];
[self setDbSchemaNames:[names array]];
}
else if ([@"GetTableNames" compare:[request messageName]] == NSOrderedSame) {
StringArray *names = [[domain asyncSchemaModelerService] endGetTableNames:request];
[self setTableNames:[names array]];
}
else if ([@"GetViewNames" compare:[request messageName]] == NSOrderedSame) {
StringArray *names = [[domain asyncSchemaModelerService] endGetViewNames:request];
[self setViewNames:[names array]];
}
}
}
@property (readonly) NSString *messageName
originatingQueue
@property (readonly) dispatch_queue_t originatingQueue
originatingThread
Keeps the reference to NSThread object on which given request was started.
If asynchronous request was started in usual way (not startOnMainThread/startOnMainThreadWithBlock:) then completion block, as well and failure block will be executed at the originating thread
@property (readonly) NSThread *originatingThread
proxy retain
Keeps the reference to the service proxy instance.
In most of cases it set automatically in auto-generated code for the service interface.
@property (retain) id proxy
responseData
The data that is being received. Read-only and mainly for reference and internal use.
@property (readonly) NSData *responseData
responseMessage
Represents a response message (a message that contains the request result that came from the server-side)
@property (readonly) ROMessage *responseMessage
retried assign
@property (assign) BOOL retried
backgroundTasksEnabled
Returns YES if OS supports background tasks, NO othervise.
+ (BOOL) backgroundTasksEnabled
setBackgroundTasksEnabled:
Set YES if given OS supports background tasks, NO othervise.
+ (void) setBackgroundTasksEnabled:(BOOL)value
Parameters:
- value:
cancel
Aborts the currently running request.
Note: because the status of the current request may be indeterminate and the request may already have been dispatched and executed on the server, sending this message is no guarantee that the requested action will not be performed. Depending on the underlying communication channel, it might also not be possible to skip retrieval of a (possibly large) response message. Sending the cancel message merely indicates that the caller is no longer interested in this request being completed.
- (void) cancel
checkActivityForThread:
- (void) checkActivityForThread:(NSThread *)aThread
Parameters:
- aThread:
failWithException:
- (void) failWithException:(NSException *)exception
Parameters:
- exception:
intCancel
- (void) intCancel
requestDidComplete
- (void) requestDidComplete
requestDidFailWithException:
- (void) requestDidFailWithException:(NSException *)exception
Parameters:
- exception:
restart
- (void) restart
setChannel:
- (void) setChannel:(ROClientChannel *)channel
Parameters:
- channel:
setMessage:
- (void) setMessage:(ROMessage *)message
Parameters:
- message:
start
Starts the request, if it is not already running. While the request itself will be executed in the background, the current thread will be considered the request's context and any callbacks to the delegate will happen on the thread that sent the start message.
If start is sent to a request that is already running, then ROAsyncRequestActiveException will be thrown.
- (void) start
startInBackground
Starts the request, if it is not already running. The request itself will be executed in the background, regardless how it was started. However, any callbacks to the delegate will happen on a background thread and not the thread that started the request. The identity of this background thread is undefined and may depend on the underlying communication structure.
If startInBackground is sent to a request that is already running, a ROAsyncRequestActiveException will be thrown.
- (void) startInBackground
startInBackgroundWithBlock:
Starts the request with given completion block. The request itself will be executed in the background, regardless how it was started. However, any callbacks to the delegate and the completion block itself will happen on a background thread and not the thread that started the request.
The identity of this background thread is undefined and may depend on the underlying communication structure.
If startInBackground is sent to a request that is already running, an ROAsyncRequestActiveException will be thrown.
- (void) startInBackgroundWithBlock:(void(^)(ROAsyncRequest *))block
Parameters:
- block: Completion block. Will be executed in the caller (background) thread.
startOnDispatchQueue:
This method is not implemented yet. Calling it will raise an exception.
- (void) startOnDispatchQueue:(dispatch_queue_t)queue
Parameters:
- queue:
startOnMainThread
Starts the request with instruction to execute any callbacks to the delegate in the the main UI thread, regardless from what thread given request was started.
- (void) startOnMainThread
startOnMainThreadWithBlock:
Starts the request with given completion block with instruction to execute this block, as well any callbacks to the delegate in the the main UI thread, regardless from what thread given request was started
- (void) startOnMainThreadWithBlock:(void(^)(ROAsyncRequest *))block
Parameters:
- block: Completion block. Will be called after async request ends
startWithBlock:
Starts the request whith given completion block. While the request itself will be executed in the background, the current thread will be considered the request's context and any callbacks to the delegate will happen on the thread that sent the start message.
If we apply this method to already running request, then ROAsyncRequestActiveException will be thrown.
- (void) startWithBlock:(void(^)(ROAsyncRequest *))block
Parameters:
- block: Completion block. Will be called after async request ends
- Asynchronous Requests
- ROAsyncRequestDelegate Protocol
- DAAsyncRequest Class