Issue helidon-io#6991 - Blocking DB Client: Removed result generic ty…

…pe from DbStatement. Code cleanup.

Signed-off-by: Tomáš Kraus <tomas.kraus@oracle.com>

dbclient/common/src/main/java/io/helidon/dbclient/common/CommonClient.java

@@ -17,14 +17,28 @@
 
 import io.helidon.dbclient.DbClient;
 
+/**
+ * Helidon database client.
+ * <p>Common {@link DbClient} implementations ancestor with {@link CommonClientContext}.
+ */
 public abstract class CommonClient implements DbClient {
 
     private final CommonClientContext context;
 
+    /**
+     * Creates an instance of {@lik CommonClient}.
+     *
+     * @param context database client context.
+     */
     public CommonClient(CommonClientContext context) {
         this.context = context;
     }
 
+    /**
+     * Get database client context.
+     *
+     * @return database client context.
+     */
     public CommonClientContext context() {
         return context;
     }

dbclient/common/src/main/java/io/helidon/dbclient/common/CommonClientBuilder.java

@@ -26,6 +26,13 @@
 import io.helidon.dbclient.spi.DbClientBuilder;
 import io.helidon.dbclient.spi.DbMapperProvider;
 
+/**
+ * Provider specific {@link io.helidon.dbclient.DbClient} builder.
+ * <p>Common {@link DbClientBuilder} implementations ancestor with {@link DbMapperManager.Builder}
+ * and common attributes required to initialize target {@code DbClient} instance.
+ *
+ * @param <T> type of the builder extending or implementing this interface.
+ */
 public abstract class CommonClientBuilder<T extends CommonClientBuilder<T>>
         implements DbClientBuilder<T> {
 
@@ -37,6 +44,9 @@ public abstract class CommonClientBuilder<T extends CommonClientBuilder<T>>
     private MapperManager mapperManager;
     private DbMapperManager dbMapperManager;
 
+    /**
+     * Creates an instance of {@link CommonClientBuilder}.
+     */
     protected CommonClientBuilder() {
     }
 
@@ -117,18 +127,38 @@ public T addMapperProvider(DbMapperProvider provider) {
         return identity();
     }
 
+    /**
+     * Get database URL.
+     *
+     * @return database URL
+     */
     public String url() {
         return url;
     }
 
+    /**
+     * Get database user name.
+     *
+     * @return database user name
+     */
     public String username() {
         return username;
     }
 
+    /**
+     * Get database user password.
+     *
+     * @return database user password.
+     */
     public String password() {
         return password;
     }
 
+    /**
+     * Get configured statements to be used by database provider.
+     *
+     * @return statements to be used by database provider
+     */
     public DbStatements statements() {
         return statements;
     }
@@ -137,10 +167,20 @@ public DbStatements statements() {
 //        return List.copyOf(clientServices);
 //    }
 
+    /**
+     * Get {@link io.helidon.common.mapper.Mapper} manager.
+     *
+     * @return {@code Mapper} manager.
+     */
     public MapperManager mapperManager() {
         return mapperManager;
     }
 
+    /**
+     * Get manager of all configured {@link DbMapper mappers}.
+     *
+     * @return manager of all configured {@link DbMapper mappers}
+     */
     public DbMapperManager dbMapperManager() {
         return dbMapperManager;
     }

dbclient/common/src/main/java/io/helidon/dbclient/common/CommonClientContext.java

@@ -110,8 +110,6 @@ public static Builder builder() {
 
     /**
      * A common base for builders for classes that want to extend {@link CommonClientContext}.
-     *
-     * @param <T> type of the builder extending this builder, to keep fluent API
      */
     public static class Builder implements io.helidon.common.Builder<Builder, CommonClientContext> {
 

dbclient/common/src/main/java/io/helidon/dbclient/common/CommonColumn.java

@@ -21,16 +21,24 @@
 import io.helidon.dbclient.DbClient;
 import io.helidon.dbclient.DbColumn;
 
+/**
+ * Column data and metadata.
+ * <p>Common {@link DbColumn} implementations ancestor with {@link MapperManager} and database column value.
+ */
 public abstract class CommonColumn implements DbColumn {
 
-    protected final Object value;
+    private final Object value;
     private final  MapperManager mapperManager;
 
     protected CommonColumn(Object value, MapperManager mapperManager) {
         this.value = value;
         this.mapperManager = mapperManager;
     }
 
+    protected Object rawValue() {
+        return value;
+    }
+
     @Override
     public <T> T as(Class<T> type) throws MapperException {
         if (null == value) {

dbclient/common/src/main/java/io/helidon/dbclient/common/CommonRow.java

@@ -26,10 +26,14 @@
 import io.helidon.dbclient.DbMapperManager;
 import io.helidon.dbclient.DbRow;
 
+/**
+ * Representation of a single row in a database (in SQL this would be a row, in a Document DB, this would be a single document).
+ * <p>Common {@link DbRow} implementations ancestor with {@link DbMapperManager} and an array of {@link DbColumn}s.
+ */
 public abstract class CommonRow implements DbRow {
 
     private final DbMapperManager dbMapperManager;
-    CommonColumn[] columns;
+    private final CommonColumn[] columns;
     private final Map<String, CommonColumn> namesIndex;
 
     protected CommonRow(CommonColumn[] columns, DbMapperManager dbMapperManager) {

dbclient/common/src/main/java/io/helidon/dbclient/common/CommonStatement.java

@@ -23,10 +23,9 @@
 /**
  * Common statement methods and fields.
  *
- * @param <S> type of a subclass
- * @param <R> the result type of the statement as returned by {@link #execute()}
+ * @param <S> type of the descendant of this class
  */
-public abstract class CommonStatement <S extends DbStatement<S, R>, R> implements DbStatement<S, R> {
+public abstract class CommonStatement<S extends DbStatement<S>> implements DbStatement<S> {
 
     private final CommonClientContext context;
 
@@ -50,6 +49,7 @@ public S indexedParam(Object parameters) {
         return identity();
     }
 
+    @Override
     public S params(List<?> parameters) {
         parameters.forEach(this::addParam);
         return identity();

dbclient/common/src/main/java/io/helidon/dbclient/common/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2023 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Helper classes to use in various implementations.
+ */
+package io.helidon.dbclient.common;

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbClient.java

@@ -16,8 +16,6 @@
 package io.helidon.dbclient;
 
 import java.util.Arrays;
-import java.util.Optional;
-import java.util.stream.Stream;
 
 import io.helidon.common.mapper.MapperManager;
 import io.helidon.config.Config;

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbClientInterceptor.java

@@ -35,6 +35,6 @@ public interface DbClientInterceptor {
      * @return single that completes when this service is finished
      */
     Void statement(Void context);
-    //TODO: replace with DbClientServiceContext statement(DbClientServiceContext context);
+    //FIXME: replace with DbClientServiceContext statement(DbClientServiceContext context);
 
 }

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbMapperManager.java

@@ -29,14 +29,13 @@
  */
 public interface DbMapperManager {
 
+    /** Generic type for the {@link DbRow} class. */
     GenericType<DbRow> TYPE_DB_ROW = GenericType.create(DbRow.class);
-    /**
-     * Generic type for the {@link java.util.Map} of String to value pairs for named parameters.
-     */
+
+    /** Generic type for the {@link java.util.Map} of String to value pairs for named parameters. */
     GenericType<Map<String, ?>> TYPE_NAMED_PARAMS = new GenericType<Map<String, ?>>() { };
-    /**
-     * Generic type for the {@link java.util.List} of indexed parameters.
-     */
+
+    /** Generic type for the {@link java.util.List} of indexed parameters. */
     GenericType<List<?>> TYPE_INDEXED_PARAMS = new GenericType<List<?>>() { };
 
     /**

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbStatement.java

@@ -23,23 +23,21 @@
 
 /**
  * Database statement that can process parameters.
- * Method {@link #execute()} processes the statement and returns appropriate response.
+ * Method {@code execute()} processes the statement and returns appropriate response.
  * <p>
- * All methods are non-blocking. The {@link #execute()} method returns either a {@link java.util.concurrent.CompletionStage}
- * or another object that provides similar API for eventual processing of the response.
+ * All methods are blocking.
  * <p>
  * Once parameters are set using one of the {@code params} methods, all other methods throw an
  * {@link IllegalStateException}.
  * <p>
  * Once a parameter is added using {@link #addParam(Object)} or {@link #addParam(String, Object)}, all other
  * {@code params} methods throw an {@link IllegalStateException}.
  * <p>
- * Once {@link #execute()} is called, all methods would throw an {@link IllegalStateException}.
+ * Once {@code execute()} is called, all methods would throw an {@link IllegalStateException}.
  *
- * @param <R> Type of the result of this statement (e.g. a {@link java.util.concurrent.CompletionStage})
- * @param <D> Type of the descendant of this class
+ * @param <D> type of the descendant of this class
  */
-public interface DbStatement<D extends DbStatement<D, R>, R> {
+public interface DbStatement<D extends DbStatement<D>> {
 
     /**
      * Configure parameters from a {@link java.util.List} by order.
@@ -304,10 +302,4 @@ default D params(Object... parameters) {
      */
     D addParam(String name, byte[] parameter);
 
-    /**
-     * Execute this statement using the parameters configured with {@code params} and {@code addParams} methods.
-     *
-     * @return The result of this statement, never blocking.
-     */
-    R execute();
 }

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbStatementDml.java

@@ -19,5 +19,13 @@
  * DML Database statement.
  * A DML statement modifies records in the database and returns the number of modified records.
  */
-public interface DbStatementDml extends DbStatement<DbStatementDml, Long> {
+public interface DbStatementDml extends DbStatement<DbStatementDml> {
+
+    /**
+     * Execute this statement using the parameters configured with {@code params} and {@code addParams} methods.
+     *
+     * @return The result of this statement, never blocking.
+     */
+    long execute();
+
 }

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbStatementGet.java

@@ -19,8 +19,14 @@
 
 /**
  * Database statement that queries the database and returns a single row if present, or an empty optional.
- * In case the statement returns more than one rows, the future returned by {@link #execute()} will end in
- * {@link java.util.concurrent.CompletionStage#exceptionally(java.util.function.Function)}.
  */
-public interface DbStatementGet extends DbStatement<DbStatementGet, Optional<DbRow>> {
+public interface DbStatementGet extends DbStatement<DbStatementGet> {
+
+    /**
+     * Execute this statement using the parameters configured with {@code params} and {@code addParams} methods.
+     *
+     * @return The result of this statement, never blocking.
+     */
+    Optional<DbRow> execute();
+
 }

dbclient/dbclient/src/main/java/io/helidon/dbclient/DbStatementQuery.java

@@ -19,9 +19,18 @@
 
 /**
  * Database query statement.
- * <p><b>Important:</b> Method {@link #execute()} returns {@link Stream} of {@link DbRow}. This {@link Stream} must
- * always be closed because it holds database resources ({@code java.sql.Connection}, {@code java.sql.Statement}
+ * <p><b>Important:</b> Method {@link #execute()} returns {@link Stream} of {@link DbRow}. This {@link Stream}
+ * must be always closed because it holds database resources ({@code java.sql.Connection}, {@code java.sql.Statement}
  * and {@code java.sql.ResultSet}).
  */
-public interface DbStatementQuery extends DbStatement<DbStatementQuery, Stream<DbRow>> {
+public interface DbStatementQuery extends DbStatement<DbStatementQuery> {
+
+    /**
+     * Execute this statement using the parameters configured with {@code params} and {@code addParams} methods.
+     * <p>Returned {@link Stream} of {@link DbRow} must be always closed because it holds database resources.
+     *
+     * @return The result of this statement, never blocking.
+     */
+    Stream<DbRow> execute();
+
 }

dbclient/dbclient/src/main/java/io/helidon/dbclient/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2023 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Database client API for Helidon.
+ */
+package io.helidon.dbclient;

dbclient/dbclient/src/main/java/io/helidon/dbclient/spi/package-info.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2023 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Service provider interface for Helidon DB.
+ * The main entry point for driver implementor is {@link io.helidon.dbclient.spi.DbClientProvider}.
+ *
+ * @see io.helidon.dbclient.spi.DbClientProvider
+ * @see io.helidon.dbclient.spi.DbClientBuilder
+ * @see io.helidon.dbclient.spi.DbMapperProvider
+ */
+package io.helidon.dbclient.spi;