Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eclipse-jnosql/jnosql

Eclipse JNoSQL is a framework which has the goal to help Java developers to create Jakarta EE applications with NoSQL.
https://github.com/eclipse-jnosql/jnosql

database flexible graph-database jnosql nosql nosql-databases

Last synced: 5 days ago
JSON representation

Eclipse JNoSQL is a framework which has the goal to help Java developers to create Jakarta EE applications with NoSQL.

Awesome Lists containing this project

README 

        
= Eclipse JNoSQL

:toc: auto



== Introduction



Eclipse JNoSQL is a compatible implementation of the https://jakarta.ee/specifications/nosql/[Jakarta NoSQL] and https://jakarta.ee/specifications/data/[Jakarta Data] specifications, a Java framework that streamlines the integration of Java applications with NoSQL databases.



== Goals



* Increase productivity performing common NoSQL operations

* Rich Object Mapping integrated with Contexts and Dependency Injection (CDI)

* Java-based Query and Fluent-API

* Persistence lifecycle events

* Low-level mapping using Standard NoSQL APIs

* Specific template API to each NoSQL category

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

* Extensible to explore the particular behavior of a NoSQL database

* Explore the popularity of Apache TinkerPop in Graph API

* Jakarta NoSQL and Data implementations



== One Mapping API to Multiples NoSQL Databases



Eclipse JNoSQL provides one API for each NoSQL database type. However, it incorporates the same annotations from the https://jakarta.ee/specifications/persistence/[Jakarta Persistence] specification and heritage Java Persistence API (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;

 //...

}

----



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



[cols="Annotation description"]

|===

|Annotation|Description



|`@jakarta.nosql.Entity`

|Specifies that the class is an entity. This annotation is applied to the entity class.



|`@jakarta.nosql.Id`

|Specifies the primary key of an entity.



|`@jakarta.nosql.Column`

|Specify the mapped column for a persistent property or field.



|`@jakarta.nosql.Embeddable`

|Specifies a class whose instances are stored as an intrinsic part of an owning entity and share the entity's identity.



|`@jakarta.nosql.Convert`

|Specifies the conversion of a Basic field or property.



|`@org.eclipse.jnosql.mapping.MappedSuperclass`

|Designates a class whose mapping information is applied to the entities that inherit from it. A mapped superclass has no separate table defined for it.



|`@jakarta.nosql.Inheritance`

|Specifies the inheritance strategy to be used for an entity class hierarchy.



|`@jakarta.nosql.DiscriminatorColumn`

|Specifies the discriminator column for the mapping strategy.



|`@jakarta.nosql.DiscriminatorValue`

|Specifies the value of the discriminator column for entities of the given type.



|===



IMPORTANT: Although similar to JPA, Jakarta NoSQL defines persistable fields with either the ```@Id``` or ```@Column``` annotation.



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);



List cars = template.select(Car.class).where("name").eq("Ferrari").result();

template.delete(Car.class).execute();

----



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



A ``Repository`` interface is also provided for exploring the Domain-Driven Design (DDD) pattern for a higher abstraction.



[source,java]

----

public interface CarRepository extends PageableRepository {



    Optional 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");

----



== Getting Started



Eclipse JNoSQL requires these minimum requirements:



* Java 17 (or higher)

* https://jakarta.ee/specifications/cdi/3.0/[Jakarta Contexts & Dependency Injection 3.0] (CDI)

* https://jakarta.ee/specifications/jsonb/2.0/[Jakarta JSON Binding 2.0] (JSON-B)

* https://jakarta.ee/specifications/jsonp/2.2/[Jakarta JSON Processing 2.0] (JSON-P)

* https://microprofile.io/microprofile-config/[MicroProfile Config]



=== NoSQL Database Types



Eclipse JNoSQL provides common annotations and interfaces. Thus, the same annotations and interfaces, ```Template``` and ```Repository```, will work on the four NoSQL database types.



As a reference implementation for Jakarta NoSQL, Eclipse JNosql provides particular behavior to the database type required by the specification, including the Graph database type, it means, Eclipse JNoSQL covers the four NoSQL database types:



* Key-Value

* Column Family

* Document

* Graph



=== Key-Value



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



Eclipse JNoSQL offers a mapping implementation for Key-Value NoSQL types:



[source,xml]

----



    org.eclipse.jnosql.mapping

    jnosql-mapping-key-value

    1.1.4



----



Furthermore, check for a Key-Value databases. You can find some implementations in the https://github.com/eclipse/jnosql-databases[JNoSQL Databases].



[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);

----



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



You can define the database settings using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification, so you can add properties and overwrite it in the environment following the https://12factor.net/config[Twelve-Factor App].



[source,properties]

----

jnosql.keyvalue.database=

jnosql.keyvalue.provider=

jnosql.provider.host=

jnosql.provider.user=

jnosql.provider.password=

----



TIP: The ```jnosql.keyvalue.provider``` property is necessary when you have more than one driver in the classpath. Otherwise, it will take the first one.



These configuration settings are the default behavior. Nevertheless, there is an option to programmatically configure these settings. Create a class that implements the ```Supplier``` interface and then define it using the ```@Alternative``` and ```@Priority``` annotations.



[source,java]

----

@Alternative

@Priority(Interceptor.Priority.APPLICATION)

@ApplicationScoped

public class ManagerSupplier implements Supplier {



    @Produces

    public BucketManager get() {

        Settings settings = Settings.builder()

                .put("credential", "value")

                .build();

        KeyValueConfiguration configuration = new NoSQLKeyValueProvider();

        BucketManagerFactory factory = configuration.apply(settings);

        return factory.apply("database");

    }

}

----



You can work with several Key-Value database instances through the CDI qualifier. To identify each database instance, make a ```BucketManager``` visible for CDI by adding the ```@Produces``` and the ```@Database``` annotations in the method.



[source,java]

----

@Inject

@Database(value = DatabaseType.KEY_VALUE, provider = "databaseA")

private KeyValueTemplate templateA;



@Inject

@Database(value = DatabaseType.KEY_VALUE, provider = "databaseB")

private KeyValueTemplate templateB;



// producers methods

@Produces

@Database(value = DatabaseType.KEY_VALUE, provider = "databaseA")

public BucketManager getManagerA() {

    BucketManager manager = // instance;

    return manager;

}



@Produces

@Database(value = DatabaseType.KEY_VALUE, provider = "databaseB")

public BucketManager getManagerB() {

    BucketManager manager = // instance;

    return manager;

}

----



The KeyValue Database module provides a simple way to integrate the `KeyValueDatabase` annotation with CDI, allowing you to inject collections managed by the key-value database. This annotation works seamlessly with various collections, such as List, Set, Queue, and Map.



To inject collections managed by the key-value database, use the `@KeyValueDatabase` annotation in combination with CDI's `@Inject` annotation. Here's how you can use it:



[source,java]

----

import javax.inject.Inject;



// Inject a List instance from the "names" bucket in the key-value database.

@Inject

@KeyValueDatabase("names")

private List names;



// Inject a Set instance from the "fruits" bucket in the key-value database.

@Inject

@KeyValueDatabase("fruits")

private Set fruits;



// Inject a Queue instance from the "orders" bucket in the key-value database.

@Inject

@KeyValueDatabase("orders")

private Queue orders;



// Inject a Map instance from the "orders" bucket in the key-value database.

@Inject

@KeyValueDatabase("orders")

private Map map;

----



=== Column Family



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



Eclipse JNoSQL offers a mapping implementation for Column NoSQL types:

[source,xml]

----



    org.eclipse.jnosql.mapping

    jnosql-mapping-column

    1.1.4



----



Furthermore, check for a Column Family databases. You can find some implementations in the https://github.com/eclipse/jnosql-databases[JNoSQL Databases].



[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);



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



Optional result = template.singleResult("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.



You can define the database settings using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification, so you can add properties and overwrite it in the environment following the https://12factor.net/config[Twelve-Factor App].



[source,properties]

----

jnosql.column.database=

jnosql.column.provider=

jnosql.provider.host=

jnosql.provider.user=

jnosql.provider.password=

----



TIP: The ```jnosql.column.provider``` property is necessary when you have more than one driver in the classpath. Otherwise, it will take the first one.



These configuration settings are the default behavior. Nevertheless, there is an option to programmatically configure these settings. Create a class that implements the ```Supplier``` interface, then define it using the ```@Alternative``` and ```@Priority``` annotations.



[source,java]

----

@Alternative

@Priority(Interceptor.Priority.APPLICrATION)

@ApplicationScoped

public class ManagerSupplier implements Supplier {



    @Produces

    @Database(DatabaseType.COLUMN)

    public DatabaseManager get() {

        Settings settings = Settings.builder()

                .put("credential", "value")

                .build();

        DatabaseConfiguration configuration = new NoSQLColumnProvider();

        DatabaseManagerFactory factory = configuration.apply(settings);

        return factory.apply("database");

    }

}

----



You can work with several column database instances through CDI qualifier. To identify each database instance, make a ``ColumnManager`` visible for CDI by putting the ```@Produces``` and the ```@Database``` annotations in the method.



[source,java]

----

@Inject

@Database(value = DatabaseType.COLUMN, provider = "databaseA")

private ColumnTemplate templateA;



@Inject

@Database(value = DatabaseType.COLUMN, provider = "databaseB")

private ColumnTemplate templateB;



// producers methods

@Produces

@Database(value = DatabaseType.COLUMN, provider = "databaseA")

public ColumnManager getManagerA() {

    return manager;

}



@Produces

@Database(value = DatabaseType.COLUMN, provider = "databaseB")

public ColumnManager getManagerB() {

    return manager;

}

----



=== Document



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



Eclipse JNoSQL offers a mapping implementation for Document NoSQL types:



[source,xml]

----



    org.eclipse.jnosql.mapping

    jnosql-mapping-document

    1.1.4



----



Furthermore, check for a Document databases. You can find some implementations in the https://github.com/eclipse/jnosql-databases[JNoSQL Databases].



[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);



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



Optional result = template.singleResult("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.



You can define the database settings using the https://microprofile.io/microprofile-config/[MicroProfile Config] specification, so you can add properties and overwrite it in the environment following the https://12factor.net/config[Twelve-Factor App].



[source,properties]

----

jnosql.document.database=

jnosql.document.provider=

jnosql.provider.host=

jnosql.provider.user=

jnosql.provider.password=

----



TIP: The ```jnosql.document.provider``` property is necessary when you have more than one driver in the classpath. Otherwise, it will take the first one.



These configuration settings are the default behavior. Nevertheless, there is an option to programmatically configure these settings. Create a class that implements the ```Supplier```, then define it using the ```@Alternative``` and ```@Priority``` annotations.



[source,java]

----

@Alternative

@Priority(Interceptor.Priority.APPLICATION)

@ApplicationScoped

public class ManagerSupplier implements Supplier {



    @Produces

    @Database(DatabaseType.DOCUMENT)

    public DatabaseManager get() {

        Settings settings = Settings.builder()

                .put("credential", "value")

                .build();

        DatabaseConfiguration configuration = new NoSQLDocumentProvider();

        DatabaseManagerFactory factory = configuration.apply(settings);

        return factory.apply("database");

    }

}

----



You can work with several document database instances through CDI qualifier. To identify each database instance, make a ```DocumentManager``` visible for CDI by putting the ```@Produces``` and the ```@Database``` annotations in the method.



[source,java]

----

@Inject

@Database(value = DatabaseType.DOCUMENT, provider = "databaseA")

private DocumentTemplate templateA;



@Inject

@Database(value = DatabaseType.DOCUMENT, provider = "databaseB")

private DocumentTemplate templateB;



// producers methods

@Produces

@Database(value = DatabaseType.DOCUMENT, provider = "databaseA")

public DocumentManager getManagerA() {

    return manager;

}



@Produces

@Database(value = DatabaseType.DOCUMENT, provider = "databaseB")

public DocumentManager getManagerB() {

    return manager;

}

----



=== Jakarta Data



Eclipse JNoSQL as a Jakarta Data implementations supports the following list of predicate keywords on their repositories.



|===

|Keyword |Description | Method signature Sample



|And

|The ```and``` operator.

|findByNameAndYear



|Or

|The ```or``` operator.

|findByNameOrYear



|Between

|Find results where the property is between the given values

|findByDateBetween



|LessThan

|Find results where the property is less than the given value

|findByAgeLessThan



|GreaterThan

|Find results where the property is greater than the given value

|findByAgeGreaterThan



|LessThanEqual

|Find results where the property is less than or equal to the given value

|findByAgeLessThanEqual



|GreaterThanEqual

|Find results where the property is greater than or equal to the given value

|findByAgeGreaterThanEqual



|Like

|Finds string values "like" the given expression

|findByTitleLike



|In

|Find results where the property is one of the values that are contained within the given list

|findByIdIn



|True

|Finds results where the property has a boolean value of true.

|findBySalariedTrue



|False

|Finds results where the property has a boolean value of false.

|findByCompletedFalse



|Not

|The logical NOT negates all the previous keywords, but True or False. It needs to include as a prefix "Not" to a keyword.

|findByNameNot, findByAgeNotGreaterThan



|OrderBy

|Specify a static sorting order followed by the property path and direction of ascending.

|findByNameOrderByAge



|OrderBy____Desc

|Specify a static sorting order followed by the property path and direction of descending.

|findByNameOrderByAgeDesc



|OrderBy____Asc

|Specify a static sorting order followed by the property path and direction of ascending.

|findByNameOrderByAgeAsc



|OrderBy____(Asc\|Desc)*(Asc\|Desc)

|Specify several static sorting orders

|findByNameOrderByAgeAscNameDescYearAsc



|===



WARNING: Eclipse JNoSQL does not support `OrderBy` annotation.



=== More Information



Check the https://www.jnosql.org/spec/[reference documentation] and https://www.jnosql.org/javadoc/[JavaDocs] to learn more.



== Code of Conduct



This project is governed by the Eclipse Foundation Code of Conduct. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to mailto:[email protected][[email protected]].



== Getting Help



Having trouble with Eclipse JNoSQL? We’d love to help!



Please report any bugs, concerns or questions with Eclipse JNoSQL to https://github.com/eclipse/jnosql[https://github.com/eclipse/jnosql].



If your issue refers to the https://github.com/eclipse/jnosql-databases[JNoSQL databases project] or

the https://github.com/eclipse/jnosql-extensions[JNoSQL extensions project], please, open the issue in this repository following the instructions in the

templates.



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



[source, Bash]

----

mvn clean install

----



== Contributing



We are very happy you are interested in helping us and there are plenty ways you can do so.



- https://github.com/eclipse/jnosql/issues[**Open an Issue:**]  Recommend improvements, changes and report bugs



- **Open a Pull Request:** If you feel like you can even make changes to our source code and suggest them, just check out our link:CONTRIBUTING.adoc[contributing guide] to learn about the development process, how to suggest bugfixes and improvements.



Here are the badges of this project:

[%autowidth,cols="a,a,a,a", frame=none, grid=none, role=stretch ]

|===

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=sqale_rating[ link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent, window=_blank, target=_blank]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=code_smells[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=ncloc[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=coverage[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=sqale_index[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=alert_status[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=reliability_rating[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=duplicated_lines_density[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=vulnerabilities[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=bugs[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

| image::https://sonarcloud.io/api/project_badges/measure?project=org.eclipse.jnosql%3Ajakarta-nosql-parent&metric=security_rating[window=_blank, link=https://sonarcloud.io/summary/new_code?id=org.eclipse.jnosql%3Ajakarta-nosql-parent]

|===



== Testing Guideline



This project's testing guideline will help you understand Jakarta Data's testing practices.

Please take a look link:TESTING-GUIDELINE.adoc[at the file].



== Migration



This migration guide explains how to upgrade from Eclipse JNoSQL version 1.0.0-b6 to the latest version, considering two significant changes: upgrading to Jakarta EE 9 and reducing the scope of the Jakarta NoSQL specification to only run on the Mapping. The guide provides instructions on updating package names and annotations to migrate your Eclipse JNoSQL project successfully.



link:MIGRATION.adoc[Migration Guide]



== To know more



If you want to know more about both the communication and mapping layer, there are two complementary files for it each specific topic:



* link:COMMUNICATION.adoc[Communication API]

* link:MAPPING.adoc[Mapping API]