{"id":23148183,"url":"https://github.com/eclipse-jnosql/jnosql-extensions","last_synced_at":"2026-04-07T04:31:34.071Z","repository":{"id":38386710,"uuid":"67732760","full_name":"eclipse-jnosql/jnosql-extensions","owner":"eclipse-jnosql","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-06T18:26:45.000Z","size":4293,"stargazers_count":34,"open_issues_count":2,"forks_count":26,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-04-06T20:23:43.519Z","etag":null,"topics":["jakartaee","java","jnosql","microprofile"],"latest_commit_sha":null,"homepage":"https://www.jnosql.org/","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-jnosql.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":"CONTRIBUTING.adoc","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-09-08T19:12:38.000Z","updated_at":"2026-04-06T18:26:51.000Z","dependencies_parsed_at":"2023-02-12T03:17:06.664Z","dependency_job_id":"02780ef5-ccb6-45b3-98a4-7a4f7cbb353c","html_url":"https://github.com/eclipse-jnosql/jnosql-extensions","commit_stats":{"total_commits":1717,"total_committers":14,"mean_commits":"122.64285714285714","dds":"0.11182294700058237","last_synced_commit":"384db10cfade99ae91bd65ea90dddd48c2923307"},"previous_names":["eclipse/jnosql-mapping-extension","eclipse-jnosql/jnosql-extensions","eclipse/jnosql-extensions"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/eclipse-jnosql/jnosql-extensions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-jnosql%2Fjnosql-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-jnosql%2Fjnosql-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-jnosql%2Fjnosql-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-jnosql%2Fjnosql-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-jnosql","download_url":"https://codeload.github.com/eclipse-jnosql/jnosql-extensions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-jnosql%2Fjnosql-extensions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31500397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jakartaee","java","jnosql","microprofile"],"created_at":"2024-12-17T17:06:29.865Z","updated_at":"2026-04-07T04:31:34.057Z","avatar_url":"https://github.com/eclipse-jnosql.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Mapping Extension API\n:toc: auto\n\nThe 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.\n\n== JNoSQL Lite\n\nThis 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.\n\nThe extension approach aims to achieve the following goals:\n\n- **Eliminate Reflection:** Remove the dependency on Reflection within the database engine or dependency, leading to improved performance and reduced runtime overhead.\n\n- **Enhance CDI Lite Compatibility:** Achieve compatibility with CDI Lite, making integrating Eclipse JNoSQL into CDI Lite-enabled environments easier.\n\nAdopting the extension approach provides several benefits:\n\n- **Improved Performance:** By eliminating Reflection, the Extension approach results in faster startup times and reduced runtime overhead, leading to better overall application performance.\n\n- **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.\n\n- **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.\n\n- **Enhanced Maintainability:** Java Annotation Processors simplify codebase maintenance and debugging by replacing reflection-based operations with compile-time checks and optimizations.\n\n=== Extension Steps\n\nTo use this Extension, follow a two-step process:\n\n==== Step 1: Remove Reflection Engine\n\nStart by removing the reflection engine from the database engine or dependency. To do this, follow these steps:\n\n1. Check the available databases at link:https://github.com/eclipse/jnosql-databases[]\n2. Choose the database you intend to use.\n3. Exclude the reflection engine dependency in your Maven project:\n\n[source,xml]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.eclipse.jnosql.databases\u003c/groupId\u003e\n    \u003cartifactId\u003echosen-database-artifact-id\u003c/artifactId\u003e\n    \u003cversion\u003echosen-database-version\u003c/version\u003e\n    \u003cexclusions\u003e\n        \u003cexclusion\u003e\n            \u003cgroupId\u003eorg.eclipse.jnosql.mapping\u003c/groupId\u003e\n            \u003cartifactId\u003ejnosql-mapping-reflection\u003c/artifactId\u003e\n        \u003c/exclusion\u003e\n    \u003c/exclusions\u003e\n\u003c/dependency\u003e\n----\n\n==== Step 2: Include Java Annotation Processor\n\nAfter removing the reflection engine, include the Java Annotation Processor. There are two ways to do this:\n\n1. Define the processor as a provided dependency:\n\n[source,xml]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.eclipse.jnosql.lite\u003c/groupId\u003e\n    \u003cartifactId\u003emapping-lite-processor\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.13\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n----\n\n2. Include the processor as a Maven plugin:\n\n[source,xml]\n----\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n            \u003cartifactId\u003emaven-compiler-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e3.8.1\u003c/version\u003e\n            \u003cconfiguration\u003e\n                \u003csource\u003e17\u003c/source\u003e \u003c!-- depending on your project --\u003e\n                \u003ctarget\u003e17\u003c/target\u003e \u003c!-- depending on your project --\u003e\n                \u003cannotationProcessorPaths\u003e\n                    \u003cpath\u003e\n                    \u003cgroupId\u003eorg.eclipse.jnosql.lite\u003c/groupId\u003e\n                    \u003cartifactId\u003emapping-lite-processor\u003c/artifactId\u003e\n                    \u003cversion\u003e1.1.13\u003c/version\u003e\n                    \u003c/path\u003e\n                    \u003c!-- other annotation processors --\u003e\n                \u003c/annotationProcessorPaths\u003e\n            \u003c/configuration\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n----\n\n=== Usage and Limitations\n\nWith the Extension, you can now leverage Eclipse JNoSQL Lite's benefits. However, be aware of the following limitations in the entity model:\n\n- Java Record is not supported.\n- A default constructor is required.\n- All persistent fields with ID or Column annotations must have a getter and setter, at least in the default access modifier.\n\nWARNING: Keep in mind these limitations when designing and implementing your application.\n\n\nAdditionally, you can use Repositories from Jakarta Data, but note that certain limitations apply to entity modeling:\n\n- There is no support for Sort in List or in Array.\n- Graph and Key-Value Repositories do not support method by query.\n\nNow you're ready to explore the enhanced features of Eclipse JNoSQL Lite and leverage its benefits without relying on Reflection.\n\n\n== JNoSQL Static Metamodel\n\nThe 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.\n\n=== Installing the Metamodel Processor\n\nTo 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:\n\n[source,xml]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.eclipse.jnosql.metamodel\u003c/groupId\u003e\n    \u003cartifactId\u003emapping-metamodel-processor\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.13\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n----\n\nWith 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.\n\n=== Example Usage\n\nGiven an entity class, such as:\n\n[source,java]\n----\n@Entity\npublic class Product {\n    public long id;\n    public String name;\n    public float price;\n}\n----\n\nYou 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:\n\n[source,java]\n----\nList\u003cProduct\u003e found = products.findByNameLike(searchPattern, Order.by(\n    _Product.price.desc(),\n    _Product.name.asc(),\n    _Product.id.asc()));\n----\n\nThis approach ensures that query attribute references are both type-safe and refactor-safe, leading to more robust and maintainable code.\n\n== Bean Validation\n\nEclipse JNoSQL provide support for bean validation. It will validate before inserting/updating and constructing an entity.\n\n[source,xml]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.eclipse.jnosql.mapping\u003c/groupId\u003e\n    \u003cartifactId\u003ejnosql-mapping-validation\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.13\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\nThis requires the https://jakarta.ee/specifications/bean-validation/[Jakarta Bean Validation] specification.\n\n[source,java]\n----\n@Entity\npublic class Car {\n\n    @Column\n    @NotNull\n    @Pattern(regexp = \"[A-Z]{3}-[0-9]{4}\", message = \"Invalid car plate\")\n    private String plate;\n\n    @Column\n    @NotNull\n    @MonetaryMin(value = \"100\", message = \"There is not car cheap like that\")\n    @MonetaryMax(value = \"1000000\", message = \"The parking does not support fancy car\")\n    @CurrencyAccepted(currencies = \"USD\", message = \"The car price must work with USD\")\n    @Convert(MonetaryAmountConverter.class)\n    private MonetaryAmount price;\n\n    @Column\n    @NotBlank\n    private String model;\n\n    @Column\n    @NotBlank\n    private String color;\n    ...\n}\n----\n\n[source,java]\n----\n@Inject\nTemplate template;\n...\ntemplate.insert(new Car()); // invalid car\n----\n\n== CriteriaQuery API\n\nThis is the experimental Criteria API, largely inspired by the JPA one.\nUsing this API you can execute queries built via CriteriaQuery.\nThe CriteriaQuery is used in combination with Metamodel Attributes.\nThese attributes are automagically generated from the defined NoSQL Entities.\n\nThe Criteria API can be used via CriteriaDocumentTemplate.\n\n=== Set dependency\n\n\n[source,xml]\n----\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.eclipse.jnosql.mapping\u003c/groupId\u003e\n    \u003cartifactId\u003ejnosql-metamodel-processor-extension\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.13\u003c/version\u003e\n    \u003coptional\u003etrue\u003c/optional\u003e\n  \u003c/dependency\u003e\n  \u003cdependency\u003e\n      \u003cgroupId\u003eorg.eclipse.jnosql.mapping\u003c/groupId\u003e\n      \u003cartifactId\u003ejnosql-criteria-extension\u003c/artifactId\u003e\n      \u003cversion\u003e1.1.13\u003c/version\u003e\n  \u003c/dependency\u003e\n----\n\n== Apache Tinkerpop Connections\n\nApache Tinkerpop Connections is a project that provides multiple `GraphConfiguration` implementations for working with various graph databases, including ArangoDB, JanusGraph, Titan, and Neo4J. It simplifies the configuration and connection process, leveraging MicroProfile Config or Jakarta Config APIs for externalized configuration.\n\n[source,xml]\n----\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.eclipse.jnosql.mapping\u003c/groupId\u003e\n  \u003cartifactId\u003ejnosql-tinkerpop-connections\u003c/artifactId\u003e\n  \u003cversion\u003e1.1.13\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\n=== Supported Databases and Configurations\n\n==== ArangoDB\n\n[cols=\"2,6\"]\n|===\n|Configuration Property |Description\n\n|`jnosql.arangodb.graph.edge`\n|The edge collection. It acts as a prefix. Example: `jnosql.arangodb.graph.edge.1=edge`.\n\n|`jnosql.arangodb.graph.relationship`\n|Specifies the edge collection, source vertex collection, and target vertex collection, separated by a pipe (`|`). Example: `jnosql.arangodb.graph.relationship.1=Person|knows|Person`.\n\n|`jnosql.arangodb.graph.vertex`\n|The vertex collection. It acts as a prefix. Example: `jnosql.arangodb.graph.vertex.1=vertex`.\n\n|`jnosql.arangodb.graph.graph`\n|The name of the graph to use.\n\n|`jnosql.arangodb.graph.host`\n|The database host.\n\n|`jnosql.arangodb.graph.user`\n|The username for the database.\n\n|`jnosql.arangodb.graph.password`\n|The password for the database.\n|===\n\nHere is an example configuration using ArangoDB's Graph API with MicroProfile Config:\n\n[source,properties]\n----\njnosql.graph.provider=org.eclipse.jnosql.mapping.tinkerpop.connections.ArangoDBGraphConfiguration\njnosql.arangodb.graph.graph=marketing\njnosql.arangodb.graph.vertex.1=Person\njnosql.arangodb.graph.edge.1=knows\njnosql.arangodb.graph.relationship.1=Person|knows|Person\n----\n\n==== JanusGraph\n\nJanusGraph is a scalable graph database supporting various storage backends like Cassandra, HBase, and BerkeleyDB.\n\nWARNING: The configuration API passes and uses the properties from `org.janusgraph.graphdb.configuration.GraphDatabaseConfiguration`.\n\nExample configuration with MicroProfile Config:\n\n[source,properties]\n----\njnosql.graph.provider=org.eclipse.jnosql.mapping.tinkerpop.connections.JanusGraphConfiguration\ngraphname=name\nallow-upgrade=false\n----\n\n==== Titan\n\nTitan is a distributed graph database designed for processing large-scale graphs.\n\nWARNING: The configuration API passes and uses the properties from `com.thinkaurelius.titan.graphdb.configuration.GraphDatabaseConfiguration`.\n\nExample configuration with MicroProfile Config:\n\n[source,properties]\n----\njnosql.graph.provider=org.eclipse.jnosql.mapping.tinkerpop.connections.TitanGraphConfiguration\n----\n\n==== Neo4J\n\n[cols=\"2,6\"]\n|===\n|Configuration Property |Description\n\n|`jnosql.neo4j.host`\n|The database host. Default: `bolt://localhost:7687`.\n\n|`jnosql.neo4j.user`\n|The username for the database. Default: `neo4j`.\n\n|`jnosql.neo4j.password`\n|The password for the database. Default: `neo4j`.\n|===\n\nExample configuration using Neo4J's Graph API with MicroProfile Config:\n\n[source,properties]\n----\njnosql.graph.provider=org.eclipse.jnosql.mapping.tinkerpop.connections.Neo4JGraphConfiguration\njnosql.neo4j.user=neo4j\njnosql.neo4j.password=neo4j\njnosql.neo4j.host=bolt://localhost:7687\n----\n\n==== Neo4J Embedded\n\nNeo4J Embedded mode is used for running Neo4J locally without a remote server. It is ideal for testing and prototyping.\n\n[cols=\"2,6\"]\n|===\n|Configuration Property |Description\n\n|`jnosql.neo4j.host`\n|The file path to the Neo4J database directory.\n|===\n\nExample configuration using Neo4J Embedded Graph API with MicroProfile Config:\n\n[source,properties]\n----\njnosql.graph.provider=org.eclipse.jnosql.mapping.tinkerpop.connections.Neo4JEmbeddedGraphConfiguration\njnosql.neo4j.host=/home/otaviojava/data/\n----\n\n== Jakarta Persistence\n\nThe `jakarta-persistence` module integrates Jakarta Persistence into the Eclipse JNoSQL ecosystem.\n\nWhy does this matter? Because Eclipse JNoSQL already provides multiple drivers that communicate with databases in different ways. For relational databases, JDBC is the natural choice, and Jakarta Persistence builds directly on top of it. Some *NewSQL* solutions also rely on JDBC, and even certain *NoSQL databases* expose JDBC drivers as an integration point.\n\nBy bridging Jakarta Persistence into Eclipse JNoSQL, we enable developers to use the **Jakarta Data** specification as the main programming model. Jakarta Data repositories (`CrudRepository`, `Repository`, etc.) can run on top of any Jakarta Persistence provider, meaning developers interact with high-level repositories while the module handles the underlying persistence plumbing.\n\nThis lowers the adoption barrier: instead of writing low-level database code, you can use the familiar Jakarta Data abstractions, which then leverage Jakarta Persistence behind the scenes.\n\n=== How To Use\n\nAdd the dependency to your project:\n\n[source,xml]\n----\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.eclipse.jnosql.mapping\u003c/groupId\u003e\n  \u003cartifactId\u003ejnosql-jakarta-persistence\u003c/artifactId\u003e\n  \u003cversion\u003e1.1.13\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\nThis is **not meant to be used directly** in your application, but it must be produced so that Jakarta Data can initialize repositories correctly:\n\n[source,java]\n----\n@ApplicationScoped\npublic class EntityManagerProducer {\n\n    @Produces\n    @ApplicationScoped\n    public EntityManager createEntityManager() {\n        return Persistence.createEntityManagerFactory(\"testPersistenceUnit\")\n                          .createEntityManager();\n    }\n\n    public void closeEntityManager(@Disposes EntityManager entityManager) {\n        entityManager.close();\n    }\n}\n----\n\nConfigure your persistence unit via `persistence.xml`:\n\n[source,xml]\n----\n\u003cpersistence xmlns=\"http://java.sun.com/xml/ns/persistence\"\n             xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n             xsi:schemaLocation=\"http://java.sun.com/xml/ns/persistence\n                                 http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd\"\n             version=\"2.0\"\u003e\n  \u003cpersistence-unit name=\"testPersistenceUnit\" transaction-type=\"RESOURCE_LOCAL\"\u003e\n     ... your configuration here ...\n  \u003c/persistence-unit\u003e\n\u003c/persistence\u003e\n----\n\n=== Example With Jakarta Data\n\nOnce configured, you can declare repositories with Jakarta Data and let the module handle the interaction with Jakarta Persistence under the hood:\n\n[source,java]\n----\n@Entity\npublic class Book {\n    @Id\n    private Long id;\n    private String title;\n}\n----\n\n[source,java]\n----\n@Repository\npublic interface Library extends CrudRepository\u003cBook, Long\u003e {\n    List\u003cBook\u003e findByTitle(String title);\n}\n----\n\nUsage:\n\n[source,java]\n----\n@Inject\nLibrary library;\n\nlibrary.save(new Book(1L, \"Domain-Driven Design with JNoSQL\"));\nList\u003cBook\u003e results = books.findByTitle(\"Domain-Driven Design with JNoSQL\");\n----\n\nWith this approach, developers work with Jakarta Data repositories, while Jakarta Persistence is only used as the provider under the covers.\nThis ensures compatibility with relational, NewSQL, and even some NoSQL databases that provide JDBC drivers, all without forcing developers to use `EntityManager` directly.\n\n== TCK Runners\n\nThe 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.\n\n=== Jakarta Data TCK Runner\n\nThe 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].\n\n\n== Getting Help\n\nHaving trouble with Eclipse JNoSQL extensions? We’d love to help!\n\nPlease report any bugs, concerns or questions with Eclipse JNoSQL extensions to https://github.com/eclipse/jnosql[https://github.com/eclipse/jnosql].\nFollow the instructions in the templates and remember to mention that the issue refers to JNoSQL extensions.\n\n== Contributing\n\nWe are very happy you are interested in helping us and there are plenty ways you can do so.\n\n- 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.\n\n- **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.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-jnosql%2Fjnosql-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-jnosql%2Fjnosql-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-jnosql%2Fjnosql-extensions/lists"}