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-extensions

This project contains all specialization to Eclipse JNoSQL. The specific behavior in a NoSQL database matters, that's why there are Eclipse JNoSQL Mapper specializations.
https://github.com/eclipse-jnosql/jnosql-extensions

jakartaee java jnosql microprofile

Last synced: 9 days ago
JSON representation

This project contains all specialization to Eclipse JNoSQL. The specific behavior in a NoSQL database matters, that's why there are Eclipse JNoSQL Mapper specializations.

Awesome Lists containing this project

README 

        
= Mapping Extension API

:toc: auto



The Eclipse JNoSQL Mapping Extension API is a collection of implementations/specializations from the https://jakarta.ee/specifications/nosql/[Jakarta NoSQL] specification that defines specific behavior in various NoSQL databases.



== JNoSQL Lite



This documentation guides extending the usage of Eclipse JNoSQL to avoid using Reflection with Java Annotation Processor while still utilizing the same APIs and achieving compatibility with CDI Lite.



The extension approach aims to achieve the following goals:



- **Eliminate Reflection:** Remove the dependency on Reflection within the database engine or dependency, leading to improved performance and reduced runtime overhead.



- **Enhance CDI Lite Compatibility:** Achieve compatibility with CDI Lite, making integrating Eclipse JNoSQL into CDI Lite-enabled environments easier.



Adopting the extension approach provides several benefits:



- **Improved Performance:** By eliminating Reflection, the Extension approach results in faster startup times and reduced runtime overhead, leading to better overall application performance.



- **Seamless Transition:** Since the same APIs are used, transitioning to the extension approach doesn't require learning new APIs. Developers can continue using familiar APIs while enjoying the advantages of the new approach.



- **CDI Lite Compatibility:** The extension approach ensures that Eclipse JNoSQL works seamlessly with CDI Lite environments, allowing easy integration and taking advantage of CDI Lite's features.



- **Enhanced Maintainability:** Java Annotation Processors simplify codebase maintenance and debugging by replacing reflection-based operations with compile-time checks and optimizations.



=== Extension Steps



To use this Extension, follow a two-step process:



==== Step 1: Remove Reflection Engine



Start by removing the reflection engine from the database engine or dependency. To do this, follow these steps:



1. Check the available databases at link:https://github.com/eclipse/jnosql-databases[]

2. Choose the database you intend to use.

3. Exclude the reflection engine dependency in your Maven project:



[source,xml]

----



    org.eclipse.jnosql.databases

    chosen-database-artifact-id

    chosen-database-version

    

        

            org.eclipse.jnosql.mapping

            jnosql-mapping-reflection

        

    



----



==== Step 2: Include Java Annotation Processor



After removing the reflection engine, include the Java Annotation Processor. There are two ways to do this:



1. Define the processor as a provided dependency:



[source,xml]

----



    org.eclipse.jnosql.lite

    mapping-lite-processor

    1.1.3

    provided



----



2. Include the processor as a Maven plugin:



[source,xml]

----



    

        

            org.apache.maven.plugins

            maven-compiler-plugin

            3.8.1

            

                17 

                17 

                

                    

                    org.eclipse.jnosql.lite

                    mapping-lite-processor

                    1.1.3

                    

                    

                

            

        

    



----



=== Usage and Limitations



With the Extension, you can now leverage Eclipse JNoSQL Lite's benefits. However, be aware of the following limitations in the entity model:



- Java Record is not supported.

- A default constructor is required.

- All persistent fields with ID or Column annotations must have a getter and setter, at least in the default access modifier.



WARNING: Keep in mind these limitations when designing and implementing your application.



Additionally, you can use Repositories from Jakarta Data, but note that certain limitations apply to entity modeling:



- There is no support for Sort in List or in Array.

- Graph and Key-Value Repositories do not support method by query.



Now you're ready to explore the enhanced features of Eclipse JNoSQL Lite and leverage its benefits without relying on Reflection.



== JNoSQL Static Metamodel



The JNoSQL Static Metamodel feature generates a Jakarta Data metamodel, facilitating type-safe access to entity attributes. This capability enhances compile-time safety, aids in refactoring, minimizes the use of "magic strings," and improves code documentation.



=== Installing the Metamodel Processor



To enable the generation of the static metamodel for your entities, include the Metamodel Processor in your project's build configuration. This processor automatically generates metamodel classes corresponding to your entity classes, ensuring type-safe queries and operations. Add the following dependency to your Maven project:



[source,xml]

----



    org.eclipse.jnosql.metamodel

    mapping-metamodel-processor

    1.1.3

    provided



----



With the metamodel classes generated, you can perform type-safe operations on your entities, such as querying, updating, or deleting records based on compile-time checked attributes.



=== Example Usage



Given an entity class, such as:



[source,java]

----

@Entity

public class Product {

    public long id;

    public String name;

    public float price;

}

----



You can use the statically generated metamodel to construct queries. For instance, to find products based on a dynamic search pattern and sort the results by price descending, name ascending, and ID ascending, you would use:



[source,java]

----

List found = products.findByNameLike(searchPattern, Order.by(

    _Product.price.desc(),

    _Product.name.asc(),

    _Product.id.asc()));

----



This approach ensures that query attribute references are both type-safe and refactor-safe, leading to more robust and maintainable code.



== Bean Validation



Eclipse JNoSQL provide support for bean validation. It will validate before inserting/updating and constructing an entity.



[source,xml]

----



    org.eclipse.jnosql.mapping

    jnosql-mapping-validation

    1.1.3



----



This requires the https://jakarta.ee/specifications/bean-validation/[Jakarta Bean Validation] specification.



[source,java]

----

@Entity

public class Car {



    @Column

    @NotNull

    @Pattern(regexp = "[A-Z]{3}-[0-9]{4}", message = "Invalid car plate")

    private String plate;



    @Column

    @NotNull

    @MonetaryMin(value = "100", message = "There is not car cheap like that")

    @MonetaryMax(value = "1000000", message = "The parking does not support fancy car")

    @CurrencyAccepted(currencies = "USD", message = "The car price must work with USD")

    @Convert(MonetaryAmountConverter.class)

    private MonetaryAmount price;



    @Column

    @NotBlank

    private String model;



    @Column

    @NotBlank

    private String color;

    ...

}

----



[source,java]

----

@Inject

Template template;

...

template.insert(new Car()); // invalid car

----



== Graph Connections



Graph connections is a project that contains several `GraphConfiguration` implementations.



[source,xml]

----



  org.eclipse.jnosql.mapping

  jnosql-jnosql-graph-connections

  1.1.3



----



=== ArangoDB



[cols="ArangoDB Properties"]

|===

|Configuration property |Description



|`jnosql.arangodb.graph.edge`

|The edge collection. It uses as a prefix. E.g.:jnosql.arangodb.graph.edge.1=edge



|`jnosql.arangodb.graph.relationship`

|Edge collection, the source vertex collection and the target vertex collection split by pipe. It hou,It uses as a prefix. E.g.: jnosql.arangodb.graph.relationship.1=Person\|knows\|Person



|`jnosql.arangodb.graph.vertex`

|The vertex collection. It uses as a prefix. E.g.: jnosql.arangodb.graph.vertex.1=vertex



|`jnosql.arangodb.graph.graph`

|Name of the graph to use.



|`jnosql.arangodb.graph.host`

|The database host.



|`jnosql.arangodb.graph.user`

|The user's credential.



|`jnosql.arangodb.graph.password`

|The password's credential.



|===



This is an example using ArangoDB's Graph API with MicroProfile Config.



[source,properties]

----

jnosql.graph.provider=org.eclipse.jnosql.mapping.graph.connections.ArangoDBGraphConfiguration

jnosql.arangodb.graph.graph=marketing

jnosql.arangodb.graph.vertex.1=Person

jnosql.arangodb.graph.edge.1=knows

jnosql.arangodb.graph.relationship.1=Person|knows|Person

----



=== Janus



This is an example using Janus's Graph API with MicroProfile Config.



WARNING: The API will pass and use the properties from `org.janusgraph.graphdb.configuration.GraphDatabaseConfiguration`

[source,properties]

----

jnosql.graph.provider=org.eclipse.jnosql.mapping.graph.connections.JanusGraphConfiguration

graphname=name

allow-upgrade=false

----



=== Titan



This is an example using Titan's Graph API with MicroProfile Config.



WARNING: The API will pass and use the properties from `com.thinkaurelius.titan.graphdb.configuration.GraphDatabaseConfiguration`

[source,properties]

----

jnosql.graph.provider=org.eclipse.jnosql.mapping.graph.connections.TitanGraphConfiguration

----



=== Neo4j



[cols="Neo4j Properties"]

|===

|Configuration property |Description



|`jnosql.neo4j.host`

|The database host. Default: "bolt://localhost:7687"



|`jnosql.neo4j.user`

|The user's credential. Default: "neo4j"



|`jnosql.neo4j.password`

|The password's credential. Default: "neo4j"



|===



This is an example using Neo4J's Graph API with MicroProfile Config.



[source,properties]

----

jnosql.graph.provider=org.eclipse.jnosql.mapping.graph.connections.Neo4JGraphConfiguration

jnosql.neo4j.user=neo4j

jnosql.neo4j.password=neo4j

jnosql.neo4j.host=bolt://localhost:7687

----



=== Neo4j Remote



[cols="Neo4j Remote Properties"]

|===

|Configuration property |Description



|`jnosql.neo4j.host`

|The database host. Default: "bolt://localhost:7687"



|===



This is an example using Neo4J's Graph API with MicroProfile Config.



[source,properties]

----

jnosql.graph.provider=org.eclipse.jnosql.mapping.graph.connections.Neo4JEmbeddedGraphConfiguration

jnosql.neo4j.host=/home/otaviojava/data/

----



== CriteriaQuery API 



This is the experimental Criteria API, largely inspired by the JPA one.

Using this API you can execute queries built via CriteriaQuery.

The CriteriaQuery is used in combination with Metamodel Attributes.

These attributes are automagically generated from the defined NoSQL Entities.



The Criteria API can be used via CriteriaDocumentTemplate.



=== Set dependency



[source,xml]

----

  

    org.eclipse.jnosql.mapping

    jnosql-metamodel-processor-extension

    1.1.3

    true

  

  

      org.eclipse.jnosql.mapping

      jnosql-criteria-extension

      1.1.3

  

----



== Driver for Jakarta Persistence entities



Provides a driver for Eclipse JNoSQL that supports Jakarta Persistence entities over a Jakarta Persistence provider. This project also contains a runner for the Jakarta Data TCK.



== TCK Runners



The Eclipse JNoSQL project provides Technology Compatibility Kit (TCK) runners for Jakarta Data. These runners allow you to run the TCK tests against the Eclipse JNoSQL implementation to verify its compatibility with the Jakarta Data specifications.



=== Jakarta Data TCK Runner



The Jakarta Data TCK Runner is a project that runs the Jakarta Data TCK tests against the Eclipse JNoSQL implementation. It provides a convenient way to verify the compatibility of a Jakarta Data implementation with the Jakarta Data specification. Learn more about it link:jnosql-data-tck-runner/README.adoc[here].



== Getting Help



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



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

Follow the instructions in the templates and remember to mention that the issue refers to JNoSQL extensions.



== 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. Please, mention that the issue refers to the JNoSQL extensions project.



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