Method and constructor overloading allows declaration of methods or constructors with the same name but with different parameter lists. The compiler inspects each call to an overloaded method or constructor and uses the declared types of the method parameters to decide which method to invoke. In some cases, however, confusion may arise because of the presence of relatively new language features such as autoboxing and generics.
Furthermore, methods or constructors with the same parameter types that differ only in their declaration order are typically not flagged by Java compilers. Errors can result when a developer fails to consult the documentation at each use of a method or constructor. A related pitfall is to associate different semantics with each of the overloaded methods or constructors. Defining different semantics sometimes necessitates different orderings of the same method parameters, creating a vicious circle. Consider, for example, an overloaded
getDistance() method in which one overloaded method returns the distance traveled from the source while another (with reordered parameters) returns the remaining distance to the destination. Implementers may fail to realize the difference unless they consult the documentation at each use.
Noncompliant Code Example (Constructor)
Constructors cannot be overridden and can only be overloaded. This noncompliant code example shows the class
Con with three overloaded constructors:
Failure to exercise caution while passing arguments to these constructors can create confusion because calls to these constructors contain the same number of similarly typed actual parameters. Overloading must also be avoided when the overloaded constructors or methods provide distinct semantics for formal parameters of the same types, differing solely in their declaration order.
Compliant Solution (Constructor)
This compliant solution avoids overloading by declaring public static factory methods having distinct names in place of the public class constructors:
Noncompliant Code Example (Method)
In this noncompliant code example, the
OverLoader class holds a
HashMap instance and has overloaded
getData() methods. One
getData() method chooses the record to return on the basis of its key value in the map; the other chooses on the basis of the actual mapped value.
For purposes of overload resolution, the signatures of the
getData() methods differ only in the static type of their formal parameters. The
OverLoader class inherits from
java.util.HashMap and overrides its
get() method to provide the checking functionality. This implementation can be extremely confusing to the client who expects both
getData() methods to behave in a similar fashion and not depend on whether an index of the record or the value to be retrieved is specified.
Although the client programmer might eventually deduce such behavior, other cases, such as with the
List interface, may go unnoticed, as Joshua Bloch [Bloch 2008] describes:
List<E>interface has two overloadings of the remove method:
remove(int). Prior to release 1.5 when it was "generified," the
Listinterface had a
remove(Object)method in place of
remove(E), and the corresponding parameter types,
int, were radically different. But in the presence of generics and autoboxing, the two parameter types are no longer radically different.
Consequently, a client programmer may fail to realize that the wrong element has been removed from the list.
A further problem is that in the presence of autoboxing, adding a new overloaded method definition can break previously working client code. This can happen when a new overloaded method with a more specific type is added to an API whose methods used less specific types in earlier versions. For example, if an earlier version of the
OverLoader class provided only the
getData(Integer) method, the client could correctly invoke this method by passing a parameter of type
int; the result would be selected on the basis of its value because the
int parameter would be autoboxed to
Integer. Subsequently, when the
getData(int) method is added, the compiler resolves all calls whose parameter is of type
int to invoke the new
getData(int) method, thereby changing their semantics and potentially breaking previously correct code. The compiler is entirely correct in such cases; the actual problem is an incompatible change to the API.
Compliant Solution (Method)
Naming the two related methods differently eliminates both the overloading and the confusion.
Ambiguous or confusing uses of overloading can lead to unexpected results.