kotlin-stdlib/kotlin/SubclassOptInRequired

SubclassOptInRequired

@Target(allowedTargets = [AnnotationTarget.CLASS])
annotation class SubclassOptInRequired(val markerClass: KClass<out Annotation>)(source)

Annotation that marks open for subclassing classes and interfaces, and makes implementation and extension of such declarations as requiring an explicit opt-in.

When applied, any attempt to subclass the target declaration will trigger an opt-in with the corresponding level and message.

The intended uses of subclass opt-in markers include, but are not limited to the following API:

  • Stable to use, but unstable to implement due to its further evolution.

  • Stable to use, but closed for 3rd-part implementations due to internal or technical reasons.

  • Stable to use, but delicate or fragile to implement.

  • Stable to use, but with a contract that may be weakened in the future in a backwards-incompatible manner for external implementations.

Contrary to regular RequiresOptIn, there are three ways to opt-in into the subclassing requirement:

  • Annotate declaration with the marker annotation, making it propagating.

  • Annotate declaration with OptIn in order to opt in into the provided guarantees in a non-propagating manner.

  • Annotate declaration with SubclassOptInRequired with the same marker class, making it further propagating only for subclassing.

Uses of this annotation are limited to open and abstract classes, and non-fun interfaces. Any other uses allowed by CLASS annotation target yield a compilation error.

Since Kotlin

1.8

See also

for a detailed description of opt-in semantics and propagation rules.

Properties

Link copied to clipboard
val markerClass: KClass<out Annotation>

specifies marker annotation that require explicit opt-in.

Since Kotlin 1.8