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 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

 

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

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

setBackgroundTasksEnabled:

Set YES if given OS supports background tasks, NO othervise.

+ (void) setBackgroundTasksEnabled:(BOOL)value

Parameters:

  • value:

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

 

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

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

Descendants

See Also