EXP50-JG. Do not confuse abstract object equality with reference equality

Java defines the equality operators == and != for testing reference equality but uses the Object.equals() method and its subclasses for testing abstract object equality. Naive programmers often confuse the intent of the == operation with that of the Object.equals() method. This confusion is frequently evident in the context of processing String objects.

As a general rule, use the Object.equals() method to check whether two objects have equivalent contents and use the equality operators == and != to test whether two references specifically refer to the same object. This latter test is referred to as referential equality. Also see MET09-J. Classes that define an equals() method must also define a hashCode() method.

This use of the equality operators also applies to numeric boxed types (for example, Byte, Character, Short, Integer, Long, Float, and Double), although the numeric relational operators (such as <, <=, >, and >=) produce results that match those provided for arguments of the equivalent primitive numeric types. See  EXP03-J. Do not use the equality operators when comparing values of boxed primitives for more information.

Noncompliant Code Example

The reference equality operator == evaluates to true only when the values it compares refer to the same underlying object. This noncompliant example declares two distinct String objects that contain the same value. The references, however, are unequal because they refer to distinct objects.

public class StringComparison {
  public static void main(String[] args) {
    String str1 = new String("one");
    String str2 = new String("one");
    System.out.println(str1 == str2); // Prints "false"
  }

}

Compliant Solution (Object.equals())

This compliant solution uses the Object.equals() method when comparing string values:

public class StringComparison {
  public static void main(String[] args) {
    String str1 = new String("one");
    String str2 = new String("one");
    System.out.println(str1.equals( str2)); // Prints "true"
  }
}

Compliant Solution (String.intern())

Reference equality behaves like abstract object equality when it is used to compare two strings that are results of the String.intern() method. This solution can be used for fast string comparisons when only one copy of each string is required.

public class StringComparison {
  public static void main(String[] args) {
    String str1 = new String("one");
    String str2 = new String("one");

    str1 = str1.intern();
    str2 = str2.intern();

    System.out.println(str1 == str2); // Prints "true"
  }
}

Use of String.intern() should be reserved for cases in which the tokenization of strings either yields an important performance enhancement or dramatically simplifies code. Examples include programs engaged in natural language processing and compiler-like tools that tokenize program input. For most other programs, performance and readability are often improved by the use of code that applies the Object.equals() approach and that lacks any dependence on reference equality.

Performance issues can arise because the Java Language Specification provides few guarantees about the implementation of String.intern(). For example,

• The cost of String.intern() grows as the number of intern strings grows. Performance should be no worse than O(n log n), but the Java Language Specification lacks a specific performance guarantee.
• In early Java Virtual Machine (JVM) implementations, interned strings became immortal: they were exempt from garbage collection. This can be problematic when large numbers of strings are interned. More recent implementations can garbage-collect the storage occupied by interned strings that are no longer referenced. However, the Java Language Specification lacks any specification of this behavior.
• In JVM implementations prior to Java 1.7, interned strings are allocated in the permgen storage region, which is typically much smaller than the remainder of the heap. Consequently interning large numbers of strings can lead to an out-of-memory condition. In many Java 1.7 implementations, interned strings are allocated on the heap, relieving this restriction. Once again, the details of allocation are unspecified by the Java Language Specification; consequently, implementations may vary.

When canonicalization of objects is required, it may be wiser to use a custom canonicalizer built on top of ConcurrentHashMap; see Joshua Bloch's Effective Java, second edition, Item 69 [Bloch 2008], for details.

Applicability

Using reference equality to compare objects can lead to unexpected results.

Using reference equality in place of object equality is permitted only when the defining classes guarantee the existence of at most one object instance for each possible object value. This generally requires that instances of such classes must be immutable. The use of static factory methods, rather than public constructors, facilitates instance control; this is a key enabling technique.

Use reference equality to determine whether two references point to the same object.

Related Guidelines

Bibliography