Support for creating queries via initialized JpqlDsl object

docs/en/jpql-with-kotlin-jdsl/custom-dsl.md

@@ -9,9 +9,12 @@ You can use them to create your own functions.
 You can also create your own `Model` that implements [`Expression`](expressions.md) or [`Predicate`](predicates.md) and create a function to return this Model.
 You can implement [`JpqlSerializer`](custom-dsl.md#serializer) to let Kotlin JDSL to render `Model` to String.
 
-{% hint style="info" %}
-You need to implement `JpqlDsl.Constructor` as a companion object so that `jpql()` can recognize the DSL.
-{% endhint %}
+There are two ways to pass your own DSL to `jpql()`.
+The first is to implement `JpqlDsl.Constructor` as a companion object to create a DSL object, and the second is to create a DSL instance.
+
+### JpqlDsl.Constructor
+
+With this way, you don't need to create an instance and a new instance is automatically created for each query creation.
 
 ```kotlin
 class MyJpql : Jpql() {
@@ -39,6 +42,34 @@ val query = jpql(MyJpql) {
 }
 ```
 
+### Jpql Instance
+
+With this way, you can reuse a single instance for query creation and utilize dependency injection.
+
+```kotlin
+class MyJpql(
+    private val encryptor: Encryptor,
+) : Jpql() {
+    fun Path<String>.equalToEncrypted(value: String): Predicate {
+        val encrypted = encryptor.encrypt(value)
+        return this.eq(encrypted)
+    }
+}
+
+val encryptor = Encryptor()
+val instance = MyJpql(encryptor)
+
+val query = jpql(instance) {
+    select(
+        entity(Book::class)
+    ).from(
+        entity(Book::class)
+    ).where(
+        path(Book::title).equalToEncrypted("plain")
+    )
+}
+```
+
 ### Serializer
 
 Implement `JpqlSerializer` and add it to `RenderContext`  to render your own `Model` to String.

docs/ko/jpql-with-kotlin-jdsl/custom-dsl.md

@@ -9,9 +9,12 @@
 그리고 [`Expression`](expressions.md) 혹은 [`Predicate`](predicates.md)를 구현한 나만의 `Model` 클래스를 만들고, 이를 반환하는 함수를 만들 수 있습니다.
 이 경우 [`JpqlSerializer`](custom-dsl.md#serializer)를 구현하여 `Model`을 String으로 랜더링하는 방법을 Kotlin JDSL에게 알려줄 수 있습니다.
 
-{% hint style="info" %}
-`jpql()`이 DSL을 인식하기 위해서 `JpqlDsl.Constructor`를 companion object로 구현해야 합니다.
-{% endhint %}
+이렇게 만들어진 나만의 DSL을 `jpql()`에 전달하기 위한 두 가지 방법이 있습니다.
+첫 번째는 DSL 객체를 생성하는 `JpqlDsl.Constructor`를 companion object로 구현하는 것이고, 두 번째는 DSL 인스턴스를 생성하는 것입니다.
+
+### JpqlDsl.Constructor
+
+이 방법을 사용하면 클래스만 선언해 사용할 수 있으며 쿼리 생성 시마다 새로운 인스턴스를 자동으로 생성합니다.
 
 ```kotlin
 class MyJpql : Jpql() {
@@ -39,9 +42,37 @@ val query = jpql(MyJpql) {
 }
 ```
 
+### Jpql Instance
+
+이 방법을 사용하면 쿼리 생성에 하나의 인스턴스를 재활용할 수 있으며 의존성 주입을 활용할 수 있습니다.
+
+```kotlin
+class MyJpql(
+    private val encryptor: Encryptor,
+) : Jpql() {
+    fun Path<String>.equalToEncrypted(value: String): Predicate {
+        val encrypted = encryptor.encrypt(value)
+        return this.eq(encrypted)
+    }
+}
+
+val encryptor = Encryptor()
+val instance = MyJpql(encryptor)
+
+val query = jpql(instance) {
+    select(
+        entity(Book::class)
+    ).from(
+        entity(Book::class)
+    ).where(
+        path(Book::title).equalToEncrypted("plain")
+    )
+}
+```
+
 ### Serializer
 
-나만의 `Model`을 String을 랜더링하기 위해 `JpqlSerializer`를 구현하고 이를 `RenderContext`에 추가해야 합니다.
+나만의 `Model`을 String으로 랜더링하기 위해 `JpqlSerializer`를 구현하고 이를 `RenderContext`에 추가해야 합니다.
 
 `JpqlSerializer`는 랜더링 로직을 구현할 수 있도록 `JpqlWriter`와 `RenderContext`를 제공합니다.
 `RenderContext`를 통해 `JpqlRenderSerializer`를 얻어 나의 `Model`이 가지고 있는 다른 `Model`을 랜더링할 수 있습니다.

dsl/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/Jpql.kt

@@ -72,6 +72,14 @@ inline fun <DSL : JpqlDsl, Q : JpqlQuery<Q>> jpql(dsl: JpqlDsl.Constructor<DSL>,
     return dsl.newInstance().init().toQuery()
 }
 
+/**
+ * Builds new JPQL query using provided JpqlDsl instance.
+ */
+@SinceJdsl("3.4.0")
+inline fun <DSL : JpqlDsl, Q : JpqlQuery<Q>> jpql(jpql: DSL, init: DSL.() -> JpqlQueryable<Q>): Q {
+    return jpql.init().toQuery()
+}
+
 /**
  * Default implementation of DSL for building a JPQL query.
  */

support/spring-batch-javax/src/main/kotlin/com/linecorp/kotlinjdsl/support/spring/batch/javax/item/database/orm/KotlinJdslQueryProviderFactory.kt

@@ -61,6 +61,31 @@ class KotlinJdslQueryProviderFactory(
         return KotlinJdslQueryProvider(query, queryParams, context)
     }
 
+    /**
+     * Creates a [KotlinJdslQueryProvider] from a select query.
+     */
+    fun <DSL : JpqlDsl, T : Any> create(
+        dsl: DSL,
+        init: DSL.() -> JpqlQueryable<SelectQuery<T>>,
+    ): KotlinJdslQueryProvider<T> {
+        val query = jpql(dsl, init)
+
+        return KotlinJdslQueryProvider(query, emptyMap(), context)
+    }
+
+    /**
+     * Creates a [KotlinJdslQueryProvider] from a select query.
+     */
+    fun <DSL : JpqlDsl, T : Any> create(
+        dsl: DSL,
+        queryParams: Map<String, Any?>,
+        init: DSL.() -> JpqlQueryable<SelectQuery<T>>,
+    ): KotlinJdslQueryProvider<T> {
+        val query = jpql(dsl, init)
+
+        return KotlinJdslQueryProvider(query, queryParams, context)
+    }
+
     /**
      * Creates a [KotlinJdslQueryProvider] from a select query.
      */

support/spring-batch-javax/src/test/kotlin/com/linecorp/kotlinjdsl/support/spring/batch/javax/item/database/orm/KotlinJdslQueryProviderFactoryTest.kt

@@ -30,12 +30,18 @@ class KotlinJdslQueryProviderFactoryTest : WithAssertions {
     @MockK
     private lateinit var createSelectQuery2: MyJpql.() -> JpqlQueryable<SelectQuery<String>>
 
+    @MockK
+    private lateinit var createSelectQuery3: MyJpqlObject.() -> JpqlQueryable<SelectQuery<String>>
+
     @MockK
     private lateinit var selectQuery1: SelectQuery<String>
 
     @MockK
     private lateinit var selectQuery2: SelectQuery<String>
 
+    @MockK
+    private lateinit var selectQuery3: SelectQuery<String>
+
     private val queryParams1 = mapOf("authorId" to 1L)
 
     private class MyJpql : Jpql() {
@@ -53,18 +59,33 @@ class KotlinJdslQueryProviderFactoryTest : WithAssertions {
         }
     }
 
+    private object MyJpqlObject : Jpql() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            return javaClass == other?.javaClass
+        }
+
+        override fun hashCode(): Int {
+            return javaClass.hashCode()
+        }
+    }
+
     @BeforeEach
     fun setUp() {
         every { createSelectQuery1.invoke(any()) } returns selectQuery1
         every { createSelectQuery2.invoke(any()) } returns selectQuery2
+        every { createSelectQuery3.invoke(any()) } returns selectQuery3
 
         every { selectQuery1.toQuery() } returns selectQuery1
         every { selectQuery2.toQuery() } returns selectQuery2
+        every { selectQuery3.toQuery() } returns selectQuery3
 
         excludeRecords { createSelectQuery1.invoke(any()) }
         excludeRecords { createSelectQuery2.invoke(any()) }
+        excludeRecords { createSelectQuery3.invoke(any()) }
         excludeRecords { selectQuery1.toQuery() }
         excludeRecords { selectQuery2.toQuery() }
+        excludeRecords { selectQuery3.toQuery() }
     }
 
     @Test
@@ -127,6 +148,36 @@ class KotlinJdslQueryProviderFactoryTest : WithAssertions {
         assertThat(actual).isEqualTo(expected)
     }
 
+    @Test
+    fun `create() with an dsl object and a select queryable`() {
+        // when
+        val actual = sut.create(MyJpqlObject, createSelectQuery3)
+
+        // then
+        val expected = KotlinJdslQueryProvider(
+            query = jpql(MyJpqlObject, createSelectQuery3),
+            queryParams = emptyMap(),
+            context = context,
+        )
+
+        assertThat(actual).isEqualTo(expected)
+    }
+
+    @Test
+    fun `create() with an dsl object, a select queryable, and query params`() {
+        // when
+        val actual = sut.create(MyJpqlObject, queryParams1, createSelectQuery3)
+
+        // then
+        val expected = KotlinJdslQueryProvider(
+            query = jpql(MyJpqlObject, createSelectQuery3),
+            queryParams = queryParams1,
+            context = context,
+        )
+
+        assertThat(actual).isEqualTo(expected)
+    }
+
     @Test
     fun `create() with a select query`() {
         // when

support/spring-batch/src/main/kotlin/com/linecorp/kotlinjdsl/support/spring/batch/item/database/orm/KotlinJdslQueryProviderFactory.kt

@@ -61,6 +61,31 @@ class KotlinJdslQueryProviderFactory(
         return KotlinJdslQueryProvider(query, queryParams, context)
     }
 
+    /**
+     * Creates a [KotlinJdslQueryProvider] from a select query.
+     */
+    fun <DSL : JpqlDsl, T : Any> create(
+        dsl: DSL,
+        init: DSL.() -> JpqlQueryable<SelectQuery<T>>,
+    ): KotlinJdslQueryProvider<T> {
+        val query = jpql(dsl, init)
+
+        return KotlinJdslQueryProvider(query, emptyMap(), context)
+    }
+
+    /**
+     * Creates a [KotlinJdslQueryProvider] from a select query.
+     */
+    fun <DSL : JpqlDsl, T : Any> create(
+        dsl: DSL,
+        queryParams: Map<String, Any?>,
+        init: DSL.() -> JpqlQueryable<SelectQuery<T>>,
+    ): KotlinJdslQueryProvider<T> {
+        val query = jpql(dsl, init)
+
+        return KotlinJdslQueryProvider(query, queryParams, context)
+    }
+
     /**
      * Creates a [KotlinJdslQueryProvider] from a select query.
      */

support/spring-batch/src/test/kotlin/com/linecorp/kotlinjdsl/support/spring/batch/item/database/orm/KotlinJdslQueryProviderFactoryTest.kt

@@ -30,12 +30,18 @@ class KotlinJdslQueryProviderFactoryTest : WithAssertions {
     @MockK
     private lateinit var createSelectQuery2: MyJpql.() -> JpqlQueryable<SelectQuery<String>>
 
+    @MockK
+    private lateinit var createSelectQuery3: MyJpqlObject.() -> JpqlQueryable<SelectQuery<String>>
+
     @MockK
     private lateinit var selectQuery1: SelectQuery<String>
 
     @MockK
     private lateinit var selectQuery2: SelectQuery<String>
 
+    @MockK
+    private lateinit var selectQuery3: SelectQuery<String>
+
     private val queryParams1 = mapOf("authorId" to 1L)
 
     private class MyJpql : Jpql() {
@@ -53,18 +59,33 @@ class KotlinJdslQueryProviderFactoryTest : WithAssertions {
         }
     }
 
+    private object MyJpqlObject : Jpql() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            return javaClass == other?.javaClass
+        }
+
+        override fun hashCode(): Int {
+            return javaClass.hashCode()
+        }
+    }
+
     @BeforeEach
     fun setUp() {
         every { createSelectQuery1.invoke(any()) } returns selectQuery1
         every { createSelectQuery2.invoke(any()) } returns selectQuery2
+        every { createSelectQuery3.invoke(any()) } returns selectQuery3
 
         every { selectQuery1.toQuery() } returns selectQuery1
         every { selectQuery2.toQuery() } returns selectQuery2
+        every { selectQuery3.toQuery() } returns selectQuery3
 
         excludeRecords { createSelectQuery1.invoke(any()) }
         excludeRecords { createSelectQuery2.invoke(any()) }
+        excludeRecords { createSelectQuery3.invoke(any()) }
         excludeRecords { selectQuery1.toQuery() }
         excludeRecords { selectQuery2.toQuery() }
+        excludeRecords { selectQuery3.toQuery() }
     }
 
     @Test
@@ -127,6 +148,36 @@ class KotlinJdslQueryProviderFactoryTest : WithAssertions {
         assertThat(actual).isEqualTo(expected)
     }
 
+    @Test
+    fun `create() with an dsl object and a select queryable`() {
+        // when
+        val actual = sut.create(MyJpqlObject, createSelectQuery3)
+
+        // then
+        val expected = KotlinJdslQueryProvider(
+            query = jpql(MyJpqlObject, createSelectQuery3),
+            queryParams = emptyMap(),
+            context = context,
+        )
+
+        assertThat(actual).isEqualTo(expected)
+    }
+
+    @Test
+    fun `create() with an dsl object, a select queryable, and query params`() {
+        // when
+        val actual = sut.create(MyJpqlObject, queryParams1, createSelectQuery3)
+
+        // then
+        val expected = KotlinJdslQueryProvider(
+            query = jpql(MyJpqlObject, createSelectQuery3),
+            queryParams = queryParams1,
+            context = context,
+        )
+
+        assertThat(actual).isEqualTo(expected)
+    }
+
     @Test
     fun `create() with a select query`() {
         // when