Merge pull request #8 from k163377/feature

Add usages to README and add test.

Author: k163377

README.md

@@ -29,6 +29,197 @@ val dst: Dst = jdbcTemplate.query(query) { rs, _ ->
 val dst: Dst = jdbcTemplate.query(query, KRowMapper(::Dst))
 ```
 
+## Usage
+### Convert Naming conventions
+`KRowMapper` searches columns by default in camel case.  
+If the DB is named in snake case, mapping can be done by passing a conversion function(e.g. defined in `JackSon`, `Guava`) to `KRowMapper`.
+
+```kotlin
+// if use Guava.
+KRowMapper(::Dst) { colName: String ->
+    CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_UNDERSCORE, colName)
+}
+```
+
+### Deserialize column
+`KRowMapper` provides a deserialization function for the acquisition results of three patterns.
+
+- Deserialize at initialization using the `factory method` or deserialize on initialize.
+- Define a deserializer for the `class`.
+- Define custom deserializer `annotation`.
+
+#### Deserialize at initialization using the factory method or deserialize on initialize
+Deserialization within a `factory method` or initialization is the simplest method.  
+Also, deserialization from multiple columns to one argument or from one column to multiple arguments cannot be realized other than this method.
+
+```kotlin
+// example of deserialize on factory method
+data class Dst(
+    foo: Foo,
+    bar: Bar,
+    baz: Baz?,
+    ...
+) {
+    companion object {
+        fun factory(
+            foo: String,
+            bar: String,
+            baz: Int?,
+            ...
+        ): Dst {
+            return Dst(
+                Foo(foo),
+                Bar.fromString(bar),
+                baz?.let { Baz(it) },
+                ...
+            )
+        }
+    }
+}
+
+val dst: Dst = jdbcTemplate.query(query, KRowMapper((Dst)::factory))
+```
+
+#### Define a deserializer for the class
+By assigning the `KColumnDeserializer` `annotation` to the `constructor` or `factory method`, deserialization by the `KFunction` can be performed.  
+The `method` that assigns this `annotation` must have one argument.
+
+When the deserializer is defined in this way, the destination will be as follows.
+
+```kotlin
+data class Dst(
+    val foo: ByConstructor,
+    val bar: BySecondaryConstructor,
+    val baz: ByCompanionObject,
+    val qux: ByStaticMethod
+)
+```
+
+##### constructor
+```kotlin
+data class ByConstructor @KColumnDeserializer constructor(val fooString: String)
+```
+
+##### secondary constructor
+```kotlin
+data class BySecondaryConstructor(val barShort: Short) {
+    @KColumnDeserializer
+    constructor(bar: String) : this(bar.toShort())
+}
+``` 
+
+##### factory method
+```kotlin
+data class ByCompanionObject(val bazInt: Int) {
+    companion object {
+        @KColumnDeserializer
+        fun factory(baz: String) = ByCompanionObject(baz.toInt())
+    }
+}
+```
+
+##### (static method)
+`Java` `static method` is also supported.
+
+```java
+public class ByStaticMethod {
+    private final String quxString;
+
+    public ByStaticMethod(String quxString) {
+        this.quxString = quxString;
+    }
+
+    public String getQuxString() {
+        return quxString;
+    }
+
+    @KColumnDeserializer
+    public static ByStaticMethod factory(Integer quxArg) {
+        return new ByStaticMethod(quxArg.toString());
+    }
+}
+```
+
+#### Define custom deserializer annotation
+`KRowMapper` supports complex deserialization by defining custom deserializer `annotations`.  
+As an example, a custom deserializer `annotation` that performs deserialization from a `String` to `LocalDateTime` is shown.
+
+```kotlin
+// annotation
+@Target(AnnotationTarget.VALUE_PARAMETER)
+@Retention(AnnotationRetention.RUNTIME)
+@MustBeDocumented
+@KColumnDeserializeBy(LocalDateTimeDeserializerImpl::class)
+annotation class LocalDateTimeDeserializer(val pattern: String = "yyyy-MM-dd'T'HH:mm:ss")
+
+// deserializer
+class LocalDateTimeDeserializerImpl(
+    annotation: LocalDateTimeDeserializer
+) : AbstractKColumnDeserializer<LocalDateTimeDeserializer, String, LocalDateTime>(annotation) {
+    private val formatter: DateTimeFormatter = DateTimeFormatter.ofPattern(annotation.pattern)
+
+    override val srcClass: Class<String> = String::class.javaObjectType
+
+    override fun deserialize(source: String?): LocalDateTime? {
+        return source?.let {
+            LocalDateTime.parse(it, formatter)
+        }
+    }
+}
+```
+
+```kotlin
+// usage
+data class Dst(@LocalDateTimeDeserializer val dateTime: LocalDateTime)
+```
+
+##### annotation
+For the `annotation class`, specify the deserializer `class` with the `KColumnDeserializeBy` `annotation`.
+Also, the fields prepared for this `annotation class` can be used from the deserializer.
+
+```kotlin
+@Target(AnnotationTarget.VALUE_PARAMETER)
+@Retention(AnnotationRetention.RUNTIME)
+@MustBeDocumented
+// LocalDateTimeDeserializerImpl is deserializer class
+@KColumnDeserializeBy(LocalDateTimeDeserializerImpl::class)
+annotation class LocalDateTimeDeserializer(val pattern: String = "yyyy-MM-dd'T'HH:mm:ss")
+```
+
+##### deserializer
+Deserializer is created by inheriting `AbstractKColumnDeserializer`.
+The meaning of each type parameter is as follows.
+
+- `A`: `Annotation class` (`LocalDateTimeDeserializer` in this example)
+- `S`: `Java class` of argument required at deserialization
+- `D`: `Class` returned after deserialization
+
+```kotlin
+abstract class AbstractKColumnDeserializer<A : Annotation, S : Any, D : Any>(protected val annotation: A) {
+    abstract val srcClass: Class<S>
+    abstract fun deserialize(source: S?): D?
+}
+```
+
+In the example, deserialization from a `String` to `LocalDateTime` is performed based on the `pattern` obtained from the
+ `LocalDateTimeDeserializer`.
+
+```kotlin
+class LocalDateTimeDeserializerImpl(
+    annotation: LocalDateTimeDeserializer
+) : AbstractKColumnDeserializer<LocalDateTimeDeserializer, String, LocalDateTime>(annotation) {
+    private val formatter: DateTimeFormatter = DateTimeFormatter.ofPattern(annotation.pattern)
+
+    override val srcClass: Class<String> = String::class.javaObjectType
+
+    override fun deserialize(source: String?): LocalDateTime? {
+        return source?.let {
+            LocalDateTime.parse(it, formatter)
+        }
+    }
+}
+```
+
 ## Installation
 Published on JitPack.  
 You can use this library on `maven`, `gradle` and any other build tools.  

src/test/java/com/mapk/krowmapper/ByStaticMethod.java

@@ -3,18 +3,18 @@
 import com.mapk.annotations.KColumnDeserializer;
 
 public class ByStaticMethod {
-    private final String bazString;
+    private final String quxString;
 
-    public ByStaticMethod(String bazString) {
-        this.bazString = bazString;
+    public ByStaticMethod(String quxString) {
+        this.quxString = quxString;
     }
 
-    public String getBazString() {
-        return bazString;
+    public String getQuxString() {
+        return quxString;
     }
 
     @KColumnDeserializer
-    public static ByStaticMethod factory(Integer bazArg) {
-        return new ByStaticMethod(bazArg.toString());
+    public static ByStaticMethod factory(Integer quxArg) {
+        return new ByStaticMethod(quxArg.toString());
     }
 }

src/test/kotlin/com/mapk/krowmapper/DeserializeByMethodTest.kt

@@ -10,17 +10,22 @@ import org.junit.jupiter.api.Test
 
 class DeserializeByMethodTest {
     data class ByConstructor @KColumnDeserializer constructor(val fooString: String)
-    data class ByCompanionObject(val barInt: Int) {
+    data class BySecondaryConstructor(val barShort: Short) {
+        @KColumnDeserializer
+        constructor(bar: String) : this(bar.toShort())
+    }
+    data class ByCompanionObject(val bazInt: Int) {
         companion object {
             @KColumnDeserializer
-            fun factory(bar: String) = ByCompanionObject(bar.toInt())
+            fun factory(baz: String) = ByCompanionObject(baz.toInt())
         }
     }
 
     data class Dst(
         val foo: ByConstructor,
-        val bar: ByCompanionObject,
-        val baz: ByStaticMethod
+        val bar: BySecondaryConstructor,
+        val baz: ByCompanionObject,
+        val qux: ByStaticMethod
     )
 
     @Test
@@ -29,12 +34,14 @@ class DeserializeByMethodTest {
         val resultSet = mockk<ResultSet>()
         every { resultSet.getObject("foo", any<Class<*>>()) } returns "foo"
         every { resultSet.getObject("bar", any<Class<*>>()) } returns "123"
-        every { resultSet.getObject("baz", any<Class<*>>()) } returns 321
+        every { resultSet.getObject("baz", any<Class<*>>()) } returns "321"
+        every { resultSet.getObject("qux", any<Class<*>>()) } returns 777
 
         val result = KRowMapper(::Dst).mapRow(resultSet, 0)
 
         Assertions.assertEquals("foo", result.foo.fooString)
-        Assertions.assertEquals(123, result.bar.barInt)
-        Assertions.assertEquals("321", result.baz.bazString)
+        Assertions.assertEquals(123, result.bar.barShort)
+        Assertions.assertEquals(321, result.baz.bazInt)
+        Assertions.assertEquals("777", result.qux.quxString)
     }
 }