Getting started
Summary
This guide outlines the setup of your development environment and introduces basic functionalities.
Install JDK
To begin, JDK 17 is required.
Get sample project
To obtain the sample project, clone the getting-started repository and navigate to the new directory using the following commands:
$ git clone https://github.com/domaframework/getting-started.git
$ cd getting-started
Ensure successful project setup with:
$ ./gradlew build
Note
For Windows users, execute gradlew build
.
Sample project structure
The getting-started sample is a Gradle multi-project that includes a java-17 subproject. This guide will focus on the java-17 subproject.
Import project to your IDE
Eclipse
Tested on Eclipse 4.23.0. Import the getting-started project as a Gradle project.
Note
If you want to store SQL statements in files, Doma Tools can help you.
IntelliJ IDEA
Tested with IntelliJ IDEA Community 2023.3.4. Import the getting-started project as a Gradle project.
Note
You can use the following IntelliJ IDEA plugins to support Doma. Since they have overlapping features, please choose one:
Programming styles
Doma supports two programming styles —DSL and DAO— and it is recommended to use them together to maximize their advantages.
The DSL style leverages the type-safe Criteria API, making it ideal for automatically generating simple dynamic SQL. On the other hand, the DAO style maps SQL statements to Java interface methods and is well suited for automatically generating conventional SQL for insert, update, and delete operations, as well as for manually writing complex SQL.
DSL style
In the DSL style, you work with examples in the boilerplate.java17.repository.EmployeeRepository
and the Unified Criteria API for operations.
SELECT
To execute a SELECT query and retrieve Java object results, follow this example:
public Employee selectById(Integer id) {
var e = new Employee_();
return queryDsl.from(e).where(c -> c.eq(e.id, id)).fetchOne();
}
You’ll use a metamodel class, like Employee_
for Employee
, which is auto-generated through annotation processing.
The queryDsl
instance from the QueryDsl
class serves as the Criteria API’s starting point.
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_();
queryDsl.delete(e).single(employee).execute();
}
INSERT
To issue an INSERT statement, write as follows:
public void insert(Employee employee) {
var e = new Employee_();
queryDsl.insert(e).single(employee).execute();
}
UPDATE
To issue an UPDATE statement, write as follows:
public void update(Employee employee) {
var e = new Employee_();
queryDsl.update(e).single(employee).execute();
}
DAO style
You can find some examples in boilerplate.java17.dao.EmployeeDao
.
See DAO interfaces and SQL templates for more information.
SELECT (DAO)
In the DAO style, for issuing a SELECT statement to retrieve Java objects,
use the @Sql
annotation with Text Blocks for SQL templates:
@Sql("""
select
/*%expand*/*
from
employee
where
id = /* id */0
""")
@Select
Employee selectById(Integer id);
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: