Getting started ¶

Contents

Summary ¶

We will introduce how to set up the development environment and basic functions.

Install JDK ¶

In this Getting started, you need JDK 15.

Note

Doma supports JDK 8 and later. See also Which version of JDK does Doma support?.

Get sample project ¶

Clone getting-started repository and change the current directory:

$ git clone https://github.com/domaframework/getting-started.git
$ cd getting-started

Make sure the following command is successful:

$ ./gradlew build

Note

In Windows, run gradlew eclipse instead of ./gradlew eclipse.

Sample project structure ¶

getting-started is a Gradle multi-project and it has following two sub-projects:

java-8
java-15

These projects are almost the same. However the java-8 project stores SQL statements in files and the java-15 project stores them in Text Blocks.

Below, we will only talk about the java-15 project.

Import project to your IDE ¶

Eclipse ¶

We tested Eclipse 2020-09. Note that you need a patch to enable Java 15 features. See also this movie.

Before importing, generate eclipse files as follows:

$ ./gradlew eclipse

Then import the java-8 and java-15 projects to your workspace.

Note

If you want to store SQL statements in files, Doma Tools can help you.

IntelliJ IDEA ¶

We tested IntelliJ IDEA Community 2020.2.

Import getting-started to your IDEA as a Gradle project.

Note

If you use IntelliJ IDEA Ultimate Edition, Doma Support can help you.

Programming styles ¶

Doma supports two programming styles as follows:

DSL style
DAO style

DSL style allows you to build type-safe SQL statements with the Criteria API. DAO style allows you to map SQL statements to methods defined in the Java interface.

We recommend you prefer the DSL style. This is because the Criteria API, which enables the DSL style, has many advantages. For example, the Criteria API does not use reflection. It also supports associations such as one-to-many, many-to-one, one-to-one.

DSL style ¶

You can find some examples in boilerplate.java15.repository.EmployeeRepository. See Criteria API for more information.

SELECT ¶

To issue a SELECT statement and get results as Java objects, write as follows:

public Employee selectById(Integer id) {
  var e = new Employee_();
  return entityql.from(e).where(c -> c.eq(e.id, id)).fetchOne();
}

Employee_ is metamodel class of Employee entity class. Metamodel classes are generated by annotation processing.

The instance entityql of Entityql class is an entry point of the Criteria API.

The above code generates the following SQL statement:

select t0_.id, t0_.name, t0_.age, t0_.version from Employee t0_ where t0_.id = ?

DELETE ¶

To issue a DELETE statement, write as follows:

public void delete(Employee employee) {
  var e = new Employee_();
  entityql.delete(e, employee).execute();
}

INSERT ¶

To issue an INSERT statement, write as follows:

public void insert(Employee employee) {
  var e = new Employee_();
  entityql.insert(e, employee).execute();
}

UPDATE ¶

To issue an UPDATE statement, write as follows:

public void update(Employee employee) {
  var e = new Employee_();
  entityql.update(e, employee).execute();
}

DAO style ¶

You can find some examples in boilerplate.java15.dao.EmployeeDao. See Dao interfaces and SQL templates for more information.

SELECT (DAO)¶

To issue a SELECT statement and get results as Java objects, write as follows:

@Sql("""
    select
      /*%expand*/*
    from
      employee
    where
      id = /* id */0
    """)
@Select
Employee selectById(Integer id);

You can write the SQL template in @Sql using Text Block.

This SQL template contains two special expressions, /*%expand*/ and /* id */. In process of SQL template, /*%expand*/ and the following * are replaced with column list. And /* id */ and the following 0 are replaced with the bind variable ?. The bound value is the id parameter of the selectById method.

The above code generates the following SQL statement:

select
  id, name, age, version
from
  employee
where
  id = ?

DELETE (DAO)¶

To issue a DELETE statement, write as follows:

@Delete
int delete(Employee employee);

INSERT (DAO)¶

To issue an INSERT statement, write as follows:

@Insert
int insert(Employee employee);

UPDATE (DAO)¶

To issue an UPDATE statement, write as follows:

@Update
int update(Employee employee);

Next Step ¶

See other example projects: