Sorm4j: Simple micro Object-Relation Mapper for Java

Sorm4j (Simple micro Object-Relation Mapper for Java) is a Java-based micro-ORM tool. Sorm4j is a sort of JDBC wrapper. It provides simple functionalities to do select, insert, update, delete and merge.

Sorm4j sets Java objects into parameters of an SQL statement and executes the SQL statement, and it maps the result to Java objects. It opens a connection to a database and closes it after the execution automatically.

Here is an example with lambda expressions:

// Creates an entry point as javax.sql.DataSource.
Sorm sorm = SormFactory.create("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;","username","password");

// insert
sorm.apply(conn -> conn.insert(new Customer(1, "Alice", "Tokyo")));

// select
List<Customer> customers =
  sorm.apply(conn -> conn.readList(Customer.class, "select * from customer where address=?","Tokyo"));

Sorm4j uses an object it simply wraps a java.sql.Connection object for object-relation mapping. Sorm4j has only one dependency on a logging facade (SLF4J). It means this tool can be integrated with any code that depends on JDBC (including code that already uses another ORM tool).

Sorm4j requires Java 11 (or above) to run and build.

Quickstart

The latest release is available at Maven Central Repository. Add dependency to your pom.xml:

 <dependency>
   <groupId>org.nkjmlab</groupId>
   <artifactId>sorm4j</artifactId>
   <version>1.3.5</version>
 </dependency>

Create a class with public fields and default constructor matching a table name. For example:

public class Customer {
  public int id;
  public String name;
  public String address;
}

Create an entry point:

Sorm sorm = SormFactory.create("jdbc:h2:mem:sormtest", "sa","");

Reads matching rows from table:

List<Customer> list =
  sorm.apply(conn -> conn.readList(Customer.class, "select * from customer where id>?", 5));

Inserts a new row:

sorm.apply(conn-> conn.insert(new Customer(1, "Alice", "Tokyo")));

Performance (Oracle JMH)

lib	read (microsec/op)	insert (microsec/op)
Hand coded (baseline)	5.7	6.1
Sorm4j	6.0 (5% slower)	6.9 (13% slower)
Sql2o	8.1 (42% slower)	11.0 (80% slower)
JDBI	18.7 (228% slower)	12.5 (105% slower)
JOOQ	35.3 (519% slower)	-
MyBatis	12.5 (119% slower)	-
Spring JDBCTemplate	10.2 (79% slower)	-
Apache DbUtils	7.3 (28% slower)	-

• read: reads one row from table including 10,240 row using primary key
• insert: inserts one row to table

Sorm4j is evaluated performance with the H2 database. The results show a small overhead to comparing hand-coded JDBC operations. If you need precise information, please take a look at the Performance page.

Website

Sorm4j website shows more information.

• Quickstart
  • To get started, see here.
• Basic Usage
  • Next to get started, see here.
• Examples
  • If you need more sample codes, please take a look at the Examples page and the Sample of Sorm4j repository.
• Features
  • The features of Sorm4j, see here.
• Performance
  • If you need more benchmark results, please take a look at the Performance page and the Benchmark of Sorm4j repository.
• Developer's Guide
  • The detailed manual is here.

Versioning

The classes in org.nkjmlab.sorm4j, org.nkjmlab.sorm4j.annotation, org.nkjmlab.sorm4j.sql are regarded as public API. If any methods are going to remove, they will be annotated by @Deprecated and announced release note. Experimental elements are annotated by @Experimental.

License

Sorm4j is distributed under a Apache License Version 2.0.

Special thanks

• r5v9 for creating r5v9/Persist (BSD license), which inspires this project.