EXP03-J. Do not use the equality operators when comparing values of boxed primitives

The values of boxed primitives cannot be directly compared using the == and != operators because they compare object references, not object values. Programmers could find this behavior surprising because autoboxing memoizes or caches, the values of some primitive variables. Consequently, reference comparisons and value comparisons produce identical results for the subset of values that are memoized.

Autoboxing automatically wraps a value of a primitive type with the corresponding wrapper object. The Section 5.1.7 "Boxing Conversion," of the Java Language Specification explains which primitive values are memoized during autoboxing:

If the value p being boxed is true, false, a byte, a char in the range \u0000 to \u007f, or an int or short number between -128 and 127, then let r1 and r2 be the results of any two boxing conversions of p. It is always the case that r1 == r2.

The == and != operators may be used to compare the values of fully memoized types.

The == and != operators may only be used for comparing the values of boxed primitives that are not fully memoized when the range of values represented is guaranteed to be within the ranges specified by the JLS to be fully memoized.

In general, avoid using these operators to compare the values of boxed primitives that are not fully memoized.

Implementations are allowed, but not required, to memoize additional values:

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

Code that depends on implementation-defined behavior is not portable.

Noncompliant Code Example

This noncompliant code example defines a Comparator with a compare() method [[Bloch 2009]]. The compare() method accepts two boxed primitives as arguments. The == operator is used to compare the two boxed primitives. In this context, however, it compares the references to the wrapper objects rather than comparing the values held in those objects.

static Comparator<Integer> cmp = new Comparator<Integer>() {
  public int compare(Integer i, Integer j) {
    return i < j ? -1 : (i == j ? 0 : 1);
  } 
};

Note that primitive integers are also accepted by this declaration because they are autoboxed at the call site.

Compliant Solution

This compliant solution uses the comparison operators, <, >, <=, or >=, because these cause automatic unboxing of the primitive values. The == and != operators should not be used to compare boxed primitives.

public int compare(Integer i, Integer j) {
  return i < j ? -1 : (i > j ? 1 : 0) ;
}

Noncompliant Code Example

This noncompliant code example uses the == operator to compare two Integer objects. According to the guideline EXP01-J. Do not confuse abstract object equality with reference equality, for the == operator to return true for two object references, they must point to the same underlying object.

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 caches integer values from -127 to 128 only, which can result in equivalent values outside this range not comparing equal. For example, a JVM that did not cache any other values when running this program would output:

true
false
false
true

Compliant Solution

This compliant solution uses the equals() method instead of the == operator to compare the values of the objects. The program now prints true, false, true and false on any platform, as expected.

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.equals(i2));
    System.out.println(!i1.equals(i2));
    System.out.println(i3.equals(i4));
    System.out.println(!i3.equals(i4));
  }
}

Noncompliant Code Example

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 contains 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 need memoize only those integer values in the range -127 to 128; it might return non-unique objects for all values outside that range. Consequently, when comparing autoboxed integer values outside that range, the == operator might return false, and the output of this example might be 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);
  }
}

If the particular JVM running this code memoized integer values from -32,768 to 32,767, all of the int values in the example would have been autoboxed to singleton 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 does not specify this interval; it only provides a minimum range. Consequently, successful prediction of this program's behavior would require implementation-specific details of the JVM.

Compliant Solution

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, 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 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);
 }
}

Noncompliant Code Example (new Boolean)

Constructors for class Boolean return distinct newly-instantiated objects. Using the reference equality operators in place of value comparisons will yield unexpected results.

Boolean b1 = new Boolean("true");
Boolean b2 = new Boolean("true");
b1 == b2;          // never equal

Compliant Solution (new Boolean)

The values of autoboxed Boolean variables 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.

Boolean b1 = true; // Or Boolean.True
Boolean b2 = true; // Or Boolean.True
b1 == b2;          // always equal

Exceptions

EXP03-EX1 In the unusual case where a program is guaranteed to execute only on a single implementation, it is permissible to depend upon implementation-specific ranges of memoized vulnerabilities.

Risk Assessment

Using the equivalence operators to compare values of boxed primitives can lead to erroneous comparisons.

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 Vulnerabilities

Search for vulnerabilities resulting from the violation of this guideline on the CERT website.

Bibliography

[[Bloch 2009]] 4. "Searching for the One"
[[JLS 2005]] Section 5.1.7, "Boxing Conversion"
[[Pugh 2009]] Using == to compare objects rather than .equals

EXP02-J. Use the two-argument Arrays.equals() method to compare the contents of arrays      02. Expressions (EXP)