Use an ORM

Java ORM support for YugabyteDB

Ebean ORM is an Object Relational Mapping (ORM) tool for Java applications. The Ebean API uses a session-less design, which eliminates the concepts of detached/attached beans, as well as the difficulties related with flushing and clearing.

YugabyteDB YSQL API has full compatibility with Ebean ORM for data persistence in Java applications. This page provides details for getting started with Ebean ORM for connecting to YugabyteDB.

Ebean ORM can be used with the YugabyteDB JDBC driver and the PostgreSQL JDBC Driver.

CRUD operations

Learn how to establish a connection to YugabyteDB database and begin basic CRUD operations using the steps in the Java ORM example application page.

The following sections demonstrate how to perform common tasks required for Java-based Play Framework application development using the Ebean ORM.

Create a new Java-based Play Framework project

Before you begin, ensure you have installed Java Development Kit (JDK) 1.8.0 or later and sbt 1.2.8 or later.

Create a new Java-Play project:

sbt new playframework/play-java-seed.g8

When prompted, provide the following project information:
- Name: demo-ebean
- Organization: com.demo-ebean
- play_version: 2.8.11
- scala_version: 2.12.8
After the project is created, go to the project directory:
```
cd demo-ebean
```
Change the sbt version in build.properties under the project directory to the following:
```
sbt.version=1.2.8
```
Download dependencies:
```
sbt compile
```

Your new Java-Play project's folder structure is ready.

Add the dependencies

To begin using Ebean in the application, do the following:

Add the following plugin in the project/plugins.sbt file:

addSbtPlugin("com.typesafe.sbt" % "sbt-play-ebean" % "5.0.0")

Connect to YugabyteDB by adding the following configuration to the conf/application.conf file:

db.default.driver=com.yugabyte.Driver
db.default.url="jdbc:yugabytedb://127.0.0.1:5433/ysql_ebean?load-balance=true"
db.default.username=yugabyte
db.default.password=""
play.evolutions {
default=true
db.default.enabled = true
autoApply=true
}

Add the following dependency for the YugabyteDB JDBC driver to the build.sbt file.
```
libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.7.3-yb-1"
```
Enable the PlayEbean plugin in the build.sbt file by adding PlayEbean as follows:
```
lazy val root = (project in file(".")).enablePlugins(PlayJava,PlayEbean)
```
If your default port is already to use, or you want to change the port, modify the settings by adding .settings(PlayKeys.playDefaultPort := 8080) to the build.sbt file as follows:
```
lazy val root = (project in file(".")).enablePlugins(PlayJava,PlayEbean).settings(PlayKeys.playDefaultPort := 8080)
```

Build the REST API using Ebean ORM with YugabyteDB

The example application has an Employee model that retrieves employee information, including the first name, last name, and email. An EmployeeController stores and retrieves the new employee information in the database using a Rest API.

Create a models folder in the app directory of your project to store the entities you create.
To use this directory as a default Ebean package of classes, add the following code at the end of the conf/application.conf file:
```
ebean.default="models.*"
```

Create a Employee.java file in app/models/. This is the class definition for the employee. Add the following code to the file:

package models;

import io.ebean.Finder;
import io.ebean.Model;
import javax.persistence.*;
import javax.validation.constraints.NotBlank;

@Entity
@Table(name = "employee")
public class Employee extends Model{

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  @Column(columnDefinition = "serial")
  public Long empId;

  @NotBlank
  public String firstName;

  @NotBlank
  public String lastName;

  @Column(name = "emp_email")
  public String email;

  public static final Finder<Long, Employee> find = new Finder<>(Employee.class);

  @Override
  public String toString(){
      return "{'empId' = '"+empId+"', firstName ='"+firstName+"', 'lastName'      ='"+lastName+"', 'email' ='"+email+"' }";

  }
}

Create an EmployeeController.java file in the app/controllers/ directory. This file controls the flow of employees data. It consists of methods for all API calls, including adding an employee, and retrieving employee information. Use the @Transactional annotation to automatically manage the transactions in that API. Add the following code to the file:

package controllers;
import models.Employee;
import javax.persistence.*;
import play.libs.Json;
import play.db.ebean.Transactional;
import play.mvc.*;
import java.util.ArrayList;
import java.util.List;
public class EmployeeController extends Controller{
  @Transactional
  public Result AddEmployee(Http.Request request){
      Employee employee=Json.fromJson(request.body().asJson(),Employee.class);
      employee.save();
      return ok(Json.toJson(employee.toString()));
  }
  public Result GetAllEmployees(){
      List <Employee> employees = Employee.find.all();
      List<String> employeesList = new ArrayList<String>();
      for(int index=0;index<employees.size();index++){
          employeesList.add(employees.get(index).toString());
      }
      return ok(Json.toJson(employeesList));
  }
}

Add the GET and POST API Request for the /employees endpoint to the conf/routes file. This defines the method needed for receiving the request:

GET      /employees            controllers.EmployeeController.GetAllEmployees
POST     /employees            controllers.EmployeeController.AddEmployee(request: Request)

Compile and run the project

To run the application and insert a new row, execute the following steps:

Compile and run the server in the project directory using the following commands:
```
sbt compile
```
```
sbt run
```

Create an employee using a POST request:

curl --data '{ "firstName" : "John", "lastName" : "Smith", "email":"jsmith@xyz.com" }' \
-v -X POST -H 'Content-Type:application/json' http://localhost:8080/employees

Get the details of the employees using a GET request:

curl  -v -X GET http://localhost:8080/employees

The output should look like the following:

["{'empId' = '1', firstName ='John', 'lastName' ='Smith', 'email' ='jsmith@xyz.com' }"]

Learn more

Build Java applications using Hibernate ORM
YugabyteDB smart drivers for YSQL