From 1b25bbd51cdb02de17b854367aa395f722ee647d Mon Sep 17 00:00:00 2001 From: Otavio Santana Date: Tue, 11 Feb 2025 08:19:49 +0000 Subject: [PATCH] docs: enhance documentation at entties Signed-off-by: Otavio Santana --- tck/README.adoc | 110 ------------------ .../tck/nosql/entities/package-info.java | 18 +++ 2 files changed, 18 insertions(+), 110 deletions(-) delete mode 100644 tck/README.adoc create mode 100644 tck/src/main/java/ee/jakarta/tck/nosql/entities/package-info.java diff --git a/tck/README.adoc b/tck/README.adoc deleted file mode 100644 index fc490d469..000000000 --- a/tck/README.adoc +++ /dev/null @@ -1,110 +0,0 @@ -= Jakarta NoSQL TCK -:toc: - -== Introduction - -The Jakarta NoSQL Technology Compatibility Kit (TCK) is a suite of tests designed to verify that a Jakarta NoSQL implementation is compatible with the Jakarta NoSQL specification. It ensures consistency and reliability across different implementations of the Jakarta NoSQL API. - -Any Jakarta NoSQL module must pass this test suite to be considered compliant with the Jakarta NoSQL standards. - - -== Dependencies - -You must add the appropriate TCK module dependency for the Jakarta NoSQL implementation you wish to test in your build file to enable the tests. Here is an example of how to configure it in your `pom.xml` file: - -[source,xml] ----- - - 1.0.0 - - - - jakarta.nosql - jakarta.nosql-tck - ${jakarta.nosql.version} - test - ----- - -== Configuration in Apache Maven pom.xml - -The tests are run by the `maven-surefire-plugin`. Ensure that your `pom.xml` is configured correctly to include this plugin and scan for the necessary dependencies. Below is an example configuration: - -[source,xml] ----- - - - - org.apache.maven.plugins - maven-surefire-plugin - ${maven.surefire.plugin.version} - - - jakarta.nosql:jakarta.nosql-tck - - - - - ----- - -== Implementing `TemplateSupplier` and Defining it in SPI - -The `TemplateSupplier` interface plays a vital role in the Jakarta NoSQL TCK (Technology Compatibility Kit). It allows developers to obtain a fully configured `Template` instance for interacting with NoSQL databases. By abstracting the complexities of database configuration and dependency injection, the `TemplateSupplier` simplifies the process of working with schema-based NoSQL databases. - -=== Implementing `TemplateSupplier` - -Your implementation must provide an instance of `Template`, which is expected to be fully configured and ready for interaction with the database. - -Example: - -[source,java] ----- -public class MyTemplateSupplier implements TemplateSupplier { - - @Override - public Template get() { - // Set up database connection, credentials, and configuration - return new MyTemplate(); // Return a Template instance connected to the database - } -} ----- - -=== Defining `TemplateSupplier` in the SPI - -To make your `TemplateSupplier` implementation available to the Service Provider Interface (SPI), follow these steps: - -1. **Create the `META-INF/services` Directory:** -Create the directory `META-INF/services` at the root of your project. - -2. **Create the SPI Configuration File:** -Inside the `META-INF/services` directory, create a file named `ee.jakarta.tck.nosql.TemplateSupplier` (the fully qualified name of the interface). - -3. **Register Your Implementation:** -In this file, specify the fully qualified name of your `TemplateSupplier` implementation class. For example: - -[source] ----- -com.example.MyTemplateSupplier ----- - -=== Expectations - -- **Database Lifecycle:** - - The `TemplateSupplier` is not responsible for managing the database's Lifecycle. The database is expected to be already running when the `Template` instance is created and returned. The `TemplateSupplier` is only responsible for setting up the `Template` with the necessary configuration to interact with the database. - -- **Template Initialization:** - - When the `get()` method is invoked, it is expected that the `Template` instance will be fully initialized and configured to interact with the database. The database connection, credentials, and any necessary configurations must be provided during the `Template` instantiation. - - For example, your `get()` method might return a `Template` connected to a specific database, with authentication credentials and configurations loaded from a configuration file or environment variables. - -=== Example SPI File - -Here is how the `META-INF/services/jakarta.nosql.tck.TemplateSupplier` file should look: - -[source] ----- -com.example.MyTemplateSupplier ----- diff --git a/tck/src/main/java/ee/jakarta/tck/nosql/entities/package-info.java b/tck/src/main/java/ee/jakarta/tck/nosql/entities/package-info.java new file mode 100644 index 000000000..5d2ac6bd0 --- /dev/null +++ b/tck/src/main/java/ee/jakarta/tck/nosql/entities/package-info.java @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2024 Contributors to the Eclipse Foundation + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0 which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +/** + * This package contains entity classes and converters for use in Jakarta NoSQL TCK tests. + * The entities represent domain models used to validate Jakarta NoSQL implementations, + * while converters handle type transformations where necessary. + * These classes support testing CRUD operations, queries, and annotation behavior + * across different NoSQL databases. + */ +package ee.jakarta.tck.nosql.entities; \ No newline at end of file