Added Serialization DSL description

Author: gtrefs

README.md

@@ -62,3 +62,119 @@ store.project(registeredUsers).thenApply { println("$it.name is active.") }
 
 // prints Raimo is active
 ```
+
+## Serialization DSL 
+
+### Default behaviour
+By default the constructor parameters of an event are assumed to be payload, meta information is empty and type is set to the full qualified name (FQN) of the underlying Java type.
+```Kotlin
+data class ColorChangedEvent(val timeStamp: Long, val oldColor: Color, val newColor: Color): DomainEvent {
+
+    private val serialized by lazy {
+        serialization(this)
+    }
+
+    override fun serialize(): SerializedDomainEvent = serialized
+
+    // companion object left out
+}
+
+data class Color(val red: Byte, val green: Byte, val blue: Byte, val alpha: Byte)
+
+val now = val now = LocalDateTime.now().toInstant(ZoneOffset.UTC).toEpochMilli()
+val colorChanged = ColorChangedEvent(now, Color(120,120,120,100), Color(120,120,120,50))
+val result = colorChanged.serialize()
+```
+
+The type of `result` is `de.gtrefs.eventstore.ColorChangedEvent`, property `meta` is empty and property `payload` is a map with three entries:
+
+```Kotlin
+result.payload == mapOf(
+    "timeStamp" to now, 
+    "oldColor" to Color(120,120,120,100), 
+    "newColor" to Color(120,120,120,50)
+)
+```
+
+### Instance access through `it`
+Within the `meta` and `payload` directives, the instance which should be translated is accessible throught `it`.
+```Kotlin
+val serialization = serialize<ColorChangedEvent> {
+    payload {
+        "oldColor" with it.oldColor
+        "newColor" with it.newColor
+    }
+}
+```
+
+### Exclution and explicit parameters
+
+Manipulating the translation is possible in two mutual exclusive ways. First, parameters can be excluded from the translation. Second, key-value-pairs can be defined explicitly.
+```Kotlin
+// Excluding parameter timeStamp from the payload
+val serialization = serialize<ColorChangedEvent>{
+    payload {
+        without("timeStamp")
+    }
+}
+
+val serialized = serialization(colorChanged)
+
+serialized.payload.keys == setOf("oldColor", "newColor")
+```
+Parameter `timeStamp` is removed from the translation. It is not in `meta` nor in `payload`. Property `payload` just contains `oldColor` and `newColor`.
+
+A more imperative approach is to explicitly declare which key-value-pairs should be stored in the properties `meta` and `payload`.
+```Kotlin
+val serialization = serialize<ColorChangedEvent> {
+    meta {
+        "timeStamp" with it.timeStamp
+    }
+   payload {
+        exclude("timeStamp")
+   }
+}
+```
+In this case `meta` contains `timeStamp` and `payload` contains the `oldColor` and `newColor`. The `with` directive is used to declare the new pair.
+
+**Note**: Being explicit has a higher precedence than exclusion. This means, if there are explicitly declared key-value-pairs, these pairs are used for serialization and `without` is ignored. 
+``` Kotlin
+val serialization = serialize<ColorChangedEvent> {
+    payload {
+        without("timeStamp")
+        "time" with it.timeStamp
+    }
+}
+
+val serialized = serialization(colorChanged)
+
+serialized.payload == mapOf("time" to now)
+```
+It is a `IllegalArgumentException` to exclude and explicitly declare values with the same key and vice versa.
+```Kotlin
+it("explicit parameters cannot be excluded"){
+     val serialization = serialize<ColorChangedEvent>{
+         payload {
+             "timeStamp" with it.timeStamp
+             without("timeStamp")
+         }
+     }
+
+     assertFailsWith<IllegalArgumentException> {
+         serialization(colorChanged)
+     }
+ }
+
+ it("excluded parameters cannot be added"){
+     val serialization = serialize<ColorChangedEvent>{
+         payload {
+             without("timeStamp")
+             "timeStamp" with it.timeStamp
+         }
+     }
+
+     assertFailsWith<IllegalArgumentException> {
+         serialization(colorChanged)
+     }
+ }
+```