Giters

eclipse / 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.

Home Page:https://www.jnosql.org/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

jakartaeejavajnosqlmicroprofile

Mapping Extension API

Table of Contents

The Eclipse JNoSQL Mapping Extension API is a collection of implementations/specializations from the 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 https://github.com/eclipse/jnosql-databases

  2. Choose the database you intend to use.

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

<dependency>
    <groupId>org.eclipse.jnosql.databases</groupId>
    <artifactId>chosen-database-artifact-id</artifactId>
    <version>chosen-database-version</version>
    <exclusions>
        <exclusion>
            <groupId>org.eclipse.jnosql.mapping</groupId>
            <artifactId>jnosql-mapping-reflection</artifactId>
        </exclusion>
    </exclusions>
</dependency>

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:

<dependency>
    <groupId>org.eclipse.jnosql.lite</groupId>
    <artifactId>mapping-lite-processor</artifactId>
    <version>1.1.0</version>
    <scope>provided</scope>
</dependency>

  1. Include the processor as a Maven plugin:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>17</source> <!-- depending on your project -->
                <target>17</target> <!-- depending on your project -->
                <annotationProcessorPaths>
                    <path>
                    <groupId>org.eclipse.jnosql.lite</groupId>
                    <artifactId>mapping-lite-processor</artifactId>
                    <version>1.1.0</version>
                    </path>
                    <!-- other annotation processors -->
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

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.

Bean Validation

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

<dependency>
    <groupId>org.eclipse.jnosql.mapping</groupId>
    <artifactId>jnosql-mapping-validation</artifactId>
    <version>1.1.0</version>
</dependency>

This requires the Jakarta Bean Validation specification.

@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;
    ...
}
@Inject
Template template;
...
template.insert(new Car()); // invalid car

Graph Connections

Graph connections is a project that contains several GraphConfiguration implementations.

<dependency>
  <groupId>org.eclipse.jnosql.mapping</groupId>
  <artifactId>jnosql-jnosql-graph-connections</artifactId>
  <version>1.1.0</version>
</dependency>

ArangoDB

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.

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 
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 
jnosql.graph.provider=org.eclipse.jnosql.mapping.graph.connections.TitanGraphConfiguration

Neo4j

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.

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

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.

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

  <dependency>
    <groupId>org.eclipse.jnosql.mapping</groupId>
    <artifactId>jnosql-metamodel-processor-extension</artifactId>
    <version>1.1.0</version>
    <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>org.eclipse.jnosql.mapping</groupId>
      <artifactId>jnosql-criteria-extension</artifactId>
      <version>1.1.0</version>
  </dependency>

Create a CriteriaDocumentTemplate

    @Inject
    private CriteriaDocumentTemplateProducer producer;

    @Inject
    private DocumentManager documentManager;
    CriteriaDocumentTemplate template = producer.get(documentManager);

EntityQuery

You can fetch entities with an EntityQuery :

CriteriaQuery<Person> personQuery = template.createQuery(Person.class);

EntityQueryResult<Person> executeQuery = template.executeQuery(
        personQuery.select().where(
                personQuery.from().get(
                        Person_.name
                ).equal(
                        "Poliana"
                ).or(
                        personQuery.from().get(
                                Person_.age
                        ).greaterThanOrEqualTo(17)
                )
        )
);

Stream<Person> stream = executeQuery.getEntities();

ExpressionQuery

You can fetch single columns/projections using an ExpressionQuery :

CriteriaQuery<Person> personQuery = template.createQuery(Person.class);

StringExpression<Person, Person> nameExpression = personQuery.from().get(
        Person_.name
);
NumberExpression<Person, Person, Integer> ageExpression = personQuery.from().get(
        Person_.age
);

ExpressionQueryResult<Person> executeQuery = template.executeQuery(
        personQuery.select(
                nameExpression,
                ageExpression
        ).where(
                nameExpression.equal(
                        "Poliana"
                ).or(
                        ageExpression.greaterThanOrEqualTo(17)
                )
        )
);

Optional<ExpressionQueryResultRow<Person>> findFirst = executeQuery.getRows().findFirst();

String name = findFirst.get().get(
        nameExpression
);

Integer age = findFirst.get().get(
        ageExpression
);

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

  • 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 contributing guide to learn about the development process, how to suggest bugfixes and improvements.

About

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://www.jnosql.org/

jakartaeejavajnosqlmicroprofile

License:Other

Languages

Language:Java 95.5%Language:Mustache 4.5%