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-
Any other uses allowed by
CLASS annotation target yield a compilation error.