3.11 Variable Arity Methods
A fixed arity method must be called with the same number of actual parameters (also called arguments) as the number of formal parameters specified in its declaration. If the method declaration specifies two formal parameters, every call of this method must specify exactly two arguments. We say that the arity of this method is 2. In other words, the arity of such a method is fixed, and it is equal to the number of formal parameters specified in the method declaration.
Java also allows declaration of variable arity methods (also called varargs methods), meaning that the number of arguments in its call can be varied. As we shall see, invocations of such a method may contain more actual parameters than formal parameters. Variable arity methods are heavily employed in formatting text representation of values, as demonstrated by the variable arity method System.out.printf() that is used in many examples for this purpose.
The last formal parameter in a variable arity method declaration is declared as follows:
type
…
formal_parameter_name
The ellipsis (…) is specified between the type and the formal_parameter_name. The type can be a primitive type, a reference type, or a type parameter. Whitespace can be specified on both sides of the ellipsis. Such a parameter is usually called a variable arity parameter (also known as a varargs parameter).
Apart from the variable arity parameter, a variable arity method is identical to a fixed arity method. The method publish() below is a variable arity method:
public static void publish(int n, String… data) { // (int, String[])
System.out.println(“n: ” + n + “, data size: ” + data.length);
}
The variable arity parameter in a variable arity method is always interpreted as having an array type:
type
[]
In the body of the publish() method, the variable arity parameter data has the type String[], so it is a simple array of Strings.
Only one variable arity parameter is permitted in the formal parameter list, and it is always the last parameter in the list. Given that the method declaration has n formal parameters and the method call has k actual parameters, k must be equal to or greater than n – 1. The last k – n + 1 actual parameters are evaluated and stored in an array whose reference value is passed as the value of the actual parameter. In the case of the publish() method, n is equal to 2, so k can be 1, 2, 3, and so on. The following invocations of the publish() method show which arguments are passed in each method call:
publish(1); // (1, new String[] {})
publish(2, “two”); // (2, new String[] {“two”})
publish(3, “two”, “three”); // (3, new String[] {“two”, “three”})
Each method call results in an implicit array being created and passed as an argument. This array can contain zero or more argument values that do not correspond to the formal parameters preceding the variable arity parameter. This array is referenced by the variable arity parameter data in the method declaration. The preceding calls would result in the publish() method printing the following output:
n: 1, data size: 0
n: 2, data size: 1
n: 3, data size: 2
To overload a variable arity method, it is not enough to change the type of the variable arity parameter to an explicit array type. The compiler will complain if an attempt is made to overload the method transmit(), as shown in the following code:
public static void transmit(String… data) { } // Compile-time error!
public static void transmit(String[] data) { } // Compile-time error!
Both methods above have the signature transmit(String[]). These declarations would result in two methods with equivalent signatures in the same class, which is not permitted.
Overloading and overriding of methods with variable arity are discussed in §5.10, p. 265.