Page History

...

Autoboxing automatically wraps a value of a primitive type with the corresponding wrapper object. The Java Language Specification (JLS), §5.1.7, "Boxing Conversion," [JLS 2005], explains which primitive values are memoized during autoboxing:

...

Use of the == and != operators for comparing the values of fully memoized boxed primitive types is permitted.

...

Use of the == and != operators for comparing the values of boxed primitive types is not allowed in all other cases.

Note that Java Virtual Machine (JVM) implementations are allowed, but not required, to memoize additional values [JLS 2005]:

Less memory-limited implementations could, for example, cache all characters and shorts, as well as integers and longs in the range of -32K −32K to +32K.

Code that depends on implementation-defined behavior is non-portablenonportable. It is permissible to depend on implementation-specific ranges of memoized values provided that all targeted implementations support these greater ranges.

...

public class Wrapper {
  public static void main(String[] args) {
    Integer i1 = 100;
    Integer i2 = 100;
    Integer i3 = 1000;
    Integer i4 = 1000;
    System.out.println(i1 == i2);
    System.out.println(i1 != i2);
    System.out.println(i3 == i4);
    System.out.println(i3 != i4);
  }
}

The Integer class is only guaranteed to cache only integer values from -128 to 127, which can result in equivalent values outside this range comparing as unequal when tested using the equality operators. For example, a Java Virtual Machine ( JVM ) that did not cache any other values when running this program would output

...

Java Collections contain only objects; they cannot contain primitive types. Further, the type parameters of all Java generics must be object types rather than primitive types. That is, attempting to declare an ArrayList<int> (which would, presumably, would contain values of type int) fails at compile time because type int is not an object type. The appropriate declaration would be ArrayList<Integer>, which makes use of the wrapper classes and autoboxing.

This noncompliant code example attempts to count the number of indices in arrays list1 and list2 that have equivalent values. Recall that class Integer is required to to memoize only those integer values in the range -128 −128 to 127; it might return a nonunique object for any value outside that range. Consequently, when comparing autoboxed integer values outside that range, the == operator might return false and the example could deceptively output 0.

public class Wrapper {
  public static void main(String[] args) {
    // Create an array list of integers, where each element 
    // is greater than 127
    ArrayList<Integer> list1 = new ArrayList<Integer>();
    for (int i = 0; i < 10; i++) {
      list1.add(i + 1000);
    }

    // Create another array list of integers, where each element
    // has the same value as the first list
    ArrayList<Integer> list2 = new ArrayList<Integer>();
    for (int i = 0; i < 10; i++) {
      list2.add(i + 1000);
    }

    // Count matching values.
    int counter = 0;
    for (int i = 0; i < 10; i++) {
      if (list1.get(i) == list2.get(i)) {  // uses '=='
        counter++;
      }
    }

    // Print the counter: 0 in this example
    System.out.println(counter);
  }

}

However, if the particular JVM running this code memoized integer values from -32−32,768 to 32,767, all of the int values in the example would have been autoboxed to the corresponding Integer objects, and the example code would have operated as expected. Using reference equality instead of object equality requires that all values encountered fall within the interval of values memoized by the JVM. The JLS lacks a specification of this interval; rather, it specifies a minimum range that must be memoized. Consequently, successful prediction of this program's behavior would require implementation-specific details of the JVM.

...

This compliant solution uses the equals() method to perform value comparisons of wrapped objects. It produces the correct output, 10.

public class Wrapper {
  public static void main(String[] args) {
    // Create an array list of integers
    ArrayList<Integer> list1 = new ArrayList<Integer>();

    for (int i = 0; i < 10; i++) {
      list1.add(i + 1000);
    }

    // Create another array list of integers, where each element
    // has the same value as the first one
    ArrayList<Integer> list2 = new ArrayList<Integer>();
    for (int i = 0; i < 10; i++) {
      list2.add(i + 1000);
    }
 
    // Count matching values
    int counter = 0;
    for (int i = 0; i < 10; i++) {
      if (list1.get(i).equals(list2.get(i))) {  // uses 'equals()'
        counter++;
      }
    }
 
    // Print the counter: 10 in this example
    System.out.println(counter);
  }
}

...

In this noncompliant code example, constructors for class Boolean return distinct newly - instantiated objects. Using the reference equality operators in place of value comparisons will yield unexpected results.

public void exampleEqualOperator(){
  Boolean b1 = new Boolean("true");
  Boolean b2 = new Boolean("true");

  if (b1 == b2) {    // neverNever equal
    System.out.println("Never printed");
  }
}

...

Boolean.TRUE, Boolean.FALSE, or the values of autoboxed true and false literals, may be compared using the reference equality operators because the Java language guarantees that the Boolean type is fully memoized. Consequently, these objects are guaranteed to be singletons.

public void exampleEqualOperator(){
  Boolean b1 = true;
  Boolean b2 = true; 
	
  if (b1 == b2) {   // alwaysAlways equal
    System.out.println("Always printed");
  }
 
  b1 = Boolean.TRUE;
  if (b1 == b2) {   // alwaysAlways equal
    System.out.println("Always printed");
  }
}

...

Automated Detection

Detection of all uses of the reference equality operators on boxed primitive objects is straightforward. Determining the correctness of such uses is infeasible in the general case.

Related Guidelines

Bibliography

[Bloch 2009]	Puzzle 4, "Searching for the One"
[JLS 2005]	§5.1.7, Boxing Conversion
[Pugh 2009]	Using == to Compare Objects Rather than .equals
[Seacord 2015]	EXP03-J. Do not use the equality operators when comparing values of boxed primitives LiveLesson

...