此参数和接收器参数的注释

首次引入 Java 注释时,没有为内部类构造函数注释实例方法的目标或隐藏的构造函数参数。这在 Java 8 中通过添加接收器参数声明得到了补救 ; 见 JLS 8.4.1

receiver 参数是实例方法或内部类构造函数的可选语法设备。对于实例方法,receiver 参数表示调用该方法的对象。对于内部类的构造函数,receiver 参数表示新构造的对象的直接封闭实例。无论哪种方式,接收器参数仅存在以允许在源代码中表示所表示的对象的类型,从而可以注释该类型。接收器参数不是形式参数; 更确切地说,它不是任何类型变量的声明(§4.12.3),它永远不会绑定到在方法调用表达式或限定类实例创建表达式中作为参数传递的任何值,并且它在任何情况下都没有任何影响运行。

以下示例说明了两种接收器参数的语法:

public class Outer {
    public class Inner {
        public Inner (Outer this) {
           // ...
        }
        public void doIt(Inner this) {
           // ...
        }
    }
}

接收器参数的唯一目的是允许你添加注释。例如,你可能有一个自定义注释 @IsOpen,其目的是断言在调用方法时 Closeable 对象尚未关闭。例如:

public class MyResource extends Closeable {
    public void update(@IsOpen MyResource this, int value) {
        // ...
    }

    public void close() {
        // ...
    }
}

在一个层面上,this 上的 @IsOpen 注释可以简单地作为文档。但是,我们可能会做得更多。例如:

  • 当调用 update 时,注释处理器可以插入 this 未处于关闭状态的运行时检查。
  • 代码检查器可以执行静态代码分析,以查找在调用 update可以关闭 this 的情况。