Merge pull request #4 from ThinkingLogic/develop

Merging develop (v 1.2.0) into master

Author: YetAnotherMatt

.gitignore

@@ -1,6 +1,8 @@
 .gradle
 .idea
 **/build/
+*.iml
+/kotlin-builder-example-usage/.kotlintest/
 
 # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
 !gradle-wrapper.jar

README.md

@@ -6,9 +6,55 @@ This project aims to be a minimal viable replacement for the Lombok @Builder plu
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ## Usage
-TODO: gradle and maven
+#### Import `kotlin-builder-annotation` and `kotlin-builder-processor`
+And configure the [Kotlin annotation processor (kapt)](https://kotlinlang.org/docs/reference/kapt.html).
+##### Gradle
+```gradle
+...
+apply plugin: 'kotlin-kapt'
+...
+dependencies {
+    ...
+    implementation 'com.thinkinglogic.builder:kotlin-builder-annotation:1.2.0'
+    kapt 'com.thinkinglogic.builder:kotlin-builder-processor:1.2.0'
+}
+```
+##### Maven
+```maven
+...
+<dependencies>
+    <dependency>
+        <groupId>com.thinkinglogic.builder</groupId>
+        <artifactId>kotlin-builder-annotation</artifactId>
+        <version>1.2.0</version>
+    </dependency>
+    ...
+</dependencies>
+...
+<execution>
+    <id>kapt</id>
+    <goals>
+        <goal>kapt</goal>
+    </goals>
+    <configuration>
+        <sourceDirs>
+            <sourceDir>src/main/kotlin</sourceDir>
+            <sourceDir>src/main/java</sourceDir>
+        </sourceDirs>
+        <annotationProcessorPaths>
+            <!-- Specify your annotation processors here. -->
+            <annotationProcessorPath>
+                <groupId>com.thinkinglogic.builder</groupId>
+                <artifactId>kotlin-builder-processor</artifactId>
+                <version>1.2.0</version>
+            </annotationProcessorPath>
+        </annotationProcessorPaths>
+    </configuration>
+</execution>
 
-#### Annotate your class with the @Builder annotation
+```
+
+#### Annotate your class(es) with the @Builder annotation
 ```kotlin
 import com.thinkinglogic.builder.annotation.Builder
 
@@ -20,8 +66,8 @@ data class MyDataClass(
 ```
 That's it! Client code can now use a builder to construct instances of your class.
 
-Unlike Lombok there's no bytecode manipulation, so we don't have a `MyDataClass.builder()` static method.
-Instead we create a `new MyDataClassBuilder()`:
+Unlike Lombok there's no bytecode manipulation, so we don't expose a `MyDataClass.builder()` static method.
+Instead clients create a `new MyDataClassBuilder()`, for instance:
 
 ```java
 public class MyDataFactory {
@@ -41,6 +87,9 @@ The builder will check for required fields, so
  `new MyDataClassBuilder().notNullString("Foo").build();`  
  would return a new instance with a null value for 'nullableString'.
 
+To replace Kotlin's `copy()` (and Lombok's `toBuilder()`) method, clients can pass an instance of the annotated class when constructing a builder:
+`new MyDataClassBuilder(myDataClassInstance)` - the builder will be initialised with values from the instance.
+
 #### Default values
 Kotlin doesn't retain information about default values after compilation, so it cannot be accessed during annotation processing. 
 Instead we must use the `@DefaultValue` annotation to tell the builder about it: 
@@ -72,7 +121,7 @@ data class MyDataClass(
 ```
 
 #### Mutable collections
-Information about the mutability of collections and maps is lost during compilation, so there is a `@Mutable` annotation:
+Information about the mutability of collections and maps is lost during compilation, so there is an `@Mutable` annotation:
 ```kotlin
 import com.thinkinglogic.builder.annotation.Builder
 import com.thinkinglogic.builder.annotation.Mutable
@@ -85,7 +134,7 @@ data class MyDataClass(
 ```
 
 #### Constructor parameters
-The `@Builder` annotation should be placed on a constructor instead of the class if you have constructor-only parameters:
+The `@Builder` annotation may be placed on a constructor instead of the class - useful if you have constructor-only parameters:
 ```kotlin
 import com.thinkinglogic.builder.annotation.Builder
 
@@ -98,8 +147,32 @@ 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).
 

build.gradle

@@ -1,5 +1,7 @@
 buildscript {
-    ext.kotlin_version = '1.2.60'
+    ext.kotlin_version = '1.3.50'
+    ext.kotlintest_version = '3.3.2'
+    ext.junit_jupiter_version = '5.3.1'
 
     repositories {
         mavenCentral()
@@ -12,17 +14,19 @@ buildscript {
     }
 }
 
-allprojects {
-    group = 'com.thinkinglogic'
-    version = '1.0.0'
-}
-
+/*
+ * to publish:
+ * gradle clean publish bintrayUpload
+ */
 
 allprojects {
+    group = 'com.thinkinglogic.builder'
+    version = '1.2.0'
     apply plugin: "kotlin"
 
     repositories {
         mavenCentral()
+        jcenter()
     }
 
     compileKotlin {
@@ -41,6 +45,13 @@ allprojects {
 
     dependencies {
         compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
+        testCompile "org.junit.jupiter:junit-jupiter-engine:$junit_jupiter_version"
+        testCompile "org.junit.jupiter:junit-jupiter-api:$junit_jupiter_version"
+        testCompile "io.kotlintest:kotlintest-runner-junit5:$kotlintest_version"
+        testCompile "io.kotlintest:kotlintest-core:$kotlintest_version"
     }
 
+    test {
+        useJUnitPlatform()
+    }
 }

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,5 @@
-#Sun Aug 05 16:37:36 BST 2018
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.2-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.9-all.zip

kotlin-builder-annotation/build.gradle

@@ -7,18 +7,19 @@ dependencies {
 
 task sourcesJar(type: Jar) {
     from sourceSets.main.allSource
-    classifier = 'sources'
+    archiveClassifier = 'sources'
 }
 
 task javadocJar(type: Jar) {
     from javadoc
-    classifier = 'javadoc'
+    archiveClassifier = 'javadoc'
 }
 
 publishing {
     publications {
         MyPublication(MavenPublication) {
-            artifactId = 'kotlin-builder-annotation'
+            groupId 'com.thinkinglogic.builder'
+            artifactId 'kotlin-builder-annotation'
             from components.java
             artifact sourcesJar
             artifact javadocJar
@@ -61,6 +62,7 @@ javadoc {
         options.addBooleanOption('html4', true)
     }
 }
+/* see: https://github.com/bintray/gradle-bintray-plugin */
 bintray {
     user = System.getenv('BINTRAY_USER')
     key = System.getenv('BINTRAY_API_KEY')
@@ -78,6 +80,9 @@ bintray {
             released  = new Date()
             vcsTag = project.version
             attributes = ['kotlin-builder-annotation': 'com.thinkinglogic:com.thinkinglogic.builder:kotlin-builder-annotation']
+            gpg {
+                sign = true
+            }
         }
     }
 }

kotlin-builder-example-usage/build.gradle

@@ -1,15 +1,13 @@
 apply plugin: 'kotlin-kapt'
 
 dependencies {
-    compile project(':kotlin-builder-annotation')
-
-    kapt project(':kotlin-builder-processor')
-
+    implementation project(':kotlin-builder-annotation')
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
     implementation "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
 
-    testCompile group: 'org.junit.jupiter', name: 'junit-jupiter-api', version: '5.2.0'
-    testCompile group: 'com.willowtreeapps.assertk', name: 'assertk', version: '0.10'
-    testCompile group: 'org.assertj', name: 'assertj-core', version: '3.10.0'
+    kapt project(':kotlin-builder-processor')
+    
+    testCompile "org.assertj:assertj-core:3.10.0"
+    testCompile "com.willowtreeapps.assertk:assertk:0.10"
 
 }

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

@@ -14,6 +14,7 @@ data class ArraysDataClass(
         val arrayOfDates: Array<LocalDate>
 
 ) {
+    // Due to the way the JVM uses instance equality for arrays, we should override equals and hashcode
     override fun equals(other: Any?): Boolean {
         if (this === other) return true
         if (javaClass != other?.javaClass) return false

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

@@ -29,4 +29,8 @@ constructor(
         result = 31 * result + fullName.hashCode()
         return result
     }
+
+    override fun toString(): String {
+        return "ClassWithConstructorParameters(otherName=$otherName, fullName='$fullName')"
+    }
 }

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

@@ -8,11 +8,11 @@ import java.util.*
 @Builder
 data class CollectionsDataClass(
         val listOfStrings: List<String>,
+        @NullableType val listOfNullableStrings: List<String?>,
         val setOfLongs: Set<Long>,
         @NullableType val setOfNullableLongs: Set<Long?>,
         val hashSet: HashSet<Long>,
         val collectionOfDates: Collection<LocalDate>,
         @NullableType val mapOfStringToNullableDates: Map<String, LocalDate?>,
         val treeMap: TreeMap<String, LocalDate>
-
 )

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

@@ -4,7 +4,8 @@ import com.thinkinglogic.builder.annotation.Builder
 
 @Builder
 data class DataClassWithAdditionalFields(
-        val constructorString: String
+        val constructorString: String,
+        private val privateString: String
 ) {
     val nonConstructorString = constructorString + "foo"
 

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

@@ -0,0 +1,22 @@
+package com.thinkinglogic.example
+
+import com.thinkinglogic.builder.annotation.Builder
+import com.thinkinglogic.builder.annotation.DefaultValue
+import java.time.LocalDate
+
+@Builder
+data class DataClassWithLongPropertyNames(
+        @DefaultValue("myDefault") val stringWithAVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongNameThatWouldCauseLineWrappingInTheGeneratedFile: String = "myDefault",
+        val nullableString: String?
+) {
+
+    /**
+     * @return a Builder initialised with fields from this object.
+     */
+    fun toBuilder() = DataClassWithLongPropertyNamesBuilder(this)
+
+    companion object {
+        @JvmStatic
+        fun builder() = DataClassWithLongPropertyNamesBuilder()
+    }
+}

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/CollectionsDataClassJavaTest.java

@@ -0,0 +1,46 @@
+package com.thinkinglogic.example;
+
+import org.junit.jupiter.api.Test;
+
+import java.time.LocalDate;
+import java.util.*;
+
+import static java.util.Arrays.asList;
+import static java.util.Collections.emptyList;
+import static java.util.Collections.emptySet;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.catchThrowable;
+import static org.assertj.core.api.BDDAssertions.then;
+
+public class CollectionsDataClassJavaTest {
+
+    @Test
+    void builderShouldAllowNullValuesInCollections() {
+        // given
+        CollectionsDataClassBuilder builder = new CollectionsDataClassBuilder();
+
+        List<String> nullableList = asList(null, null, "foo");
+        Set<Long> nullableSet = new HashSet<>(asList(null, null, 1L));
+
+        HashMap<String, LocalDate> nullableMap = new HashMap<>();
+        nullableMap.put("Foo", null);
+
+
+        // when
+        CollectionsDataClass result = builder
+                .listOfNullableStrings(nullableList)
+                .mapOfStringToNullableDates(nullableMap)
+                .setOfNullableLongs(nullableSet)
+                .collectionOfDates(emptySet())
+                .listOfStrings(emptyList())
+                .setOfLongs(emptySet())
+                .hashSet(new HashSet<>())
+                .treeMap(new TreeMap<>())
+                .build();
+
+        // then
+        assertThat(result.getListOfNullableStrings()).isEqualTo(nullableList);
+        assertThat(result.getMapOfStringToNullableDates()).isEqualTo(nullableMap);
+        assertThat(result.getSetOfNullableLongs()).isEqualTo(nullableSet);
+    }
+}