Added examples of creates .builder() and .toBuilder() methods for Lombok interoperability

Author: YetAnotherMatt

README.md

@@ -147,7 +147,31 @@ constructor(
 ) {
     val fullName = "$forename $surname"
 }
-```  
+```
+
+#### builder() and toBuilder() methods
+The `@Builder` annotation processor cannot modify bytecode, so it cannot generate builder() and toBuilder() methods for you,
+but you can add them yourself:
+```kotlin
+import com.thinkinglogic.builder.annotation.Builder
+
+@Builder
+data class MyDataClass(
+        val notNullString: String,
+        val nullableString: String?
+) {
+
+     fun toBuilder(): MyDataClassBuilder = MyDataClassBuilder(this)
+ 
+     companion object {
+         @JvmStatic fun builder() = MyDataClassBuilder()
+     }
+ }
+```
+`MyDataClass.builder()` and `myDataClassObject.toBuilder()` can now be invoked from java,
+enabling a complete drop-in replacement for the Lombok @Builder annotation.
+
+---
 Examples of all of the above may be found in the kotlin-builder-example-usage sub-project.
 ## License
 This software is Licenced under the [MIT License](LICENSE.md).

kotlin-builder-example-usage/src/main/kotlin/com/thinkinglogic/example/SimpleDataClass.kt

@@ -13,4 +13,15 @@ data class SimpleDataClass(
         val date: LocalDate,
         @DefaultValue("withDefaultValue") val stringWithDefault: String = "withDefaultValue",
         @DefaultValue("LocalDate.MIN") val defaultDate: LocalDate = LocalDate.MIN
-)
+) {
+
+    /**
+     * @return a Builder initialised with fields from this object.
+     */
+    fun toBuilder() = SimpleDataClassBuilder(this)
+
+    companion object {
+        @JvmStatic
+        fun builder() = SimpleDataClassBuilder()
+    }
+}

kotlin-builder-example-usage/src/test/java/com/thinkinglogic/example/SimpleDataClassJavaTest.java

@@ -2,6 +2,9 @@
 
 import org.junit.jupiter.api.Test;
 
+import java.time.LocalDate;
+
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.catchThrowable;
 import static org.assertj.core.api.BDDAssertions.then;
 
@@ -20,4 +23,32 @@ void builderShouldRejectNullValueForRequiredFields() {
                 .isInstanceOf(IllegalArgumentException.class)
                 .hasMessageContaining("notNullString");
     }
+
+    @Test
+    void toBuilderShouldReturnInitialisedBuilder() {
+        // given
+        SimpleDataClass original = new SimpleDataClassBuilder()
+            .date(LocalDate.now())
+                .notNullString("Foo")
+                .nullableString("Bar")
+                .notNullLong(123L)
+                .build();
+
+        // when
+        SimpleDataClass result = original.toBuilder().build();
+
+        // then
+        assertThat(result).isEqualTo(original);
+    }
+
+    @Test
+    void staticBuilderMethodReturnsBuilder() {
+        // given
+
+        // when
+        SimpleDataClassBuilder builder = SimpleDataClass.builder();
+
+        // then
+        assertThat(builder).isNotNull();
+    }
 }