Request for review: proposal for @FunctionalInterface checking

[Joe Darcy]

On 12/29/2012 8:25 AM, Gernot Neppert wrote:
>
>
>>
>> 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.

Yes; the intention is that interfaces meant to be used for lambdas be 
annotated with @FunctionalInterface.

> 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.

Amongst others; we would systematically find and annotate such 
interfaces in the JDK if the FunctionalInterface type is added. In JDK 
7, analagous efforts were undertaken for adding @SafeVarargs and 
AutoCloseable:

     "Project Coin: Safe Varargs in JDK Libraries"
https://blogs.oracle.com/darcy/entry/project_coin_safe_vararg_libraries

     "Project Coin: Bringing it to a Close(able)"
     https://blogs.oracle.com/darcy/entry/project_coin_bring_close


>
> 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?

That is not my assessment of the situation.

If the interface is annotated with @FunctionalInterface that means its 
future evolution should be constrained to not add, directly or 
indirectly, new methods without defaults, including in superinterfaces.

>
> 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?
>

As mentioned in subsequent discussion,

http://mail.openjdk.java.net/pipermail/lambda-libs-spec-observers/2012-December/000890.html

it is not immediately obvious from inspection the set of interface 
declarations that meet the definition of a functional interface.

Cheers,

-Joe