Annotation Interface RequiresOptIn

@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface RequiresOptIn

Denotes that the annotated annotation class is a marker annotation of an API that requires an explicit opt-in.

Marker annotations must have runtime retention and apply to the following targets (or a subset thereof):

• ElementType.ANNOTATION_TYPE
• ElementType.CONSTRUCTOR
• ElementType.FIELD
• ElementType.METHOD
• ElementType.MODULE
• ElementType.PACKAGE
• ElementType.RECORD_COMPONENT
• ElementType.TYPE

Declarations annotated with the marker annotation require an explicit opt-in either by OptIn, or by having the same opt-in requirements (for example) by being annotated with the same marker annotation.

Opt-in requirements are contagious. Use-sites of a declaration that requires an explicit opt-in, must explicitly opt in into the requirement (via OptIn) or propagate the requirement by also using the marker annotation. Users may utilize this property to exempt certain APIs from the libraries default API stability rules. If, for example, an Experimental annotation marker is used to denote potentially unstable APIs, a removal of a declaration marked as experimental would only break use-sites that explicitly opted into using the experimental API.

A declared type requires opt-in if its declaration or any enclosing declaration is annotated with a marker annotation. Enclosing declarations may include (but are not limited to) outer classes, interfaces, packages, and modules. A type that mentions a type that requires an explicit opt-in in its signature also requires an explicit opt-in.

    @UnstableApi
    public class Unstable {
        void memberMethod() {}

        static class NestedClass {
            void nestedMethod() {}
        }
    }

In this example, any use of `Unstable`, `NestedClass`, or their member methods require an explicit opt-in.

Since:

0.1.0

See Also:

• SubtypingRequiresOptIn

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	RequiresOptIn.Level	Levels used for identifying the severity of using an opt-in API without explicitly declaring it.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
RequiresOptIn.Level	level	Returns the severity of the diagnostic that should be reported on usages which did not explicitly opted into the API either by using OptIn or by being annotated with the corresponding marker annotation.
String	message	Returns the message to be reported on usages of API without an explicit opt-in, or the empty string for a generated default message.

Element Details

message

String message

Returns the message to be reported on usages of API without an explicit opt-in, or the empty string for a generated default message.

Returns:

the message to be reported on usages of API without an explicit opt-in, or the empty string for a generated default message

Since:

0.1.0

Default:

""

level

RequiresOptIn.Level level

Returns the severity of the diagnostic that should be reported on usages which did not explicitly opted into the API either by using OptIn or by being annotated with the corresponding marker annotation.

Returns:

the severity of the diagnostic that should be reported on usages which did not explicitly opted into the API either by using OptIn or by being annotated with the corresponding marker annotation

Since:

0.1.0

Default:

ERROR