Use an ORM
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
- Name:
-
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.3.3"
-
Enable the PlayEbean plugin in the
build.sbt
file by addingPlayEbean
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 thebuild.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 theapp
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 inapp/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 theapp/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 theconf/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