Some projects introduce custom annotations like @Beta or @Incubating which are - with a few exceptions - unsupported
by IDEs and have no compiler support.
OptIn aims to standardize declaring and working with APIs that require explicit opt-in in Java.
Kotlin's opt-in requirements solve this problem elegantly. Library authors declare a requirement marker - a custom annotation - and attach it to any API that requires explicit opt-in. Users can then opt in to the requirements locally or propagate the requirements. The Kotlin compiler enforces that all requirements are satisfied at compile-time.
The result is opt-in as a contract, not a suggestion. Consumers can't stumble into an unstable API by accident. They have to make a deliberate, visible choice.
This project brings the same mechanism to Java.
At its core, OptIn for Java introduces two annotations:
@RequiresOptIn - a meta-annotation used to define requirement markers. You attach it to your own annotation
interface, giving it a message and a severity level (WARNING or ERROR). That annotation then
becomes the marker your users must acknowledge.@OptIn - the acknowledgment. Callers annotate their own code with @OptIn(ExperimentalApi.class) to say:
"I know what I'm doing, and I accept the risk."Requirements are contagious by design. An @ExperimentalApi class passes its requirement to all its members and nested
types. A method whose signature mentions an experimental type inherits the requirement automatically. This means
opt-in can't be circumvented by routing through an intermediary - the verifier sees through the whole chain.
OptIn implements javac plugin and an annotation processor that together form the verifier that verifies opt-in usage at compile-time.
While the core aspects of the API and specification are unlikely to change, there are still a few details to iron out and - presumably - issues to discover. We need your feedback now to finalize the specification! Please consider trying out opt-in.
]]>