Merge pull request #140 from eclipse-ee4j/update-documentation

Review the documentation and spec

CHANGELOG.adoc

@@ -17,10 +17,18 @@ and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Version
 - Create a CHANGELOG file to track the specification evolution
 - Move the default documentation to ASCIIDOC
 - Add supplier at Settings API
+- Change the Configurations APIs to be a supplier
+- Update the nomenclature on the Document and Column APIs
+
 
 === Removed
+
 - Remove the settings methods to avoid mutability in the instance.
 
+=== Deprecated
+
+- Deprecate the APIs and annotations that will belong to Jakarta Data
+
 == [1.0.0.4-b4] - 2022-06-04
 
 === Changed

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnCondition.java

@@ -28,7 +28,7 @@
  * It is the state of column queries, with a condition and a value, as a {@link Column},
  * where both combined define a predicate.
  *
- * @see ColumnFamilyManager#select(ColumnQuery)
+ * @see ColumnManager#select(ColumnQuery)
  * @see Condition
  */
 public interface ColumnCondition {

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnConfiguration.java

@@ -20,36 +20,19 @@
 import jakarta.nosql.Settings;
 
 import java.util.ServiceLoader;
+import java.util.function.Function;
 
 
 /**
- * The Jakarta NoSQL configuration to create a {@link ColumnFamilyManagerFactory}
+ * It is a function that reads from {@link Settings} and then creates a manager factory instance.
+ * It should return a {@link NullPointerException} when the {@link Settings} parameter is null.
+ *
+ * @see ColumnManagerFactory
+ * @see ColumnManager
  */
-public interface ColumnConfiguration {
-
-    /**
-     * Reads configuration either from default configuration or a file defined by NoSQL
-     * provider and then creates a {@link ColumnFamilyManagerFactory} instance.
-     *
-     * @param <T> the ColumnFamilyManagerFactory type
-     * @return a {@link ColumnFamilyManagerFactory}
-     */
-    <T extends ColumnFamilyManagerFactory> T get();
+public interface ColumnConfiguration extends Function<Settings, ColumnManagerFactory> {
 
 
-    /**
-     * Reads configuration from the {@link Settings} instance, the parameters are defined by NoSQL
-     * provider, then creates a {@link ColumnFamilyManagerFactory} instance.
-     *
-     * @param <T>      the ColumnFamilyManagerFactory type
-     * @param settings the settings
-     * @return a {@link ColumnFamilyManagerFactory}
-     * @throws NullPointerException when settings is null
-     * @see Settings
-     * @see Settings {@link java.util.Map}
-     */
-    <T extends ColumnFamilyManagerFactory> T get(Settings settings);
-
     /**
      * creates and returns a  {@link ColumnConfiguration}  instance from {@link java.util.ServiceLoader}
      *

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnDeleteQuery.java

@@ -27,7 +27,7 @@
 /**
  * A unit that has the columnFamily and condition to delete from conditions.
  * This instance will be used on:
- * <p>{@link ColumnFamilyManager#delete(ColumnDeleteQuery)}</p>
+ * <p>{@link ColumnManager#delete(ColumnDeleteQuery)}</p>
  */
 public interface ColumnDeleteQuery {
 
@@ -261,7 +261,7 @@ interface ColumnDeleteNotCondition extends ColumnDeleteNameCondition {
     /**
      * The last step to the build of {@link ColumnDeleteQuery}.
      * It either can return a new {@link ColumnDeleteQuery} instance or execute a query with
-     * {@link ColumnFamilyManager}
+     * {@link ColumnManager}
      */
     interface ColumnDeleteQueryBuild {
 
@@ -273,12 +273,12 @@ interface ColumnDeleteQueryBuild {
         ColumnDeleteQuery build();
 
         /**
-         * executes the {@link ColumnFamilyManager#delete(ColumnDeleteQuery)}
+         * executes the {@link ColumnManager#delete(ColumnDeleteQuery)}
          *
          * @param manager the entity manager
          * @throws NullPointerException when manager is null
          */
-        void delete(ColumnFamilyManager manager);
+        void delete(ColumnManager manager);
 
     }
 
@@ -370,13 +370,13 @@ interface ColumnDeleteQueryBuilder {
         ColumnDeleteQuery build();
 
         /**
-         * executes the {@link ColumnFamilyManager#delete(ColumnDeleteQuery)}
+         * executes the {@link ColumnManager#delete(ColumnDeleteQuery)}
          *
          * @param manager the entity manager
          * @throws NullPointerException  when manager is null
          * @throws IllegalStateException It returns a state exception when an element is not valid or not fill-up,
          *                               such as the {@link ColumnDeleteQueryBuilder#from(String)} method was not called.
          */
-        void delete(ColumnFamilyManager manager);
+        void delete(ColumnManager manager);
     }
 }

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnEntity.java

@@ -29,8 +29,10 @@
 import java.util.function.Function;
 
 /**
- * It represents a column family or wide column objects.
- * Each ColumnFamily has a name and one or more {@link Column}.
+ * The communication level entity. It is the API entity between the database and the Jakarta NoSQL communication level.
+ * It represents a column family.
+ * Each ColumnEntity has a name and one or more {@link Column}.
+ *
  * @see Column
  * @see ColumnEntity#getColumns()
  * @see ColumnEntity#getName()

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnFamilyManager.java → api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnManager.java

@@ -29,12 +29,18 @@
 import java.util.stream.Stream;
 
 /**
- * The persistence context to {@link ColumnEntity}.
- * The ColumnFamilyManager API is used to create and remove persistent {@link ColumnEntity} instances,
- * to select entities by their primary key, and to select over entities.
- * Thus, ColumnFamilyManager enables CRUD Operation for {@link ColumnEntity}.
+ * The manager instance bridges the Jakarta NoSQL and the NoSQL vendor.
+ *
+ * @see ColumnEntity
  */
-public interface ColumnFamilyManager extends AutoCloseable {
+public interface ColumnManager extends AutoCloseable {
+
+    /**
+     * Returns the database's name of this {@link ColumnManager}
+     *
+     * @return the database's name
+     */
+    String getName();
 
     /**
      * Saves a Column family entity
@@ -56,7 +62,7 @@ public interface ColumnFamilyManager extends AutoCloseable {
 
     /**
      * Updates a Column family entities, by default it's just run for each saving using
-     * {@link ColumnFamilyManager#update(ColumnEntity)}, each NoSQL vendor might
+     * {@link ColumnManager#update(ColumnEntity)}, each NoSQL vendor might
      * replace to a more appropriate one.
      *
      * @param entities column family to be saved
@@ -78,7 +84,7 @@ public interface ColumnFamilyManager extends AutoCloseable {
 
     /**
      * Saves a Column family entities, by default it's just run for each saving using
-     * {@link ColumnFamilyManager#insert(ColumnEntity)}, each NoSQL vendor might
+     * {@link ColumnManager#insert(ColumnEntity)}, each NoSQL vendor might
      * replace to a more appropriate one.
      *
      * @param entities column family to be saved
@@ -89,7 +95,7 @@ public interface ColumnFamilyManager extends AutoCloseable {
 
     /**
      * Saves a Column family entity with time to live, by default it's just run for each saving using
-     * {@link ColumnFamilyManager#insert(ColumnEntity, Duration)},
+     * {@link ColumnManager#insert(ColumnEntity, Duration)},
      * each NoSQL vendor might replace to a more appropriate one.
      *
      * @param entities column family to be saved

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnFamilyManagerFactory.java → api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnManagerFactory.java

@@ -16,23 +16,16 @@
 
 package jakarta.nosql.column;
 
+import java.util.function.Function;
+
 /**
- * {@link ColumnFamilyManager} factory.
- * When the application has finished using the column family manager factory, and/or at application shutdown,
- * the application should close the column family manager factory.
+ * The manager factory instance creates a manager instance from the database name.
+ * It should return a {@link NullPointerException} when the {@link String} parameter is null.
+ *
+ * @see ColumnManager
  */
-public interface ColumnFamilyManagerFactory extends AutoCloseable {
+public interface ColumnManagerFactory extends Function<String, ColumnManager>, AutoCloseable {
 
-    /**
-     * Creates a {@link ColumnFamilyManager} from database's name
-     *
-     * @param <T>      the {@link ColumnFamilyManager} type
-     * @param database a database name
-     * @return a new {@link ColumnFamilyManager} instance
-     * @throws UnsupportedOperationException when this operation is not supported
-     *                                       throws {@link NullPointerException} when the database is null
-     */
-    <T extends ColumnFamilyManager> T get(String database);
 
     /**
      * closes a resource

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnQuery.java

@@ -31,7 +31,7 @@
 /**
  * Class that contains information to do a select to {@link ColumnEntity}
  *
- * @see ColumnFamilyManager#select(ColumnQuery)
+ * @see ColumnManager#select(ColumnQuery)
  * @see ColumnCondition
  * @see Sort
  */
@@ -267,7 +267,7 @@ interface ColumnOrder {
     /**
      * The last step to the build of {@link ColumnQuery}.
      * It either can return a new {@link ColumnQuery} instance or execute a query with
-     * {@link ColumnFamilyManager}
+     * {@link ColumnManager}
      */
     interface ColumnQueryBuild {
 
@@ -279,22 +279,22 @@ interface ColumnQueryBuild {
         ColumnQuery build();
 
         /**
-         * Executes {@link ColumnFamilyManager#select(ColumnQuery)}
+         * Executes {@link ColumnManager#select(ColumnQuery)}
          *
          * @param manager the entity manager
-         * @return the result of {@link ColumnFamilyManager#select(ColumnQuery)}
+         * @return the result of {@link ColumnManager#select(ColumnQuery)}
          * @throws NullPointerException when manager is null
          */
-        Stream<ColumnEntity> getResult(ColumnFamilyManager manager);
+        Stream<ColumnEntity> getResult(ColumnManager manager);
 
         /**
-         * Executes {@link ColumnFamilyManager#singleResult(ColumnQuery)}
+         * Executes {@link ColumnManager#singleResult(ColumnQuery)}
          *
          * @param manager the entity manager
-         * @return the result of {@link ColumnFamilyManager#singleResult(ColumnQuery)}
+         * @return the result of {@link ColumnManager#singleResult(ColumnQuery)}
          * @throws NullPointerException when manager is null
          */
-        Optional<ColumnEntity> getSingleResult(ColumnFamilyManager manager);
+        Optional<ColumnEntity> getSingleResult(ColumnManager manager);
 
     }
 
@@ -601,25 +601,25 @@ interface ColumnQueryBuilder {
         ColumnQuery build();
 
         /**
-         * Executes {@link ColumnFamilyManager#select(ColumnQuery)}
+         * Executes {@link ColumnManager#select(ColumnQuery)}
          *
          * @param manager the entity manager
-         * @return the result of {@link ColumnFamilyManager#select(ColumnQuery)}
+         * @return the result of {@link ColumnManager#select(ColumnQuery)}
          * @throws NullPointerException  when manager is null
          * @throws IllegalStateException It returns a state exception when an element is not valid or not fill-up,
          *                               such as the {@link ColumnQueryBuilder#from(String)} method was not called.
          */
-        Stream<ColumnEntity> getResult(ColumnFamilyManager manager);
+        Stream<ColumnEntity> getResult(ColumnManager manager);
 
         /**
-         * Executes {@link ColumnFamilyManager#singleResult(ColumnQuery)}
+         * Executes {@link ColumnManager#singleResult(ColumnQuery)}
          *
          * @param manager the entity manager
-         * @return the result of {@link ColumnFamilyManager#singleResult(ColumnQuery)}
+         * @return the result of {@link ColumnManager#singleResult(ColumnQuery)}
          * @throws NullPointerException  when manager is null
          * @throws IllegalStateException It returns a state exception when an element is not valid or not fill-up,
          *                               such as the {@link ColumnQueryBuilder#from(String)} method was not called.
          */
-        Optional<ColumnEntity> getSingleResult(ColumnFamilyManager manager);
+        Optional<ColumnEntity> getSingleResult(ColumnManager manager);
     }
 }

api/communication/communication-column/src/main/java/jakarta/nosql/column/ColumnQueryParser.java

@@ -21,7 +21,7 @@
 import java.util.stream.Stream;
 
 /**
- * A query parser to column database type, this class will convert a String to an operation in {@link ColumnFamilyManager}.
+ * A query parser to column database type, this class will convert a String to an operation in {@link ColumnManager}.
  */
 public interface ColumnQueryParser {
 
@@ -37,7 +37,7 @@ public interface ColumnQueryParser {
      * @throws IllegalArgumentException when the query has value parameters
      * @throws QueryException           when there is error in the syntax
      */
-    Stream<ColumnEntity> query(String query, ColumnFamilyManager manager, ColumnObserverParser observer);
+    Stream<ColumnEntity> query(String query, ColumnManager manager, ColumnObserverParser observer);
 
     /**
      * Executes a query and returns a {@link ColumnPreparedStatement}, when the operations are <b>insert</b>, <b>update</b> and <b>select</b>
@@ -51,7 +51,7 @@ public interface ColumnQueryParser {
      * @throws IllegalArgumentException when the query has value parameters
      * @throws QueryException           when there is error in the syntax
      */
-    ColumnPreparedStatement prepare(String query, ColumnFamilyManager manager, ColumnObserverParser observer);
+    ColumnPreparedStatement prepare(String query, ColumnManager manager, ColumnObserverParser observer);
 
 
 }

api/communication/communication-column/src/test/java/jakarta/nosql/column/ColumnFamilyManagerTest.java → api/communication/communication-column/src/test/java/jakarta/nosql/column/ColumnManagerTest.java

@@ -34,10 +34,10 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 @ExtendWith(MockitoExtension.class)
-class ColumnFamilyManagerTest {
+class ColumnManagerTest {
 
     @Spy
-    private ColumnFamilyManager manager;
+    private ColumnManager manager;
 
     @Test
     public void shouldReturnSingleResult() {

api/communication/communication-document/src/main/java/jakarta/nosql/document/DocumentCondition.java

@@ -28,7 +28,7 @@
  * It is the state of column queries, with a condition and a value, as a {@link Document},
  * where both combined define a predicate.
  *
- * @see DocumentCollectionManager#select(DocumentQuery)
+ * @see DocumentManager#select(DocumentQuery)
  * @see Condition
  */
 public interface DocumentCondition {

api/communication/communication-document/src/main/java/jakarta/nosql/document/DocumentConfiguration.java

@@ -20,35 +20,16 @@
 import jakarta.nosql.Settings;
 
 import java.util.ServiceLoader;
+import java.util.function.Function;
 
 /**
- * The Jakarta NoSQL configuration to create a {@link DocumentCollectionManagerFactory}
+ * It is a function that reads from {@link Settings} and then creates a manager factory instance.
+ * It should return a {@link NullPointerException} when the {@link Settings} parameter is null.
+ *
+ * @see DocumentManagerFactory
+ * @see DocumentManager
  */
-public interface DocumentConfiguration {
-
-
-    /**
-     * Reads configuration either from default configuration or a file defined by NoSQL provider and then creates a
-     * {@link DocumentCollectionManagerFactory} instance.
-     *
-     * @param <T> the type to DocumentCollectionManagerFactory
-     * @return a {@link DocumentCollectionManagerFactory} instance
-     */
-    <T extends DocumentCollectionManagerFactory> T get();
-
-
-    /**
-     * Reads configuration from the {@link Settings} instance, the parameters are defined by NoSQL
-     * provider, then creates a {@link DocumentCollectionManagerFactory} instance.
-     *
-     * @param <T>      the type to DocumentCollectionManagerFactory
-     * @param settings the settings
-     * @return a {@link DocumentCollectionManagerFactory}
-     * @throws NullPointerException when settings is null
-     * @see Settings
-     * @see Settings {@link java.util.Map}
-     */
-    <T extends DocumentCollectionManagerFactory> T get(Settings settings);
+public interface DocumentConfiguration extends Function<Settings, DocumentManagerFactory> {
 
     /**
      * creates and returns a  {@link DocumentConfiguration}  instance from {@link java.util.ServiceLoader}