User Guide Gleam

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.

json-class-diagram

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

tsv-class-diagram

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.

tsv-class-diagram

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