github/jooq
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[jOOQ/jOOQ#14953] Add Javadoc hints about implementation of JSONB::toString, JSONB::hashCode, and JSONB::equals

Browse Source
This commit is contained in:
Lukas Eder 2023-04-19 10:26:25 +02:00
parent b5a7847f03
commit c8aa64b4c5
2 changed files with 100 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
jOOQ/src/main/java/org/jooq/JSON.java
View File

@ -50,6 +50,23 @@ import org.jetbrains.annotations.Nullable;
* reference of type {@link JSON}, not as <code>data() == null</code>. This is
* consistent with jOOQ's general way of returning <code>NULL</code> from
* {@link Result} and {@link Record} methods.
* <p>
* Unlike the normalising {@link JSONB} data type, the {@link JSON} type uses a
* purely text based, formatting-preserving representation of the JSON content,
* meaning that e.g. the following two documents are <em>not</em> equal, due to
* their different object attribute order and formatting:
* <p>
* <ul>
* <li><code>{"a":1,"b":2}</code></li>
* <li><code>{"b": 2, "a": 1}</code></li>
* </ul>
* <p>
* This impacts the behaviour of
* <ul>
* <li>{@link #equals(Object)}</li>
* <li>{@link #hashCode()}</li>
* <li>{@link #toString()}</li>
* </ul>
*/
public final class JSON implements Serializable {
@ -92,11 +109,31 @@ public final class JSON implements Serializable {
return data == null ? null : json(data);
}
/**
* {@inheritDoc}
* <p>
* <h3>{@link JSON} specifics:</h3>
* <p>
* The {@link JSON} type uses a text-based, formatting-preserving
* representation of the JSON content, meaning that two equivalent JSON
* documents are considered not equal if their formatting or object
* attribute ordering differs (see {@link JSON} for details).
*/
@Override
public int hashCode() {
return data.hashCode();
}
/**
* {@inheritDoc}
* <p>
* <h3>{@link JSON} specifics:</h3>
* <p>
* The {@link JSON} type uses a text-based, formatting-preserving
* representation of the JSON content, meaning that two equivalent JSON
* documents are considered not equal if their formatting or object
* attribute ordering differs (see {@link JSON} for details).
*/
@Override
public boolean equals(Object obj) {
if (this == obj)
@ -107,6 +144,16 @@ public final class JSON implements Serializable {
}
/**
* {@inheritDoc}
* <p>
* <h3>{@link JSON} specifics:</h3>
* <p>
* The {@link JSON} type uses a text-based, formatting-preserving
* representation of the JSON content, meaning that two equivalent JSON
* documents are considered not equal if their formatting or object
* attribute ordering differs (see {@link JSON} for details).
*/
@Override
public String toString() {
return String.valueOf(data);

53
jOOQ/src/main/java/org/jooq/JSONB.java
View File

@ -55,6 +55,25 @@ import org.jetbrains.annotations.Nullable;
* reference of type {@link JSONB}, not as <code>data() == null</code>. This is
* consistent with jOOQ's general way of returning <code>NULL</code> from
* {@link Result} and {@link Record} methods.
* <p>
* Unlike the purely text based, formatting-preserving {@link JSON} data type,
* the {@link JSONB} type uses a normalised representation of the JSON content,
* meaning that e.g. the following two documents are equal, despite their
* different object attribute order and formatting:
* <p>
* <ul>
* <li><code>{"a":1,"b":2}</code></li>
* <li><code>{"b": 2, "a": 1}</code></li>
* </ul>
* <p>
* This impacts the behaviour (and performance!) of
* <ul>
* <li>{@link #equals(Object)}</li>
* <li>{@link #hashCode()}</li>
* <li>{@link #toString()}</li>
* </ul>
* <p>
* The {@link #data()} content, however, is not normalised.
*/
public final class JSONB implements Serializable {
@ -111,12 +130,36 @@ public final class JSONB implements Serializable {
return parsed;
}
// -------------------------------------------------------------------------
// The Object API
// -------------------------------------------------------------------------
/**
* {@inheritDoc}
* <p>
* <h3>{@link JSONB} specifics:</h3>
* <p>
* The {@link JSONB} type uses a normalised representation of the JSON
* content, meaning that two equivalent JSON documents are considered equal
* (see {@link JSONB} for details). This impacts both behaviour and
* performance!
*/
@Override
public int hashCode() {
Object p = parsed();
return p == null ? 0 : p.hashCode();
}
/**
* {@inheritDoc}
* <p>
* <h3>{@link JSONB} specifics:</h3>
* <p>
* The {@link JSONB} type uses a normalised representation of the JSON
* content, meaning that two equivalent JSON documents are considered equal
* (see {@link JSONB} for details). This impacts both behaviour and
* performance!
*/
@Override
public boolean equals(Object obj) {
if (this == obj)
@ -126,6 +169,16 @@ public final class JSONB implements Serializable {
return false;
}
/**
* {@inheritDoc}
* <p>
* <h3>{@link JSONB} specifics:</h3>
* <p>
* The {@link JSONB} type uses a normalised representation of the JSON
* content, meaning that two equivalent JSON documents are considered equal
* (see {@link JSONB} for details). This impacts both behaviour and
* performance!
*/
@Override
public String toString() {
return JSONValue.toJSONString(parsed());