Summary

Describe more explicitly how ExecutableElement .getReceiverType() is expected to behave when class files are the backing store.

Problem

The receiver parameter mechanism was added as part of the type annotations feature. The language feature is estimated to not be widely used.

Many executables have a sensibly defined receiver type even if an executable does not happen to be declared with a receiver parameter.

The specification and reference implementation of ExecutableElement .getReceiverType() has gone through a few iterations, see JDK-8225755 in JDK 14.

The changes in this CSR are:

• to require the behavior of returning a receiver type when annotations on a receiver type are found in a class file, the behavioral updates of JDK-8319196.
• allow, but not require, a non-sentinel receiver type object to be returned when a receiver parameter is not defined

The second point allows non-reference implementations more flexibility in how to implement this method; the javac reference implementation will continue to return a sentinel "not present" object when a receiver parameter is absent, even from source code.

Solution

Add a paragraph to ExecutableElement .getReceiverType() describing the behavior of the method after the improvements made under JDK-8319196.

Specification

diff --git a/src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java b/src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
index d4c9c881f3b..8bff3748394 100644
--- a/src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
+++ b/src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
@@ -89,6 +89,17 @@ public interface ExecutableElement extends Element, Parameterizable {
      * non-inner class, or an initializer (static or instance), has no
      * receiver type.
      *
+     * <p>The receiver <em>parameter</em> is a syntactic device added
+     * to the language for the purpose of hosting annotations. Even
+     * when source code is used as the basis for creating an
+     * executable, if a receiver parameter is not present in the
+     * source code, an implementation may elect to return a {@code
+     * NoType} object even in cases where a receiver <em>type</em> is
+     * nominally defined on the executable in question, such as an
+     * instance method.  When a receiver parameter is present and
+     * hosting annotations, a suitably annotated receiver type is
+     * returned.
+     *
      * @return the receiver type of this executable
      * @since 1.8
      *