How to Configure and Manage Timeouts in the SDK Project

Owned by Rea Ben Yossef (Unlicensed)
May 21, 2020
3 min read

Introduction

A Timeout is defined as the amount of time that a process should wait between a request and the returning response, before termination.
Timeouts in the OpenLegacy system are associated with the backend processing and network latency time, but not to OpenLegacy core processing. Thus, the timeout clock starts with the synchronous call to the backend and includes only the payload send time + backend processing time + time to the first byte.

Timeouts are configured in the application.yml file properties.  The values can be overridden  by setting the Timeout property in RpcJsonRequest / RpcRequest or by passing  a parameter when using the SDK to RpcSession.doAction(...) method.

Note: For most of our backend we uses milli seconds, but for few it is seconds. the developer responsibility to verify the time scale for the specific connector.


API-Level Timeouts

Several timeout levels can be defined:

  • Default timeout - applies to all operations if no other timeout configuration is specified.
    • If a timeout is not configured, then its default is infinite.
  • Backend-defined timeout - applies to all entities of the respective backend, if no other configuration is specified
    • Overrides default timeout configuration.
  • Entity Action-level timeout - applies to designated actions, so multiple timeouts can be defined on the Entity Action level, but only one timeout can be defined per action.
    • This level overrides backend timeout configuration.
  • Operation - applies to designated annotation.
    • This level overrides backend timeout configuration.

Timeouts are defined in milliseconds, except for the AS/400 which is defined in seconds 


Example

The configuration can be a combination of the timeout levels. So, for example, assuming that we have two backends, Oracle and SQL Server, and we have a Service Accounts API, we can configure the timeouts as follows:

Timeouts:

ol:
  timeout:
	entity:
      "[com.backend1.openlegacy.Entity1]": 500
      "[com.backend1.openlegacy.Entity2]": 5000
      "[com.backend2.openlegacy.Entity1]": 1500
  	operation:
      "[TestOperation]": 5


This numeric value means that the timeout used in Entity1 at Backend1  will be triggered in 0.5 secs from the start of the synchronous call to the backend, until the first byte of the response. Entity2 timeout is defined at 5 secs. 


Step-by-Step Guide

  1. After generating the SDK project, open the application.yml file in the resources folder and add the code (SDK Timeout), connect it to the API and generate the entity. The same code with the same value will then appear in the application.yml of the API
  2. After connecting the SDK project and the API project, we need to define the timeouts.
  3. If there are two or more Backends of the same type connected to the same API, they will all have the SDK timeout. To change it, open the application.yml, there will be a name for the backend marked with # in red; add the timeout under it to separate it from the global  backend timeout
  4. To use timeouts, we need to define timeout values (the value needs to be defined in milliseconds). To do so, we open the application.yml and add the following properties (Entity Timeout). This will be the Entity level timeout.
  5. Now go to the Service Package in the API, and open the .impl class (right click → Java Editor), and add a numeric-value to the end of the doAction method, (the number must be in milliseconds - except AS/400 which is defined in seconds) (Method Timeout).


Priority between different timeout definitions :

  • RpcJsonRequest / RpcRequest and method timeout have the highest priority.
  •  application.yml with specific operation / entity overrides everything not mention in previous bullet.
  • RpcAction / RpcOperation / using OperationDefinition programmatically overrides project / backend  global setting
  • Backend setting on application.yml
  • Project setting on application.yml 


SDK Timeout:

ol:
  timeout:
    backend:
      Type-of-Backend: 1000

Same Backend with Different Timeouts: 

# Entity-name 
ol:
  timeout:
    Type-of-Backend: 250

Operation timeout using configuration

# Entity-name 
ol:
  timeout:
    operation:
      "[Name of the Operation]":(numeric value of the timeout)

Operation timeout using annotation

@RpcOperation(timeout = 3)
TestOperation

Request timeout

Entity Timeout:

ol:
  timeout:
	entity:
      "[Name of the Entity package (can be found in the SDK).entity]":(numeric value of the timeout)

Method Timeout:

entity = spOracleSdkRpcSession.doAction(ActionUtil.getRpcAction(LongProcedure.class), entity,(numeric value of the timeout));