├── .github ├── ISSUE_TEMPLATE │ ├── bug-report.md │ ├── certification.yml │ ├── clarification.md │ ├── tck-challenge.yml │ └── use-case.md └── workflows │ ├── java-17.yml │ └── java-21.yml ├── .gitignore ├── CHANGELOG.adoc ├── CONTRIBUTING.adoc ├── LICENSE ├── NOTICE.adoc ├── README.adoc ├── SECURITY.adoc ├── TESTING-GUIDELINE.adoc ├── api ├── .gitignore ├── pom.xml └── src │ └── main │ ├── java │ ├── jakarta │ │ └── nosql │ │ │ ├── AttributeConverter.java │ │ │ ├── Column.java │ │ │ ├── Convert.java │ │ │ ├── DiscriminatorColumn.java │ │ │ ├── DiscriminatorValue.java │ │ │ ├── Embeddable.java │ │ │ ├── Entity.java │ │ │ ├── Id.java │ │ │ ├── Inheritance.java │ │ │ ├── MappedSuperclass.java │ │ │ ├── MappingException.java │ │ │ ├── NoSQLException.java │ │ │ ├── QueryMapper.java │ │ │ ├── Template.java │ │ │ └── package-info.java │ └── module-info.java │ └── javadoc │ └── doc-files │ └── speclicense.html ├── pmd └── pmd-rules.xml ├── pom.xml ├── spec ├── README.adoc ├── pom.xml └── src │ ├── main │ ├── asciidoc │ │ ├── chapters │ │ │ ├── api │ │ │ │ ├── annotations.adoc │ │ │ │ ├── entity.adoc │ │ │ │ ├── jakarta--ee.adoc │ │ │ │ └── template.adoc │ │ │ ├── introduction │ │ │ │ ├── introduction.adoc │ │ │ │ └── project_team.adoc │ │ │ └── license │ │ │ │ ├── license-alv2.asciidoc │ │ │ │ └── license-efsl.adoc │ │ ├── images │ │ │ ├── jakarta_ee_logo_schooner_color_stacked_default.png │ │ │ ├── jnosql.png │ │ │ ├── jpa.svg │ │ │ ├── logic_tier.svg │ │ │ ├── nosql_issue.svg │ │ │ ├── tiers.svg │ │ │ └── title_image.png │ │ └── jakarta_nosql_spec.adoc │ └── resources │ │ └── META-INF │ │ ├── LICENSE │ │ └── NOTICE │ └── theme │ └── jakartaee-theme.yml └── tck ├── .gitignore ├── README.adoc ├── pom.xml └── src ├── main └── java │ └── ee │ └── jakarta │ └── tck │ └── nosql │ ├── AbstractTemplateTest.java │ ├── NoSQLType.java │ ├── TemplateSupplier.java │ ├── basic │ ├── BasicConverterFieldTemplateTest.java │ ├── BasicEnumFieldTemplateTest.java │ ├── BasicIterableEntityTemplateTest.java │ ├── BasicTemplateInheritanceTest.java │ ├── BasicTemplateMappedSuperclassTest.java │ ├── BasicTemplateRecordTest.java │ ├── BasicTemplateTest.java │ └── package-info.java │ ├── delete │ ├── DeleteFieldConvertTest.java │ ├── DeleteRecordTest.java │ ├── DeleteTemplateInheritanceTest.java │ ├── DeleteTemplateMappedSuperclassTest.java │ ├── DeleteTemplateTest.java │ └── package-info.java │ ├── entities │ ├── AbstractAnimal.java │ ├── Animal.java │ ├── Beer.java │ ├── Book.java │ ├── Coffee.java │ ├── Drink.java │ ├── Fruit.java │ ├── Money.java │ ├── MoneyConverter.java │ ├── Person.java │ ├── Transmission.java │ ├── Vehicle.java │ └── package-info.java │ ├── factories │ ├── AbstractListSupplier.java │ ├── AbstractSupplier.java │ ├── AnimalListSupplier.java │ ├── AnimalSupplier.java │ ├── BookListSupplier.java │ ├── BookSupplier.java │ ├── DrinkListSupplier.java │ ├── DrinkSupplier.java │ ├── FruitListSupplier.java │ ├── FruitSupplier.java │ ├── PersonListSupplier.java │ ├── PersonSupplier.java │ ├── VehicleListSupplier.java │ ├── VehicleSupplier.java │ └── package-info.java │ ├── package-info.java │ └── select │ ├── SelectEnumTest.java │ ├── SelectFieldConvertTest.java │ ├── SelectMappedSuperclassTest.java │ ├── SelectNegateTemplateTest.java │ ├── SelectRecordTest.java │ ├── SelectTemplateInheritanceTest.java │ ├── SelectTemplateTest.java │ └── package-info.java └── test └── java └── ee └── jakarta └── tck └── nosql ├── NoSQLTypeTest.java └── entities └── MoneyConverterTest.java /.github/ISSUE_TEMPLATE/bug-report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Report a mistake or inconsistency in the specification code or documentation text. 4 | title: '' 5 | labels: 'bug :beetle:' 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | 12 | **Describe the bug** 13 | 14 | (Describe the problem as concisely as possible.) 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/certification.yml: -------------------------------------------------------------------------------- 1 | name: Platform Certification 2 | description: Jakarta Data Platform Certification 3 | title: "[Certification]: " 4 | labels: ["certification"] #TODO need to add this label 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: > 9 | Before submitting a Platform Certification to the Jakarta Data community 10 | please read and be familiar with the 11 | [TCK Process document](https://jakarta.ee/committees/specification/tckprocess) 12 | which may be updated occasionally. 13 | - type: input 14 | id: organization 15 | validations: 16 | required: true 17 | attributes: 18 | label: Organization 19 | description: Organization name and URL (if applicable) 20 | - type: input 21 | id: implementation 22 | validations: 23 | required: true 24 | attributes: 25 | label: Implementation 26 | description: Product name, version, and download URL (if applicable) 27 | - type: input 28 | id: specification 29 | validations: 30 | required: true 31 | attributes: 32 | label: Specification 33 | description: Specification name, version, and download URL (if applicable) 34 | - type: input 35 | id: tck 36 | validations: 37 | required: true 38 | attributes: 39 | label: Technology Compatibility Kit (TCK) 40 | description: TCK name, version, and download URL (if applicable) 41 | - type: input 42 | id: tckSHA 43 | validations: 44 | required: true 45 | attributes: 46 | label: Technology Compatibility Kit (TCK) Validation 47 | description: TCK SHA-256 fingerprint 48 | - type: textarea 49 | id: tckResults 50 | validations: 51 | required: true 52 | attributes: 53 | label: Technology Compatibility Kit (TCK) Results 54 | description: | 55 | Public URL of TCK Results Summary 56 | TIP: You can attach TCK Results to this issue by clicking this area to highlight it and then dragging files in. 57 | # TODO determine if we wil have any additional certification requirements 58 | # Will users need to test against a NoSQL/SQL database? 59 | - type: textarea 60 | id: additionalRequirements 61 | validations: 62 | required: true 63 | attributes: 64 | label: Additional Specification Requirements 65 | description: > 66 | Specification projects may require additional items for a Certification Request 67 | as defined in their corresponding TCK Documentation under the section labeled "Additional Certification Requirements". 68 | - type: textarea 69 | id: javaRuntime 70 | validations: 71 | required: true 72 | attributes: 73 | label: Java Runtime(s) 74 | description: | 75 | Java runtime(s) used to run the implementation. 76 | Output from `java -version` 77 | - type: textarea 78 | id: environment 79 | validations: 80 | required: true 81 | attributes: 82 | label: Environments 83 | description: Summary of the information for the certification environment, operating system, cloud, etc. 84 | - type: checkboxes 85 | id: ackEFTL 86 | attributes: 87 | label: Eclipse Foundation Technology Compatibility Kit License (EFTL) 88 | description: Do you accept the terms of the (EFTL)? 89 | options: 90 | - label: By checking this box I acknowledge that the organization I represent accepts the terms of the [EFTL](https://www.eclipse.org/legal/tck.php) 91 | required: true 92 | - type: checkboxes 93 | id: ackRules 94 | attributes: 95 | label: TCK Requirements and Compatibility 96 | options: 97 | - label: By checking this box I attest that all TCK requirements have been met, including any compatibility rules. 98 | required: true -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/clarification.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Clarification request 3 | about: Request that some aspect of the specification be clarified. 4 | title: '' 5 | labels: 'clarification :mag_right:' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Description** 11 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/tck-challenge.yml: -------------------------------------------------------------------------------- 1 | name: TCK Challenge 2 | description: Jakarta Data TCK Challenge 3 | title: "[TCK Challenge]: " 4 | labels: ["challenge"] #TODO need to add this label 5 | body: 6 | - type: markdown 7 | attributes: 8 | value: > 9 | Before submitting a TCK Challenge to the Jakarta Data community 10 | please read and be familiar with the 11 | [TCK Process document](https://jakarta.ee/committees/specification/tckprocess) 12 | which may be updated occasionally. 13 | - type: input 14 | id: specification 15 | validations: 16 | required: true 17 | attributes: 18 | label: Specification 19 | description: What specification is the challenge related to? Provide a link to the specification class or document section. 20 | placeholder: | 21 | ex. [Entity value](https://github.com/jakartaee/data/blob/main/api/src/main/java/jakarta/data/Entity.java#L33) 22 | - type: input 23 | id: assertion 24 | validations: 25 | required: true 26 | attributes: 27 | label: Assertion 28 | description: What assertion is the challenge related to? Provide a link to the assertion description 29 | placeholder: | 30 | ex. [Signature tests](https://github.com/jakartaee/data/blob/main/tck/src/main/java/ee/jakarta/tck/data/standalone/signature/SignatureTests.java#L50) 31 | - type: dropdown 32 | id: version 33 | validations: 34 | required: true 35 | attributes: 36 | label: TCK Version 37 | description: What version of the TCK are you running against? 38 | options: #TODO need to update this list per release 39 | - 1.0.0-SNAPSHOT (Locally built) 40 | - 1.0.0-RC1 (Release candidate) 41 | - 1.0.0 (Generally available) 42 | - type: input 43 | id: implementation 44 | validations: 45 | required: true 46 | attributes: 47 | label: Implementation being tested 48 | description: What implementation is being tested? Include name of company/organization 49 | placeholder: | 50 | ex. Open Liberty / IBM 51 | - type: dropdown 52 | id: challengeType 53 | validations: 54 | required: true 55 | attributes: 56 | label: Challenge Scenario 57 | description: Which of the following scenarios best match this challenge? 58 | options: 59 | - Claims that a test assertion conflicts with the specification. 60 | - Claims that a test asserts requirements over and above that of the specification. 61 | - Claims that an assertion of the specification is not sufficiently implementable. 62 | - Claims that a test is not portable or depends on a particular implementation. 63 | - Something else 64 | - type: textarea 65 | id: fullDescription 66 | validations: 67 | required: true 68 | attributes: 69 | label: Full Description 70 | description: | 71 | Describe the challenge in full detail including logs. 72 | Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. 73 | value: | 74 | > Description of issue using markdown syntax 75 | - type: textarea 76 | id: additionalContext 77 | attributes: 78 | label: Additional Context 79 | description: Additional context about the problem, possible solutions, alternative interpretations, etc. 80 | - type: checkboxes 81 | attributes: 82 | label: Is there an existing challenge for this? 83 | description: | 84 | Please search to see if a challenge already exists, or has been approved, that matches your challenge. 85 | https://github.com/jakartaee/data/issues?q=is%3Aissue+label%3Achallenge 86 | options: 87 | - label: I have searched the existing issues 88 | required: true -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/use-case.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Use case 3 | about: Describe a new use case for the specification. 4 | title: '' 5 | labels: 'use case :bulb:' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Description** 11 | 12 | As a: 13 | 14 | - [ ] Application user/user of the configuration itself 15 | - [ ] API user (application developer) 16 | - [ ] SPI user (container or runtime developer) 17 | - [ ] Specification implementer 18 | 19 | ...I need to be able to: 20 | 21 | 22 | 23 | ...which enables me to: 24 | 25 | 26 | -------------------------------------------------------------------------------- /.github/workflows/java-17.yml: -------------------------------------------------------------------------------- 1 | # This workflow will build a Java project with Maven 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven 3 | 4 | name: Java 17 CI with Maven 5 | 6 | on: 7 | push: 8 | branches: [ main ] 9 | pull_request: 10 | branches: [ main ] 11 | 12 | jobs: 13 | build: 14 | 15 | runs-on: ubuntu-latest 16 | 17 | steps: 18 | - uses: actions/checkout@v3 19 | - name: Set up JDK 17 20 | uses: actions/setup-java@v3 21 | with: 22 | distribution: 'temurin' 23 | java-version: 17 24 | - name: Build with Maven 25 | run: mvn -B package --file pom.xml 26 | -------------------------------------------------------------------------------- /.github/workflows/java-21.yml: -------------------------------------------------------------------------------- 1 | # This workflow will build a Java project with Maven 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven 3 | 4 | name: Java 21 CI with Maven 5 | 6 | on: 7 | push: 8 | branches: [ main ] 9 | pull_request: 10 | branches: [ main ] 11 | 12 | jobs: 13 | build: 14 | 15 | runs-on: ubuntu-latest 16 | 17 | steps: 18 | - uses: actions/checkout@v3 19 | - name: Set up JDK 21 20 | uses: actions/setup-java@v3 21 | with: 22 | distribution: 'temurin' 23 | java-version: 21 24 | - name: Build with Maven 25 | run: mvn -B package --file pom.xml 26 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | target/ 2 | pom.xml.tag 3 | pom.xml.releaseBackup 4 | pom.xml.versionsBackup 5 | pom.xml.next 6 | test-output/ 7 | /doc 8 | *.iml 9 | *.idea 10 | *.log 11 | /.idea 12 | .checkstyle 13 | 14 | # Eclipse metadata 15 | .settings/ 16 | .project 17 | .factorypath 18 | .classpath 19 | -project 20 | /.resourceCache 21 | /.project 22 | **/.DS_Store 23 | # Annotation processor metadata 24 | .apt_generated/ 25 | .apt_generated_tests/ 26 | -------------------------------------------------------------------------------- /CHANGELOG.adoc: -------------------------------------------------------------------------------- 1 | = Changelog 2 | :toc: auto 3 | 4 | All notable changes to this project will be documented in this file. 5 | 6 | The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog], 7 | and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning]. 8 | 9 | == [Unreleased] 10 | 11 | == [1.0.0-M1] - 2024-03-23 12 | 13 | === Removed 14 | 15 | - Remove document API 16 | - Remove column API 17 | - Remove key-value API 18 | 19 | === Changed 20 | 21 | - Define Entity by Jakarta NoSQL 22 | - Define inheritance by Jakarta NoSQL 23 | - Define MappedSuperclass by Jakarta NoSQL 24 | - Define Embeddable by Jakarta NoSQL 25 | 26 | === Added 27 | 28 | - add MappedSuperclass, Embeddable, Inheritance, DiscriminatorColumn, DiscriminatorValue annotations 29 | 30 | == [1.0.0-b7] - 2023-06-22 31 | 32 | === Added 33 | 34 | * Create test to Java 20 35 | * Include Javadoc at Modules 36 | 37 | === Changed 38 | 39 | * Define Java 17 as minimum requirement 40 | * improve Javadoc to explore the relation among Templates 41 | * Improve specification 42 | * Improve documentation and Java Doc 43 | 44 | == [1.0.0-b6] - 2023-02-07 45 | 46 | === Changed 47 | 48 | - Update Jakarta API to after the Big-bang 49 | - Define high level API 50 | - Change the package name to "jakarta.nosql" 51 | 52 | === Added 53 | 54 | - Add select mapper using fluent-API on Template 55 | - Add delete mapper using fluent-API on Template 56 | - Add Jakarta Data as dependency 57 | 58 | === Removed 59 | 60 | - Remove communication API level. 61 | - Remove ColumnQueryMapper 62 | - Remove DocumentQueryMapper 63 | - Remove communication API 64 | - Remove the TCK tests on this repository 65 | 66 | == [1.0.0-b5] - 2022-12-22 67 | 68 | === Added 69 | 70 | - Add support to persist by constructor 71 | 72 | === Changed 73 | 74 | - Create a CHANGELOG file to track the specification evolution 75 | - Move the default documentation to ASCIIDOC 76 | - Add supplier at Settings API 77 | - Change the Configurations APIs to be a supplier 78 | - Update the nomenclature on the Document and Column APIs 79 | 80 | 81 | === Removed 82 | 83 | - Remove the settings methods to avoid mutability in the instance. 84 | 85 | === Deprecated 86 | 87 | - Deprecate the repository interfaces that will belong to Jakarta Data 88 | 89 | == [1.0.0-b4] - 2022-06-04 90 | 91 | === Changed 92 | - Improve Query to both Document and Column communication API 93 | - Parasite property in document deserialization 94 | - Documentation improvement 95 | 96 | == [1.0.0-b3] - 2021-03-01 97 | 98 | === Added 99 | - Creates TCK Mapping 100 | - Creates TCK Communication 101 | - Creates TCK Driver 102 | 103 | === Changed 104 | - Remove JNoSQL logo from repositories 105 | - Remove "Artemis" references in the package and use "mapping" instead 106 | - Remove "diana" references in the package name and use "communication" instead. 107 | - Update Cassandra library to use DataStax OSS 108 | 109 | === Fixed 110 | - Fixes HashMap issue in the mapping API 111 | 112 | == [1.0.0-b2] - 2020-06-07 113 | 114 | === Added 115 | - Creates TCK Mapping 116 | - Creates TCK Communication 117 | - Creates TCK Driver 118 | 119 | === Changed 120 | 121 | - Update Javadoc documentation 122 | - Update Ref documentation 123 | - Remove Async APIs 124 | - Keep the compatibility with Java 11 and Java 8 125 | 126 | == [1.0.0-b1] - 2019-12-01 127 | 128 | === Added 129 | 130 | - Creates communication API 131 | - Creates Mapping API 132 | - Creates Spec 133 | -------------------------------------------------------------------------------- /CONTRIBUTING.adoc: -------------------------------------------------------------------------------- 1 | = Contributing to Jakarta NoSQL 2 | 3 | Thanks for your interest in this project. 4 | 5 | == Project description 6 | 7 | Create the specification in Jakarta EE to help Jakarta EE developers create 8 | enterprise-grade applications using Java® and NoSQL technologies. It helps them 9 | create scalable applications while maintaining low coupling with the underlying 10 | NoSQL technology. 11 | 12 | * https://projects.eclipse.org/projects/ee4j.nosql 13 | 14 | == Developer resources 15 | 16 | Information regarding source code management, builds, coding standards, and 17 | more. 18 | 19 | * https://projects.eclipse.org/projects/ee4j.nosql/developer 20 | 21 | The project maintains the following source code repositories 22 | 23 | 24 | == Eclipse Contributor Agreement 25 | 26 | Before your contribution can be accepted by the project team contributors must 27 | electronically sign the Eclipse Contributor Agreement (ECA). 28 | 29 | * http://www.eclipse.org/legal/ECA.php 30 | 31 | Commits that are provided by non-committers must have a Signed-off-by field in 32 | the footer indicating that the author is aware of the terms by which the 33 | contribution has been provided to the project. The non-committer must 34 | additionally have an Eclipse Foundation account and must have a signed Eclipse 35 | Contributor Agreement (ECA) on file. 36 | 37 | For more information, please see the Eclipse Committer Handbook: 38 | https://www.eclipse.org/projects/handbook/#resources-commit 39 | 40 | == Contact 41 | 42 | Contact the project developers via the project's "dev" list. 43 | 44 | * https://accounts.eclipse.org/mailing-list/nosql-dev 45 | -------------------------------------------------------------------------------- /NOTICE.adoc: -------------------------------------------------------------------------------- 1 | = Notices for Eclipse Jakarta NoSQL 2 | 3 | This content is produced and maintained by the Eclipse Jakarta NoSQL project. 4 | 5 | * Project home: https://projects.eclipse.org/projects/ee4j.nosql 6 | 7 | == Trademarks 8 | 9 | Eclipse Jakarta NoSQL, and Jakarta NoSQL are trademarks of the Eclipse 10 | Foundation. 11 | 12 | == Copyright 13 | 14 | All content is the property of the respective authors or their employers. For 15 | more information regarding authorship of content, please consult the listed 16 | source code repository logs. 17 | 18 | == Declared Project Licenses 19 | 20 | This program and the accompanying materials are made available under the terms 21 | of the Eclipse Public License v. 2.0 which is available at 22 | http://www.eclipse.org/legal/epl-2.0. This Source Code may also be made 23 | available under the following Secondary Licenses when the conditions for such 24 | availability set forth in the Eclipse Public License v. 2.0 are satisfied: GNU 25 | General Public License, version 2 with the GNU Classpath Exception which is 26 | available at https://www.gnu.org/software/classpath/license.html. 27 | 28 | SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 29 | 30 | == Source Code 31 | 32 | The project maintains the following source code repositories: 33 | 34 | 35 | == Third-party Content 36 | 37 | This project leverages the following third party content. 38 | 39 | None 40 | 41 | == Cryptography 42 | 43 | Content may contain encryption software. The country in which you are currently 44 | may have restrictions on the import, possession, and use, and/or re-export to 45 | another country, of encryption software. BEFORE using any encryption software, 46 | please check the country's laws, regulations and policies concerning the import, 47 | possession, or use, and re-export of encryption software, to see if this is 48 | permitted. -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta NoSQL 2 | :toc: auto 3 | 4 | ifndef::imagesdir[:imagesdir: spec/src/main/asciidoc/images] 5 | image::jakarta_ee_logo_schooner_color_stacked_default.png[Jakarta NoSQL logo,align=center, width=25%, height=25%] 6 | 7 | == Introduction 8 | 9 | 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. 10 | 11 | == Goals 12 | 13 | * Increase productivity performing common NoSQL operations. 14 | * Rich Object Mapping integrated. 15 | * Java-based Query and Fluent-API. 16 | * It is designed to work with various NoSQL databases and can quickly adapt to support new types and behaviors through extensions. 17 | * Annotation-oriented using Jakarta Persistence-like naming when it makes sense. 18 | 19 | == One Mapping API to Multiples NoSQL Databases 20 | 21 | 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. 22 | 23 | [source,java] 24 | ---- 25 | @Entity 26 | public class Car { 27 | 28 | @Id 29 | private Long id; 30 | @Column 31 | private String name; 32 | @Column 33 | private CarType type; 34 | //... 35 | } 36 | 37 | ---- 38 | 39 | === Annotations 40 | 41 | The annotations from the Mapping API will look familiar to Jakarta Persistence developers: 42 | 43 | [cols="2"] 44 | |=== 45 | | Annotation | Description 46 | | `@Entity` | Specifies that the class is an entity. This annotation is applied to the entity class. 47 | | `@Id` | Specifies the primary key of an entity. 48 | | `@Column` | Specifies the mapped column for a persistent property or field. 49 | | `@MappedSuperclass` | Specifies a class whose mapping information is applied to entities that inherit from it. 50 | | `@Embeddable` | Declares a class whose instances are stored as an intrinsic part of an owning entity, sharing the identity of the entity. 51 | | `@Inheritance` | Specifies the inheritance mapping strategy for the entity class hierarchy. 52 | | `@DiscriminatorColumn` | Specifies the discriminator column for the mapping strategy. 53 | | `@DiscriminatorValue` | Specifies the value of the discriminator column for the annotated entity type. 54 | | `@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. 55 | |=== 56 | 57 | These annotations provide a powerful toolkit for defining and mapping entities in NoSQL databases, analogous to their counterparts in Jakarta Persistence. 58 | 59 | === Template 60 | 61 | After mapping an entity, you can explore the advantage of using a `Template` interface, which can increase productivity on NoSQL operations. 62 | 63 | [source,java] 64 | ---- 65 | @Inject 66 | Template template; 67 | ... 68 | 69 | Car ferrari = Car.id(1L) 70 | .name("Ferrari") 71 | .type(CarType.SPORT); 72 | 73 | template.insert(ferrari); 74 | Optional car = template.find(Car.class, 1L); 75 | template.delete(Car.class, 1L); 76 | ---- 77 | 78 | The `Template` interface provides specialized methods to leverage the features of specific NoSQL database types. 79 | 80 | *Maven dependency* 81 | 82 | [source,xml] 83 | ---- 84 | 85 | jakarta.nosql 86 | jakarta.nosql-api 87 | 1.0.0 88 | 89 | ---- 90 | 91 | === More Information 92 | 93 | To learn more, please refer to the https://www.jnosql.org/spec/[reference documentation], and https://www.jnosql.org/javadoc/[JavaDocs]. 94 | 95 | == Code of Conduct 96 | 97 | 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. 98 | 99 | == Getting Help 100 | 101 | Having trouble with Jakarta NoSQL? We’d love to help! 102 | 103 | Please report any bugs, concerns or questions with Jakarta NoSQL to https://github.com/jakartaee/nosql. 104 | 105 | == Building from Source 106 | 107 | 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. 108 | 109 | [source, Bash] 110 | ---- 111 | mvn clean install 112 | ---- 113 | -------------------------------------------------------------------------------- /SECURITY.adoc: -------------------------------------------------------------------------------- 1 | = Security Policy 2 | 3 | This project implements the Eclipse Foundation Security Policy 4 | 5 | * https://www.eclipse.org/security 6 | 7 | == Reporting a Vulnerability 8 | 9 | Please report vulnerabilities to the Eclipse Foundation Security Team at 10 | security@eclipse.org -------------------------------------------------------------------------------- /TESTING-GUIDELINE.adoc: -------------------------------------------------------------------------------- 1 | == Testing Guideline 2 | 3 | === 1. Tools in use 4 | 5 | === 1.1 JUnit 5 as the testing framework 6 | 7 | https://junit.org/junit5/[JUnit 5] is the most advanced testing library for Java developers. 8 | It provides advanced features for testing any layer. 9 | Here it’s used to create unit tests. 10 | 11 | === 1.2 AssertJ as the assertions library 12 | 13 | https://assertj.github.io/doc/[AssertJ] extends the assertions of the testing framework, providing a rich set of assertions and improving the test code readability. 14 | 15 | ==== 1.2.1 Prefer using AssertJ assertions methods over JUnit 5 ones 16 | 17 | The assertion methods on both sides will achieve the main goal: validate the actual to the expected result. 18 | The main difference is that AssertJ provides more assertions than `assertEquals` or `assertTrue`, it has a variety of methods to use for different objects. 19 | 20 | === 2. Naming 21 | 22 | ==== 2.1 Test class name 23 | 24 | The test classes must match the subject of the test, plus the suffix 25 | `Test`. 26 | Example: if the subject of the test is the `Limit` class, the test name will be `LimitTest`. 27 | 28 | ==== 2.2 Test method name 29 | 30 | All the test methods should describe the test intent in the following structure: 31 | 32 | * fixed prefix `should` 33 | * action name 34 | * expected result optional for happy paths and mandatory for negative scenarios (corner cases) 35 | 36 | Example for happy paths (positive scenario): 37 | 38 | * `shouldCreatePageable` 39 | * shouldCreateLimitWithEqualsRange 40 | 41 | Example for negative scenario (or corner-case): 42 | 43 | * `shouldReturnErrorWhenMaxResultsIsNegative` 44 | 45 | ==== 2.3 Test description 46 | 47 | This project uses the `@DisplayName` annotation from JUnit 5 48 | 49 | ==== 2.4 Structure 50 | 51 | [source,java] 52 | ---- 53 | class CalculatorTest { 54 | 55 | @Test 56 | @DisplayName("Should sum up correctly two numbers") 57 | void sumUpCorrectly() { 58 | // AAA pattern (arrange, act, assert) 59 | } 60 | } 61 | ---- 62 | 63 | === 3. Creation 64 | 65 | ==== 3.1 Prefer soft assertions to hard assertions 66 | 67 | Hard Assertions are the normal assertion method that will halt the test execution once the actual result is not matching the expected one. 68 | Soft Assertion is a mechanism to run a group of assertions that won’t halt the execution until all the assertions have been executed, showing an error summary when it happens. 69 | It’s more beneficial when we assert multiple attributes from an object. 70 | 71 | This project uses the `SoftAssertions.assertSoftly()` method from the AssertJ library, and you can see a lot of already implemented examples in the available tests. 72 | The current usage is done by importing statically the `SoftAssertions` class, using directly the 73 | `assertSoftly()` method. 74 | The assertions are done by using the consumer name, followed by the `assertThat()` method, as the consumer name in the below example is `softly`: 75 | 76 | [source,java] 77 | ---- 78 | assertSoftly(softly->{ 79 | softly.assertThat(pageable.size()).as("page size is correct").isEqualTo(20); 80 | 81 | softly.assertThat(pageable.mode()).as("default page mode is correct") 82 | .isEqualTo(Pageable.Mode.CURSOR_NEXT); 83 | 84 | softly.assertThat(pageable.cursor().getKeysetElement(2)).as("first keySetElement is correct") 85 | .isEqualTo("First"); 86 | }); 87 | ---- 88 | 89 | Don't forget to use the `as()` method! 90 | It will be useful to fast identity which assertion is failing. 91 | 92 | ==== 3.2 Use the AssertJ method for expected exceptions 93 | 94 | Use one of the existing AssertJ methods to test any exception. 95 | Try to write the `assertThat` followed by the exception class name. 96 | Example: 97 | `assertThatIllegalArgumentException()`. 98 | 99 | When you can not find a method with a specific exception, use the method 100 | `assertThatThrownBy()`. 101 | 102 | === 4. Coverage 103 | 104 | ==== 4.1 Verify possible missing scenarios using PIT (pitest) 105 | 106 | Sometimes we can forget to test one or two scenarios, and it’s acceptable. 107 | PIT can help us to analyze the code and see the areas not covered by tests applying the mutation testing. 108 | 109 | After you finish writing your tests, ensure that the main scenario and corner cases (exception) are covered. 110 | Check it following these steps: 111 | 112 | [arabic] 113 | . Run `mvn clean test-compile -P pitest` 114 | . Open the `index.html` file located at `target/pit-reports` 115 | . In the report, click on `jakarta.data.repository` package link 116 | . Implement new tests focusing on the not covered _Mutation Coverage_ 117 | section 118 | * Click in the class name to see the possible not covered code, marked in red 119 | . Repeat this process until you have the `Mutation Coverage` covered 120 | 121 | .... 122 | NOTE: we don't seek 100% of coverage, but we must make sure the main scenario and all the corner cases have tests. 123 | .... 124 | -------------------------------------------------------------------------------- /api/.gitignore: -------------------------------------------------------------------------------- 1 | target/ 2 | pom.xml.tag 3 | pom.xml.releaseBackup 4 | pom.xml.versionsBackup 5 | pom.xml.next 6 | test-output/ 7 | /doc 8 | *.iml 9 | *.idea 10 | *.log 11 | /.idea 12 | .checkstyle 13 | 14 | # Eclipse metadata 15 | .settings/ 16 | .project 17 | .factorypath 18 | .classpath 19 | -project 20 | /.resourceCache 21 | /.project 22 | **/.DS_Store 23 | # Annotation processor metadata 24 | .apt_generated/ 25 | .apt_generated_tests/ 26 | -------------------------------------------------------------------------------- /api/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 10 | 13 | 4.0.0 14 | 15 | 16 | jakarta.nosql 17 | jakarta.nosql-parent 18 | 1.0.1-SNAPSHOT 19 | 20 | 21 | jakarta.nosql-api 22 | Jakarta NoSQL API 23 | Jakarta NoSQL :: API 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | org.apache.maven.plugins 32 | maven-javadoc-plugin 33 | ${maven-javadoc-plugin.version} 34 | 35 | 36 | attach-api-javadocs 37 | 38 | jar 39 | 40 | 41 | ${maven.compiler.source} 42 | true 43 | -Xdoclint:none 44 | Jakarta NoSQL API documentation 45 | Jakarta NoSQL API documentation 46 | Jakarta NoSQL API documentation 47 |
Jakarta NoSQL API v${spec.version}]]>
48 | nosql-dev@eclipse.org.
50 | Copyright © 2024 Eclipse Foundation. All rights reserved.
51 | Use is subject to license terms.]]> 52 | 53 | true 54 | 55 | 56 | Jakarta NOSQL API Documentation 57 | 58 | jakarta.nosql 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/AttributeConverter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | /** 19 | * A class that implements this interface can be used to convert entity attribute state into a database column 20 | * representation and vice versa. Note that the types X and Y may be the same Java type. 21 | * 22 | *

This interface is implemented by custom attribute converters. A converter is a class whose methods convert 23 | * between the target type of the converter (an arbitrary Java type which may be used as the type of a persistent 24 | * field or property) and a basic type or a type that can be persisted by a persistence provider, used as an 25 | * intermediate step in mapping to the database representation. 26 | * 27 | *

A converted field or property is considered basic, since, with the aid of the converter, its values can be 28 | * represented as instances of a basic type. 29 | * 30 | *

Note that the target type {@code X} and the converted basic type {@code Y} may be the same Java type. 31 | * 32 | * @param the target type, that is, the type of the entity attribute 33 | * @param a basic type or a supported type in the NoSQL database representing the type of the database column 34 | * 35 | * @see Convert 36 | * @since 1.0.0 37 | */ 38 | public interface AttributeConverter { 39 | 40 | /** 41 | * Converts the value stored in the entity attribute into the data representation to be stored in the database. 42 | * 43 | * @param attribute the entity attribute value to be converted 44 | * @return the converted data to be stored in the database column 45 | */ 46 | Y convertToDatabaseColumn(X attribute); 47 | 48 | /** 49 | * Converts the data stored in the database column into the value to be stored in the entity attribute. 50 | * Note that it is the responsibility of the converter writer to specify the correct database data type for the 51 | * corresponding column for use by the NoSQL database: i.e., persistence providers are not expected to do 52 | * such type conversion. 53 | * 54 | * @param dbData the data from the database column to be converted 55 | * @return the converted value to be stored in the entity attribute 56 | */ 57 | X convertToEntityAttribute(Y dbData); 58 | } 59 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/Column.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2022 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Specifies the column mapped by the annotated persistent property or field. 26 | *

27 | * If no {@code Column} annotation is explicitly specified, the field will be ignored by Jakarta NoSQL. 28 | *

29 | * 30 | * Example: 31 | * 
{@code
32 |  * @Column(name = "DESC")
33 |  * private String description;
34 |  * }
35 | * 36 | * @see Convert 37 | * @see Entity 38 | * @see Id 39 | * @since 1.0.0 40 | */ 41 | @Retention(RetentionPolicy.RUNTIME) 42 | @Target({ElementType.FIELD, ElementType.PARAMETER}) 43 | public @interface Column { 44 | /** 45 | * (Optional) The name of the column. Defaults to the property or field name. 46 | *

47 | * For example, in the {@code Person} entity class below, the mapped fields with {@code @Column} 48 | * will be mapped to columns with their respective field name: 49 | *

50 | * 
{@code
51 |      * @Entity
52 |      * public class Person {
53 |      *     @Column
54 |      *     private String name;
55 |      * }
56 |      * }
57 | *

58 | * If any name customization is needed, set the value of this attribute to specify the desired name. 59 | * For instance, in the example below, the {@code name} field of the {@code Person} class will be mapped 60 | * to the "personName" column: 61 | *

62 | * 
{@code
63 |      * @Entity
64 |      * public class Person {
65 |      *     @Column("personName")
66 |      *     private String name;
67 |      * }
68 |      * }
69 | * 70 | * @return the column name 71 | */ 72 | String value() default ""; 73 | 74 | /** 75 | * (Optional) Defines the name of the user-defined type (UDT) used by the NoSQL database for this field. 76 | *

77 | * If a NoSQL database supports UDTs, this attribute allows specifying the name of the UDT to be used 78 | * for serializing this field. If the database does not support UDTs, this field will be skipped during serialization. 79 | *

80 | * 81 | * @return the user-defined type (UDT) name 82 | */ 83 | String udt() default ""; 84 | } 85 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/Convert.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * 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. 26 | * 27 | *

The {@code Convert} annotation may be applied to any field or property and must be used in conjunction with the 28 | * {@link Id} or {@link Column} annotation (if not, a default value will be used). 29 | * 30 | *

The dot notation may also be used with map entries: 31 | *

Convert a basic attribute 32 | * 

33 |  * {@code
34 |  * @Converter
35 |  * public class BooleanToIntegerConverter
36 |  *         implements AttributeConverter {  ... }
37 |  *
38 |  * @Entity
39 |  * public class Employee {
40 |  *     @Id
41 |  *     long id;
42 |  *
43 |  *     @Convert(converter = BooleanToIntegerConverter.class)
44 |  *     boolean fullTime;
45 |  * }
46 |  * }
47 |  *
48 | * @since 1.0.0 49 | */ 50 | @Retention(RetentionPolicy.RUNTIME) 51 | @Target({ElementType.FIELD, ElementType.PARAMETER}) 52 | public @interface Convert { 53 | /** 54 | * Specifies the converter to be applied. 55 | * @return the converter class 56 | */ 57 | Class> value(); 58 | } 59 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/DiscriminatorColumn.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Specifies the discriminator column for the mapping strategy. 26 | * If the DiscriminatorColumn annotation is missing, 27 | * the name of the discriminator column defaults to "dtype". 28 | * 29 | *

Example usage: 30 | * 

{@code
31 |  * @Entity
32 |  * @DiscriminatorColumn("dtype")
33 |  * public class Animal {
34 |  *     // Common fields and methods for all animals
35 |  * }
36 |  *
37 |  * @Entity
38 |  * public class Dog extends Animal {
39 |  *     // Specific fields and methods for dogs
40 |  * }
41 |  *
42 |  * @Entity
43 |  * public class Cat extends Animal {
44 |  *     // Specific fields and methods for cats
45 |  * }
46 |  * }
47 | * @since 1.0.0 48 | */ 49 | @Retention(RetentionPolicy.RUNTIME) 50 | @Target(ElementType.TYPE) 51 | public @interface DiscriminatorColumn { 52 | 53 | /** 54 | * The default name of the discriminator column, which is {@code "dtype"}. 55 | */ 56 | String DEFAULT_DISCRIMINATOR_COLUMN = "dtype"; 57 | 58 | /** 59 | * (Optional) The name of the column to be used for the discriminator. 60 | * 61 | * @return the column's name 62 | */ 63 | String value() default DEFAULT_DISCRIMINATOR_COLUMN; 64 | } 65 | 66 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/DiscriminatorValue.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Specifies the value of the discriminator column for the annotated entity type. 26 | *

The {@code DiscriminatorValue} annotation can only be specified on a concrete entity class. 27 | * Specifies the value of the discriminator column for entities of the given type. 28 | * 29 | *

The DiscriminatorValue annotation can only be specified on a concrete entity class. 30 | * 31 | *

If the DiscriminatorValue annotation is not specified and a discriminator column is used, 32 | * a provider-specific function will be used to generate a value representing the entity type. 33 | * So the discriminator value default is the {@link Class#getSimpleName()}. 34 | * 35 | *

Example usage of the {@code DiscriminatorValue} annotation: 36 | * 

{@code
37 |  * @Entity
38 |  * @DiscriminatorValue("Mammal")
39 |  * public class Animal {
40 |  *     // Animal-specific fields and methods
41 |  * }
42 |  *
43 |  * @Entity
44 |  * @DiscriminatorValue("Dog")
45 |  * public class Dog extends Animal {
46 |  *     // Dog-specific fields and methods
47 |  * }
48 |  * }
49 | * 50 | * @see Inheritance 51 | * @see DiscriminatorColumn 52 | * @see DiscriminatorValue 53 | * @since 1.0.0 54 | */ 55 | @Retention(RetentionPolicy.RUNTIME) 56 | @Target(ElementType.TYPE) 57 | public @interface DiscriminatorValue { 58 | /** 59 | * (Optional) The value that indicates that the row is an entity of the annotated entity type. 60 | * 61 | * @return the discriminator Value 62 | */ 63 | String value(); 64 | } 65 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/Entity.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2022 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Annotates a class as an entity, representing a persistent class corresponding to a database structure. 26 | *

27 | * Entity classes must adhere to specific rules: 28 | *

37 | *

38 | * Enums or interfaces cannot be designated as entities. 39 | *

40 | *

41 | * Each entity must have a unique identifier, typically annotated with {@link Id}. 42 | *

43 | *

44 | * The following example demonstrates two classes, {@code Person} and {@code Address}, where a person has an address: 45 | *

46 | * 
{@code
 47 |  * @Entity
 48 |  * public class Person {
 49 |  *
 50 |  *     @Id
 51 |  *     private Long id;
 52 |  *
 53 |  *     @Column
 54 |  *     private String name;
 55 |  *
 56 |  *     @Column
 57 |  *     private Address address;
 58 |  * }
 59 |  *
 60 |  * @Embeddable
 61 |  * public class Address {
 62 |  *     @Column
 63 |  *     private String street;
 64 |  *
 65 |  *     @Column
 66 |  *     private String city;
 67 |  * }
 68 |  * }
69 | *

70 | * Note: NoSQL databases may have varying behaviors regarding serialization, resulting in different storage formats based on the NoSQL vendor. 71 | *

72 | *

73 | * The sample below demonstrates the use of records as entities: 74 | *

75 | * 
{@code
 76 |  * @Entity
 77 |  * public record Person(@Id Long id, @Column String name, @Column Address address) {
 78 |  * }
 79 |  *
 80 |  * @Embeddable
 81 |  * public class Address {
 82 |  *     @Column
 83 |  *     private String street;
 84 |  *
 85 |  *     @Column
 86 |  *     private String city;
 87 |  *
 88 |  *     public Address(@Column String street, @Column String city) {
 89 |  *         this.street = street;
 90 |  *         this.city = city;
 91 |  *     }
 92 |  * }
 93 |  * }
94 | * 95 | * @see Id 96 | * @see Column 97 | * @since 1.0 98 | */ 99 | @Retention(RetentionPolicy.RUNTIME) 100 | @Target(ElementType.TYPE) 101 | public @interface Entity { 102 | /** 103 | * The name of the entity. If not specified, defaults to the unqualified simple name of the class. 104 | * This name is used to refer to the entity in queries and also to represent the name in the NoSQL database structure, such as the table name or collection name. 105 | *

106 | * For example, given the class {@code org.jakarta.nosql.demo.Person}, the default name will be {@code Person}. 107 | *

108 | *

109 | * To customize the name, set the value of the {@code @Entity} annotation to the desired name, as shown below: 110 | * 

{@code
111 |      * @Entity("ThePerson")
112 |      * public class Person {
113 |      * }
114 |      * }
115 | * 116 | * @return the entity name (optional) 117 | */ 118 | String value() default ""; 119 | } -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/Id.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2022 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Identifies the primary key of an entity. 26 | * Specifies the mapped field of an entity as the entity’s ID, or the Key in Key-Value databases. 27 | * The field or property to which the {@code Id} annotation is 28 | * applied should have one of the following types: 29 | * 37 | * Or it uses the {@link Convert} to convert the type to one of the above types. 38 | *

39 | * The mapped column for the primary key of the entity is assumed 40 | * to be the primary key of the database structure. 41 | *

42 | * 43 | *

Example:

44 | * 
45 |  * {@code
46 |  * @Id
47 |  * public Long id;
48 |  * }
49 |  *
50 | *

51 | * An insertion with an ID value might vary from the vendor, where vendors can throw a NullPointerException, 52 | * for example, a Key-value database, or apply a strategy of auto generating value, for example, UUID or auto-increment. 53 | *

54 | * 55 | * @see Convert 56 | * @see Column 57 | * @see Entity 58 | * @since 1.0.0 59 | */ 60 | @Retention(RetentionPolicy.RUNTIME) 61 | @Target({ElementType.FIELD, ElementType.PARAMETER}) 62 | public @interface Id { 63 | 64 | /** 65 | * The name of the entity ID. Default value is {@code _id}. 66 | *

67 | * By default, the field marked with {@code @Id} maps to the field {@code _id} in the database. However, 68 | * this can vary depending on the NoSQL provider. Certain databases may use a different field name for 69 | * the identifier, such as {@code _key}, or allow users to override this value based on the specific 70 | * database implementation. It is recommended to consult the documentation of the database provider 71 | * to understand its requirements for primary key fields. 72 | *

73 | *

Example of customization:

74 | * 
75 |      * {@code
76 |      * @Entity
77 |      * public class User {
78 |      *     @Id("userId")
79 |      *     private String userName;
80 |      * }
81 |      * }
82 |      *
83 | * 84 | * @return the entity ID name 85 | */ 86 | String value() default "_id"; 87 | } 88 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/Inheritance.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Specifies the inheritance mapping strategy for the entity class hierarchy, which descends from the annotated entity class. 26 | * Specifies the inheritance strategy to be used for an entity class hierarchy. 27 | * It is specified on the entity class that is the root of the entity class hierarchy. 28 | * This class can be either a regular or an abstract; 29 | * The NoSQL database structure will have a column for every attribute 30 | * of every class in the hierarchy. 31 | * The subclass will use the {@link Entity} name from that class with this annotation. 32 | * 33 | * 
34 |  *
35 |  *   Example:
36 |  *   @Entity
37 |  *   @Inheritance
38 |  *   public class Notification { ... }
39 |  *
40 |  *   @Entity
41 |  *   public class SMSNotification extends Notification { ... }
42 |  *
43 | * @see DiscriminatorColumn 44 | * @see DiscriminatorValue 45 | * @since 1.0.0 46 | */ 47 | @Retention(RetentionPolicy.RUNTIME) 48 | @Target(ElementType.TYPE) 49 | public @interface Inheritance { 50 | } 51 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/MappedSuperclass.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | /** 24 | * Defines a class whose mapping information is applied to entities that inherit from it. 25 | * Unlike regular entities, a mapped superclass does not imply the existence of separate storage 26 | * structures. 27 | * 28 | *

Declares a class that is not itself an entity, but whose mappings are inherited by entities that extend it. 29 | * A mapped superclass is not a persistent type and is not mapped to a specific database structure. 30 | * 31 | *

The persistent fields and properties of a mapped superclass are declared and mapped using the same mapping 32 | * annotations used to map {@linkplain Entity entity classes}. However, these mappings are interpreted in the context 33 | * of each entity class that inherits the mapped superclass, since the mapped superclass itself does not have a 34 | * predefined storage structure in NoSQL databases. 35 | * 36 | *

Example:

37 | * 
{@code
38 |  * @MappedSuperclass
39 |  * public class Employee {
40 |  *     @Id
41 |  *     protected Integer id;
42 |  *     @Column
43 |  *     protected Address address;
44 |  * }
45 |  *
46 |  * @Entity
47 |  * public class Programmer extends Employee {
48 |  *     @Column
49 |  *     protected Money salary;
50 |  * }
51 |  * }
52 | * 53 | * @since 1.0.0 54 | */ 55 | @Retention(RetentionPolicy.RUNTIME) 56 | @Target(ElementType.TYPE) 57 | public @interface MappedSuperclass { 58 | 59 | } 60 | 61 | 62 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/MappingException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | /** 19 | * An exception that occurs when there is a mapping error during entity mapping or persistence. 20 | * This exception typically indicates issues with the usage or missing annotations at the entity level. 21 | * Some scenarios where this exception may be thrown include: 22 | * 29 | * 30 | *

This exception may occur at runtime or build time, depending on the Jakarta NoSQL provider being used.

31 | */ 32 | public class MappingException extends NoSQLException { 33 | 34 | /** 35 | * Constructs a {@code MappingException} using the given message and cause. 36 | * 37 | * @param message A message explaining the exception condition 38 | * @param cause The underlying cause 39 | */ 40 | public MappingException(String message, Throwable cause) { 41 | super(message, cause); 42 | } 43 | 44 | /** 45 | * Constructs a {@code MappingException} using the given cause. 46 | * 47 | * @param cause The underlying cause 48 | */ 49 | public MappingException(Throwable cause) { 50 | super(cause); 51 | } 52 | 53 | /** 54 | * Constructs a {@code MappingException} using the given message. 55 | * 56 | * @param message A message explaining the exception condition 57 | */ 58 | public MappingException(String message) { 59 | super(message); 60 | } 61 | } 62 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/NoSQLException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2022 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package jakarta.nosql; 17 | 18 | 19 | /** 20 | * Thrown by the persistence provider when a problem occurs. 21 | */ 22 | public class NoSQLException extends RuntimeException { 23 | 24 | /** 25 | * Constructs a new runtime exception with null as its detail message. 26 | */ 27 | public NoSQLException() { 28 | super(); 29 | } 30 | 31 | /** 32 | * Constructs a new runtime exception with the specified detail message. 33 | * 34 | * @param message the message 35 | */ 36 | public NoSQLException(String message) { 37 | super(message); 38 | } 39 | 40 | /** 41 | * Constructs a new runtime exception with the specified detail message and cause. 42 | * 43 | * @param message the message 44 | * @param cause the cause 45 | */ 46 | public NoSQLException(String message, Throwable cause) { 47 | super(message, cause); 48 | } 49 | 50 | /** 51 | * Constructs a new runtime exception with the specified cause and a detail 52 | * message of (cause==null ? null : cause.toString()) (which typically contains 53 | * the class and detail message of cause). 54 | * 55 | * @param cause the cause 56 | */ 57 | public NoSQLException(Throwable cause) { 58 | super(cause); 59 | } 60 | 61 | /** 62 | * Constructs a new runtime exception with the specified detail 63 | * message, cause, suppression enabled or disabled, and writable stack 64 | * trace enabled or disabled. 65 | * 66 | * @param message the message 67 | * @param cause the cause 68 | * @param enableSuppression the enableSuppression 69 | * @param writableStackTrace the writableStackTrace 70 | */ 71 | protected NoSQLException(String message, Throwable cause, 72 | boolean enableSuppression, 73 | boolean writableStackTrace) { 74 | super(message, cause, enableSuppression, writableStackTrace); 75 | } 76 | } 77 | 78 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/nosql/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | /** 18 | * Provides classes and interfaces for integrating Java applications with various NoSQL databases. 19 | *

20 | * NoSQL databases are a category of database systems that differ from traditional relational databases in their data 21 | * storage and retrieval mechanisms. Unlike relational databases, which organize data into tables with predefined schemas, 22 | * NoSQL databases use flexible data models that allow for unstructured or semi-structured data storage. These databases 23 | * are often preferred for their ability to handle large volumes of data, their scalability, and their flexibility in 24 | * accommodating evolving data schemas. 25 | *

26 | * The {@link jakarta.nosql.Entity} annotation specifies that the class is an entity. 27 | *

28 | * The {@link jakarta.nosql.Embeddable} annotation declares a class whose instances are stored as an intrinsic part of an 29 | * owning entity, sharing the identity of the entity. 30 | *

31 | * The {@link jakarta.nosql.Id} annotation specifies the primary key of an entity. 32 | *

33 | * The {@link jakarta.nosql.Column} annotation specifies the mapping of a persistent property or field to a database column. 34 | *

35 | * The {@link jakarta.nosql.Convert} annotation specifies how the values of a field or property are converted to a basic 36 | * type or a type that can be persisted by a persistence provider. 37 | *

38 | * The {@link jakarta.nosql.MappedSuperclass} annotation specifies a class whose mapping information is applied to entities 39 | * that inherit from it. 40 | *

41 | * The {@link jakarta.nosql.Inheritance} annotation specifies the inheritance mapping strategy for the entity class hierarchy. 42 | *

43 | * The {@link jakarta.nosql.DiscriminatorColumn} annotation specifies the discriminator column for the inheritance mapping 44 | * strategy. 45 | *

46 | * The {@link jakarta.nosql.DiscriminatorValue} annotation specifies the value of the discriminator column for the annotated 47 | * entity type. 48 | *

49 | * The {@link jakarta.nosql.Template} interface provides methods for interacting with NoSQL databases, allowing operations 50 | * such as insertion, updating, querying, and deletion of entities. 51 | */ 52 | package jakarta.nosql; -------------------------------------------------------------------------------- /api/src/main/javadoc/doc-files/speclicense.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | Eclipse Foundation Specification License - v1.1 4 | 5 | 6 |

Eclipse Foundation Specification License - v1.1

7 |

By using and/or copying this document, or the Eclipse Foundation 8 | document from which this statement is linked or incorporated by reference, you (the licensee) agree 9 | that you have read, understood, and will comply with the following 10 | terms and conditions:

11 | 12 |

Permission to copy, and distribute the contents of this document, or 13 | the Eclipse Foundation document from which this statement is linked, in 14 | any medium for any purpose and without fee or royalty is hereby 15 | granted, provided that you include the following on ALL copies of the 16 | document, or portions thereof, that you use:

17 | 18 | 27 | 28 |

Inclusion of the full text of this NOTICE must be provided. We 29 | request that authorship attribution be provided in any software, 30 | documents, or other items or products that you create pursuant to the 31 | implementation of the contents of this document, or any portion 32 | thereof.

33 | 34 |

No right to create modifications or derivatives of Eclipse Foundation 35 | documents is granted pursuant to this license, except anyone may 36 | prepare and distribute derivative works and portions of this document 37 | in software that implements the specification, in supporting materials 38 | accompanying such software, and in documentation of such software, 39 | PROVIDED that all such works include the notice below. HOWEVER, the 40 | publication of derivative works of this document for use as a technical 41 | specification is expressly prohibited.

42 | 43 |

The notice is:

44 | 45 |

"Copyright © 2022, 2024 Eclipse Foundation AISBL. This software or 46 | document includes material copied from or derived from Jakarta Data and https://jakarta.ee/specifications/data/1.0/."

47 | 48 |

Disclaimers

49 | 50 |

THIS DOCUMENT IS PROVIDED "AS IS," AND TO THE EXTENT PERMITTED BY APPLICABLE LAW THE COPYRIGHT 51 | HOLDERS AND THE ECLIPSE FOUNDATION AISBL MAKE NO REPRESENTATIONS OR 52 | WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 53 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 54 | NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE 55 | SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS 56 | WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR 57 | OTHER RIGHTS.

58 | 59 |

TO THE EXTENT PERMITTED BY APPLICABLE LAW THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION AISBL WILL NOT BE LIABLE 60 | FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT 61 | OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE 62 | CONTENTS THEREOF.

63 | 64 |

The name and trademarks of the copyright holders or the Eclipse 65 | Foundation AISBL may NOT be used in advertising or publicity pertaining to 66 | this document or its contents without specific, written prior 67 | permission. Title to copyright in this document will at all times 68 | remain with copyright holders.

69 | 70 | 71 | -------------------------------------------------------------------------------- /pmd/pmd-rules.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 7 | 11 | Remove rules 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /spec/README.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta NoSQL Specification 2 | :toc: auto 3 | 4 | This module contains AsciiDoc sources and configuration to generate Jakarta NoSQL documentation in HTML and PDF formats for both Apache License 2 and Jakarta Eclipse Foundation Specification Process. 5 | 6 | == Generating the Documentation 7 | 8 | === Prerequisites: 9 | 10 | * JDK 11+ 11 | * Maven 3.0.5+ 12 | 13 | === Execute the full build: 14 | 15 | From the `spec` directory, execute `mvn install` 16 | 17 | Maven will generate the final documentation in HTML and PDF format in `target` directory with the default license (ASL2). 18 | 19 | The HTML version of the document may be found in: 20 | - `target/generated-docs/jakarta-nosql-1.0.0-.html` 21 | 22 | The PDF version of the document may be found in: 23 | - `target/generated-docs/jakarta-nosql-1.0.0-.pdf` 24 | 25 | == License in Documentation 26 | 27 | The documentation can be generated for 2 licenses : Apache License v 2.0 (by default) and EFSL license. 28 | To generate doc with the final EFSL license, change the `license-file` property to `final`. Use `asl` or 29 | specify nothing for the Apache V2 License. 30 | 31 | For instance `mvn -Dlicense-file=final` will generate documentation with the link:https://www.eclipse.org/legal/efsl.php[EFSL] final license. 32 | 33 | == Working on the Specification 34 | 35 | This specification is split among different AsciiDoc files located in `src/main/asciidoc` 36 | The master document (entry point) is `jakarta_nosql_spec.adoc` that includes all the specification documents. 37 | 38 | To work with the specification documents, you may want to install an AsciiDoc plugin in your preferred IDE. You can also use a good text editor that provides an AsciiDoc plugin. The best candidate are: 39 | 40 | === Atom 41 | * https://atom.io/[Atom] 42 | * https://atom.io/packages/asciidoc-preview[AsciiDoc Preview for Atom] 43 | * https://atom.io/packages/language-asciidoc[AsciiDoc language support for Atom] 44 | 45 | === Brackets 46 | 47 | * http://brackets.io/[Brackets] 48 | * https://github.com/asciidoctor/brackets-asciidoc-preview[AsciiDoc Preview for Brackets] 49 | 50 | === AsciiDocFX 51 | 52 | * http://www.asciidocfx.com/[AsciiDocFX] 53 | * Download the latest https://github.com/rahmanusta/AsciidocFX/releases[AsciidocFX.zip] and extract it 54 | * Execute `bin/asciidocfx.bat` or `bin/asciidocfx.sh` 55 | -------------------------------------------------------------------------------- /spec/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 10 | 11 | 13 | 4.0.0 14 | 15 | 16 | jakarta.nosql 17 | jakarta.nosql-parent 18 | 1.0.1-SNAPSHOT 19 | 20 | 21 | jakarta.nosql-spec 22 | Jakarta NoSQL Specification 23 | 24 | 25 | 3.1.1 26 | 2.3.19 27 | MMMM dd, yyyy 28 | ${maven.build.timestamp} 29 | Final 30 | 1.0 31 | ${project.build.directory}/generated-docs 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | clean package 40 | 41 | 42 | org.asciidoctor 43 | asciidoctor-maven-plugin 44 | ${asciidoctor-maven.version} 45 | 46 | 47 | org.asciidoctor 48 | asciidoctorj-pdf 49 | ${asciidoctorj-pdf.version} 50 | 51 | 52 | 53 | 54 | generate-pdf-doc 55 | generate-resources 56 | 57 | process-asciidoc 58 | 59 | 60 | pdf 61 | ${gen-doc-dir}/jakarta-nosql-${spec.version}.pdf 62 | 63 | 64 | 65 | output-html 66 | generate-resources 67 | 68 | process-asciidoc 69 | 70 | 71 | html5 72 | ${gen-doc-dir}/jakarta-nosql-${spec.version}.html 73 | 74 | 75 | 76 | 77 | src/main/asciidoc 78 | jakarta_nosql_spec.adoc 79 | coderay 80 | true 81 | 82 | Apache License v2.0 83 | ${spec.version} 84 | Jakarta NoSQL 85 | ${revremark} 86 | ${revisiondate} 87 | Jakarta NoSQL 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | org.eclipse.m2e 97 | lifecycle-mapping 98 | 1.0.1-SNAPSHOT 99 | 100 | 101 | 102 | 103 | 104 | org.asciidoctor 105 | 106 | asciidoctor-maven-plugin 107 | 108 | 109 | [1.5.6,) 110 | 111 | 112 | process-asciidoc 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | -------------------------------------------------------------------------------- /spec/src/main/asciidoc/chapters/introduction/project_team.adoc: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2022 Contributors to the Eclipse Foundation 2 | // 3 | // This program and the accompanying materials are made available under the 4 | // terms of the Eclipse Public License v. 2.0 which is available at 5 | // http://www.eclipse.org/legal/epl-2.0. 6 | // 7 | // This Source Code may also be made available under the following Secondary 8 | // Licenses when the conditions for such availability set forth in the Eclipse 9 | // Public License v. 2.0 are satisfied: GNU General Public License, version 2 10 | // with the GNU Classpath Exception which is available at 11 | // https://www.gnu.org/software/classpath/license.html. 12 | // 13 | // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 14 | 15 | === Jakarta NoSQL Project Team 16 | 17 | This specification is being developed as part of Jakarta NoSQL project under the 18 | Jakarta EE Specification Process. It is the result of the collaborative work 19 | of the project committers and various contributors. 20 | 21 | ==== Project Lead 22 | 23 | * https://projects.eclipse.org/content/otavio-santana-project-lead-jakarta-nosql[Otavio Santana,windows=\_blank] 24 | 25 | ==== Contributors 26 | 27 | * https://projects.eclipse.org/user/8408[Ivar Grimstad,windows=\_blank] 28 | * https://projects.eclipse.org/user/8180[Kevin Sutter,windows=\_blank] 29 | * https://projects.eclipse.org/user/10810[Scott Stark,windows=\_blank] 30 | 31 | ==== Committers 32 | 33 | * https://projects.eclipse.org/content/andres-galante-committer-jakarta-nosql[Andres Galante,windows=\_blank] 34 | * https://projects.eclipse.org/content/fred-rowe-committer-jakarta-nosql[Fred Rowe,windows=\_blank] 35 | * https://projects.eclipse.org/content/gaurav-gupta-committer-jakarta-nosql[Gaurav Gupta,windows=\_blank] 36 | * https://projects.eclipse.org/content/ivan-junckes-filho-committer-jakarta-nosql[Ivan Junckes Filho,windows=\_blank] 37 | * https://projects.eclipse.org/content/jesse-gallagher-committer-jakarta-nosql[Jesse Gallagher,windows=\_blank] 38 | * https://projects.eclipse.org/content/michael-redlich-committer-jakarta-nosql[Michael Redlich,windows=\_blank] 39 | * https://projects.eclipse.org/content/nathan-rauh-committer-jakarta-nosql[Nathan Rauh,windows=\_blank] 40 | * https://projects.eclipse.org/content/otavio-santana-committer-jakarta-nosql[Otavio Santana,windows=\_blank] 41 | * https://projects.eclipse.org/content/werner-keil-committer-jakarta-nosql[Werner Keil,windows=\_blank] 42 | 43 | ==== Historical Committer 44 | 45 | * https://projects.eclipse.org/content/leonardo-lima-committer-jakarta-nosql[Leonardo Lima,windows=\_blank] 46 | 47 | ==== Mentor 48 | 49 | * https://projects.eclipse.org/content/wayne-beaton-mentor-jakarta-nosql[Wayne Beaton,windows=\_blank] 50 | 51 | ==== Full List of Contributors 52 | 53 | The complete list of Jakarta NoSQL contributors may be found https://github.com/jakartaee/nosql/graphs/contributors[here,windows=\_blank]. 54 | 55 | -------------------------------------------------------------------------------- /spec/src/main/asciidoc/chapters/license/license-alv2.asciidoc: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2022 Contributors to the Eclipse Foundation 2 | // 3 | // This program and the accompanying materials are made available under the 4 | // terms of the Eclipse Public License v. 2.0 which is available at 5 | // http://www.eclipse.org/legal/epl-2.0. 6 | // 7 | // This Source Code may also be made available under the following Secondary 8 | // Licenses when the conditions for such availability set forth in the Eclipse 9 | // Public License v. 2.0 are satisfied: GNU General Public License, version 2 10 | // with the GNU Classpath Exception which is available at 11 | // https://www.gnu.org/software/classpath/license.html. 12 | // 13 | // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 14 | 15 | [subs="normal"] 16 | .... 17 | 18 | Specification: {doctitle} 19 | 20 | Version: {revnumber} 21 | 22 | Status: {revremark} 23 | 24 | Release: {revdate} 25 | 26 | Copyright (c) {docyear} Eclipse Foundation: 27 | {authors} 28 | 29 | This program and the accompanying materials are made available under the 30 | terms of the Eclipse Public License v. 2.0 which is available at 31 | https://www.eclipse.org/legal/epl-2.0. 32 | 33 | .... 34 | -------------------------------------------------------------------------------- /spec/src/main/asciidoc/chapters/license/license-efsl.adoc: -------------------------------------------------------------------------------- 1 | [subs="normal"] 2 | .... 3 | Specification: {specification} 4 | 5 | Version: {revnumber} 6 | 7 | Status: {revremark} 8 | 9 | Release: {revdate} 10 | .... 11 | 12 | == Copyright 13 | 14 | Copyright (c) {docyear} Eclipse Foundation. 15 | 16 | === Eclipse Foundation Specification License - v1.1 17 | 18 | By using and/or copying this document, or the Eclipse Foundation 19 | document from which this statement is linked or incorporated by reference, you (the licensee) agree 20 | that you have read, understood, and will comply with the following 21 | terms and conditions: 22 | 23 | Permission to copy, and distribute the contents of this document, or 24 | the Eclipse Foundation document from which this statement is linked, in 25 | any medium for any purpose and without fee or royalty is hereby 26 | granted, provided that you include the following on ALL copies of the 27 | document, or portions thereof, that you use: 28 | 29 | * link or URL to the original Eclipse Foundation document. 30 | * All existing copyright notices, or if one does not exist, a notice 31 | (hypertext is preferred, but a textual representation is permitted) 32 | of the form: "Copyright (c) [$date-of-document] 33 | Eclipse Foundation AISBL https://www.eclipse.org/legal/efsl.php " 34 | 35 | Inclusion of the full text of this NOTICE must be provided. We 36 | request that authorship attribution be provided in any software, 37 | documents, or other items or products that you create pursuant to the 38 | implementation of the contents of this document, or any portion 39 | thereof. 40 | 41 | No right to create modifications or derivatives of Eclipse Foundation 42 | documents is granted pursuant to this license, except anyone may 43 | prepare and distribute derivative works and portions of this document 44 | in software that implements the specification, in supporting materials 45 | accompanying such software, and in documentation of such software, 46 | PROVIDED that all such works include the notice below. HOWEVER, the 47 | publication of derivative works of this document for use as a technical 48 | specification is expressly prohibited. 49 | 50 | The notice is: 51 | 52 | "Copyright (c) {docyear} Eclipse Foundation AISBL.This software or 53 | document includes material copied from or derived from Jakarta NoSQL and 54 | https://jakarta.ee/specifications/nosql/." 55 | 56 | === Disclaimers 57 | 58 | THIS DOCUMENT IS PROVIDED "AS IS," AND TO THE EXTENT PERMITTED BY APPLICABLE LAW THE COPYRIGHT 59 | HOLDERS AND THE ECLIPSE FOUNDATION AISBL MAKE NO REPRESENTATIONS OR 60 | WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 61 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 62 | NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE 63 | SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS 64 | WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR 65 | OTHER RIGHTS. 66 | 67 | TO THE EXTENT PERMITTED BY APPLICABLE LAW THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION AISBL WILL NOT BE LIABLE 68 | FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT 69 | OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE 70 | CONTENTS THEREOF. 71 | 72 | The name and trademarks of the copyright holders or the Eclipse 73 | Foundation AISBL may NOT be used in advertising or publicity pertaining to 74 | this document or its contents without specific, written prior 75 | permission. Title to copyright in this document will at all times 76 | remain with copyright holders. 77 | -------------------------------------------------------------------------------- /spec/src/main/asciidoc/images/jakarta_ee_logo_schooner_color_stacked_default.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jakartaee/nosql/2a2ccfc60ad75564d6a22fb5ac9186859716d2ac/spec/src/main/asciidoc/images/jakarta_ee_logo_schooner_color_stacked_default.png -------------------------------------------------------------------------------- /spec/src/main/asciidoc/images/jnosql.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jakartaee/nosql/2a2ccfc60ad75564d6a22fb5ac9186859716d2ac/spec/src/main/asciidoc/images/jnosql.png -------------------------------------------------------------------------------- /spec/src/main/asciidoc/images/title_image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jakartaee/nosql/2a2ccfc60ad75564d6a22fb5ac9186859716d2ac/spec/src/main/asciidoc/images/title_image.png -------------------------------------------------------------------------------- /spec/src/main/asciidoc/jakarta_nosql_spec.adoc: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2022 Contributors to the Eclipse Foundation 2 | // 3 | // This program and the accompanying materials are made available under the 4 | // terms of the Eclipse Public License v. 2.0 which is available at 5 | // http://www.eclipse.org/legal/epl-2.0. 6 | // 7 | // This Source Code may also be made available under the following Secondary 8 | // Licenses when the conditions for such availability set forth in the Eclipse 9 | // Public License v. 2.0 are satisfied: GNU General Public License, version 2 10 | // with the GNU Classpath Exception which is available at 11 | // https://www.gnu.org/software/classpath/license.html. 12 | // 13 | // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 14 | 15 | = Jakarta NoSQL 16 | :pdf-theme: {docdir}/../../theme/jakartaee-theme.yml 17 | :authors: 18 | :email: nosql-dev@eclipse.org 19 | :version-label!: 20 | :doctype: book 21 | :license: Apache License v2.0 22 | :source-highlighter: coderay 23 | :toc: left 24 | :toclevels: 3 25 | :sectnumlevels: 4 26 | :sectanchors: 27 | :stem: 28 | ifdef::backend-pdf[] 29 | :pagenums: 30 | :numbered: 31 | :title-logo-image: image:jakarta_ee_logo_schooner_color_stacked_default.png[pdfwidth=4.25in,align=right] 32 | endif::[] 33 | :icons: font 34 | ifndef::imagesdir[:imagesdir: images] 35 | ifndef::sourcedir[:sourcedir: ../../main/java] 36 | 37 | :sectnums!: 38 | include::chapters/license/license-efsl.adoc[] 39 | 40 | :sectnums: 41 | include::chapters/introduction/introduction.adoc[] 42 | include::chapters/api/entity.adoc[] 43 | include::chapters/api/annotations.adoc[] 44 | include::chapters/api/template.adoc[] 45 | include::chapters/api/jakarta--ee.adoc[] -------------------------------------------------------------------------------- /spec/src/main/resources/META-INF/NOTICE: -------------------------------------------------------------------------------- 1 | ========================================================================= 2 | == NOTICE file corresponding to section 4(d) of the Apache License, == 3 | == Version 2.0, in this case for Microprofile Metrics == 4 | ========================================================================= 5 | 6 | 7 | SPDXVersion: SPDX-2.1 8 | PackageName: Jakarta NoSQL 9 | PackageHomePage: https://jakarta.ee/specifications/nosql/ 10 | PackageLicenseDeclared: Apache-2.0 11 | 12 | PackageCopyrightText: 13 | Eclipse Foundation 14 | 15 | -------------------------------------------------------------------------------- /spec/src/theme/jakartaee-theme.yml: -------------------------------------------------------------------------------- 1 | extends: base 2 | page: 3 | margin: [30,50,30,50] 4 | size: Letter 5 | font: 6 | catalog: 7 | # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols 8 | Noto Serif: 9 | normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf 10 | bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf 11 | italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf 12 | bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf 13 | # M+ 1mn supports ASCII and the circled numbers used for conums 14 | M+ 1mn: 15 | normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf 16 | bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf 17 | italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf 18 | bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf 19 | # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols 20 | # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font 21 | M+ 1p Fallback: 22 | normal: GEM_FONTS_DIR/mplus1p-regular-fallback.ttf 23 | bold: GEM_FONTS_DIR/mplus1p-regular-fallback.ttf 24 | italic: GEM_FONTS_DIR/mplus1p-regular-fallback.ttf 25 | bold_italic: GEM_FONTS_DIR/mplus1p-regular-fallback.ttf 26 | fallbacks: 27 | - M+ 1p Fallback 28 | base: 29 | font: 30 | color: #151e3d 31 | family: Noto Serif 32 | size: 9 33 | line-height-length: 11.5 34 | line-height: $base-line-height-length / $base-font-size 35 | prose: 36 | margin-bottom: 8 37 | image: 38 | width: 70% 39 | align: center 40 | codespan: 41 | font: 42 | size: 0.94em 43 | family: M+ 1mn 44 | color: #281e5d 45 | code: 46 | font: 47 | size: 0.94em 48 | color: #281e5d 49 | family: M+ 1mn 50 | border-width: 0 51 | padding: [4,4,4,20] 52 | # background-color: #f7f7f7 53 | sidebar: 54 | border-width: 0 55 | title: 56 | align: center 57 | admonition: 58 | label: 59 | vertical-align: top 60 | padding: [4, 8, 4, 8] 61 | column-rule: 62 | style: solid 63 | width: 1 64 | color: #f0f0f0 65 | icon: 66 | tip: 67 | stroke-color: #FFC300 68 | warning: 69 | stroke-color: #FF5733 70 | caution: 71 | stroke-color: #FF5733 72 | heading: 73 | font: 74 | color: #001861 75 | size: 11 76 | style: bold 77 | line-height: 1.2 78 | h2-font-size: $base-font-size * 1.3 79 | h3-font-size: $base-font-size * 1.2 80 | h4-font-size: $base-font-size * 1.1 81 | h5-font-size: $base-font-size * 1.0 82 | margin-bottom: $base-line-height-length 83 | link: 84 | font-color: #002FA7 85 | list: 86 | indent: $base-font-size * 1.5 87 | item-spacing: 2 88 | table: 89 | font-size: 0.94em 90 | caption: 91 | text-align: center 92 | side: top 93 | font-size: 0.94em 94 | grid: 95 | color: #f0f0f0 96 | style: solid 97 | width: 1 98 | border: 99 | width: 1 100 | color: #f0f0f0 101 | head: 102 | background-color: #f0f0f0 103 | cell: 104 | padding: 6 105 | footer: 106 | border-width: 0 107 | quote: 108 | font-style: italic 109 | font-color: #001861 110 | font-size: 1.1em 111 | # background-color: #f1f1f1 112 | border-color: #000000 113 | border-radius: 2 114 | border-style: dotted 115 | padding: [10,20,10,25] 116 | title_page: 117 | align: right 118 | logo: 119 | top: 10% 120 | title: 121 | top: 55% 122 | font_size: $heading-h1-font-size 123 | font_color: 999999 124 | line_height: 0.9 125 | subtitle: 126 | font_size: $heading-h3-font-size 127 | font_style: bold_italic 128 | line_height: 1 129 | authors: 130 | margin_top: $base-font-size * 1.25 131 | font_size: $base-font-size * 1.25 132 | font_color: 181818 133 | revision: 134 | margin_top: $base_font_size * 1.25 135 | -------------------------------------------------------------------------------- /tck/.gitignore: -------------------------------------------------------------------------------- 1 | target/ 2 | pom.xml.tag 3 | pom.xml.releaseBackup 4 | pom.xml.versionsBackup 5 | pom.xml.next 6 | test-output/ 7 | /doc 8 | *.iml 9 | *.idea 10 | *.log 11 | /.idea 12 | .checkstyle 13 | 14 | # Eclipse metadata 15 | .settings/ 16 | .project 17 | .factorypath 18 | .classpath 19 | -project 20 | /.resourceCache 21 | /.project 22 | **/.DS_Store 23 | # Annotation processor metadata 24 | .apt_generated/ 25 | .apt_generated_tests/ 26 | -------------------------------------------------------------------------------- /tck/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 10 | 13 | 4.0.0 14 | 15 | 16 | jakarta.nosql 17 | jakarta.nosql-parent 18 | 1.0.1-SNAPSHOT 19 | 20 | 21 | jakarta.nosql-tck 22 | Jakarta NoSQL TCK 23 | Jakarta NoSQL :: TCK 24 | 25 | 26 | 5.12.0 27 | 5.15.2 28 | 3.27.2 29 | 4.2.2 30 | 2.4.2 31 | 1.17.1 32 | 1.2.1 33 | 34 | 35 | 36 | 37 | 38 | jakarta.nosql 39 | jakarta.nosql-api 40 | ${project.version} 41 | provided 42 | 43 | 44 | org.junit.jupiter 45 | junit-jupiter-api 46 | ${junit.version} 47 | 48 | 49 | org.junit.jupiter 50 | junit-jupiter-engine 51 | ${junit.version} 52 | 53 | 54 | org.junit.jupiter 55 | junit-jupiter-params 56 | ${junit.version} 57 | 58 | 59 | org.mockito 60 | mockito-core 61 | ${mockito.version} 62 | 63 | 64 | org.mockito 65 | mockito-junit-jupiter 66 | ${mockito.version} 67 | 68 | 69 | net.datafaker 70 | datafaker 71 | ${datafaker.version} 72 | 73 | 74 | org.assertj 75 | assertj-core 76 | ${assertj.version} 77 | 78 | 79 | org.awaitility 80 | awaitility 81 | ${awaitility.version} 82 | 83 | 84 | 85 | 86 | -------------------------------------------------------------------------------- /tck/src/main/java/ee/jakarta/tck/nosql/AbstractTemplateTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package ee.jakarta.tck.nosql; 17 | 18 | import jakarta.nosql.Template; 19 | import ee.jakarta.tck.nosql.entities.Animal; 20 | import ee.jakarta.tck.nosql.entities.Book; 21 | import ee.jakarta.tck.nosql.entities.Drink; 22 | import ee.jakarta.tck.nosql.entities.Person; 23 | import ee.jakarta.tck.nosql.entities.Vehicle; 24 | import org.junit.jupiter.api.BeforeEach; 25 | 26 | import java.util.logging.Logger; 27 | 28 | public abstract class AbstractTemplateTest { 29 | 30 | private static final Logger LOGGER = Logger.getLogger(AbstractTemplateTest.class.getName()); 31 | 32 | protected Template template; 33 | 34 | @BeforeEach 35 | void setUp() { 36 | LOGGER.info("Getting the template"); 37 | TemplateSupplier supplier = TemplateSupplier.template(); 38 | this.template = supplier.get(); 39 | LOGGER.info("Cleaning up the database"); 40 | try { 41 | template.delete(Person.class).execute(); 42 | template.delete(Animal.class).execute(); 43 | template.delete(Vehicle.class).execute(); 44 | template.delete(Book.class).execute(); 45 | template.delete(Drink.class).execute(); 46 | } catch (UnsupportedOperationException e) { 47 | LOGGER.warning("The delete operation is not supported"); 48 | } 49 | } 50 | 51 | 52 | } 53 | -------------------------------------------------------------------------------- /tck/src/main/java/ee/jakarta/tck/nosql/TemplateSupplier.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024 Contributors to the Eclipse Foundation 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0 which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the Eclipse 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2 11 | * with the GNU Classpath Exception which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | package ee.jakarta.tck.nosql; 17 | 18 | import jakarta.nosql.Template; 19 | 20 | import java.util.ServiceLoader; 21 | import java.util.function.Supplier; 22 | 23 | /** 24 | * The {@code TemplateSupplier} interface provides a mechanism for obtaining instances of {@link Template}. 25 | * {@link Template} is a utility class designed to enhance productivity by simplifying common NoSQL operations. 26 | * 27 | *

The {@code TemplateSupplier} abstracts the complexity of database configuration and dependency injection, 28 | * facilitating seamless interaction with NoSQL databases, particularly schema-based databases.

29 | * 30 | *

Upon creation of a {@code TemplateSupplier} instance, the Jakarta NoSQL provider is responsible for:

31 | *
    32 | *
  • Setting up the database credentials
    • 33 | *
  • Initializing the database
    • 34 | *
  • Configuring the dependency injection mechanism
    • 35 | *
36 | *

Although Jakarta CDI (Contexts and Dependency Injection) is recommended as the dependency injection engine, 37 | * its specific implementation is beyond the scope of the Jakarta NoSQL specification. The specification primarily 38 | * focuses on configuration and management of database resources.

39 | * 40 | *

Once the {@code TemplateSupplier} is instantiated and the {@link #get()} method is invoked, it is expected that the 41 | * returned {@link Template} instance is fully configured and ready for interaction with the database.

42 | * 43 | *

The Jakarta NoSQL provider must implement this interface as part of the Service Provider Interface (SPI) 44 | * to define the creation and configuration of the {@link Template}.

45 | * 46 | * 
47 |  * {@code
48 |  * public interface TemplateSupplier extends Supplier