Refactor documentation for Java Records and Kotlin Data Classes to en…

…sure asciidoc snippets have examples for all languages, and to eliminate embedded code in asciidoc (that is not compiled and untested).

closes #2896

doc-examples/jdbc-example-records-groovy/build.gradle

@@ -0,0 +1,28 @@
+plugins {
+    id "groovy"
+    id "io.micronaut.build.internal.data-example"
+}
+
+application {
+    mainClass = "example.Application"
+}
+
+micronaut {
+    version libs.versions.micronaut.platform.get()
+    runtime "netty"
+    testRuntime "spock"
+}
+
+dependencies {
+    compileOnly projects.micronautDataProcessor
+
+    implementation projects.micronautDataJdbc
+    implementation mnSerde.micronaut.serde.support
+    implementation mn.micronaut.http.client
+    implementation mnValidation.micronaut.validation
+    implementation(libs.managed.jakarta.persistence.api)
+
+    runtimeOnly mnSql.micronaut.jdbc.tomcat
+    runtimeOnly mnLogging.logback.classic
+    runtimeOnly mnSql.h2
+}

doc-examples/jdbc-example-records-groovy/gradle.properties

@@ -0,0 +1 @@
+skipDocumentation=true

doc-examples/jdbc-example-records-groovy/src/main/groovy/example/Book.groovy

@@ -0,0 +1,29 @@
+
+package example
+
+import io.micronaut.core.annotation.Nullable
+import io.micronaut.data.annotation.DateCreated
+import io.micronaut.data.annotation.MappedEntity
+import jakarta.persistence.*
+
+@MappedEntity // <1>
+class Book {
+    @Id @GeneratedValue Long id // <2>
+    @DateCreated @Nullable Date dateCreated
+
+    private String title
+    private int pages
+
+    Book(String title, int pages) {
+        this.title = title
+        this.pages = pages
+    }
+
+    String getTitle() {
+        return title
+    }
+
+    int getPages() {
+        return pages
+    }
+}

doc-examples/jdbc-example-records-groovy/src/main/groovy/example/BookDTO.groovy

@@ -0,0 +1,11 @@
+
+package example
+
+import io.micronaut.serde.annotation.Serdeable
+
+@Serdeable
+class BookDTO {
+
+    String title
+    int pages
+}

doc-examples/jdbc-example-records-groovy/src/main/groovy/example/BookRepository.groovy

@@ -0,0 +1,114 @@
+
+// tag::repository[]
+package example
+
+import io.micronaut.core.annotation.NonNull
+import io.micronaut.data.annotation.*
+import io.micronaut.data.annotation.sql.Procedure
+import io.micronaut.data.jdbc.annotation.JdbcRepository
+import io.micronaut.data.model.*
+import io.micronaut.data.model.query.builder.sql.Dialect
+import io.micronaut.data.repository.CrudRepository
+import java.util.List
+
+
+@JdbcRepository(dialect = Dialect.H2)        // <1>
+interface BookRepository extends CrudRepository<Book, Long> { // <2>
+// end::repository[]
+
+    // tag::simple[]
+    Book findByTitle(String title);
+
+    Book getByTitle(String title);
+
+    Book retrieveByTitle(String title);
+    // end::simple[]
+
+    // tag::greaterthan[]
+    List<Book> findByPagesGreaterThan(int pageCount);
+    // end::greaterthan[]
+
+    // tag::logical[]
+    List<Book> findByPagesGreaterThanOrTitleLike(int pageCount, String title);
+    // end::logical[]
+
+    // tag::simple-alt[]
+    // tag::repository[]
+    Book find(String title);
+    // end::simple-alt[]
+    // end::repository[]
+
+    // tag::pageable[]
+    List<Book> findByPagesGreaterThan(int pageCount, Pageable pageable);
+
+    Page<Book> findByTitleLike(String title, Pageable pageable);
+
+    Slice<Book> list(Pageable pageable);
+    // end::pageable[]
+
+    // tag::simple-projection[]
+    List<String> findTitleByPagesGreaterThan(int pageCount);
+    // end::simple-projection[]
+
+    // tag::top-projection[]
+    List<Book> findTop3ByTitleLike(String title);
+    // end::top-projection[]
+
+    // tag::ordering[]
+    List<Book> listOrderByTitle();
+
+    List<Book> listOrderByTitleDesc();
+    // end::ordering[]
+
+    // tag::explicit[]
+    @Query("SELECT * FROM Book AS b WHERE b.title = :t ORDER BY b.title")
+    List<Book> listBooks(String t);
+    // end::explicit[]
+
+    // tag::save[]
+    Book persist(Book entity);
+    // end::save[]
+
+    // tag::save2[]
+    Book persist(String title, int pages);
+    // end::save2[]
+
+    // tag::update[]
+    void update(@Id Long id, int pages);
+
+    void update(@Id Long id, String title);
+    // end::update[]
+
+    // tag::update2[]
+    void updateByTitle(String title, int pages);
+    // end::update2[]
+
+    // tag::deleteall[]
+    void deleteAll();
+    // end::deleteall[]
+
+    // tag::deleteone[]
+    void delete(String title);
+    // end::deleteone[]
+
+    // tag::deleteby[]
+    void deleteByTitleLike(String title);
+    // end::deleteby[]
+
+    // tag::dto[]
+    BookDTO findOne(String title);
+    // end::dto[]
+
+    // tag::native[]
+    @Query("select * from book b where b.title like :title limit 5")
+    List<Book> findBooks(String title);
+    // end::native[]
+
+    // tag::procedure[]
+    @Procedure
+    Long calculateSum(@NonNull Long bookId);
+    // end::procedure[]
+
+// tag::repository[]
+}
+// end::repository[]

doc-examples/jdbc-example-records-groovy/src/main/resources/application.yml

@@ -0,0 +1,8 @@
+datasources:
+  default:
+    url: jdbc:h2:mem:devDb;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE
+    driverClassName: org.h2.Driver
+    username: sa
+    password: ''
+    schema-generate: CREATE_DROP
+    dialect: H2

doc-examples/jdbc-example-records-groovy/src/test/groovy/example/BookRepositorySpec.groovy

@@ -0,0 +1,59 @@
+package example
+
+import io.micronaut.context.BeanContext
+import io.micronaut.test.extensions.spock.annotation.MicronautTest
+import spock.lang.Shared
+import spock.lang.Specification
+
+import jakarta.inject.Inject
+
+@MicronautTest
+class BookRepositorySpec extends Specification {
+
+    @Inject @Shared BookRepository bookRepository
+
+    @Inject
+    BeanContext beanContext
+
+    void 'test CRUD operations'() {
+
+        when: "Create: Save a new book"
+
+        // tag::save[]
+        Book book = new Book("The Stand", 1000)
+        bookRepository.save(book)
+        // end::save[]
+        Long id = book.id
+
+        then: "An ID was assigned"
+        id != null
+
+        when: "Read a book from the database"
+        // tag::read[]
+        book = bookRepository.findById(id).orElse(null)
+        // end::read[]
+
+        then:"The book was read"
+        book != null
+        book.title == 'The Stand'
+
+        // Check the count
+        bookRepository.count() == 1
+        bookRepository.findAll().iterator().hasNext()
+
+        when: "The book is updated"
+        // tag::update[]
+        bookRepository.update(book.getId(), "Changed")
+        // end::update[]
+        book = bookRepository.findById(id).orElse(null)
+        then: "The title was changed"
+        book.title == 'Changed'
+
+        when: "The book is deleted"
+        // tag::delete[]
+        bookRepository.deleteById(id)
+        // end::delete[]
+        then:"It is gone"
+        bookRepository.count() == 0
+    }
+}

doc-examples/jdbc-example-records-groovy/src/test/resources/logback.xml

@@ -0,0 +1,12 @@
+<configuration>
+
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%cyan(%d{HH:mm:ss.SSS}) %gray([%thread]) %highlight(%-5level) %magenta(%logger{36}) - %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <root level="info">
+        <appender-ref ref="STDOUT" />
+    </root>
+</configuration>

doc-examples/jdbc-example-records-java/build.gradle

@@ -17,6 +17,7 @@ dependencies {
     annotationProcessor mnValidation.micronaut.validation
 
     implementation projects.micronautDataJdbc
+    implementation mnSerde.micronaut.serde.support
     implementation mn.micronaut.http.client
     implementation mnValidation.micronaut.validation
     implementation(libs.managed.jakarta.persistence.api)

doc-examples/jdbc-example-records-java/src/main/java/example/BookDTO.java

@@ -1,9 +1,9 @@
 
 package example;
 
-import io.micronaut.core.annotation.Introspected;
+import io.micronaut.serde.annotation.Serdeable;
 
-@Introspected
+@Serdeable
 public class BookDTO {
 
     private String title;

doc-examples/jdbc-example-records-kotlin/build.gradle

@@ -0,0 +1,34 @@
+plugins {
+    id "org.jetbrains.kotlin.jvm"
+    id "org.jetbrains.kotlin.kapt"
+    id "org.jetbrains.kotlin.plugin.allopen"
+    id "io.micronaut.build.internal.data-kotlin-example"
+}
+
+application {
+    mainClass = "example.ApplicationKt"
+}
+
+micronaut {
+    version libs.versions.micronaut.platform.get()
+    runtime "netty"
+    testRuntime "junit5"
+}
+
+dependencies {
+    kapt projects.micronautDataProcessor
+    kapt mnValidation.micronaut.validation
+
+    implementation mnSerde.micronaut.serde.support
+    implementation projects.micronautDataJdbc
+    implementation mn.micronaut.http.client
+    implementation mnValidation.micronaut.validation
+    implementation libs.managed.jakarta.persistence.api
+
+    implementation libs.kotlin.coroutines
+    implementation libs.kotlin.coroutines.reactive
+
+    runtimeOnly mnSql.micronaut.jdbc.tomcat
+    runtimeOnly mnLogging.logback.classic
+    runtimeOnly mnSql.h2
+}

doc-examples/jdbc-example-records-kotlin/gradle.properties

@@ -0,0 +1 @@
+skipDocumentation=true

doc-examples/jdbc-example-records-kotlin/src/main/kotlin/example/Book.kt

@@ -0,0 +1,14 @@
+package example
+
+import io.micronaut.core.annotation.Nullable
+import io.micronaut.data.annotation.*
+import java.util.*
+
+@MappedEntity // (1)
+data class Book(@Id
+                @field:Id @GeneratedValue var id: Long?, // (2)
+                @DateCreated @Nullable var dateCreated: Date? = null,
+                var title: String,
+                var pages: Int = 0) {
+    constructor(title: String, pages: Int) : this(null, null, title, pages)
+}

doc-examples/jdbc-example-records-kotlin/src/main/kotlin/example/BookDTO.kt

@@ -0,0 +1,9 @@
+package example
+
+import io.micronaut.serde.annotation.Serdeable
+
+@Serdeable
+data class BookDTO(
+    var title: String,
+    var pages: Int
+)