Overview

The purpose of the document is to guide on how to use HTTP Layer and its classes to help on working with REST API calls. This will also provide a way to get the response back via the callback methods. Using this, you can work with your GET and POST REST API methods and get the response as a callback. Please notice, we are not supporting Image or File downloading approach using this.

Creating a request object

To serve the web service calls, first step is to create a ORARequest object. Below are the different constructors to create ORARequest object

// Construct Request object with URL. Throws ORAInvalidRequestException if url is not a valid

url.public ORARequest(String url);

// Construct request object with url and map payload.

public ORARequest(String url, Map<String, String> payload);

// Construct request object with url and payload.

public ORARequest(String url, String jsonPayload);

In addition to the above constructors, we can use below setter methods to add more value to the ORARequest object.

// To be used if you want to set the URL separately without constructor
public void setUrl(String url);
// Set the url. If the payload is null, it will throw  ORAInvalidRequestException
public void setPayload(String jsonPayload);
// Set the request method. Default value is REQUEST_TYPE_POST
public void setRequestType(@RequestType int requestType);
// Set whether payload should be compressed or not. Default value is false.
public void setCompress(boolean compress);
// Sets the retry count. If the request is failed, the same request is retried for retryCount times. The default value is 1. Minimum is 0 and maximum is 15.
public void setRetryCount(int retryCount);
// set the priority of the request. Default value is PRIORITY_NORMAL
public void setPriority(@Priority int priority);
//Set the request TAG. Default value is null.
public void setTAG(String tag)
// Set the callback.
public void setCallback(ORAHTTPResponseCallback callback);
// To add single request header.
public void addRequestHeader(String key, String value);
// To add multiple request headers
public void addRequestHeaders(Map<String, String> headers);

Example

ORARequest request = new ORARequest("https://YOUR_END_POINT");
request.setPayload("YOUR_PAYLOAD");
request.addRequestHeader("Content-Type", "application/json");
request.setTAG("some_id");
request.setRequestType(ORARequest.REQUEST_TYPE_POST);

Add the request to request queue

Once the ORARequest object is ready, now we need to use ORAHTTPManager.addRequest() method to trigger the request. Below is the implementation.

ORAHTTPManager.getInstance(context).addRequest(request, new ORAHTTPResponseCallback() {
            @Override
publicvoid onResponse(ORAResponse oraResponse) {
if (oraResponse.getResponseCode() < 0) {
// Something wrong...!
                                                                        

                                                                        
                }
            }
        });

When you call addRequest() method, the request will be added to the end of the queue. Once the requests prior to this requests are done, this request will be processed.

Immediate Request

If you set the priority as PRIORITY_IMMEDIATE for the ORARequest, the request will be added to the head of the queue and executed immediately after the current running process.

Get response call back

Since we passed the ORAHTTPResponseCallback to the request queue above, whenever there is a response to the request, the below method will trigger automatically.

// Called when a request is processed.
                                                                        
void onResponse(ORAResponse oraResponse);

ORAResponse will contain below methods

//Returns HTTP response code of corresponding request or error code
                                                                        
publicint getResponseCode();

//Returns response message
                                                                        
public String getMessage();

//Returns response body
                                                                        
public String getBody();

//Returns exception. Otherwise returns NULL
                                                                        
public Exception getException();

//Returns response tag if corresponding request has the tag. NUll otherwise
                                                                        
public String getRequestTAG();

Execute Request when app is in background

By default HTTP requests are not processed when the application is in background. The HTTP request queue will be paused when the application goes to background. If any HTTP request is already started before app going to background, it will be completed even after the application went to background. All other requests in the queue will not be scheduled. Once the application comes back to foreground, the queue will be resumed and the requests will be processed. This behavior will same for the PRIORITY_IMMEDIATE requests also.

This behavior can be overridden by using HTTP_BACKGROUND_TASK_ENABLED configuration. By default HTTP_BACKGROUND_TASK_ENABLED configuration value is false. If HTTP_BACKGROUND_TASK_ENABLED value set to true, all the HTTP requests are processed even if the application is in background. Below is the code snippet to make HTTP requests execute in background.

ORACoreDataContainer container = new ORACoreDataContainer(context);
container.putValue(ORABaseConfigSettings.HTTP_BACKGROUND_TASK_ENABLED, "true");

Or you can add below line in oracle.json file under ORACORE to enable background execution.

"ora_dc_http_background_task_enabled" : "true"

HTTP Layer Guide