Request for review: proposal for @FunctionalInterface checking

[Gernot Neppert]

>
> We've had some discussions internally at Oracle about adding a 
> FunctionalInterface annotation type to the platform and we'd now like 
> to get the expert group's evaluation and feedback on the proposal.
>
> Just as the java.lang.Override annotation type allows compile-time 
> checking of programmer intent to override a method, the goal for the 
> FunctionalInterface annotation type is to enable analogous 
> compile-time checking of whether or not an interface type is 
> functional.  Draft specification:
>
> package java.lang;
>
> /**
> Indicates that an interface type declaration is intended to be a 
> <i>functional interface</i> as defined by the Java Language 
> Specification.  Conceptually, a functional interface has exactly one 
> abstract method.  Since default methods are not abstract, any default 
> methods declared in an interface do not contribute to its abstract 
> method count.  If an interface declares a method overriding one of the 
> public methods of java.lang.Object, that also does <em>not</em> count 
> toward the abstract method count.
>
> Note that instances of functional interfaces can be created with 
> lambda expressions, method references, or constructor references.
>
> If a type is annotated with this annotation type, compilers are 
> required to generate an error message unless:
>
> <ul>
> <li> The type is an interface type and not an annotation type, enum, 
> or class.
> <li> The annotated type satisfies the requirements of a functional 
> interface.
> </ul>
>
> @jls 9.8 Functional Interfaces
> @jls 9.4.3 Interface Method Body
> @jls 9.6.3.8 FunctionalInterface  [Interfaces in the java.lang package 
> get a corresponding JLS section]
> @since 1.8
> */
> @Documented
> @Retention(RUNTIME)
> @Target(TYPE)
> @interface FunctionalInterface {} // Marker annotation
>
> Annotations on interfaces are *not* inherited, which is the proper 
> semantics in this case.  A subinterface of a functional interface can 
> add methods and thus not itself be functional.  There are some 
> subtleties to the definition of a functional interface, but I thought 
> that including those by reference to the JLS was sufficient and 
> putting in all the details would be more likely to confuse than clarify.
>
> Please send comments by January 4, 2013; thanks,
>

Hello,

if I understand the proposal correctly, once the new annotation is 
available, it shall become a matter of "good style" to use it on all 
appropriate interfaces.
Thus, the following (arbitrarily chosen) set of interfaces will also 
become "FunctionalInterfaces":

java.lang.Runnable,
java.util.concurrent.Callabe,
java.lang.AutoCloseable,
java.io.Flushable.

Suppose I'm new to Java. I want to use java.lang.Runnable and open its 
JavaDoc. At first glance I can see that it comprises but one method 'run()'.
Then I notice it's annotated with '@FunctionalInterface', and I click on 
the link to find out what this is about. The JavaDoc says:

"...is intended to be a functional interface as defined by the Java 
Language Specification.  Conceptually, a functional interface has 
exactly one abstract method. "

Obviously, there's absolutely no useful information to gain here, right?

Granted, for a SAM interface with several default methods, it may be 
harder to see that it has actually one abstract method.
But since the 'default' syntax will be parsed by the JavaDoc tool 
anyway, wouldn't it be the better approach to make the non-defaulted 
method stand out by using appropriate markup?