Annotation Interface SubtypingRequiresOptIn

@Documented
@Repeatable(SubtypingRequiresOptIn.Repeated.class)
@Retention(RUNTIME)
@Target(TYPE)
public @interface SubtypingRequiresOptIn

A type annotated with SubtypingRequiresOptIn requires an explicit opt-in for a specified marker annotation only when it is sub-typed.

This annotation is intended to be used when abstract or open types are exposed and generally stable to use, but unsafe to implement by third parties. Examples include (but are not limited to) types that are stable to use, but also

• likely to evolve in a backwards-incompatible manner,
• require careful handling and are hard to implement correctly, or
• are not intended for third-party implementations.

There are three ways to opt-in into the subtyping requirement:

• The subtype may be annotated with the marker annotation to propagate the requirement to all its use-sites.
• The subtype may be annotated with SubtypingRequiresOptIn with the same marker annotation to propagate the requirement to its subtypes.
• The subtype may be annotated with OptIn to opt-in into the requirement without propagating it.

Only types that permit unrestricted subtyping may be annotated with SubtypingRequiresOptIn. Notably, using this annotation on sealed classes or interfaces is not permitted.

Since:

0.1.0

See Also:

• RequiresOptIn

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	SubtypingRequiresOptIn.Repeated	A container for the repeatable SubtypingRequiresOptIn annotation.

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
Class<? extends Annotation>	value	Returns the marker annotation to require when subtyping the annotated type.

Element Details

value

Class<? extends Annotation> value

Returns the marker annotation to require when subtyping the annotated type.

Returns:

the marker annotation to require when subtyping the annotated type

Since:

0.1.0