| Wiki Markup |
|---|
Composition or inheritance may be used to create a new class that both encapsulates an existing class and adds one or more fields. When one class extends another in this way, the concept of equality for the subclass may or may not involve its new fields. That is, when comparing two subclass objects for equality, sometimes their respective fields must also be equal, and other times they need not be equal. Depending on the concept of equality for the subclass, the subclass might override {{equals()}}. Furthermore, this method must follow the general contract for {{equals()}} as specified by the _Java Language Specification_ \[[JLS 2005|AA. Bibliography#JLSReferences#JLS 05]\]. |
An object is characterized both by its identity (location in memory) and by its state (actual data). The == operator compares only the identities of two objects (to check whether the references refer to the same object); the equals() method defined in java.lang.Object can be overridden to compare the state as well. When a class defines an equals() method, it implies that the method compares state. When the class lacks a customized equals() method (either locally declared or inherited from a parent class), it uses the default Object.equals() implementation inherited from Object. The default Object.equals() implementation compares only the references and may produce unexpected results.
...
| Wiki Markup |
|---|
Unfortunately, in this case it is impossible to extend an instantiable class (as opposed to an {{abstract}} class) by adding a value or field in the subclass while preserving the {{equals()}} contract. Use composition rather than inheritance to achieve the desired effect \[[Bloch 2008|AA. Bibliography#BlochReferences#Bloch 08]\]. This compliant solution adopts this approach by adding a private {{card}} field to the {{XCard}} class and providing a public {{viewCard()}} method. |
...
| Wiki Markup |
|---|
A uniform resource locator (URL) specifies both the location of a resource and also a method to access it. According to the Java API documentation for class {{URL}} \[[API 2006|AA. Bibliography#APIReferences#API 06]\]: |
Two URL objects are equal if they have the same protocol, reference equivalent hosts, have the same port number on the host, and the same file and fragment of the file.
Two hosts are considered equivalent if both host names can be resolved into the same IP addresses; else if either host name can't be resolved, the host names must be equal without regard to case; or both host names equal to null.
...
| Wiki Markup |
|---|
A Uniform Resource Identifier (URI) contains a string of characters used to identify a resource; this is a more general concept than an URL. The {{java.net.URI}} class provides string-based {{equals()}} and {{hashCode()}} methods that satisfy the general contracts for {{Object.equals()}} and {{Object.hashCode()}}; they do not invoke hostname resolution and are unaffected by network connectivity. {{URI}} also provides methods for normalization and canonicalization that {{URL}} lacks. Finally, the {{URL.toURI()}} and {{URI.toURL()}} methods provide easy conversion between the two classes. Programs should use URIs instead of URLs whenever possible. According to the Java API \[[API 2006|AA. Bibliography#APIReferences#API 06]\] {{URI}} class documentation: |
...
| Wiki Markup |
|---|
Additionally, the {{URI}} class performs normalization (removing extraneous path segments like '..') and relativization of paths \[[API 2006|AA. Bibliography#APIReferences#API 06]\] and \[[Darwin 2004|AA. Bibliography#DarwinReferences#Darwin 04]\]. |
Noncompliant Code Example (java.security.Key)
...
| Wiki Markup |
|---|
This compliant solution uses the {{equals()}} method as a first test and then compares the encoded version of the keys to facilitate provider-independent behavior. For example, this code can determine whether a {{RSAPrivateKey}} and {{RSAPrivateCrtKey}} represent equivalent private keys \[[Sun 2006|AA. Bibliography#SunReferences#Sun 06]\]. |
| Code Block | ||
|---|---|---|
| ||
private static boolean keysEqual(Key key1, Key key2) {
if (key1.equals(key2)) {
return true;
}
if (Arrays.equals(key1.getEncoded(), key2.getEncoded())) {
return true;
}
// More code for different types of keys here.
// For example, the following code can check if
// an RSAPrivateKey and an RSAPrivateCrtKey are equal:
if ((key1 instanceof RSAPrivateKey) &&
(key2 instanceof RSAPrivateKey)) {
if ((((RSAKey)key1).getModulus().equals(
((RSAKey)key2).getModulus())) &&
(((RSAPrivateKey) key1).getPrivateExponent().equals(
((RSAPrivateKey) key2).getPrivateExponent()))) {
return true;
}
}
return false;
}
|
...
| Wiki Markup |
|---|
*MET08-EX0:* Requirements of this rule may be violated provided that the incompatible types are never compared. There are classes in the Java platform libraries (and elsewhere) that extend an instantiable class by adding a value component. For example, {{java.sql.Timestamp}} extends {{java.util.Date}} and adds a nanoseconds field. The {{equals()}} implementation for {{Timestamp}} violates symmetry and can cause erratic behavior when {{Timestamp}} and {{Date}} objects are used in the same collection or are otherwise intermixed \[[Bloch 2008|AA. Bibliography#BlochReferences#Bloch 08]\]. |
Risk Assessment
Violating the general contract when overriding the equals() method can lead to unexpected results.
...
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="9b6588dcac5ca16d-475e564b-47ba4d76-be749f67-c20f52ab9ec55c317cf43d29"><ac:plain-text-body><![CDATA[ | [[API 2006 | AA. Bibliography#API References#API 06]] | [Method | http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#equals(java.lang.Object)] | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="77da5775289510d3-7389ec3b-4a024905-a64984e3-cc914dcf260d7cb47cc07649"><ac:plain-text-body><![CDATA[ | [[Bloch 2008 | AA. Bibliography#Bloch References#Bloch 08]] | Item 8. Obey the general contract when overriding equals | ]]></ac:plain-text-body></ac:structured-macro> | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c598c71656158ee2-1fb880af-4bef4775-b4b1b6df-6a56c36a53f207742568281e"><ac:plain-text-body><![CDATA[ | [[Darwin 2004 | AA. Bibliography#Darwin References#Darwin 04]] | 9.2, Overriding the | ]]></ac:plain-text-body></ac:structured-macro> | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="e8fb84372e2e65b7-7c8d6c59-45d9447d-a6668915-647e508bd715dcf42085379e"><ac:plain-text-body><![CDATA[ | [[Harold 1997 | AA. Bibliography#Harold References#Harold 97]] | Chapter 3, Classes, Strings, and Arrays, The Object Class (Equality) | ]]></ac:plain-text-body></ac:structured-macro> | |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5fa2da6de7dfa759-465ac4ff-4c844899-8aecb19d-000618d9eef9822e5a75ed16"><ac:plain-text-body><![CDATA[ | [[Sun 2006 | AA. Bibliography#Sun References#Sun 06]] | [Determining If Two Keys Are Equal | http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html#Determining%20If%20Two%20Keys%20Are%20Equal] (JCA Reference Guide) | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="2c7d456cb4e8bca4-bc8fbc0d-4a314f19-8f7fb8fa-1c0219971663df8de338f275"><ac:plain-text-body><![CDATA[ | [[Techtalk 2007 | AA. Bibliography#Techtalk References#Techtalk 07]] | More Joy of Sets | ]]></ac:plain-text-body></ac:structured-macro> |
...