#13: QueryResultRow conversion for Product types

.github/workflows/build.yml

@@ -69,6 +69,7 @@ jobs:
           psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/05_testing._base_types_data.sql
           psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/06_testing.pg_types.ddl
           psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/07_testing_pg_types_data.sql
+          psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/08_testing.simple_function.sql
 
       - name: Build and run integration tests
         run: sbt ++${{matrix.scala}} testIT

.github/workflows/jacoco_report.yml

@@ -46,6 +46,7 @@ jobs:
           psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/05_testing._base_types_data.sql
           psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/06_testing.pg_types.ddl
           psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/07_testing_pg_types_data.sql
+          psql postgresql://postgres:postgres@localhost:5432/mag_db -f balta/src/test/resources/db/postgres/08_testing.simple_function.sql
 
       - name: Build and run tests
         continue-on-error: true

.sbtrc

@@ -25,3 +25,5 @@ alias test=; testOnly *UnitTests
 # * Integration tests
 alias testIT=; testOnly *IntegrationTests
 
+# Run all tests
+alias testAll=; testOnly *

README.md

@@ -27,17 +27,71 @@ It's a natural complement to the use of [Fa-Db library](https://github.com/AbsaO
 
  * The transaction start and rollback are done automatically before or after the execution respectively of the `test` function provided
 
-Advantages of this approach is that the tests repeateble, they are isolated from each other and the database is always 
+Advantages of this approach is that the tests are repeatable, they are isolated from each other and the database is always 
 in a known state before and after each test.
 
-## How to Test
-There are integration tests part of the package that can be run with the following command:
 
+## How to write tests
+
+### [`DBTestSuite`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/DBTestSuite.scala) class
+
+The foundation is the [`DBTestSuite`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/DBTestSuite.scala) 
+class that provides the necessary setup and teardown for the tests to each run in its own transaction. It is an 
+enhancement class to standard ScalaTest `AnyFunSuite` class.
+
+Besides that, it provides easy access to tables, queries them and inserts data into them.
+
+And it allows easy access to database functions and executing them.
+
+### [`DBTable`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/classes/DBTable.scala) class
+
+Class for representing a database table. It provides methods for querying the table and inserting data into it. The class 
+instance is spawned by each `DBTestSuite.table` method call. 
+
+### [`DBFunction`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/classes/DBFunction.scala) class
+
+Class for representing a database function. It provides methods for calling the function and verifying the return values.
+The class instance is spawned by each `DBTestSuite.function` method call.
+
+### [`QueryResult`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/classes/QueryResult.scala) class
+
+This iterator represents the result of a query. It provides methods for iterating over the rows and columns of the result.
+
+### [`QueryResultRow`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/classes/QueryResultRow.scala) class
+
+This class represents a row in a query result. It provides methods for accessing the columns of the row - via name or index.
+
+To make specific Postgres types available in `QueryResultRow` there is the implicit class 
+[`Postgres.PostgresRow`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/implicits/Postgres.scala)
+enhancing the `QueryResultRow` with the ability to get type like `JSON` (including JSONB) and `JSON[]` (JSON array).
+
+There is also an implicit class 
+[`QueryResultImplicits.ProductTypeConvertor`](https://github.com/AbsaOSS/balta/blob/master/balta/src/main/scala/za/co/absa/db/balta/implicits/QueryResultImplicits.scala) 
+enhancing  the `QueryResultRow` with the ability to convert the row to a product type (case class or tuple) via function
+`toProductType[T]`.
+
+
+
+
+
+## How to test the library
+
+Use the `test` command to execute all unit tests, skipping all other types of tests.
+```bash
+sbt test
+```
+
+There are integration tests part of the package that can be run with the following command:
 ```bash
 sbt testIT
 ```
 
-The tests to finish successfully, a Postgres database must be running and populated.
+If you want to run all tests, use the following command.
+```bash
+sbt testAll
+```
+
+The integrations tests to finish successfully, a Postgres database must be running and populated.
 * by default the database is expected to be running on `localhost:5432`
 * if you wish to run against a different server modify the `src/test/resources/database.properties` file
 * to populate the database run the scripts in the `src/test/resources/db/postgres` folder
@@ -59,3 +113,4 @@ Please see [this file](RELEASE.md) for more details.
 
 ### Postgres
 * `TIMESTAMP WITH TIME ZONE[]`, `TIME WITH TIME ZONE[]`, generally arrays of time related types are not translated to appropriate time zone aware Scala/Java types
+* Conversion to product type won't work if there are complex members in the product type like subclasses; with container types like `List`, it hasn't been tested 

balta/src/main/scala/za/co/absa/db/balta/classes/QueryResultRow.scala

@@ -17,6 +17,7 @@
 package za.co.absa.db.balta.classes
 
 import QueryResultRow._
+import za.co.absa.db.balta.implicits.MapImplicits.MapEnhancements
 
 import java.sql
 import java.sql.{Date, ResultSet, ResultSetMetaData, Time, Types}
@@ -26,16 +27,21 @@ import java.util.UUID
 /**
  * This is a row of a query result. It allows to safely extract values from the row by column name.
  *
- * @param rowNumber   - the number of the row in the result set
- * @param fields      - the values of the row
- * @param columnNames - the names of the columns
+ * @param rowNumber     - the number of the row in the result set
+ * @param fields        - the values of the row
+ * @param columnLabels  - the names of the columns; class uses `columnLabel(s)` to refer to the column names in accordance
+ *                      to `java.sql.ResultSet`, which is is build around and that despite that aliases are not expected
+ *                      to appear here
  */
 class QueryResultRow private[classes](val rowNumber: Int,
                                       private val fields: Vector[Option[Object]],
-                                      private val columnNames: FieldNames) {
+                                      private val columnLabels: FieldNames) {
 
   def columnCount: Int = fields.length
-  def columnNumber(columnLabel: String): Int = columnNames(columnLabel.toLowerCase)
+  def columnNumber(columnLabel: String): Int = {
+    val actualLabel = columnLabel.toLowerCase
+    columnLabels.getOrThrow(actualLabel, new NoSuchElementException(s"Column '$actualLabel' not found"))
+  }
 
   /**
    * Extracts a value from the row by column number.
@@ -131,7 +137,6 @@ class QueryResultRow private[classes](val rowNumber: Int,
 
     getAs(column: Int, transformerFnc _)
   }
-
 }
 
 object QueryResultRow {

balta/src/main/scala/za/co/absa/db/balta/implicits/MapImplicits.scala

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2023 ABSA Group Limited
+ *
+ * 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.
+ */
+
+package za.co.absa.db.balta.implicits
+
+object MapImplicits {
+  implicit class MapEnhancements[K, V](val map: Map[K, V]) extends AnyVal {
+    /**
+     * Gets the value associated with the key or throws the provided exception
+     * @param key       - the key to get the value for
+     * @param exception - the exception to throw in case the `option` is None
+     * @tparam V1       - the type of the value
+     * @return          - the value associated with key if it exists, otherwise throws the provided exception
+     */
+    def getOrThrow[V1 >: V](key: K, exception: => Throwable): V1 = {
+      map.getOrElse(key, throw exception)
+    }
+  }
+
+}

balta/src/main/scala/za/co/absa/db/balta/implicits/QueryResultRowImplicits.scala

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2023 ABSA Group Limited
+ *
+ * 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.
+ */
+
+package za.co.absa.db.balta.implicits
+
+import za.co.absa.db.balta.classes.QueryResultRow
+import za.co.absa.db.balta.implicits.OptionImplicits.OptionEnhancements
+import za.co.absa.db.mag.naming.NamingConvention
+
+import scala.reflect.runtime.currentMirror
+import scala.reflect.runtime.universe._
+
+object QueryResultRowImplicits {
+
+  def isOptionType(typeToCheck: Type): Boolean = {
+    typeToCheck <:< typeOf[Option[_]]
+  }
+
+  /**
+   * This class provides an implicit conversion from QueryResultRow to a case class
+   * This logic placed in an implicit class to prevent polluting the QueryResultRow class with too much unrelated logic
+   * @param row The QueryResultRow to convert
+   */
+  implicit class ProductTypeConvertor(val row: QueryResultRow) extends AnyVal {
+
+    /**
+     * Converts a QueryResultRow to a case class
+     * @param namingConvention  - The naming convention to use when converting field names to column names
+     * @tparam T                - The case class to convert to
+     * @return                  - The case class instance filled with data from the QueryResultRow
+     */
+    def toProductType[T <: Product : TypeTag](implicit namingConvention: NamingConvention): T = {
+      val tpe = typeOf[T]
+      val defaultConstructor = getConstructor(tpe)
+      val constructorMirror = getConstructorMirror(tpe, defaultConstructor)
+      val params = readParamsFromRow(defaultConstructor)
+      constructorMirror(params: _*).asInstanceOf[T]
+    }
+
+    private def getConstructor(tpe: Type): MethodSymbol = {
+      val constructorSymbol = tpe.decl(termNames.CONSTRUCTOR)
+      val defaultConstructor =
+        if (constructorSymbol.isMethod) constructorSymbol.asMethod
+        else {
+          val ctors = constructorSymbol.asTerm.alternatives
+          ctors.map(_.asMethod).find(_.isPrimaryConstructor).get
+        }
+      defaultConstructor
+    }
+
+    private def getConstructorMirror(tpe: Type, constructor: MethodSymbol): MethodMirror = {
+      val classSymbol = tpe.typeSymbol.asClass
+      val classMirror = currentMirror.reflectClass(classSymbol)
+      val constructorMirror = classMirror.reflectConstructor(constructor)
+      constructorMirror
+    }
+
+    private def readParamsFromRow(constructor: MethodSymbol)(implicit namingConvention: NamingConvention): List[Any] = {
+      constructor.paramLists.flatten.map { param =>
+        val name = param.name.decodedName.toString
+        val paramType = param.typeSignature
+        val columnLabel = namingConvention.stringPerConvention(name)
+        getParamValue(columnLabel, paramType)
+      }
+
+    }
+
+    private def getParamValue[T: TypeTag](columnLabel: String, expectedType: Type): Any = {
+      val value = row(columnLabel)
+      if (isOptionType(expectedType)) {
+        value
+      } else {
+        value.getOrThrow(new NullPointerException(s"Column '$columnLabel' is null"))
+      }
+    }
+  }
+}

balta/src/main/scala/za/co/absa/db/mag/exceptions/NamingException.scala

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2022 ABSA Group Limited
+ *
+ * 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.
+ */
+
+package za.co.absa.db.mag.exceptions
+
+/**
+ *  Exception thrown when a naming convention is not found for a given string
+ */
+case class NamingException(message: String) extends Exception(message)

balta/src/main/scala/za/co/absa/db/mag/naming/LettersCase.scala

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2022 ABSA Group Limited
+ *
+ * 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.
+ */
+
+package za.co.absa.db.mag.naming
+
+/**
+ *  `LettersCase` is a sealed trait that represents different cases of letters.
+ *  It provides a method to convert a string to the specific case.
+ */
+sealed trait LettersCase {
+
+  /**
+   *  Converts a string to the specific case.
+   *  @param s - The original string.
+   *  @return The string converted to the specific case.
+   */
+  def convert(s: String): String
+}
+
+object LettersCase {
+
+  /**
+   *  `AsIs` is a [[LettersCase]] that leaves strings as they are.
+   */
+  case object AsIs extends LettersCase {
+    override def convert(s: String): String = s
+  }
+
+  /**
+   *  `LowerCase` is a [[LettersCase]] that converts strings to lower case.
+   */
+  case object LowerCase extends LettersCase {
+    override def convert(s: String): String = s.toLowerCase
+  }
+
+  /**
+   *  `UpperCase` is a [[LettersCase]] that converts strings to upper case.
+   */
+  case object UpperCase extends LettersCase {
+    override def convert(s: String): String = s.toUpperCase
+  }
+}