Ballerina-Transformer tools

A data transformation function is a general-purpose API to apply a function to a set of data points. The output may contain data points generated by adding, removing, or altering some. The Ballerina transformer is also a set of such tools that provide the following capabilities.

1. Validate if a given Ballerina package is a transformer package
2. Generate Ballerina service(s) to expose Ballerina transformer functions as REST APIs

Create a data-transformation service

To create a data transformation service, a Ballerina package has to be created and transformer tools have to be imported. Once after writing the transformer functions, the build command would generate the required transformer services for the transformer functions written. The below is an example.

Example:

import ballerinax/transformer as _;

public type Person record {
    string firstName;
    string lastName;
};

public type Student record {
    string fullName;
    string school;
};

public isolated function transform(Person person, string school) returns Student => {
    fullName: person.firstName + " " + person.lastName,
    school: school
};

Once the above code is validated, a service would get generated for the transformer function, which transforms a Person into a Student.

Request

POST /transform/

curl -X POST http://localhost:7000/transform
    -H 'Content-Type: application/json'
    -d '{"person": {"firstName": "Joe", "lastName": "Root"}, "school": "Kingswood"}'

Response

HTTP/1.1 201 Created
Date: Thu, 24 Feb 2011 12:36:30 GMT
Status: 201 Created
Connection: close
Content-Type: application/json
Location: /thing/1
Content-Length: 36

{"fullName": "Joe Root", "school": "Kingswood"}

For the transformer function above, it would create a Ballerina record to capture all parameters and that record would be passed as the payload of the service's resource function.

type transformPayload record {
    Person person;
    string school;
};

Validator and Generator

Transformer Package Validator

Ballerina transformer tools can validate a Ballerina package if that complies with the constraints of a Ballerina transformer package. For a Ballerina package to be treated as a transformer package, it should comply with the constraints below.

1. The package should not contain any entry points (i. e., main function or services)
2. The package should have one or more expression-bodied functions (transformer-function) with public and isolated qualifiers
3. The package can contain other functions, which can be used at util functions (cannot be public)
4. The package can contain records
5. The package is not allowed to have class definitions or listener definitions
6. Expression-bodied functions in the package are only allowed to have a public qualifier
7. The package is not allowed to have annotations
8. The public isolated expression-bodied functions (transformer-functions) are allowed to have serializable types as a parameter type and return type

As of now, to activate the transformer tools on a Ballerina package, the tool is required to be imported to the relevant package as specified below. After that, when the Ballerina transformer package is built, it will be validated against the aforementioned constraints.

import ballerinax/transformer as _;

Ballerina Service Generator

Once a Ballerina package is validated, the transformer tools will generate a service, which would allow the transformer functions to be consumed through REST APIs. The parameters of the transformer function have to be passed as a JSON payload.

Note: The service for the Ballerina package would only get generated if there are no validation errors, and the parameter types and return types of the transformer function should be serializable and should be supported by the Ballerina HTTP module. The list of such Ballerina types can be found in the Ballerina HTTP module specification.

Build from the source

Set up the prerequisites

1. OpenJDK 11 (Adopt OpenJDK or any other OpenJDK distribution)

   Info: You can also use Oracle JDK. Set the JAVA_HOME environment variable to the pathname of the directory into which you installed JDK.

2. Export the GitHub Personal access token with the read package permissions as follows.

   export packageUser=<Username>
   export packagePAT=<Personal access token>
   

Build the source

Execute the commands below to build from the source.

1. To build the library:

   ./gradlew clean build

2. To run the integration tests:

   ./gradlew clean test

3. To build the module without the tests:

   ./gradlew clean build -x test

4. To publish to local Maven:

   ./gradlew clean build publishToMavenLocal

Contribute to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All the contributors are encouraged to read the Ballerina Code of Conduct.

Useful links

• For example demonstrations of the usage, go to Ballerina By Examples.
• Chat live with us via our Discord community.
• Post all technical questions on Stack Overflow with the #ballerina tag.