The Data-compat library resolves the Java binary incompatibility that library developers face when using Kotlin data classes. In a nutshell, every change to a data class results in major breaking change. This project attempts to resolve this binary incompatibility by using annotation processing. Users can keep using their original data classes definitions, but the generated code will compatible for Java consumption. To read more about this incompatibility, please refer to Jake Wharton's Public API challenges in Kotlin blogpost.
This library uses Kotlin Symbol Processing API (KSP) in combination with KotlinPoet to generate Kotlin classes. Input is a private data class that supports a @DataCompat annotation and the code generator outputs a Kotlin class that supports a builder pattern compatible for Java usage.
The project is hosted on jitpack and requires to add jitpack.io lookup to your gradle configuration:
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}Since this project uses ksp, you will have to include it:
plugins {
id 'com.google.devtools.ksp' version '1.6.10-1.0.2' apply false
}And you will have to include the required dependencies:
dependencies {
implementation 'com.github.tobrun.kotlin-data-compat:annotation:0.4.0'
ksp 'com.github.tobrun.kotlin-data-compat:processor:0.4.0'
}Given an exisiting data class:
- add
@DataCompatannotation - mark class private
- append
Datato the class name - support default parameters by using
@Defaultannotation - support imports for default parameters
- retain existing class annotations (but not parameters for them)
- retain existing interfaces
For example:
interface SampleInterface
annotation class SampleAnnotation
/**
* Represents a person.
* @property name The full name.
* @property nickname The nickname.
* @property age The age.
*/
@DataCompat
@SampleAnnotation
private data class PersonData(
@Default("\"John\" + Date(1580897313933L).toString()", imports = ["java.util.Date"])
val name: String,
val nickname: String?,
@Default("42")
val age: Int
) : SampleInterfaceAfter compilation, the following class will be generated:
package com.tobrun.`data`.compat.example
import java.util.Date
import java.util.Objects
import kotlin.Any
import kotlin.Boolean
import kotlin.Int
import kotlin.String
import kotlin.Unit
import kotlin.jvm.JvmSynthetic
/**
* Represents a person.
* @property name The full name.
* @property nickname The nickname.
* @property age The age.
*/
@SampleAnnotation
public class Person private constructor(
public val name: String,
public val nickname: String?,
public val age: Int
) : SampleInterface {
public override fun toString() = """Person(name=$name, nickname=$nickname,
age=$age)""".trimIndent()
public override fun equals(other: Any?): Boolean {
if (this === other) return true
if (javaClass != other?.javaClass) return false
other as Person
return name == other.name && nickname == other.nickname && age == other.age
}
public override fun hashCode(): Int = Objects.hash(name, nickname, age)
/**
* Convert to Builder allowing to change class properties.
*/
public fun toBuilder(): Builder = Builder() .setName(name) .setNickname(nickname) .setAge(age)
/**
* Composes and builds a [Person] object.
*
* This is a concrete implementation of the builder design pattern.
*
* @property name The full name.
* @property nickname The nickname.
* @property age The age.
*/
public class Builder {
@set:JvmSynthetic
public var name: String? = "John" + Date(1580897313933L).toString()
@set:JvmSynthetic
public var nickname: String? = null
@set:JvmSynthetic
public var age: Int? = 42
/**
* Set the full name.
*
* @param name the full name.
* @return Builder
*/
public fun setName(name: String?): Builder {
this.name = name
return this
}
/**
* Set the nickname.
*
* @param nickname the nickname.
* @return Builder
*/
public fun setNickname(nickname: String?): Builder {
this.nickname = nickname
return this
}
/**
* Set the age.
*
* @param age the age.
* @return Builder
*/
public fun setAge(age: Int?): Builder {
this.age = age
return this
}
/**
* Returns a [Person] reference to the object being constructed by the builder.
*
* Throws an [IllegalArgumentException] when a non-null property wasn't initialised.
*
* @return Person
*/
public fun build(): Person {
if (name==null) {
throw IllegalArgumentException("Null name found when building Person.")
}
if (age==null) {
throw IllegalArgumentException("Null age found when building Person.")
}
return Person(name!!, nickname, age!!)
}
}
}
/**
* Creates a [Person] through a DSL-style builder.
*
* @param initializer the initialisation block
* @return Person
*/
@JvmSynthetic
public fun Person(initializer: Person.Builder.() -> Unit): Person =
Person.Builder().apply(initializer).build()