Merge pull request #37 from cucumber/native-case-class-transformer

Add optional Jackson Default DataTable transformer

Author: gaeljw

CHANGELOG.md

@@ -13,6 +13,10 @@ See also the [CHANGELOG](https://github.com/cucumber/cucumber-jvm/blob/master/CH
 ### Added
 
 - [Doc] Users documentation on Scala DSL
+- [Scala DSL] Support for transformers ([#32](https://github.com/cucumber/cucumber-jvm-scala/issues/32) Gaël Jourdan-Weil) 
+  - See [Transformers](docs/transformers.md)
+- [Transformers] Add optional `JacksonDefaultDataTableEntryTransformer` ([#31](https://github.com/cucumber/cucumber-jvm-scala/issues/31) Gaël Jourdan-Weil)
+  - See [here](docs/default_jackson_datatable_transformer.md)
 
 ### Changed
 

README.md

@@ -30,6 +30,7 @@ The minor version might differ because Cucumber Scala may add Scala-related feat
   - [Step Definitions](docs/step_definitions.md)
   - [Hooks](docs/hooks.md)
   - [Transformers](docs/transformers.md)
+    - [Default Jackson DataTable Transformer](docs/default_jackson_datatable_transformer.md)
 - [Example project](examples/README.md)
 - [Reference documentation for Java](https://docs.cucumber.io/docs/cucumber/)
 - [Changelog](CHANGELOG.md)

docs/default_jackson_datatable_transformer.md

@@ -0,0 +1,68 @@
+# Default Jackson DataTable Transformer
+
+Cucumber Scala provides an optional Default DataTable Transformer that uses Jackson.
+
+It can be used to automatically convert DataTables to case classes without defining custom converters.
+
+## Add Jackson dependency
+
+To use this optional transformer, you need to have Jackson Scala in your dependencies.
+
+```xml
+<dependency>
+    <groupId>com.fasterxml.jackson.module</groupId>
+    <artifactId>jackson-module-scala_2.13</artifactId>
+    <version>2.10.3</version>
+    <scope>test</scope>
+</dependency>
+```
+
+Or:
+```sbt
+libraryDependencies += "com.fasterxml.jackson.module" %% "jackson-module-scala" % "2.10.3" % Test
+```
+
+
+The current version of Cucumber Scala has been tested against Jackson Module Scala **version 2.10.3**.
+
+## Add the transformer
+
+The transformer has to be added to your glue code by extending the `JacksonDefaultDataTableEntryTransformer` trait.
+
+For instance:
+```scala
+class MySteps extends ScalaDsl with EN with JacksonDefaultDataTableEntryTransformer {
+  // Your usual glue code
+}
+```
+
+### Empty string replacement
+
+The default empty string replacement used by the default transformer is `[empty]`.
+
+You can override it if you need to:
+```scala
+override def emptyStringReplacement: String = "[blank]"
+```
+
+## Example
+
+Then, let the transformer do its work!
+
+For instance, the following DataTable:
+```gherkin
+Given I have the following datatable
+| field1 | field2 | field3 |
+| 1.2    | true   | abc    |
+| 2.3    | false  | def    |
+| 3.4    | true   | ghj    |
+```
+
+will be automatically converted to the following case class:
+```scala
+case class MyCaseClass(field1: Double, field2: Boolean, field3: String)
+
+Given("I have the following datatable") { (data: java.util.List[MyCaseClass]) =>
+  // Do something
+}
+```

docs/transformers.md

@@ -265,6 +265,8 @@ Default transformers are used when there is no specific transformer.
 
 They can be used with object mappers like Jackson to easily convert from well known strings to objects.
 
+See also [Default Jackson DataTable Transformer](default_jackson_datatable_transformer.md).
+
 ### String
 
 For instance, the following definition:
@@ -304,6 +306,8 @@ Given("A step with a datatable") { (dataTable: DataTable) =>
 }
 ```
 
+This is what to `DefaultJacksonDataTableTransformer` uses.
+
 #### Cells
 
 For instance the following definition:

pom.xml

@@ -55,6 +55,30 @@
                 <artifactId>cucumber-core</artifactId>
                 <version>${cucumber.version}</version>
             </dependency>
+            <dependency>
+                <groupId>com.fasterxml.jackson.core</groupId>
+                <artifactId>jackson-databind</artifactId>
+                <version>${jackson-databind.version}</version>
+                <scope>provided</scope>
+            </dependency>
+            <dependency>
+                <groupId>com.fasterxml.jackson.module</groupId>
+                <artifactId>jackson-module-scala_2.11</artifactId>
+                <version>${jackson-databind.version}</version>
+                <scope>provided</scope>
+            </dependency>
+            <dependency>
+                <groupId>com.fasterxml.jackson.module</groupId>
+                <artifactId>jackson-module-scala_2.12</artifactId>
+                <version>${jackson-databind.version}</version>
+                <scope>provided</scope>
+            </dependency>
+            <dependency>
+                <groupId>com.fasterxml.jackson.module</groupId>
+                <artifactId>jackson-module-scala_2.13</artifactId>
+                <version>${jackson-databind.version}</version>
+                <scope>provided</scope>
+            </dependency>
             <dependency>
                 <groupId>io.cucumber</groupId>
                 <artifactId>cucumber-junit</artifactId>

scala/pom.xml

@@ -33,6 +33,11 @@
             <groupId>io.cucumber</groupId>
             <artifactId>cucumber-core</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <scope>provided</scope>
+        </dependency>
         <dependency>
             <groupId>io.cucumber</groupId>
             <artifactId>cucumber-junit</artifactId>
@@ -43,11 +48,6 @@
             <artifactId>junit</artifactId>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>com.fasterxml.jackson.core</groupId>
-            <artifactId>jackson-databind</artifactId>
-            <scope>test</scope>
-        </dependency>
     </dependencies>
 
     <build>

scala/scala_2.11/pom.xml

@@ -19,6 +19,13 @@
             <scope>provided</scope>
         </dependency>
 
+        <!-- Users have to provide it (for JacksonDefaultDataTableTransformer) -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.module</groupId>
+            <artifactId>jackson-module-scala_2.11</artifactId>
+            <scope>provided</scope>
+        </dependency>
+
         <dependency>
             <groupId>org.scala-lang</groupId>
             <artifactId>scala-library</artifactId>

scala/scala_2.12/pom.xml

@@ -19,6 +19,13 @@
             <scope>provided</scope>
         </dependency>
 
+        <!-- Users have to provide it (for JacksonDefaultDataTableTransformer) -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.module</groupId>
+            <artifactId>jackson-module-scala_2.12</artifactId>
+            <scope>provided</scope>
+        </dependency>
+
         <dependency>
             <groupId>org.scala-lang</groupId>
             <artifactId>scala-library</artifactId>

scala/scala_2.13/pom.xml

@@ -19,6 +19,13 @@
             <scope>provided</scope>
         </dependency>
 
+        <!-- Users have to provide it (for JacksonDefaultDataTableTransformer) -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.module</groupId>
+            <artifactId>jackson-module-scala_2.13</artifactId>
+            <scope>provided</scope>
+        </dependency>
+
         <dependency>
             <groupId>org.scala-lang</groupId>
             <artifactId>scala-library</artifactId>

scala/sources/src/main/scala/io/cucumber/scala/JacksonDefaultDataTableEntryTransformer.scala

@@ -0,0 +1,38 @@
+package io.cucumber.scala
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.module.scala.DefaultScalaModule
+
+/**
+ * <p>This trait register a `DefaultDataTableEntryTransformer` using Jackson `ObjectMapper`.</p>
+ *
+ * <p>The `[empty]` string is used as default empty string replacement. You can override it if you need to.</p>
+ *
+ * <p>Note: Jackson is not included with Cucumber Scala, you have to add the dependency:
+ * `com.fasterxml.jackson.module:jackson-module-scala_2.xx`
+ * to your project if you want to use this trait.</p>
+ */
+trait JacksonDefaultDataTableEntryTransformer extends ScalaDsl {
+
+  /**
+   * Define the string to be used as replacement for empty.
+   * Default is `[empty]`.
+   */
+  def emptyStringReplacement: String = "[empty]"
+
+  /**
+   * Create the Jackson ObjectMapper to be used.
+   * Default is a simple ObjectMapper with DefaultScalaModule registered.
+   */
+  def createObjectMapper(): ObjectMapper = {
+    val objectMapper = new ObjectMapper()
+    objectMapper.registerModule(DefaultScalaModule)
+  }
+
+  private lazy val objectMapper: ObjectMapper = createObjectMapper()
+
+  DefaultDataTableEntryTransformer(emptyStringReplacement) { (fromValue: Map[String, String], toValueType: java.lang.reflect.Type) =>
+    objectMapper.convertValue[AnyRef](fromValue, objectMapper.constructType(toValueType))
+  }
+
+}