docs: EXPOSED-419 Rework the getting started tutorial and add sample …

…project (#2160)

documentation-website/Writerside/hi.tree

@@ -7,7 +7,7 @@
                   start-page="Home.topic">
 
     <toc-element topic="Home.topic"/>
-    <toc-element topic="Getting-Started-with-Exposed.md"/>
+    <toc-element topic="Getting-Started-with-Exposed.topic" toc-title="Get started with Exposed"/>
     <toc-element topic="Exposed-Modules.md"/>
     <toc-element topic="Database-and-DataSource.md"/>
     <toc-element toc-title="Working with Tables">

documentation-website/Writerside/snippets/get-started-with-exposed/.gitattributes

@@ -0,0 +1,9 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+

documentation-website/Writerside/snippets/get-started-with-exposed/README.md

@@ -0,0 +1,12 @@
+# Get started with Exposed tutorial project
+
+A sample Gradle/Kotlin project built by following the steps explained in
+the [Get started with Exposed](https://jetbrains.github.io/Exposed/getting-started-with-exposed.html) tutorial.
+
+## Run
+
+To run the application, execute the following command in the repository's root directory:
+
+```bash
+./gradlew run
+```

documentation-website/Writerside/snippets/get-started-with-exposed/app/build.gradle.kts

@@ -0,0 +1,52 @@
+/*
+ * This file was generated by the Gradle 'init' task.
+ *
+ * This generated file contains a sample Kotlin application project to get you started.
+ * For more details on building Java & JVM projects, please refer to https://docs.gradle.org/8.8/userguide/building_java_projects.html in the Gradle documentation.
+ */
+
+plugins {
+    // Apply the org.jetbrains.kotlin.jvm Plugin to add support for Kotlin.
+    alias(libs.plugins.jvm)
+
+    // Apply the application plugin to add support for building a CLI application in Java.
+    application
+}
+
+repositories {
+    // Use Maven Central for resolving dependencies.
+    mavenCentral()
+}
+
+dependencies {
+    // Use the Kotlin JUnit 5 integration.
+    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
+
+    // Use the JUnit 5 integration.
+    testImplementation(libs.junit.jupiter.engine)
+
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+
+    // This dependency is used by the application.
+    implementation(libs.guava)
+    implementation(libs.exposed.core)
+    implementation(libs.exposed.jdbc)
+    implementation("com.h2database:h2:2.2.224")
+}
+
+// Apply a specific Java toolchain to ease working on different environments.
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+application {
+    // Define the main class for the application.
+    mainClass = "org.example.AppKt"
+}
+
+tasks.named<Test>("test") {
+    // Use JUnit Platform for unit tests.
+    useJUnitPlatform()
+}

documentation-website/Writerside/snippets/get-started-with-exposed/app/src/main/kotlin/org/example/App.kt

@@ -0,0 +1,53 @@
+/*
+ * This source file was generated by the Gradle 'init' task
+ */
+package org.example
+
+import Tasks
+import org.jetbrains.exposed.sql.*
+import org.jetbrains.exposed.sql.SqlExpressionBuilder.eq
+import org.jetbrains.exposed.sql.transactions.transaction
+
+fun main() {
+    Database.connect("jdbc:h2:mem:test", driver = "org.h2.Driver")
+
+    transaction {
+        // print sql to std-out
+        addLogger(StdOutSqlLogger)
+
+        // ...
+
+        SchemaUtils.create(Tasks)
+
+        val taskId = Tasks.insert {
+            it[title] = "Learn Exposed"
+            it[description] = "Go through the Get started with Exposed tutorial"
+        } get Tasks.id
+
+        val secondTaskId = Tasks.insert {
+            it[title] = "Read The Hobbit"
+            it[description] = "Read the first two chapters of The Hobbit"
+            it[isCompleted] = true
+        } get Tasks.id
+
+        println("Created new tasks with ids $taskId and $secondTaskId.")
+
+        Tasks.select(Tasks.id.count(), Tasks.isCompleted).groupBy(Tasks.isCompleted).forEach {
+            println("${it[Tasks.isCompleted]}: ${it[Tasks.id.count()]} ")
+        }
+
+        // Update a task
+        Tasks.update({ Tasks.id eq taskId }) {
+            it[isCompleted] = true
+        }
+
+        val updatedTask = Tasks.select(Tasks.isCompleted).where(Tasks.id eq taskId).single()
+
+        println("Updated task details: $updatedTask")
+
+        // Delete a task
+        Tasks.deleteWhere { id eq secondTaskId }
+
+        println("Remaining tasks: ${Tasks.selectAll().toList()}")
+    }
+}

documentation-website/Writerside/snippets/get-started-with-exposed/app/src/main/kotlin/org/example/Task.kt

@@ -0,0 +1,10 @@
+import org.jetbrains.exposed.sql.Table
+
+const val MAX_VARCHAR_LENGTH = 128
+
+object Tasks : Table("tasks") {
+    val id = integer("id").autoIncrement()
+    val title = varchar("name", MAX_VARCHAR_LENGTH)
+    val description = varchar("description", MAX_VARCHAR_LENGTH)
+    val isCompleted = bool("completed").default(false)
+}

documentation-website/Writerside/snippets/get-started-with-exposed/gradle/libs.versions.toml

@@ -0,0 +1,16 @@
+# This file was generated by the Gradle 'init' task.
+# https://docs.gradle.org/current/userguide/platforms.html#sub::toml-dependencies-format
+
+[versions]
+guava = "33.0.0-jre"
+junit-jupiter-engine = "5.10.2"
+exposed = "0.51.1"
+
+[libraries]
+guava = { module = "com.google.guava:guava", version.ref = "guava" }
+junit-jupiter-engine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit-jupiter-engine" }
+exposed-core = { module= "org.jetbrains.exposed:exposed-core", version.ref = "exposed"}
+exposed-jdbc = { module= "org.jetbrains.exposed:exposed-jdbc", version.ref = "exposed"}
+
+[plugins]
+jvm = { id = "org.jetbrains.kotlin.jvm", version = "1.9.22" }

documentation-website/Writerside/snippets/get-started-with-exposed/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists