Getting started 

Summary 

This guide outlines the setup of your development environment and introduces basic functionalities.

Install JDK 

To begin, JDK 17 is required.

Note

It’s important to note that Doma is compatible with JDK 8 onwards. For details on supported JDK versions, refer to the appropriate section. Which version of JDK does Doma support?.

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.

The getting-started sample is a Gradle multi-project consisting of java-8 and java-17 sub-projects. Both are similar, with the primary difference being how SQL statements are stored: in files for java-8 and as Text Blocks in java-17.

This guide will focus on the java-17 project.

Import project to your IDE 

Eclipse 

Tested on Eclipse 4.23.0. Generate Eclipse project files using ./gradlew eclipse before importing the java-8 and java-17 projects into your workspace.

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

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

Programming styles 

Doma supports two programming styles: DSL and DAO.

The DSL style utilizes the Criteria API for building type-safe SQL statements, offering several benefits, such as not requiring reflection and supporting various types of associations (one-to-many, many-to-one, one-to-one).

The DAO style, on the other hand, maps SQL statements to Java interface methods.

It’s recommended to use the DSL style due to the Criteria API’s advantages.

DSL style 

In the DSL style, you work with examples in the boilerplate.java17.repository.EmployeeRepository and the 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 entityql.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 entityql instance from the Entityql 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_();
  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.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:

simple-examples