Open API without subclass opt-in
| Diagnostic | OPEN_API_WITHOUT_SUBCLASS_OPT_IN |
| Default severity | Error |
| Gradle property | openApiWithoutSubclassOptIn |
| Exemption | @IntentionallyOpen |
What it reports
An open or abstract class in the public API with a constructor that external subclasses can call,
or a non-sealed interface, without @SubclassOptInRequired.
public open class Component
Rationale
A new abstract member or a changed member signature can break external subclasses.
For an unstable subclass contract, use @SubclassOptInRequired.
Don't
public interface Plugin {public fun run()}
Do
@RequiresOptInpublic annotation class InternalMyLibrarySubclassApi@SubclassOptInRequired(InternalMyLibrarySubclassApi::class)public interface Plugin {public fun run()}
Notes
-
Classes whose constructors are all
internalorprivatearen't reported. -
Users implement a
fun interfacewith a lambda, so external implementations are its purpose.@SubclassOptInRequiredisn't applicable to afun interface, and the compiler rejects it. The check reports thefun interfaceanyway. The open contract must be an explicit decision of the author, so acknowledge the external implementations with@IntentionallyOpen.public fun interface Listener {public fun onEvent()}@IntentionallyOpen(reason = ExemptionReason.API_DESIGN)public fun interface AcknowledgedListener {public fun onEvent()} -
In a multiplatform project, users on a platform can subclass the
actualdeclaration. The check reports anactualdeclaration that is open when itsexpectdeclaration isn't:- An
openactualclass for a finalexpectclass. - A public or protected constructor that only the
actualclass declares. - An
actual typealiasto an open class or interface of another module.@SubclassOptInRequireddoesn't apply to a type alias, so declare anactualclass or interface instead. - An
actual typealiasto an open Java class or interface of the module. Apply@SubclassOptInRequiredto the Java declaration.
@IntentionallyOpenon anexpectdeclaration also exempts itsactualdeclarations. - An
-
Subclass opt-in without markers reports a markerless
@SubclassOptInRequiredinstead. -
Exhaustive public API reports sealed types.
-
@PublishedApi internaltypes aren't reported.
Exemption
If this is intended, apply @IntentionallyOpen to the class, interface, or type alias.
Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.
@IntentionallyOpen(reason = ExemptionReason.API_DESIGN)public open class Widget
Configuration
apiWatchdog {openApiWithoutSubclassOptIn = WatchdogSeverity.ERROR}
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=OPEN_API_WITHOUT_SUBCLASS_OPT_IN:error