rspec/rules/S1698/java/rule.adoc

== Why is this an issue?

It is equivalent to use the equality ``++==++`` operator and the ``++equals++`` method to compare two objects if the ``++equals++`` method inherited from ``++Object++`` has not been overridden. In this case both checks compare the object references.


But as soon as ``++equals++`` is overridden, two objects not having the same reference but having the same value can be equal. This rule spots suspicious uses of ``++==++`` and ``++!=++`` operators on objects whose ``++equals++`` methods are overridden.

=== Noncompliant code example

[source,java]
----
String firstName = getFirstName(); // String overrides equals 
String lastName = getLastName();

if (firstName == lastName) { ... }; // Non-compliant; false even if the strings have the same value
----

=== Compliant solution

[source,java]
----
String firstName = getFirstName();
String lastName = getLastName();

if (firstName != null && firstName.equals(lastName)) { ... };
----

=== Exceptions

Comparing two instances of the ``++Class++`` object will not raise an issue:

[source,java]
----
Class c;
if(c == Integer.class) { // No issue raised
}
----

Comparing ``++Enum++`` will not raise an issue:

[source,java]
----
public enum Fruit {
   APPLE, BANANA, GRAPE
}
public boolean isFruitGrape(Fruit candidateFruit) {
  return candidateFruit == Fruit.GRAPE; // it's recommended to activate S4551 to enforce comparison of Enums using ==
}
----

Comparing with ``++final++`` reference will not raise an issue:

[source,java]
----
private static final Type DEFAULT = new Type();

void foo(Type other) {
  if (other == DEFAULT) { // Compliant
  //...
  }
}
----

Comparing with ``++this++`` will not raise an issue:


[source,java]
----
  public boolean equals(Object other) {
    if (this == other) {  // Compliant
      return false;
    }
 }
----

Comparing with ``++java.lang.String++`` and boxed types ``++java.lang.Integer++``, ... will not raise an issue. 

== Resources

* S4973 - Strings and Boxed types should be compared using "equals()"
* CWE - https://cwe.mitre.org/data/definitions/595[CWE-595 - Comparison of Object References Instead of Object Contents]
* CWE - https://cwe.mitre.org/data/definitions/597[CWE-597 - Use of Wrong Operator in String Comparison]
* https://wiki.sei.cmu.edu/confluence/x/UjdGBQ[CERT, EXP03-J.] - Do not use the equality operators when comparing values of boxed primitives
* https://wiki.sei.cmu.edu/confluence/x/yDdGBQ[CERT, EXP50-J.] - Do not confuse abstract object equality with reference equality

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

include::../message.adoc[]

'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]