= Jakarta NoSQL :toc: auto

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%]

== Introduction

Jakarta NoSQL is a comprehensive framework designed to simplify the integration of Java applications with various NoSQL databases. By providing a unified API and a set of powerful annotations, Jakarta NoSQL enables developers to seamlessly work with different NoSQL data stores while maintaining flexibility and productivity.

== Goals

• Increase productivity performing common NoSQL operations.
• Rich Object Mapping integrated.
• Java-based Query and Fluent-API.
• It is designed to work with various NoSQL databases and can quickly adapt to support new types and behaviors through extensions.
• Annotation-oriented using Jakarta Persistence-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.

[source,java]

@Entity public class Car {

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

//... }

=== Annotations

The annotations from the Mapping API will look familiar to Jakarta Persistence developers:

[cols="2"] |=== | 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 | Specifies the mapped column for a persistent property or field. | @MappedSuperclass | Specifies a class whose mapping information is applied to entities that inherit from it. | @Embeddable | Declares a class whose instances are stored as an intrinsic part of an owning entity, sharing the identity of the entity. | @Inheritance | Specifies the inheritance mapping strategy for the entity class hierarchy. | @DiscriminatorColumn | Specifies the discriminator column for the mapping strategy. | @DiscriminatorValue | Specifies the value of the discriminator column for the annotated entity type. | @Convert | Specifies how the values of a field or property are converted to a basic type or a type that can be persisted by a persistence provider. |===

These annotations provide a powerful toolkit for defining and mapping entities in NoSQL databases, analogous to their counterparts in Jakarta Persistence.

=== Template

After mapping an entity, you can explore the advantage of using a Template interface, which can 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);

The Template interface provides specialized methods to leverage the features of specific NoSQL database types.

Maven dependency

[source,xml]

=== More Information

To learn more, please refer to the https://www.jnosql.org/spec/[reference documentation], and https://www.jnosql.org/javadoc/[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 codeofconduct@eclipse.org.

== 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/jakartaee/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 17 or higher.

[source, Bash]

mvn clean install