Docs: Extend entities definition docs and reference code from snippets (

#2264)

* extend docs for defining entity instances and add links to the CRUD operations topic

* extend exposed-dao code example and add README files

* replace code blocks with references from code snippets and move the entity definition section

* reference code from snippets in the DAO CRUD operations topic

documentation-website/Writerside/hi.tree

@@ -29,6 +29,7 @@
     </toc-element>
     <toc-element toc-title="Deep Dive into DAO">
         <toc-element topic="DAO-Table-Types.topic"/>
+        <toc-element topic="DAO-Entity-definition.topic"/>
         <toc-element topic="DAO-CRUD-Operations.topic"/>
         <toc-element topic="DAO-Relationships.topic"/>
         <toc-element topic="DAO-Field-Transformations.topic"/>

documentation-website/Writerside/snippets/README.md

@@ -0,0 +1,85 @@
+# Exposed Docs code examples
+
+The `snippets` folder contains a Gradle project with runnable code examples that show how to work with the Exposed library.
+Code from these examples is referenced in corresponding documentation sections.
+
+## Run samples
+
+Each example has its own `README` file with instructions on how to run it.
+To run an example, you can use a **run** Gradle task that depends on an example location. 
+For example, to run the `exposed-dao` example, open a new terminal window from the `snippets` folder and execute the following command:
+
+```bash
+./gradlew :exposed-dao:run
+```
+
+Wait until IntelliJ IDEA builds and runs an example.
+
+## Reference code snippets
+
+### Reference files and symbols
+
+To display a specific source file in a topic, use the [`code-block`](https://www.jetbrains.com/help/writerside/semantic-markup-reference.html#code-block)
+element with the `src` attribute. Whenever possible, reference the entire files or use the `include-symbol` attribute 
+to specify a class, method, or another symbol from the source file to include in the code block.
+
+
+#### XML
+
+````xml
+<!-- Include all file contents -->
+<code-block lang="kotlin" src="exposed-dao/src/main/kotlin/org/example/StarWarsFilms.kt" />
+
+<!-- Include specific symbol/s -->
+<code-block lang="kotlin" src="exposed-dao/src/main/kotlin/org/example/StarWarsFilms.kt" include-symbol="MAX_VARCHAR_LENGTH, StarWarsFilmsTable" />
+````
+
+#### Markdown
+
+````
+```kotlin
+```
+{src="exposed-dao/src/main/kotlin/org/example/StarWarsFilms.kt"}
+````
+
+### Reference by line numbers
+
+In cases where the example code is not assigned or is commented out, use the `include-lines` attribute to specify the line
+numbers from the source file to include in the code block:
+
+#### XML
+
+```xml
+<!-- Include specific lines -->
+<code-block lang="sql" src="exposed-dao/src/main/kotlin/org/example/StarWarsFilms.kt" include-lines="9-13" />
+```
+#### Markdown
+
+````
+```kotlin
+```
+{src="exposed-dao/src/main/kotlin/org/example/StarWarsFilms.kt" include-lines="9-13"}
+````
+
+When using this approach, be sure to document it for future reference by adding a note about the explicitly referenced
+lines, as shown in the example below:
+
+```kotlin
+/*
+    ...
+
+    Important: The SQL query is referenced by line number in `TOPIC_NAME.topic`.
+    If you add, remove, or modify any lines before the SELECT statement, ensure you update the corresponding
+    line numbers in the `code-block` element of the referenced file.
+
+    CREATE TABLE IF NOT EXISTS STARWARSFILMS
+    (ID INT AUTO_INCREMENT PRIMARY KEY,
+    SEQUEL_ID INT NOT NULL,
+    "name" VARCHAR(50) NOT NULL,
+    DIRECTOR VARCHAR(50) NOT NULL);
+ */
+object StarWarsFilmsTable : IntIdTable() {
+    //...
+}
+```
+

documentation-website/Writerside/snippets/exposed-dao/README.md

@@ -0,0 +1,25 @@
+# Exposed DAO API examples
+
+A Gradle application that shows how to work with Exposed DAO API.
+The files are referenced in the DAO's [CRUD operations](../../topics/DAO-CRUD-Operations.topic),
+[Table types](../../topics/DAO-Table-Types.topic) and [Entity definition](../../topics/DAO-Entity-definition.topic)
+topics.
+
+## Build
+
+To build the application, in a terminal window navigate to the `snippets` folder and run the following command:
+
+```shell
+./gradlew :exposed-dao:build
+```
+
+## Run
+
+To run the application, in a terminal window navigate to the `snippets` folder and run the following command:
+
+```shell
+./gradlew :exposed-dao:run
+```
+
+This will run queries to create new tables and run all functions in the `/examples` folder.
+To only run a specific example, modify the `App.kt` file and re-run the project.

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

@@ -1,13 +1,64 @@
 package org.example
 
-import org.jetbrains.exposed.sql.*
+import org.example.examples.*
+import org.example.tables.*
+import org.jetbrains.exposed.sql.Database
+import org.jetbrains.exposed.sql.DatabaseConfig
+import org.jetbrains.exposed.sql.SchemaUtils
+import org.jetbrains.exposed.sql.StdOutSqlLogger
+import org.jetbrains.exposed.sql.addLogger
 import org.jetbrains.exposed.sql.transactions.transaction
 
 fun main() {
-    Database.connect("jdbc:h2:mem:test", driver = "org.h2.Driver")
+    Database.connect(
+        "jdbc:h2:mem:test",
+        "org.h2.Driver",
+        databaseConfig = DatabaseConfig { useNestedTransactions = true }
+    )
 
     transaction {
         addLogger(StdOutSqlLogger)
-        SchemaUtils.create(StarWarsFilms)
+        createTables()
+        runCreateExamples()
+        runReadExamples()
+        runUpdateExamples()
+        runDeleteExamples()
     }
 }
+
+fun createTables() {
+    SchemaUtils.create(StarWarsFilmsTable)
+    SchemaUtils.create(DirectorsTable)
+    SchemaUtils.create(UsersTable)
+    SchemaUtils.create(UserRatingsTable)
+    SchemaUtils.create(GuildsTable)
+    SchemaUtils.create(CitiesTable)
+    SchemaUtils.create(StarWarsFilmsWithRankTable)
+}
+
+fun runCreateExamples() {
+    val createExamples = CreateExamples()
+    createExamples.createFilms()
+    createExamples.createNewWithCompositeId()
+}
+
+fun runReadExamples() {
+    val readExamples = ReadExamples()
+    readExamples.readAll()
+    readExamples.readWithJoin()
+    readExamples.find()
+    readExamples.findByCompositeId()
+    readExamples.queriesAsExpressions()
+    readExamples.readComputedField()
+}
+
+fun runUpdateExamples() {
+    val updateExamples = UpdateExamples()
+    updateExamples.updateFilms()
+    updateExamples.updateFilmProperty()
+}
+
+fun runDeleteExamples() {
+    val deleteExamples = DeleteExamples()
+    deleteExamples.deleteFilm()
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/entities/DirectorCustomEntity.kt

@@ -0,0 +1,12 @@
+package org.example.entities
+
+import org.example.tables.DirectorsCustomTable
+import org.jetbrains.exposed.dao.Entity
+import org.jetbrains.exposed.dao.EntityClass
+import org.jetbrains.exposed.dao.id.EntityID
+
+class DirectorCustomEntity(id: EntityID<String>) : Entity<String>(id) {
+    companion object : EntityClass<String, DirectorCustomEntity>(DirectorsCustomTable)
+
+    var name by DirectorsCustomTable.name
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/entities/DirectorEntity.kt

@@ -0,0 +1,13 @@
+package org.example.entities
+
+import org.example.tables.DirectorsTable
+import org.jetbrains.exposed.dao.CompositeEntity
+import org.jetbrains.exposed.dao.CompositeEntityClass
+import org.jetbrains.exposed.dao.id.CompositeID
+import org.jetbrains.exposed.dao.id.EntityID
+
+class DirectorEntity(id: EntityID<CompositeID>) : CompositeEntity(id) {
+    companion object : CompositeEntityClass<DirectorEntity>(DirectorsTable)
+
+    var genre by DirectorsTable.genre
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/entities/StarWarsFilmEntity.kt

@@ -0,0 +1,14 @@
+package org.example.entities
+
+import org.example.tables.StarWarsFilmsTable
+import org.jetbrains.exposed.dao.IntEntity
+import org.jetbrains.exposed.dao.IntEntityClass
+import org.jetbrains.exposed.dao.id.EntityID
+
+class StarWarsFilmEntity(id: EntityID<Int>) : IntEntity(id) {
+    companion object : IntEntityClass<StarWarsFilmEntity>(StarWarsFilmsTable)
+
+    var sequelId by StarWarsFilmsTable.sequelId
+    var name by StarWarsFilmsTable.name
+    var director by StarWarsFilmsTable.director
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/entities/StarWarsFilmWithRankEntity.kt

@@ -0,0 +1,25 @@
+package org.example.entities
+
+import org.example.tables.StarWarsFilmsWithRankTable
+import org.jetbrains.exposed.dao.IntEntity
+import org.jetbrains.exposed.dao.IntEntityClass
+import org.jetbrains.exposed.dao.id.EntityID
+import org.jetbrains.exposed.sql.Op
+import org.jetbrains.exposed.sql.Query
+
+class StarWarsFilmWithRankEntity(id: EntityID<Int>) : IntEntity(id) {
+    var sequelId by StarWarsFilmsWithRankTable.sequelId
+    var name by StarWarsFilmsWithRankTable.name
+    var rating by StarWarsFilmsWithRankTable.rating
+
+    val rank: Long
+        get() = readValues[StarWarsFilmsWithRankTable.rank]
+
+    companion object : IntEntityClass<StarWarsFilmWithRankEntity>(StarWarsFilmsWithRankTable) {
+        override fun searchQuery(op: Op<Boolean>): Query {
+            return super.searchQuery(op).adjustSelect {
+                select(columns + StarWarsFilmsWithRankTable.rank)
+            }
+        }
+    }
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/entities/UserEntity.kt

@@ -0,0 +1,12 @@
+package org.example.entities
+
+import org.example.tables.UsersTable
+import org.jetbrains.exposed.dao.IntEntity
+import org.jetbrains.exposed.dao.IntEntityClass
+import org.jetbrains.exposed.dao.id.EntityID
+
+class UserEntity(id: EntityID<Int>) : IntEntity(id) {
+    companion object : IntEntityClass<UserEntity>(UsersTable)
+
+    var name by UsersTable.name
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/entities/UserRatingEntity.kt

@@ -0,0 +1,14 @@
+package org.example.entities
+
+import org.example.tables.UserRatingsTable
+import org.jetbrains.exposed.dao.IntEntity
+import org.jetbrains.exposed.dao.IntEntityClass
+import org.jetbrains.exposed.dao.id.EntityID
+
+class UserRatingEntity(id: EntityID<Int>) : IntEntity(id) {
+    companion object : IntEntityClass<UserRatingEntity>(UserRatingsTable)
+
+    var value by UserRatingsTable.value
+    var film by StarWarsFilmEntity referencedOn UserRatingsTable.film // use referencedOn for normal references
+    var user by UserEntity referencedOn UserRatingsTable.user
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/examples/CreateExamples.kt

@@ -0,0 +1,42 @@
+package org.example.examples
+
+import org.example.entities.DirectorEntity
+import org.example.entities.StarWarsFilmEntity
+import org.example.tables.DirectorsTable
+import org.example.tables.Genre
+import org.jetbrains.exposed.dao.id.CompositeID
+import java.util.*
+
+const val MOVIE_SEQUEL_ID = 8
+const val MOVIE2_SEQUEL_ID = 9
+
+class CreateExamples {
+    fun createFilms() {
+        val movie = StarWarsFilmEntity.new {
+            name = "The Last Jedi"
+            sequelId = MOVIE_SEQUEL_ID
+            director = "Rian Johnson"
+        }
+        println("Created a new record with name " + movie.name)
+
+        // Create a new record with id
+        val movie2 = StarWarsFilmEntity.new(id = 2) {
+            name = "The Rise of Skywalker"
+            sequelId = MOVIE2_SEQUEL_ID
+            director = "J.J. Abrams"
+        }
+        println("Created a new record with id " + movie2.id)
+    }
+
+    // Create a new record with a composite id
+    fun createNewWithCompositeId() {
+        val directorId = CompositeID {
+            it[DirectorsTable.name] = "J.J. Abrams"
+            it[DirectorsTable.guildId] = UUID.randomUUID()
+        }
+
+        val director = DirectorEntity.new(directorId) {
+            genre = Genre.SCI_FI
+        }
+    }
+}

documentation-website/Writerside/snippets/exposed-dao/src/main/kotlin/org/example/examples/DeleteExamples.kt

@@ -0,0 +1,19 @@
+package org.example.examples
+
+import org.example.entities.StarWarsFilmEntity
+
+class DeleteExamples {
+/*
+    Delete a record.
+
+    Important: The `movie.delete` statement is referenced by line number in `DAO-CRUD-operations.topic`.
+    If you add, remove, or modify any lines prior to this one, ensure you update the corresponding
+    line numbers in the `code-block` element of the referenced file.
+*/
+    fun deleteFilm() {
+        val movie = StarWarsFilmEntity.findById(2)
+        if (movie != null) {
+            movie.delete()
+        }
+    }
+}