Kotlin Builder Annotation

A replacement for the Lombok @Builder annotation for Kotlin

License

License

Categories

Categories

Kotlin Languages
GroupId

GroupId

com.thinkinglogic.builder
ArtifactId

ArtifactId

kotlin-builder-annotation
Last Version

Last Version

1.2.1
Release Date

Release Date

Type

Type

jar
Description

Description

Kotlin Builder Annotation
A replacement for the Lombok @Builder annotation for Kotlin
Project URL

Project URL

https://github.com/ThinkingLogic/kotlin-builder-annotation
Source Code Management

Source Code Management

https://github.com/ThinkingLogic/kotlin-builder-annotation

Download kotlin-builder-annotation

How to add to project

<!-- https://jarcasting.com/artifacts/com.thinkinglogic.builder/kotlin-builder-annotation/ -->
<dependency>
    <groupId>com.thinkinglogic.builder</groupId>
    <artifactId>kotlin-builder-annotation</artifactId>
    <version>1.2.1</version>
</dependency>
// https://jarcasting.com/artifacts/com.thinkinglogic.builder/kotlin-builder-annotation/
implementation 'com.thinkinglogic.builder:kotlin-builder-annotation:1.2.1'
// https://jarcasting.com/artifacts/com.thinkinglogic.builder/kotlin-builder-annotation/
implementation ("com.thinkinglogic.builder:kotlin-builder-annotation:1.2.1")
'com.thinkinglogic.builder:kotlin-builder-annotation:jar:1.2.1'
<dependency org="com.thinkinglogic.builder" name="kotlin-builder-annotation" rev="1.2.1">
  <artifact name="kotlin-builder-annotation" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.thinkinglogic.builder', module='kotlin-builder-annotation', version='1.2.1')
)
libraryDependencies += "com.thinkinglogic.builder" % "kotlin-builder-annotation" % "1.2.1"
[com.thinkinglogic.builder/kotlin-builder-annotation "1.2.1"]

Dependencies

compile (1)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.3.50

Project Modules

There are no modules declared in this project.

kotlin-builder-annotation

A builder annotation for Kotlin interoperability with Java. This project aims to be a minimal viable replacement for the Lombok @Builder plugin for Kotlin code.

Build Status License

Usage

Import kotlin-builder-annotation and kotlin-builder-processor

And configure the Kotlin annotation processor (kapt).

Gradle
...
apply plugin: 'kotlin-kapt'
...
dependencies {
    ...
    implementation 'com.thinkinglogic.builder:kotlin-builder-annotation:1.2.1'
    kapt 'com.thinkinglogic.builder:kotlin-builder-processor:1.2.1'
}
Maven
...
<dependencies>
    <dependency>
        <groupId>com.thinkinglogic.builder</groupId>
        <artifactId>kotlin-builder-annotation</artifactId>
        <version>1.2.1</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.1</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</execution>

Annotate your class(es) with the @Builder annotation

import com.thinkinglogic.builder.annotation.Builder

@Builder
data class MyDataClass(
        val notNullString: String,
        val nullableString: String?
)

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 expose a MyDataClass.builder() static method. Instead clients create a new MyDataClassBuilder(), for instance:

public class MyDataFactory {
    public MyDataClass create() {
        return new MyDataClassBuilder()
                .notNullString("Foo")
                .nullableString("Bar")
                .build();
    }
}

The builder will check for required fields, so
new MyDataClassBuilder().notNullString(null);
would throw an IllegalArgumentException and
new MyDataClassBuilder().nullableString("Bar").build();
would throw an IllegalStateException naming the required field ('notNullString' in this case), while
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:

import com.thinkinglogic.builder.annotation.Builder
import com.thinkinglogic.builder.annotation.DefaultValue

@Builder
data class MyDataClass(
        val notNullString: String,
        val nullableString: String?,
        @DefaultValue("myDefaultValue") val stringWithDefault: String = "myDefaultValue",
        @DefaultValue("LocalDate.MIN") val defaultDate: LocalDate = LocalDate.MIN
)

(The text value of @DefaultValue is interpreted directly as Kotlin code, but for convenience double quotes are added around a String value).

Collections containing nullable elements

Information about the nullability of elements in a collection is lost during compilation, so there is a @NullableType annotation:

import com.thinkinglogic.builder.annotation.Builder
import com.thinkinglogic.builder.annotation.NullableType

@Builder
data class MyDataClass(
        val setOfLongs: Set<Long>,
        @NullableType val setOfNullableLongs: Set<Long?>
)

Mutable collections

Information about the mutability of collections and maps is lost during compilation, so there is an @Mutable annotation:

import com.thinkinglogic.builder.annotation.Builder
import com.thinkinglogic.builder.annotation.Mutable

@Builder
data class MyDataClass(
        val setOfLongs: Set<Long>,
        @Mutable val listOfStrings: MutableList<String>
)

Constructor parameters

The @Builder annotation may be placed on a constructor instead of the class - useful if you have constructor-only parameters:

import com.thinkinglogic.builder.annotation.Builder

class MyClass
@Builder
constructor(
        forename: String,
        surname: String,
        val nickName: String?
) {
    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:

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.

com.thinkinglogic.builder

Thinking Logic Limited

Versions

Version
1.2.1
1.1.0
1.0.3
1.0.2