DanSilva41/eclipse-ee4j-nosql

= Jakarta NoSQL
:toc: auto

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

ifndef::imagesdir[:imagesdir: spec/src/main/asciidoc/images]

image::jakarta_ee_logo_schooner_color_stacked_default.png[Jakarta NoSQL logo,align=center, width=25%, height=25%]

== One Mapping API to multiples NoSQL databases

Jakarta NoSQL has one API for each NoSQL database type. However, it uses the same annotations to map Java objects. Therefore, with just these annotations that look like JPA, there is support for more than twenty NoSQL databases.

[source,java]

@entity
public class Car {

@Id
private Long id;
@Column
private String name;
@Column
private CarType type;

//...
}

---

The Mapper annotations are pretty familiar if you are a JPA developer:

• Entity
• Id
• Column
• Embeddable
• Convert
• DiscriminatorColumn
• DiscriminatorValue
• Inheritance
• MappedSuperclass

IMPORTANT: Although similar to JPA, Jakarta NoSQL defines persistable fields with either ID or Column annotation.

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

[source,java]

@Inject
Template template;
...

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

Optional 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.

There is Repository exploring the DDD pattern to have a higher abstraction.

[source,java]

public interface CarRepository extends Repository<Car, String> {

Optional<Car> findByName(String name);

}

@Inject
CarRepository repository;
...

Car ferrari = Car.id(1L).name("Ferrari").type(CarType.SPORT);
repository.save(ferrari);
Optional idResult = repository.findById(1L);
Optional nameResult = repository.findByName("Ferrari");

=== Key-value

Jakarta NoSQL has a key-value template to explore the specific behavior of this NoSQL type.

[source,java]

@Inject
KeyValueTemplate template;
...

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

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

It is a key-value agnostic database; thus, you can change the database without or less code impact possible.

=== Column

Jakarta NoSQL has a column template to explore the specific behavior of this NoSQL type.

[source,java]

@Inject
ColumnTemplate template;
...

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

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

ColumnDeleteQuery deleteQuery = delete().from("Car")
.where("_id").eq(1L).build();
template.delete(deleteQuery);

ColumnDeleteQuery query = select().from("Car")
.where("_id").eq(1L).build();

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

---

It is a wide-column agnostic database; thus, you can change the database without or less code impact possible.

=== Document

Jakarta NoSQL has a document template to explore the specific behavior of this NoSQL type.

[source,java]

@Inject
DocumentTemplate template;
...

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

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

DocumentDeleteQuery deleteQuery = delete().from("Car")
.where("_id").eq(1L).build();
template.delete(deleteQuery);

DocumentDeleteQuery query = select().from("Car")
.where("_id").eq(1L).build();

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

---

It is a document agnostic database; thus, you can change the database without or less code impact possible.

=== More information

Check the https://www.jnosql.org/spec/[reference documentation], and https://www.jnosql.org/javadoc/[Javadocs] to know more.

== 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 codeofconduct@eclipse.org.

== Getting Help

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

Report bugs with Jakarta NoSQL at https://github.com/eclipse-ee4j/nosql.

== Building from Source

You don’t need to build from source to use the project, but if you want to try, you can make it using Maven and Java 11 or higher.

[source, Bash]

mvn clean install

== TCK

Any Jakarta NoSQL module must pass this test suite.
The TCK uses JUnit Jupiter 5.
Check it more link:tck/README.adoc[to know more]

== Spec

Any Jakarta NoSQL module must pass this test suite.
The TCK uses JUnit Jupiter 5.
Check it more link:spec/README.adoc[to know more]