Ujorm3: New Lightweight ORM for JavaBeans and Records, Final Version

Do the simplest thing that could possibly work. — Kent Beck, creator of Extreme Programming and pioneer of test-driven development.

Today, I would like to introduce the final version of the Ujorm3 library with a newly written ORM module for working with JavaBean and Record objects in the context of relational databases. The goal of this module was a transparent solution without additional dependencies, supporting type-safe construction of SQL statements.

For fast manipulation of domain object data, the library compiles its own bytecode at runtime, achieving performance comparable to handwritten code. The core of the library intensively utilizes the Typed Key Pattern design pattern. Two interfaces in particular were carried over from the original version of the Ujorm library — Ujo and Key. Both interfaces applied this pattern back in 2007, even before the pattern received its name.

The Typed Key Pattern design pattern represents a technique for reading and writing domain object values through its key API, replacing traditional getters and setters with an internal property map. Keys are type-parameterized descriptors carrying information about the data type (or a default value) and, thanks to generics, ensure type safety without casting; they also allow mass operations on attributes without reflection. In terms of internal representation, this approach corresponds to the Typesafe Heterogeneous Container concept, which was first systematically published by Joshua Bloch in May 2008 in the second edition of the book Effective Java following the introduction of generics to the Java language.

Let me remind you of some basic information from the previous blog: the default mapping of entity attributes to database columns is described using JPA annotations from the Jakarta package. The @Column annotation is used for mapping attributes to columns, and @Enumerated is used for mapping enum types. The table name is declared with the @Table annotation.

Since the library does not use any binary-modified classes, partial column updates in an UPDATE statement require providing a list of modified attribute names (for example, as a String[] array) or the original object, from which the library creates this list itself. A single database table can be serviced by several classes — typically representing a subset of the entity.

One of the goals of the new library was to find the optimal balance between utility value and minimalist source code. The author believes that such an approach has a positive impact on minimizing errors and significantly extends the lifespan of the library. However, certain limitations arise from this approach. For example: The library does not support lazy-loading and supports only M:1 relationships when mapping relations.

The ORM module of the Ujorm3 library offers a set of tools with different levels of abstraction for database commands. Choose the solution that best suits your specific requirement:

1. EntityManager — the fastest way to handle CRUD (Create, Read, Update, Delete) operations with a single table using a primary key. For such elementary cases, the class generates the SQL command itself.
2. SelectQuery — a tool primarily designed for fetching data, including relations. It supports filtering data using type-safe Criterion objects, which can be arranged into a binary tree (using AND and OR operators). An alternative is using the bind() method. For specific cases, the beginning and end of the generated SQL command can be manually appended.
3. SqlQuery — a low-level universal class for general requirements. It allows writing native SQL while maintaining safety using the bind(), label(), and column() methods. Using a generic mapper, the library can automatically populate relational objects as well. The last two classes share a common ancestor, which can serve as a base for any future implementations.

Let's look at simple usage examples, starting with the low-level approach. The following method inserts a city into the database table (using a fluent API) and returns the identifier of the inserted row.

public Long insertCity(String name, String country) {
    return SqlQuery.run(connection(), query -> query
        .sql("""
             INSERT INTO city
             ( name,  country_code) VALUES
             (:name, :countryCode )
             """)
        .bind("name", name)
        .bind("countryCode", country)
        .executeInsert(rs -> rs.getLong(1))
        .findFirst().orElseThrow());
}

The next example searches for employees and fetches their data, including the city name. The ResultSetMapper class supports multithreaded access.

static final ResultSetMapper EMPLOYEE_MAPPER =
             ResultSetMapper.of(Employee.class);

public List<Employee> findEmployees(Connection connection, Long minId) {
    return SqlQuery.run(connection, query -> query
        .sql("""
             SELECT e.id  AS ${e.id}
             , e.name     AS ${e.name}
             , c.name     AS ${c.name}
             FROM employee e
             JOIN city c ON c.id = e.city_id
             WHERE e.id >= :id
             """)
        .label("e.id"  , MetaEmployee.id)
        .label("e.name", MetaEmployee.name)
        .label("c.name", MetaEmployee.city, MetaCity.name) // Key Path mapping
        .bind("id", minId)
        .toStream(EMPLOYEE_MAPPER.mapper()) // Generic mapping including relations
        .toList());
}

The MetaEmployee class is an automatically generated metamodel created using the optional ujorm-meta-processor APT plugin. However, mapping can also be written directly in the SQL SELECT statement at the column alias position in the format of dot-separated property names (properties, for example, boss.name). However, it needs to be enclosed in quotes (or other characters depending on the database type). If the DB column name matches the attribute, explicit mapping is unnecessary. For example:

SELECT e.id, e.name, c.name AS "city.name" FROM ...

The last example performs a similar SELECT using the SelectQuery class. Here, the columns(true) method loads all columns of the table, including foreign keys. The column(...) method adds another column to the mapping and can also handle multiple relations.

The relation type is determined by the nullable property from the JPA annotation: a mandatory object attribute (marked as nullable=false) generates an INNER JOIN relation type, otherwise it generates a LEFT JOIN. The beginning of the SQL statement can (optionally) be changed using the sql() method, and the end can (optionally) be appended using the tail() method.

final EntityContext CTX = EntityContext.ofDefault();
final EntityManager<Employee, Long> EMPLOYEE_EM = CTX.entityManager(Employee.class);

List<Employee> select(Connection connection) {
    return SelectQuery.run(connection, EMPLOYEE_EM, query -> query
            .sql("SELECT")  // Optional
            .columns(true)
            .column(MetaEmployee.city, MetaCity.name)     // INNER JOIN
            .column(MetaEmployee.boss, MetaEmployee.name) // LEFT JOIN
            .where(MetaEmployee.id.whereGe(1L).and(MetaCity.id.whereGe(1L)))
            .tail("ORDER BY", MetaEmployee.id)
            .toList()
    );
}

The code of the Ujorm3 project is thoroughly covered by JUnit tests. Integration tests are run via a Bash script (in the bin directory) against dockerized databases: PostgreSQL, MySQL, MariaDB, OracleFree, and MSSQL Server. More detailed information about the Ujorm3 library can be found on the homepage of the project — including additional examples.

A reference usage of Ujorm3 can be found in the PetStore project, which (aside from the Ujorm library) has no other Maven dependencies. The PetStore project then gave rise to a prototype web application called TopMovies for movie viewers — this application recommends movies to users based on how their ratings match a virtual group with similar preferences.

Apart from the Ujorm library, this project also has no other dependencies. Data is stored in an H2 database, or optionally in PostgreSQL. Although the project is not publicly available, you can freely try the prototype at the provided link (the number of fictitious users is limited).

Web Links

• Homepage — is part of the Ujorm3 project hosted on GitHub.
• PetStore — a sample open-source application demonstrating the Ujorm3 library. It uses the ORM module for database queries and the Element class to build the UI.
• TopMovies — a prototype application for recommending movies based on the alignment of user ratings with a virtual movie group.
• JavaDoc — class description.
• An ORM performance comparison — comparing performance and other metrics with Hibernate, Jdbi, MyBatis, and other libraries. Tests run on PostgreSQL (in Docker) and H2 (in-memory) databases using Java 25.