Data classes in public API
| Diagnostic | DATA_CLASS_PUBLIC_API |
| Default severity | Error |
| Gradle property | dataClassPublicApi |
| Exemption | @IntentionallyDataClass |
What it reports
A data class in the public API or declared as @PublishedApi internal.
public data class Point(public val x: Int,public val y: Int,)
Rationale
A data class exposes its primary constructor properties through these generated members:
copy: One parameter for each property, in declaration order.componentN: One function for each property, in declaration order.equals,hashCode, andtoString
Data classes can define equals, hashCode, and toString, or inherit final implementations.
Kotlin still generates copy and componentN.
In a regular class, you choose which members to declare.
Poko generates equals, hashCode, and toString
without copy or componentN.
Callers can use the generated API:
public data class Region(public val width: Int,public val height: Int,)private fun clientCode() {val region = Region(1920, 1080)val cropped = region.copy(1280) // positional copyval (width, height) = region // componentN destructuringval same = region == Region(1920, 1080) // structural equality}
The generated members also have these behaviors:
-
The
copyfunction is shallow, so the copy shares references to objects stored in properties. -
A change to a primary constructor property can change the instance's hash code. This can prevent lookup in hash-based collections.
-
The generated members exclude properties declared in the class body:
public data class Session(public val value: String,) {public val createdAt: Long = System.currentTimeMillis()}Sessions with the same
valuecompare equal and have the same string representation, even if theircreatedAtvalues differ. A call tocopyinitializescreatedAtagain.
Compatibility overloads
If Region gains an offsetX property, existing compiled callers still need the old constructor and copy signatures.
The secondary constructor and copy overload below restore calls that pass both width and height.
public data class Region(public val width: Int,public val height: Int,public val offsetX: Int,) {public constructor(width: Int, height: Int) : this(width, height, 0)public fun copy(width: Int, height: Int): Region = Region(width, height, offsetX)}
On the JVM, compiled calls that omit copy arguments use copy$default.
This example doesn't restore that method's old signature.
From the Kotlin library authors' guide, Avoid using data classes in your API:
It's possible to work around these issues by manually writing a secondary constructor and overriding the
copymethod. However, the effort involved negates the convenience of using a data class.
Don't
public data class Coordinates(public val x: Int,public val y: Int,)
Do
Notes
data objects aren't reported.- A non-public primary constructor or non-public properties don't exempt a data class.
Exemption
If this is intended, apply @IntentionallyDataClass to the class.
Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.
@IntentionallyDataClass(reason = ExemptionReason.API_DESIGN)public data class Coordinates(public val x: Int,public val y: Int,)
Configuration
apiWatchdog {dataClassPublicApi = WatchdogSeverity.ERROR}
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=DATA_CLASS_PUBLIC_API:error