Page History

In the absence of autoboxing, the The values of boxed primitives cannot be directly compared using the == and != operators by default. This is because these are interpreted as reference comparison operators. This condition is demonstrated in the first noncompliant code example.operators compare object references rather than object values. Programmers can 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 Java Language Specification (JLS), §5.1.7, "Boxing Conversion" [JLS 2015], explains which primitive values are memoized during autoboxing Wiki MarkupAutoboxing on the other hand, can also produce subtle effects. It works by automatically wrapping the primitive type to the corresponding wrapper object. Some care should be taken during this process, especially when performing comparisons. The Java Language Specification \[[JLS 05|AA. Java References#JLS 05]\] explains this point clearly:

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.

Noncompliant Code Example

This noncompliant example (adopted from \[[Bloch 09|AA. Java References#Bloch 09]\]), defines a {{Comparator}} with a {{compare()}} method. The {{compare()}} method accepts two boxed primitives as arguments. Note that primitive integers are also accepted by this declaration as they are appropriately autoboxed. The main issue is that the {{==}} operator is being used to compare the two boxed primitives. This however, compares their references and not the actual values. 

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 that are not fully memoized is permitted only when the range of values represented is guaranteed to be within the ranges specified by the JLS to be fully memoized.

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 2015]:

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

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

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.

import java.util.Comparator;
 

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

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

import java.util.Comparator;
 
static Comparator<Integer> cmp = new Comparator<Integer>() { 
  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 in an attempt to compare two the values of pairs of Integer objects. According to EXP03-J. Do not compare String objects using equality or relational operators, for == to return true for two object references, they must point to the same underlying object. Results of using the == operator in this case will be misleadingHowever, the == operator compares object references rather than object values.

public class TestWrapper2Wrapper {
  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);
 
 }
}

These comparisons generate the output sequence: true, false, false and true. The cache in the Integer class can only make the integers is guaranteed to cache only integer values from -127 to 128 refer to the same object, which explains the output of the above code. To avoid making such mistakes, use equals instead of == to compare wrapper classes (See EXP03-J for further details).

Compliant Solution

127, which can result in equivalent values outside this range comparing as unequal when tested using the equality operators. 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, false on all platformsUsing object1.equals(object2) only compares their values. Now, the results will be true, as expected.

public class TestWrapper2Wrapper {
  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

Sometimes a list of integers is desired. Recall that the type parameter inside the angle brackets of a list cannot be of a primitive type. It is not possible to form an ArrayList<int>. With the help of the wrapper classs and autoboxing, storing primitive integer values in ArrayList<Integer> becomes possible.

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, 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 memoize only those integer values in the range −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 In this noncompliant code example, it is desired to count the integers of arrays list1 and list2. As class Integer only caches integers from -127 to 128, when an int value is beyond this range, it is autoboxed into the corresponding wrapper type. The == operator returns false when these distinct wrapper objects are compared. As a result, the output of this example is 0.

import java.util.ArrayList;
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 < 10; i++) {
      list1.add(i + 1000);
    }

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

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

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

}

If it were possible to expand the Integer cache (for example, caching all the values -32K – 32K, which means that all However, 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 be have been autoboxed to cached the corresponding Integer objects), then the results may have differedand 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.

Compliant Solution

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

public class TestWrapper1Wrapper {
  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 < 10; i++) {
      list1.add(i + 1000);
    }

    // Create another array list of integers, where each element
    // ishas the same value as the first one
    ArrayList<Integer> list2 = new ArrayList<Integer>();
    for (int i = 0;i<10; i < 10; i++) {
      list2.add(i + 1000);
    }
 
    // Count matching values
    int counter = 0;
    for (int i = 0;i<10; 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);
  }
}

Risk Assessment

Noncompliant Code Example (Boolean)

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) {    // Never equal
    System.out.println("Never printed");
  }
}

Compliant Solution (Boolean)

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) {   // Always equal
    System.out.println("Always printed");
  }
 
  b1 = Boolean.TRUE;
  if (b1 == b2) {   // Always equal
    System.out.println("Always printed");
  }
}

Risk Assessment

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

Automated Detection

Detection

...

TODO

Related Vulnerabilities

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

References

\[[Bloch 09|AA. Java References#Bloch 09]\] 4. "Searching for the One"
\[[Pugh 09|AA. Java References#Pugh 09]\] Using == to compare objects rather than .equals

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 2015]	§5.1.7, "Boxing Conversion"
[Pugh 2009]	Using == to Compare Objects Rather than .equals
[Seacord 2015]	Image Added EXP03-J. Do not use the equality operators when comparing values of boxed primitives LiveLesson

...

Image Added Image Added Image AddedEXP31-J. Avoid side effects in assertions      04. Expressions (EXP)      04. Scope (SCP)