49. Working with the receiver parameter

Starting with JDK 8, we can enrich any of our instance methods with the optional receiver parameter. This is a purely syntactic parameter of enclosing type exposed via the this keyword. The following two snippets of code are identical:

public class Truck {
  public void revision1(Truck this) {
    Truck thisTruck = this;
    System.out.println("Truck: " + thisTruck);
  }
  public void revision2() {
    Truck thisTruck = this;
    System.out.println("Truck: " + thisTruck);
  }
}

Do not conclude that revision2() is an overloading of revision1(), or vice versa. Both methods have the same output, the same signature, and produce the same bytecode.

The receiver parameter can be used in inner classes as well. Here is an example:

public class PaymentService {
  class InvoiceCalculation {
    final PaymentService paymentService;
    InvoiceCalculation(PaymentService PaymentService.this) {
      paymentService = PaymentService.this;
    }
  }
}

Okay, but why use the receiver parameter? Well, JDK 8 introduced so-called type annotations, which are exactly as the name suggests: annotations that can be applied to types. In this context, the receiver parameter was added for annotating the type of object for which the method is called. Check out the following code:

@Target(ElementType.TYPE_USE)
public @interface ValidAddress {}
public String getAddress(@ValidAddress Person this) { ... }

Or, check this more elaborate example:

public class Parcel {
  public void order(@New Parcel this) {...}
  public void shipping(@Ordered Parcel this) {...}
  public void deliver(@Shipped Parcel this) {...}
  public void cashit(@Delivered Parcel this) {...}
  public void done(@Cashed Parcel this) {...}
}

Every client of a Parcel must call these methods in a precise sequence drawn via type annotations and receiver parameters. In other words, an order can be placed only if it is a new order, it can be shipped only if the order was placed, it can be delivered only if it was shipped, it can be paid only if it was delivered, and it can be closed only if it was paid.

At this moment, this strict sequence is pointed out only by these hypothetical annotations. But, this is the right road to implement further a static analysis tool that will understand the meaning of these annotations and trigger warnings every time a client of Parcel doesn’t follow this precise sequence.