Page History

Java defines the equality operators == and != for objects. Naive for testing reference equality but uses the equals() method defined in Object and its subclasses for testing abstract object equality. Naïve programmers often confuse the intent of the == operation with that of the Object.equals() method. This confusion is frequently seen evident in the context of processing String processing. 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. For classes that require overriding the default equals() implementation, care must be taken to also override the hashCode() method (see MET09-J. Classes that define an equals() method must also define a hashCode() method).

Numeric boxed types (for example, Further confusion arises because the numerical comparison operators <, <=, >, and >= can be used with the numeric boxed types Byte, Character, Short, Integer, Long, Float, and Double. In this case, auto-unboxing results in the numeric values contained in the boxed objects being compared, with the expected results (see JLS Section 5.6.2, "Binary Numeric Promotion"). When both arguments of a == or != operator are numeric boxed type, the equality operators are defined to be reference equality operators; the operation is thus a reference comparison rather than the anticipated numeric comparison, which may produce unexpected results.

Noncompliant Code Example

) should also be compared using Object.equals() rather than the == operator. While reference equality may appear to work for Integer values between the range −128 and 127, it may fail if either of the operands in the comparison are outside that range. Numeric relational operators other than equality (such as <, <=, >, and >=) can be safely used to compare boxed primitive types (see  EXP03-J. Do not use the equality operators when comparing values of boxed primitives for more information).

Noncompliant Code Example

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

public class BadComparisonStringComparison {
  public static void main(String[] args) {
    String onestr1 = new String("one");
    String twostr2 = new String("one");
    if(one == two)
      System.out.println("Equal"str1 == str2); //not printed Prints "false"
  }
}

The reference equality operator == evaluates to true only when the values it compares refer to the same underlying object. The references in this example are unequal because they refer to distinct objects.

Compliant Solution (Object.equals())

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

public class GoodComparisonStringComparison {
  public static void main(String[] args) {
    String onestr1 = new String("one");
    String twostr2 = new String("one");
    boolean result;
    if (one == null){
      result = two == null;
    }
    else{
      result = one == two || one.equals(two);
    }
   System.out.println(result);System.out.println(str1.equals( str2)); // Prints "true"
  }
}

Compliant Solution (String.intern())

Reference equality produces the desired result when comparing string literals (e.g. String one = "one"; and String two = "two";) or when the intern method has been used on both strings.When a task requires both keeping only one copy of each string in memory as well as performing quick repeated string comparisons, the following Compliant Solution may be usedequality behaves like abstract object equality when it is used to compare two strings that are results of the String.intern() method. This compliant solution uses String.intern() and can perform fast string comparisons when only one copy of the string one is required in memory.

public class GoodComparisonStringComparison {
  public static void main(String[] args) {
    String onestr1 = new String("one");
    String twostr2 = new String("one");
    boolean result;
    if (onestr1 != null){
      one = onestr1.intern();
    }
    if (two != null){
      two = twostr2 = str2.intern();
    }
    result = oneSystem.out.println(str1 == twostr2);

 //  System.out.println(result);Prints "true"
  }
}

Use this approach with care; performance and clarity may be better served by 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 a any dependence on reference equality.

General Rule

Assume that object comparisons require use of Object.equals() unless the defining classes specifically document their compliance with the exception below. See also guideline MET13-J. Ensure that hashCode() is overridden when equals() is overridden.

Exceptions

The Java Language Specification (JLS) [JLS 2013] provides very limited 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 JLS 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 JLS 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 rest 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 JLS; consequently, implementations may vary.

String interning may also be used in programs that accept repetitively occurring strings. Its use boosts the performance of comparisons and minimizes memory consumption.

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

Confusing reference equality and object equality can lead to unexpected results.

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

Objects that are instances of classes that provide this guarantee obey the invariant that, for any two references {{a}} and {{b}}, {{a.equals(b)}} is exactly equivalent to {{a == b}} \[[Bloch 2008|AA. Bibliography#Bloch 08]\]. The {{String}} class does not meet these requirements and consequently does not obey this invariant.

Another technique is to use an enum type.

EXP01-EX2: Use reference equality to determine whether two references point to the same object instance.

Risk Assessment

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

Automated Detection

The Coverity Prevent Version 5.0 BAD_EQ checker can detect the instance where The "==" operator is being used for equality of objects when in ideal case equal method should have been used. The "==" operator may consider objects different when the equals method considers them the same.

Findbugs checks this guideline for type String.

Related Vulnerabilities

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

Bibliography

\[[FindBugs 2008|AA. Bibliography#FindBugs 08]\] ES: Comparison of String objects using == or \!=
\[[JLS 2005|AA. Bibliography#JLS 05]\] [Section 3.10.5|http://java.sun.com/docs/books/jls/third_edition/html/lexical.html#3.10.5], "String Literals" and [Section 5.6.2|http://java.sun.com/docs/books/jls/third_edition/html/conversions.html#5.6.2], "Binary Numeric Promotion"
\[[MITRE 2009|AA. Bibliography#MITRE 09]\] [CWE ID 595|http://cwe.mitre.org/data/definitions/595.html] "Incorrect Syntactic Object Comparison", [CWE ID 597|http://cwe.mitre.org/data/definitions/597.html] "Use of Wrong Operator in String Comparison"

Automated Detection

Bibliography

...

Image Added Image Added Image AddedImage Removed      04. Expressions (EXP)      EXP02-J. Use the two-argument Arrays.equals() method to compare the contents of arrays