Merge pull request #1506 from jdbi/column-name-docs

Add docs and tests for @ColumnName annotation

core/src/main/java/org/jdbi/v3/core/mapper/reflect/ColumnName.java

@@ -22,7 +22,16 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specify the mapping name for a property or parameter explicitly.
+ * Specify the mapping name for a property or parameter explicitly. This annotation is respected by:
+ *
+ * <ul>
+ *     <li>BeanMapper, FieldMapper, and ConstructorMapper in core</li>
+ *     <li>The Kotlin data class mapper in KotlinPlugin</li>
+ * </ul>
+ *
+ * Note that this annotation only applies to mapping, not parameter binding. When binding with e.g.
+ * {@link org.jdbi.v3.core.statement.SqlStatement#bindBean(Object) bindBean()}, bind parameters by
+ * the property name ({@code :firstName}), not the column name ({@code :first_name}).
  */
 @Retention(RUNTIME)
 @Target({PARAMETER, FIELD, METHOD})

docs/src/adoc/index.adoc

@@ -1200,6 +1200,11 @@ public User(@ColumnName("user_id") int id, String name) {
 }
 ----
 
+[NOTE]
+The `@ColumnName` annotation only applies while mapping SQL data into Java
+objects. When binding object properties (e.g. with `bindBean()`), bind the
+property name (`:id`) rather than the column name (`:user_id`).
+
 Nested constructor-injected types can be mapped using the `@Nested` annotation:
 
 [source,java]
@@ -1331,6 +1336,11 @@ public class User {
 The `@ColumnName` annotation can be placed on either the getter or setter
 method.
 
+[NOTE]
+The `@ColumnName` annotation only applies while mapping SQL data into Java
+objects. When binding object properties (e.g. with `bindBean()`), bind the
+property name (`:id`) rather than the column name (`:user_id`).
+
 Nested Java Bean types can be mapped using the `@Nested` annotation:
 
 [source,java]
@@ -1449,6 +1459,11 @@ public class User {
 }
 ----
 
+[NOTE]
+The `@ColumnName` annotation only applies while mapping SQL data into Java
+objects. When binding object properties (e.g. with `bindBean()`), bind the
+property name (`:id`) rather than the column name (`:user_id`).
+
 Nested field-mapped types can be mapped using the `@Nested` annotation:
 
 [source,java]
@@ -4118,7 +4133,6 @@ Ensure the Kotlin compiler's https://kotlinlang.org/docs/reference/using-maven.h
 <kotlin.compiler.jvmTarget>1.8</kotlin.compiler.jvmTarget>
 ----
 
-
 Then install the plugin into your `Jdbi` instance:
 
 [source,kotlin]
@@ -4130,6 +4144,11 @@ The Kotlin mapper also supports `@ColumnName` annotation that allows to specify
 name for a property or parameter explicitly, as well as the `@Nested` annotation
 that allows mapping nested Kotlin objects.
 
+[NOTE]
+The `@ColumnName` annotation only applies while mapping SQL data into Java
+objects. When binding object properties (e.g. with `bindBean()`), bind the
+property name (`:id`) rather than the column name (`:user_id`).
+
 If you load all Jdbi plugins via `Jdbi.installPlugins()` this plugin will be
 discovered and registered automatically. Otherwise, you can attach it using
 `Jdbi.installPlugin(KotlinPlugin())`.

kotlin/src/test/kotlin/org/jdbi/v3/core/kotlin/KotlinMapperTest.kt

@@ -63,19 +63,35 @@ class KotlinMapperTest {
         assertThat(result).isEqualTo(expected)
     }
 
-    data class DataClassWithAnnotatedParameter(val id: Int, @ColumnName("first") val n: String)
+    data class DataClassWithAnnotatedValParameter(val id: Int, @ColumnName("first") val n: String)
 
     @Test
-    fun testDataClassWithAnnotatedParameter() {
-        val expected = DataClassWithAnnotatedParameter(1, "does this work?")
+    fun testDataClassWithAnnotatedValParameter() {
+        val expected = DataClassWithAnnotatedValParameter(1, "does this work?")
 
-        handle.createUpdate("INSERT INTO the_things(id, first) VALUES(:id, :first)")
-                .bind("id", expected.id)
-                .bind("first", expected.n)
+        handle.createUpdate("INSERT INTO the_things(id, first) VALUES(:id, :n)")
+                .bindBean(expected)
+                .execute()
+
+        val result = handle.createQuery("SELECT * from the_things")
+                .mapTo<DataClassWithAnnotatedValParameter>()
+                .single()
+
+        assertThat(result).isEqualTo(expected)
+    }
+
+    data class DataClassWithAnnotatedVarParameter(var id: Int, @ColumnName("first") var n: String)
+
+    @Test
+    fun testDataClassWithAnnotatedVarParameter() {
+        val expected = DataClassWithAnnotatedVarParameter(1, "does this work?")
+
+        handle.createUpdate("INSERT INTO the_things(id, first) VALUES(:id, :n)")
+                .bindBean(expected)
                 .execute()
 
         val result = handle.createQuery("SELECT * from the_things")
-                .mapTo<DataClassWithAnnotatedParameter>()
+                .mapTo<DataClassWithAnnotatedVarParameter>()
                 .single()
 
         assertThat(result).isEqualTo(expected)