User Guide Gleam

JSON Mapping

Strengths

The advantages of the Gleam JSON mapping library are:

Use POJO - Plain Old Java Objects - and do not require Java Bean naming conventions for getters and setters.
Support immutable record constructs of Java. The field values are retrieved from CSV record in the first step. The record is constructed with values in the second step.
Support heterogeneous collections and can instantiate the expected instances through a user provided discriminator function.
Use lambda for reading and writing properties

The JSON manipulation uses the JSON-Java library. We use the library variant com.guicedee.services:json supporting Java 9 module semantic.

Complex structures are implemented through fields have a JSON entity as the generic parameter U.

TSV Mapping

The advantages of the Gleam TSV mapping library are:

Strengths

Recipes

The classes provide factory methods to create JSON entity defining the transformation of a Java object to a JSON instance and vice-versa. Below the code to map a bank connection object defined as a Java record with three String properties.

public static JsonEntity<BankConnection> createJsonBankConnection() {
    Function<JSONObject, BankConnection> imports = object -> {  (1)
        BankConnection connection = new BankConnection(JsonField.get("iban", object), JsonField.get("bic", object), JsonField.get("institute", object));
        return (connection.isValid()) ? connection : null;
    };

    List<JsonField<BankConnection, ?>> fields =
            List.of(JsonProperty.ofString("iban", BankConnection::iban, null), JsonProperty.ofString("bic", BankConnection::bic, null),
                    JsonProperty.ofString("institute", BankConnection::institute, null));
    return JsonEntity.of(fields, imports); (2)
}

1	Defines the import method to retrieve the values to create a bank connection, create an immutable Java record object, and validate the properties.
2	Returns a JSON entity defining an import method to construct an instance, and regular properties to create the JSON representation.

The InvoiceJson class is a good example using most of the factory methods provided in the JSON conversion library.

TSV Mapping

Strengths

The advantages of the Gleam TSV mapping library are:

Use POJO - Plain Old Java Objects - and do not require Java Bean naming conventions for getters and setters.
Support for immutable record constructs of Java
Support one to one and one to multiple instances relations. The identifier of the owner is stored in the TSV file as a foreign key. You do not need to change your classes to support the relation.

The TSV manipulation uses the apache commons csv library.

Transform a Java Record

The classes provide factory methods to create an entity defining the transformation of a Java object to a TSV instance and vice-versa. Below the code to map a bank connection object defined as a Java record with three String properties.

The key features to realize the transformation are:

Definition of the mapping of properties to TSV columns: To be written
Definition of a constructor for the Java object: To be written
Definition of transformation methods: To be written

static TsvEntity<BankConnection> createTsvBankConnection() {
    Function<CSVRecord, BankConnection> imports = (CSVRecord record) -> {                (1)
        BankConnection connection = new BankConnection(get(record, IBAN), get(record, BIC), get(record, INSTITUTE));
        if (!connection.isValid()) {
            logger.atWarn().log("Invalid bank connection {}", connection);
        }
        return connection;
    };

    List<TsvProperty<BankConnection, ?>> fields =
            List.of(TsvProperty.ofString(IBAN, BankConnection::iban, null),              (2)
                    TsvProperty.ofString(BIC, BankConnection::bic, null),
                    TsvProperty.ofString(INSTITUDE, BankConnection::institute, null)
    return TsvEntity.of(BankConnection.class, fields, imports);                          (3)
}

1	Define the import method to retrieve the values to create a bank connection, create an immutable Java record object, and validate the properties. The constants IBAN, BIC, and INSTITUTE define the column headers in the TSV file.
2	Declare a property of type string to a column named IBAN with a getter and no setter to identify a read-only property. These declarations are used to transform a Java object into a TSV record.
3	Return a TSV entity defining an import method to construct an instance, and regular properties to create the TSV representation.

Transform a 1-1, 1-n, or 0-n Relation

The classes provide factory methods to create owned entities defining the transformation of a relationship to a TSV instance and vice-versa.

The key features to realize the transformation are:

Definition of foreign key owner identifier: To be written
Transform an owned Java object to a TSV record: To be written
Transform a TSV record to an owned Java object: To be written