Skip to content

Commit

Permalink
Adding readme code snippets to testing suits.
Browse files Browse the repository at this point in the history
  • Loading branch information
@urosjarc
urosjarc committed Mar 31, 2024
1 parent d100f10 commit 0cd572b
Show file tree
Hide file tree
Showing 4 changed files with 659 additions and 41 deletions.
302 changes: 262 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,27 @@
<h1 align="center">db-messiah-extra</h1>
<h3 align="center">Extra Utils for Db Messiah, kotlin lib. for enterprise database development</h3>
<p align="center">
readme code snippets are
<a href="https://github.com/urosjarc/db-messiah/blob/master/src/tutorials/kotlin/Test_README.md">autogenerated</a>
and
<a href="https://github.com/urosjarc/db-messiah/blob/master/src/tutorials/kotlin/Test_README.kt">tested</a><br>
+<b>15</b> <a href="https://github.com/urosjarc/db-messiah/blob/master/src/e2e">e2e</a> tests with <b>100%</b> instruction coverage
</p>
<br>
<br>
<table width="100%" border="0">
<tr>
<td width="50%">
<td width="33%">
<h3 align="center"><a href="https://github.com/urosjarc/db-messiah">db-messiah</a></h3>
<p align="center">Kotlin lib. for enterprise database development</p>
</td>
<td width="50%">
<td width="33%" align="center">
<p><a href="#get-started">Get started</a></p>
<p><a href="#specifications">Specifications</a></p>
<p><a href="#arhitecture">Arhitecture</a></p>
<p><a href="https://urosjarc.github.io/db-messiah/">Documentation</a></p>
</td>
<td width="33%">
<h3 align="center"><a href="https://github.com/urosjarc/db-analyser">db-analyser</a></h3>
<p align="center">GUI for db analysis, to help you create complex JOIN statements for SQL or db-messiah.
</td>
Expand All @@ -20,59 +33,39 @@
<h2 align="center">Get started</h2>

```kotlin
implementation("com.urosjarc:db-messiah-extra:0.0.1")
implementation("com.urosjarc:db-messiah-extra:0.0.1") // Required
implementation("com.urosjarc:db-messiah-extra-extra:0.0.1") // Optional
```

<br><h3 align="center">DB Serializers</h3>
<br><h3 align="center">Domain</h3>

```kotlin
/** SQLITE */

val sqliteSerializer = SqliteSerializer(
globalSerializers = BasicTS.sqlite + KotlinxTimeTS.sqlite,
...
data class MyTable(
var pk: Int? = null,
val instant: kotlinx.datetime.Instant,
val localDate: kotlinx.datetime.LocalDate,
val localTime: kotlinx.datetime.LocalTime,
)

/** POSTGRESQL */
```

<br><h3 align="center">DB Serializers</h3>

```kotlin
val sqliteSerializer = SqliteSerializer(
globalSerializers = BasicTS.sqlite + KotlinxTimeTS.sqlite,
...
tables = listOf(Table(MyTable::pk)),
)
```

<br><h3 align="center">JSON Serializers</h3>


```kotlin
/** JSON */

val json = Json {
serializersModule = SerializersModule {
contextual(InstantJS)
contextual(LocalDateJS)
contextual(LocalTimeJS)
contextual(UUIDJS)
}
}

val jsonStr = json.encodeToString(...)
val obj = json.decodeFromString<...>(...)

/** KTOR */

install(ContentNegotiation) {
json(Json {
serializersModule = SerializersModule {
contextual(InstantJS)
contextual(LocalDateJS)
contextual(LocalTimeJS)
contextual(UUIDJS)
}
})
}
// START 'JSON Serializers'
```

<br><br><h2 align="center">Specifications</h3>

<br><h3 align="center">Features</h3>

| Class | COLUMN | Databases | db-messiah-extra | JSON |
Expand All @@ -81,5 +74,234 @@ install(ContentNegotiation) {
| Instant | TIMESTAMP | Derby, Postgres, Oracle | KotlinxInstantTS. TIMESTAMP | InstantJS |
| LocalDate | DATE | :white_check_mark: | KotlinxLocalDateTS. DATE | LocalDateJS |
| LocalTime | TIME | :white_check_mark: but Oracle | KotlinxTimeTS.TIME | LocalDateJS |
| LocalTime | NUMBER(8, 0) | Oracle | KotlinxTimeTS. NUMBER8 | LocalTimeJS |>
| UUID | db-messiah | db-messiah | db-messiah | UUIDJS |>
| LocalTime | NUMBER(8, 0) | Oracle | KotlinxTimeTS. NUMBER8 | LocalTimeJS |
| UUID | db-messiah | db-messiah | db-messiah | UUIDJS |

<br><br><h2 align="center">Arhitecture</h3>

```text
src/main/kotlin/com/urosjarc/dbmessiah/
|-- builders...........................| Builders to help you build type safe queries.
| |-- ProcedureBuilder.kt............| Builder for procedures.
| |-- QueryBuilder.kt................| Builder for custom queries.
| |-- RowBuilder.kt..................| Builder for creating row queries.
| `-- SqlBuilder.kt..................| Builder for SQL templates.
// START 'builders'
|-- ConnectionPool.kt..................| For getting db autocommit or transactional connections.
|-- data...............................| Internal data representations of db elements.
| |-- BatchQuery.kt
| |-- Column.kt
| |-- DbValue.kt
| |-- DecodeInfo.kt..................| Additional info for Decoder about the decoding value.
| |-- Decoder.kt.....................| TypeSerializer callback for decoding value.
| |-- Encoder.kt.....................| TypeSerializer callback for encoding value.
| |-- ForeignColumn.kt
| |-- OtherColumn.kt
| |-- PrimaryColumn.kt
| |-- ProcedureArg.kt
| |-- Procedure.kt
| |-- Query.kt
| |-- QueryValue.kt
| |-- TableInfo.kt
| `-- TypeSerializer.kt..............| Structure that holds information on how some KClass will be mapped to db value.
|-- domain
| |-- C.kt...........................| All user available constraints, other are inferred with the reflection.
| |-- Cursor.kt
| |-- Isolation.kt
| |-- Order.kt
| |-- Page.kt
| |-- QueryLog.kt....................| Log structure used for profiling.
| |-- Rollback.kt
| `-- Table.kt
|-- Driver.kt..........................| Driver for preparing and executing Query on JDBC.
|-- exceptions
| |-- base
| | |-- IssueException.kt..........| Exception that needs to be reported on issue tracker.
| | |-- UnknownException.kt........| Exception when system does not know if this is an issue or a warning.
| | `-- WarningException.kt........| Warning to the user that he did something wrong.
| |-- ConnectionException.kt
| |-- DbValueException.kt
| |-- DriverException.kt
| |-- MapperException.kt
| |-- QueryException.kt
| `-- SerializerTestsException.kt
|-- Exporter.kt........................| Logic for exporting db structure to PlantUML, dbdiagram.io, ...
|-- extend
| |-- Iterable.kt....................| All extends functions attached to Iterable.
| |-- KClass.kt......................| All extends functions attached to KClass.
| `-- KProperty1.kt..................| All extends functions attached to KProperty1.
|-- impl
| |-- db2
| | |-- Db2Schema.kt...............| Structure that will user use to create schema.
| | |-- Db2Serializer.kt...........| Serializer for mapping user command to appropriate SQL Query string.
| | `-- Db2Service.kt..............| Service for executing user commands on database connection.
| |-- derby
| | |-- DerbySchema.kt
| | |-- DerbySerializer.kt
| | `-- DerbyService.kt
| |-- h2
| | |-- H2Schema.kt
| | |-- H2Serializer.kt
| | `-- H2Service.kt
| |-- maria
| | |-- MariaSchema.kt
| | |-- MariaSerializer.kt
| | `-- MariaService.kt
| |-- mssql
| | |-- MssqlSchema.kt
| | |-- MssqlSerializer.kt
| | `-- MssqlService.kt
| |-- mysql
| | |-- MysqlSchema.kt
| | |-- MysqlSerializer.kt
| | `-- MysqlService.kt
| |-- oracle
| | |-- OracleSchema.kt
| | |-- OracleSerializer.kt
| | `-- OracleService.kt
| |-- postgresql
| | |-- PgSchema.kt
| | |-- PgSerializer.kt
| | `-- PgService.kt
| `-- sqlite
| |-- SqliteSerializer.kt
| `-- SqliteService.kt
|-- MapperCache.kt.....................| Internal mapping cache containing hashmaps like KClass to TableInfo, KProperty1 to TypeSerializer, etc...
|-- Mapper.kt..........................| User friendly API for MapperCache.
|-- Profiler.kt........................| Simple static class that logs every query executed on Driver.
|-- queries............................| Execution logic for db queries.
| |-- BatchQueries.kt
| |-- GetManyQueries.kt..............| Some databases support multiple db calls per query.
| |-- GetOneQueries.kt...............| For databases that only support one db call per query.
| |-- NoReturnProcedureQueries.kt
| |-- ProcedureQueries.kt
| |-- RowQueries.kt
| |-- SchemaCascadeQueries.kt........| Some databases support cascading queries on schema.
| |-- SchemaQueries.kt...............| For databases that does not support cascading queries.
| |-- TableCascadeQueries.kt
| `-- TableQueries.kt
|-- Schema.kt..........................| Interface defining common schema logic.
|-- Serializer.kt......................| Interface defining common serializer logic.
|-- serializers........................| Here are all type serializers (TS) that are supported by the system.
| |-- BasicTS.kt.....................| User friendly API for accessing all TS for specific database.
| |-- BooleanTS.kt
| |-- CharTS.kt
| |-- DecimalTS.kt
| |-- IdTS.kt........................| User friendly API for creating custom inline primary key type serializer.
// START 'IdTS'
| |-- InstantTS.kt
| |-- JavaTimeTS.kt..................| User friendly API for accessing all java.time.* supported TS for specific database.
| |-- LocalDateTS.kt
| |-- LocalTimeTS.kt
| |-- NumberTS.kt
| |-- StringTS.kt
| |-- UNumber.kt
| `-- UUIDTS.kt
|-- SerializerTests.kt.................| Initialization tests for serializer to find any error and inconsistency in user defined db schema.
`-- Service.kt.........................| Interface defining common service logic.
```

<br><br><h2 align="center">Sources</h2>

```text
src/
|-- main...............................| Already described in architecture.
|-- chinook............................| Implementation of chinook sample database for all supported databases.
| |-- kotlin
| | |-- domain
| | | |-- Album.kt
| | | |-- Artist.kt
| | | |-- Customer.kt
| | | |-- Employee.kt
| | | |-- Genre.kt
| | | |-- Invoice.kt
| | | |-- InvoiceLine.kt
| | | |-- MediaType.kt
| | | |-- Playlist.kt
| | | |-- PlaylistTrack.kt
| | | `-- Track.kt
| | |-- Id.kt
| | |-- Schemas.kt
| | |-- Seed.kt....................| INSERT elements to tables.
| | |-- Serializers.kt
| | |-- Services.kt
| | `-- Test_Chinook.kt............| Main testing entry.
| `-- resources
| `-- log4j2.xml
|-- e2e
| |-- kotlin
| | |-- domain.kt
| | |-- Test_Benchmarks.kt.........| Testing speed of the system.
| | |-- Test_Contract.kt...........| Testing interface for all db tests.
| | |-- Test_Db2.kt
| | |-- Test_Derby.kt
| | |-- Test_H2.kt
| | |-- Test_Maria.kt
| | |-- Test_Mssql.kt
| | |-- Test_Mysql.kt
| | |-- Test_Oracle.kt
| | |-- Test_Postgresql.kt
| | `-- Test_Sqlite.kt
| `-- resources
| `-- log4j2.xml
|-- test
| |-- kotlin
| | `-- com
| | `-- urosjarc
| | `-- dbmessiah
| | |-- builders
| | | |-- Test_ProcedureBuilder.kt
| | | |-- Test_QueryBuilder.kt
| | | |-- Test_RowBuilder.kt
| | | `-- Test_SqlBuilder.kt
| | |-- data
| | | |-- Test_Column.kt
| | | |-- Test_OtherColumn.kt
| | | |-- Test_PrimaryColumn.kt
| | | |-- Test_ProcedureArg.kt
| | | |-- Test_Procedure.kt
| | | `-- Test_Query.kt
| | |-- domain
| | | `-- Test_Table.kt
| | |-- extend
| | | |-- Test_Iterable.kt
| | | |-- Test_KClass.kt
| | | `-- Test_KProperty.kt
| | |-- impl
| | | |-- Test_Db2Serializer.kt
| | | |-- Test_DerbySerializer.kt
| | | |-- Test_H2Serializer.kt
| | | |-- Test_MariaSerializer.kt
| | | |-- Test_MssqlSerializer.kt
| | | |-- Test_MysqlSerializer.kt
| | | |-- Test_OracleSerializer.kt
| | | |-- Test_PgSerializer.kt
| | | `-- Test_SqliteSerializer.kt
| | `-- Test_Serializer.kt
| `-- resources
| `-- log4j2.xml
`-- tutorials
|-- kotlin
| |-- 000_basic_sqlite.kt
| |-- 001_basic_postgresql.kt
| |-- 002_query_sqlite.kt
| |-- 003_query_postgresql.kt
| |-- 004_primary_keys.kt
| |-- 005_constraints.kt
| |-- 006_transactions.kt
| |-- 007_procedures.kt
| |-- 008_indexing_and_profiling.kt
| |-- 009_exceptions.kt
| |-- 010_custom_type_serializers.kt
| |-- 011_custom_database_serializers.kt
| |-- Test_README.kt...............................| Code from where README.md is generated.
| |-- Test_README.md...............................| Template from where README.md is generated.
| `-- Test_Tutorials.kt............................| Main testing entry.
`-- resources
`-- log4j2.xml
```
42 changes: 41 additions & 1 deletion build.gradle.kts
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
import org.jetbrains.dokka.DokkaConfiguration.Visibility
import java.lang.Thread.sleep
import java.net.URI

val GPG_PRIVATE_KEY = System.getenv("GPG_PRIVATE_KEY")
val GPG_PRIVATE_PASSWORD = System.getenv("GPG_PRIVATE_PASSWORD")
Expand Down Expand Up @@ -166,3 +165,44 @@ publishing {
}

}

tasks.register<GradleBuild>("readme") {
group = "verification"
description = "Create README.md tests."
this.tasks = listOf("test")

doLast {
val templateLines = File("./src/test/kotlin/Test_README.kt").readLines()
var readme = File("./src/test/kotlin/Test_README.md").readText()

val dependencies = mutableListOf(
"implementation(\"${project.group}:${project.name}:$version\") // Required",
"implementation(\"${project.group}:${project.name}-extra:$version\") // Optional",
)

val readmeMap: MutableList<Pair<String, MutableList<String>>> = mutableListOf(
"// START 'Dependencies'" to dependencies,
)


var active = false
var indent = ""
templateLines.forEach {
if (it.contains("// START '")) {
indent = it.split("//").first()
active = true
readmeMap.add(it.replaceFirst(indent, "") to mutableListOf())
} else if (it.contains("// STOP")) {
active = false
} else if (active) {
readmeMap.last().second.add(it.replaceFirst(indent, ""))
}
}

readmeMap.forEach { (key, value) ->
readme = readme.replace(oldValue = key, newValue = value.joinToString("\n"))
}

File("README.md").writeText(readme)
}
}
Loading

0 comments on commit 0cd572b

Please sign in to comment.