ballerina-platform / ballerina-library

The Ballerina Library
https://ballerina.io/learn/api-docs/ballerina/
Apache License 2.0
137 stars 58 forks source link

[Proposal] Enhanced Usability for SAP JCo Function Execution in Ballerina with Multiple Parameters #6783

Closed RDPerera closed 1 month ago

RDPerera commented 2 months ago

This proposal outlines the mapping of JCo data types to Ballerina data types for the SAP JCo Connector. The objective is to ensure accurate and efficient data exchange between SAP systems and Ballerina applications by providing clear and consistent mappings for both import (setters) and export (getters) parameter types.

JCo to Ballerina Data Type Mapping

ABAP Type Description Ballerina Type
CHAR Fixed-length character string string
CHAR Single character string
NUMC Numeric text string
INT1 1-byte integer int
INT2 2-byte integer int
INT4 4-byte integer int
INT8 8-byte integer (if supported) int
FLTP Floating-point number float
DEC Packed decimal decimal
RAW/XSTR Variable-length byte string byte[]
CHAR/FLAG Character representing true/false (e.g., 'X' for true) boolean
DATS Date in the format YYYYMMDD time:Date
TIMS Time in the format HHMMSS time:TimeOfDay
DATS/TIMS Combination of date and time time:Utc
LANG Language key string
CUKY Currency key string
QUAN Quantity field decimal
UNIT Unit of measure string
Complex ABAP Type Description Ballerina Type
STRUCTURE Group of fields record {}
TABLE Multi-row dataset, array of structures record{}[]
niveathika commented 2 months ago

When considering the use case for input parameters and output parameters in SAP JCo, the RFC accepts multiple values. To improve usability, we can introduce two functions in Ballerina:

public type FieldType string|int|float|decimal|boolean|byte[]|time:Date|time:TimeOfDay|time:Utc|record {|FieldType...;|}|record {|FieldType...;|}[];

isolated remote function execute(string functionName, FieldType? importParams = (), typedesc<FieldType|FieldType[]|map<FieldType>|xml|json?> exportParams = <>) returns exportParams|Error;

isolated remote function executeWithMultipleParams(string functionName, FieldType[]|map<FieldType>? importParams = (), typedesc<FieldType|FieldType[]|map<FieldType>|xml|json?> exportParams = <>) returns exportParams|Error;

The execute() function can be used when there is only one input parameter, and executeWithMultipleParams() can be used for multiple values.

For the output return, all simple types can be used to bind to specific types:

// Returns one string field
string result = check jcoClient->execute("functionName", "a");

// Returns multiple fields in order
FieldType[] results = check jcoClient->execute("functionName", "a");

// Returns multiple fields with parameter names
map<string> resultsMap = check jcoClient->execute("functionName", "a");

// Returns one JCoStructure
record{||} structure = check jcoClient->execute("functionName", "a");

// Returns one JCoStructure with parameter names
map<record{||}> structuresMap = check jcoClient->execute("functionName", "a");

// Returns a table
record{||}[] table = check jcoClient->execute("functionName", "a");

// Returns multiple tables in positional value
record{||}[][] tables = check jcoClient->execute("functionName", "a");

To handle the case where multiple JCoStructures are expected in an array, we introduce a special annotation:

public annotation MultiStructure on type;

@MultiStructure
type MultipleValues record{||}[];

MultipleValues _ = check jcoClient->execute("", "a");

This exception addresses potential confusion when the user expects either one return value of table type or multiple JCoStructures in an array.

Note on Data Mapping in Ballerina In Ballerina, another consideration for data mapping is to process all return values if the return type is an open record, or only return specified fields for closed records. This will not apply to JCoStructure or JCoTable. Due to compile-time validation of types, the user must always use a closed record. Since these types contain only limited fields, significant performance degradation due to this behavior is not expected.