Receiver Parameters

Optional informal parameter added at the beginning of the parameter list of a method or constructor.

The receiver parameter syntactically expresses the access that a constructor or an instance method has to the surrounding instance's this keyword, which in turn represents the state of the object that the instance method or constructor is called on. Its primary use of a receiver parameter is in allowing the type of the keyword this to be annotated.

Instance methods and constructors in inner classes implicitly have access to the this keyword and the state it represents. Utilizing a receiver parameter does not give additional access privilege to the construct.

Syntax

A receiver parameter consists of:

1	annotation-list type `this`
2	annotation-list type identifier `.` `this`

where...

annotation-list	is a list of annotations applied to the following type. Each annotation is the `@` symbol followed by the name of the annotation. The `@` can be followed by whitespace.
type	is the type of the `this` receiver parameter. For 1, the type must be exactly the method's containing class. For 2, the type must be exactly the immediate outer type of the constructor's containing class.
identifier	is the name of the containing type, used to clarify which `this` instance is being declared in the receiver parameter. The identifier must be the simple name of the immediate outer type of the constructor's containing class.

Syntax Elements

1 A receiver parameter in an instance method.

2 A receiver parameter in an inner class constructor.

Usage

Receiver parameters are not formal parameters. They do not alter the behavior of a method, change the method's signature, nor change the override-equivalence of a method. Other than allowing the presence of an annotation, they do not affect the rest of a program. In fact, a method or constructor with a receiver parameter that has no annotation, is equivalent to one without the receiver parameter.

Receiver parameters can either be for a non-static method (instance method) or a constructor in a non-static inner class. Their only functional purpose is to allow annotations, though they can be included in a method or constructor without having annotations. A receiver parameter must be first in a parameter list.

Examples

In an Instance Method

class Test {
	void someMethod(Test this) {

	}
}

The type of the receiver parameter may be fully qualified:

package net.javaref.examples;
class ReceiverParameterExample {
	void someMethod(net.javaref.examples.ReceiverParameterExample this) {

	}
}

In a Constructor

class Outer {
	class Inner {
		Inner(Outer Outer.this) {

		}
	}
}

The type of the receiver parameter may be fully qualified, but the identifier prefixing this may not. This is therefore valid:

package net.javaref.examples;
class Outer {
	class Inner {
		Inner(net.javaref.examples.Outer Outer.this) {
		
		}
	}
}

whereas the fully-qualified name in the following example is not:

package net.javaref.examples;
class Outer {
	class Inner {
//		Inner(Outer net.javaref.examples.Outer.this) { // Does not compile; expected "Outer.this", not "net.javaref.examples.Outer.this"
		
//		}
	}
}

Such simple-name restriction on the identifier prefixing this restricts even against semi-qualified names:

package net.javaref.examples;
class Top {
	class Middle {
		class Bottom {
			Bottom(Middle Top.Middle.this) { // Does not compile; expected "Middle.this", not "Top.Middle.this"
			
			}
		}
	}
}

With Other Parameters

Receiver parameters may also be used with other parameters.

class Test {
	void test(Test this, int first, int second, double third, String fourth, String... fifth) {	}
}

In such cases that other parameters are used, the receiver parameter must be first in the parameter list.