eclipse-ee4j / nosql

The specification in Jakarta EE to help Jakarta EE developers create enterprise-grade applications using Java® and NoSQL technologies.

Jakarta NoSQL

Table of Contents

• Introduction
• Goals
• One Mapping API to Multiples NoSQL Databases
  • Key-Value
  • Column Family
  • Document
  • More Information
• Code of Conduct
• Getting Help
• Building from Source

Introduction

Jakarta NoSQL is a Java framework that streamlines the integration of Java applications with NoSQL databases.

Goals

• Increase productivity performing common NoSQL operations

• Rich Object Mapping integrated

• Java-based Query and Fluent-API

• Specific template API to each NoSQL category

• Annotation-oriented using JPA-like naming when it makes sense

One Mapping API to Multiples NoSQL Databases

Jakarta NoSQL provides one API for each NoSQL database type. However, it incorporates the same annotations from the Jakarta Persistence specification and heritage Java Persistence Architecture (JPA) to map Java objects. Therefore, with just these annotations that look like JPA, there is support for more than twenty NoSQL databases.

@Entity
public class Car {

    @Id
    private Long id;
    @Column
    private String name;
    @Column
    private CarType type;
 //...
}

The annotations from the Mapping API annotations will look familiar to the Jakarta Persistence/JPA developer:

Annotation	Description
@Entity	Specifies that the class is an entity. This annotation is applied to the entity class.
@Id	Specifies the primary key of an entity.
@Column	Specify the mapped column for a persistent property or field.

After mapping an entity, you can explore the advantage of using a Template interface, which can increase productivity on NoSQL operations.

@Inject
Template template;
...

Car ferrari = Car.id(1L)
        .name("Ferrari")
        .type(CarType.SPORT);

template.insert(ferrari);
Optional<Car> car = template.find(Car.class, 1L);
template.delete(Car.class, 1L);

This template has specialization to take the benefits of a particular NoSQL database type.

Key-Value

Jakarta NoSQL provides a Key-Value template to explore the specific behavior of this NoSQL type.

@Inject
KeyValueTemplate template;
...

Car ferrari = Car.id(1L)
        .name("ferrari")
        .city("Rome")
        .type(CarType.SPORT);

template.put(ferrari);
Optional<Car> car = template.get(1L, Car.class);
template.delete(1L);

Key-Value is database agnostic. Thus, you can change the database in your application with no or minimal impact on source code.

Column Family

Jakarta NoSQL provides a Column Family template to explore the specific behavior of this NoSQL type.

@Inject
ColumnTemplate template;
...

Car ferrari = Car.id(1L)
        .name("ferrari")
        .city("Rome")
        .type(CarType.SPORT);

template.insert(ferrari);
Optional<Car> car = template.find(Car.class, 1L);

List<Car> cars = template.select(Car.class).where("city").eq("Rome").result();

template.delete(Car.class).where("id").eq(1L).execute();

Optional<Car> result = template.singleResult("select * from Car where id = 1");

Column Family is database agnostic. Thus, you can change the database in your application with no or minimal impact on source code.

Document

Jakarta NoSQL provides a Document template to explore the specific behavior of this NoSQL type.

@Inject
DocumentTemplate template;
...

Car ferrari = Car.id(1L)
        .name("ferrari")
        .city("Rome")
        .type(CarType.SPORT);

template.insert(ferrari);
Optional<Car> car = template.find(Car.class, 1L);

List<Car> cars = template.select(Car.class).where("city").eq("Rome").result();

template.delete(Car.class).where("id").eq(1L).execute();

Optional<Car> result = template.singleResult("select * from Car where id = 1");

Document is database agnostic. Thus, you can change the database in your application with no or minimal impact on source code.

More Information

To learn more, please refer to the reference documentation, and JavaDocs.

Code of Conduct

This project is governed by the Eclipse Foundation of Conduct. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to [e-mail].

Getting Help

Having trouble with Jakarta NoSQL? We’d love to help!

Please report any bugs, concerns or questions with Jakarta NoSQL to https://github.com/eclipse-ee4j/nosql.

Building from Source

You don’t need to build from source to use the project, but should you be interested in doing so, you can build it using Maven and Java 11 or higher.

mvn clean install