docs: EXPOSED-747 Add a get started tutorial for Exposed DAO (#2556)

* docs: add a new snippets project and tutorial for getting started with Exposed DAO

* fix text, code snippets and create a new toc-element

* include get-started-with-exposed to the snippets project and update refs

* update downloadable gradle project

Author: vnikolova

documentation-website/Writerside/hi.tree

@@ -8,7 +8,10 @@
 
     <toc-element topic="Home.topic" toc-title="Home"/>
     <toc-element topic="About.topic" toc-title="About"/>
-    <toc-element topic="Getting-Started-with-Exposed.topic" toc-title="Get started with Exposed"/>
+    <toc-element toc-title="Get started">
+        <toc-element topic="Get-Started-with-Exposed.topic" toc-title="Get started with Exposed" accepts-web-file-names="getting-started-with-exposed.html"/>
+        <toc-element topic="Get-started-with-Exposed-DAO.md"/>
+    </toc-element>
     <toc-element topic="Exposed-Modules.md"/>
     <toc-element toc-title="Databases">
         <toc-element topic="Working-with-Database.md"/>

documentation-website/Writerside/resources/init-kotlin-gradle-app.zip

@@ -0,0 +1 @@
+ALTER TABLE USERS ADD PRIMARY KEY (ID);

documentation-website/Writerside/snippets/exposed-migrations/src/main/kotlin/org/example/migrations/V2__Add_primary_key.sql

@@ -0,0 +1,21 @@
+# Get started with Exposed DAO tutorial project
+
+A sample Gradle/Kotlin project built by following the steps explained in
+the [Get started with Exposed DAO](https://www.jetbrains.com/help/exposed/get-started-with-exposed-dao.html)
+tutorial.
+
+## Build
+
+To build the application, navigate to the `snippets` folder and run the following command:
+
+```shell
+./gradlew :get-started-with-exposed-dao:build
+```
+
+## Run
+
+To run the application, execute the following command:
+
+```bash
+./gradlew :get-started-with-exposed-dao:run
+```

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

@@ -0,0 +1,53 @@
+/*
+ * 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.dao)
+    implementation(libs.exposed.jdbc)
+    implementation(libs.h2)
+}
+
+// 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-dao/build.gradle.kts

@@ -0,0 +1,43 @@
+package org.example
+
+import org.jetbrains.exposed.v1.core.StdOutSqlLogger
+import org.jetbrains.exposed.v1.jdbc.Database
+import org.jetbrains.exposed.v1.jdbc.SchemaUtils
+import org.jetbrains.exposed.v1.jdbc.transactions.transaction
+
+fun main() {
+    Database.connect("jdbc:h2:mem:test", driver = "org.h2.Driver")
+
+    transaction {
+        addLogger(StdOutSqlLogger)
+
+        // ...
+
+        SchemaUtils.create(Tasks)
+
+        val task1 = Task.new {
+            title = "Learn Exposed DAO"
+            description = "Follow the DAO tutorial"
+        }
+
+        val task2 = Task.new {
+            title = "Read The Hobbit"
+            description = "Read chapter one"
+            isCompleted = true
+        }
+
+        println("Created new tasks with ids ${task1.id} and ${task2.id}")
+
+        val completed = Task.find { Tasks.isCompleted eq true }.toList()
+        println("Completed tasks: ${completed.count()}")
+
+        // Update
+        task1.title = "Try Exposed DAO"
+        task1.isCompleted = true
+        println("Updated task1: $task1")
+
+        // Delete
+        task2.delete()
+        println("Remaining tasks: ${Task.all().toList()}")
+    }
+}

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

@@ -0,0 +1,28 @@
+package org.example
+
+// ...
+import org.jetbrains.exposed.v1.core.dao.id.EntityID
+import org.jetbrains.exposed.v1.core.dao.id.IntIdTable
+import org.jetbrains.exposed.v1.dao.IntEntity
+import org.jetbrains.exposed.v1.dao.IntEntityClass
+
+@Suppress("MagicNumber")
+object Tasks : IntIdTable("tasks") {
+    val title = varchar("name", 128)
+    val description = varchar("description", 128)
+    val isCompleted = bool("completed").default(false)
+}
+
+// ...
+
+class Task(id: EntityID<Int>) : IntEntity(id) {
+    companion object : IntEntityClass<Task>(Tasks)
+
+    var title by Tasks.title
+    var description by Tasks.description
+    var isCompleted by Tasks.isCompleted
+
+    override fun toString(): String {
+        return "Task(id=$id, title=$title, completed=$isCompleted)"
+    }
+}

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

@@ -1,12 +1,20 @@
 # 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.
+the [Get started with Exposed](https://www.jetbrains.com/help/exposed/get-started-with-exposed.html) tutorial.
+
+## Build
+
+To build the application, navigate to the `snippets` folder and run the following command:
+
+```shell
+./gradlew :get-started-with-exposed:build
+```
 
 ## Run
 
 To run the application, execute the following command in the repository's root directory:
 
 ```bash
-./gradlew run
+./gradlew :get-started-with-exposed:run
 ```

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

@@ -31,7 +31,7 @@ dependencies {
     implementation(libs.guava)
     implementation(libs.exposed.core)
     implementation(libs.exposed.jdbc)
-    implementation("com.h2database:h2:2.2.224")
+    implementation(libs.h2)
 }
 
 // Apply a specific Java toolchain to ease working on different environments.