kotlin-java-library

name	kotlin-java-library
description	Kotlin design for Java libraries and Java consumers. Use when building Kotlin code intended for Java callers, aligning with Java interop, JVM annotations, records, and backward/binary compatibility rules.

Kotlin Java Library Design

Quick start

• Design Kotlin APIs as if the primary caller is Java: explicit overloads, stable names, and predictable nullability.
• Use JVM interop annotations (@JvmOverloads, @JvmStatic, @JvmField, @JvmName) to shape the Java surface.
• Prefer Java-friendly top-level functions with @file:JvmName, and use @file:JvmMultifileClass when splitting across files.
• Use fun interface for Java callbacks; avoid function types that return Unit.
• Document checked exceptions with @Throws and return defensive copies for read-only collections.
• Follow binary compatibility rules; add overloads instead of changing signatures.
• Read references/kotlin-java-library.md for examples, recipes, and checklists.

Workflow

1. Identify which public APIs must be Java-friendly (constructors, factories, utilities).
2. Shape the Java surface with JVM annotations and explicit overloads.
3. Audit public signatures for Java stability (names, nullability, overload sets, and collection exposure).
4. Apply backward-compatibility rules before publishing.
5. Validate with Java call-site examples.

Rules of thumb

• Avoid Kotlin-only surface features in public API: default args without overloads, extension-only entry points, and name clashes.
• Use @JvmOverloads for Java-callable optional parameters, and provide explicit overloads when behavior differs.
• Use @JvmStatic for companion/object members meant to be static in Java.
• Use @JvmField only for constants or immutable fields you want exposed as fields.
• Use @JvmName to resolve signature clashes or to provide a stable Java name.
• Avoid Nothing in public generic signatures; it becomes raw types in Java.

Output expectations

• Offer Java-call-site examples when proposing API changes.
• Call out binary compatibility risks and safer alternatives.

References

• Load references/kotlin-java-library.md for interop details, examples, and testing prompts.