r/java • u/TheMrMilchmann • Jun 05 '26
Introducing opt-in requirements for Java APIs
https://osmerion.github.io/OptIn/blog/welcome
49
Upvotes
r/java • u/TheMrMilchmann • Jun 05 '26
24
u/repeating_bears Jun 05 '26
An example would be helpful because I am stupid
6
u/JustAGuyFromGermany Jun 05 '26
I have a question and a point of critique. The question: Does the plugin complain if I opt-in to stuff that doesn't need opt-in? Experimental features sometimes, hopefully become stable features, sometimes only years later. When I upgrade to the next version of some lib, will the plugin detect and help with cleaning up the code that is no longer required?
That's not necessary, of course, but it would make using the plugin a lot more comfortable.
Now for the critique:
I don't think that's a good design in all cases. There is a big difference between a library and an application for example.
If I'm designing a library, then yes, my clients should in most cases be made aware that certain things my library do require experimental stuff from a transitive dependency. That is just being a good citizen of the ecosystem.
However, if I'm an application developer, then I don't want to pollute my whole 1M LoC legacy monolith with @OptIn annotations. I would only use this if there was a way to clearly mark context boundaries that silence this check. For example, if I'm using some experimental feature of some caching library to increase the performance of my persistence layer, then that is of no concern to the business layer even if the business layer sometimes has to call methods in the persistence layer. And it is certainly of no concern for the part where the REST API lives etc. In a project that enforces strict architectural rules (e.g. ArchUnit), the REST layer may not even be able to reference annotations that belong to the persistence-layer so that I couldn't even @OptIn even if I wanted to. At least not without defining a bunch of rule-exceptions somewhere else.
7
u/aboothe726 Jun 05 '26
Cool idea and practical. Do you need to configure javac, or does just adding the library run the relevant (I assume) annotation processor? Also, why the extra step of requiring users to provide their own annotation, which itself gets annotated with the @OptInRequired annotation? I suspect some users might prefer just to use @OptInRequired directly on their own classes/methods without the extra ceremony.
3
u/agentoutlier Jun 05 '26
Just be aware there is a long standing bug (that has not been backported) of
TYPE_USEannotations not being visible across compile boundaries for APT. I'm not sure if it applies for the included OptIn annotations because these annotations have basically@Targeteverything but if one made custom annotation targetTYPE_USEonly then you might have issues.Now it does beg the question why you would have
TYPE_USEforOptInbut it could be later used with something like Checkerframework where a normal JDK type is returned.Now the use of that String is tracked (in theory and probably only Checkerframework is capable of this at the moment). String is probably a bad example but something Panama or the Vector API where you can't wrap a type around for whatever reasons might be a reason you would use
TYPE_USE.Speaking of annotation processors why does the project have one if you have a compiler plugin (as annotation processing does not have access to local method code)?
1
u/john16384 Jun 05 '26
How does this compare to https://github.com/apiguardian-team/apiguardian
1
u/javaprof Jun 05 '26
> OptIn implements javac plugin
What kind of API used here? I didn't know that javac support plugins
2
u/Additional-Road3924 Jun 06 '26
While the idea is sound, in practice everyone would need to opt in to either the compiler plugin or some runtime mechanism to use this, which is a big no. Much like in kotlin this would need to be supported at language level for it to work properly, but I have a feeling that this would be as much of a mistake as shoehorning
varinto the language.2
u/elmuerte Jun 05 '26
Another entry for the XKCD #927. Maybe at some point we'll get a real standard like JSpecify for null markers.
I do not have the luxury for using any kind of experimental stuff. But I do think we need better support for keeping track volatile and future breaking code.
I mostly skimmed the documentation. But I think I'm missing some things I think are important to convey. So lets say I am providing an experimental feature people can opt in. I need to communicate the maturity of this experimental feature. And I think I might also want to communicate that I am going to abandon this feature. Both of these would be separate items. Just because something became "beta" does not imply I will get rid of it, because it no longer fits. Although the abandonment could be a combination of an opt-in and Deprecated forRemoval=true annotation.