Skip to content

Commit

Permalink
Re-ordering of JsonNode methods to prep for #4958
Browse files Browse the repository at this point in the history
  • Loading branch information
@cowtowncoder
cowtowncoder committed Feb 13, 2025
1 parent 7c2c6a0 commit 4e9c268
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 145 deletions.
303 changes: 159 additions & 144 deletions src/main/java/tools/jackson/databind/JsonNode.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -522,10 +522,26 @@ public boolean canConvertToExactIntegral() {

/*
/**********************************************************************
/* Public API, straight value access
/* Public API, scalar value access (exact, converting)
/**********************************************************************
*/

// // Scalar access: generic

/**
* Method that will return a {@link JsonNode} wrapped in Java's {@link Optional}.
* All nodes except of {@link MissingNode} will return non-empty {@link Optional};
* {@link MissingNode} will return empty {@link Optional}.
*
* @return {@code Optional<JsonNode>} containing this node, or {@link Optional#empty()}
* if this is a {@link MissingNode}.
*/
public Optional<JsonNode> asOptional() {
return Optional.of(this);
}

// // Scalar access: Strings

/**
* Method to use for accessing String values.
* Does <b>NOT</b> do any conversions for non-String value nodes;
Expand All @@ -540,6 +556,49 @@ public boolean canConvertToExactIntegral() {
*/
public String stringValue() { return null; }

/**
* Method that will return a valid String representation of
* the contained value, if the node is a value node
* (method {@link #isValueNode} returns true),
* otherwise empty String.
*<p>
* NOTE: this is NOT same as {@link #toString()} in that result is
* <p>NOT VALID ENCODED JSON</p> for all nodes (but is for some, like
* {@code NumberNode}s and {@code BooleanNode}s).
*/
public abstract String asString();

/**
* Returns the text value of this node or the provided {@code defaultValue} if this node
* does not have a text value. Useful for nodes that are {@link MissingNode} or
* {@link tools.jackson.databind.node.NullNode}, ensuring a default value is returned instead of null or missing indicators.
*
* @param defaultValue The default value to return if this node's text value is absent.
* @return The text value of this node, or {@code defaultValue} if the text value is absent.
*/
public String asString(String defaultValue) {
String str = asString();
return (str == null) ? defaultValue : str;
}

/**
* @deprecated Use {@link #asString()} instead.
*/
@Deprecated // since 3.0
public final String asText() {
return asString();
}

/**
* @deprecated Use {@link #asString(String)} instead.
*/
@Deprecated // since 3.0
public String asText(String defaultValue) {
return asString(defaultValue);
}

// // Scalar access: Binary

/**
* Method to use for accessing binary content of binary nodes (nodes
* for which {@link #isBinary} returns true); or for String Nodes
Expand All @@ -554,6 +613,8 @@ public byte[] binaryValue() {
return null;
}

// // Scalar access: Boolean

/**
* Method to use for accessing JSON boolean values (value
* literals 'true' and 'false').
Expand All @@ -564,6 +625,36 @@ public byte[] binaryValue() {
*/
public boolean booleanValue() { return false; }

/**
* Method that will try to convert value of this node to a Java <b>boolean</b>.
* JSON booleans map naturally; integer numbers other than 0 map to true, and
* 0 maps to false
* and Strings 'true' and 'false' map to corresponding values.
*<p>
* If representation cannot be converted to a boolean value (including structured types
* like Objects and Arrays),
* default value of <b>false</b> will be returned; no exceptions are thrown.
*/
public boolean asBoolean() {
return asBoolean(false);
}

/**
* Method that will try to convert value of this node to a Java <b>boolean</b>.
* JSON booleans map naturally; integer numbers other than 0 map to true, and
* 0 maps to false
* and Strings 'true' and 'false' map to corresponding values.
*<p>
* If representation cannot be converted to a boolean value (including structured types
* like Objects and Arrays),
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
*/
public boolean asBoolean(boolean defaultValue) {
return defaultValue;
}

// // Scalar access: Numbers, generic

/**
* Returns numeric value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true); otherwise
Expand All @@ -574,6 +665,8 @@ public byte[] binaryValue() {
*/
public Number numberValue() { return null; }

// // Scalar access: Numbers, Java short

/**
* Returns 16-bit short value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
Expand All @@ -586,6 +679,8 @@ public byte[] binaryValue() {
*/
public short shortValue() { return 0; }

// // Scalar access: Numbers, Java int

/**
* Returns integer value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
Expand All @@ -598,108 +693,6 @@ public byte[] binaryValue() {
*/
public int intValue() { return 0; }

/**
* Returns 64-bit long value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns 0.
* For floating-point numbers, value is truncated using default
* Java coercion, similar to how cast from double to long operates.
*
* @return Long value this node contains, if any; 0 for non-number
* nodes.
*/
public long longValue() { return 0L; }

/**
* Returns 32-bit floating value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns 0.0.
* For integer values, conversion is done using coercion; this means
* that an overflow is possible for `long` values
*
* @return 32-bit float value this node contains, if any; 0.0 for non-number nodes.
*/
public float floatValue() { return 0.0f; }

/**
* Returns 64-bit floating point (double) value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns 0.0.
* For integer values, conversion is done using coercion; this may result
* in overflows with {@link BigInteger} values.
*
* @return 64-bit double value this node contains, if any; 0.0 for non-number nodes.
*/
public double doubleValue() { return 0.0; }

/**
* Returns floating point value for this node (as {@link BigDecimal}), <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns <code>BigDecimal.ZERO</code>.
*
* @return {@link BigDecimal} value this node contains, if numeric node; <code>BigDecimal.ZERO</code> for non-number nodes.
*/
public BigDecimal decimalValue() { return BigDecimal.ZERO; }

/**
* Returns integer value for this node (as {@link BigInteger}), <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns <code>BigInteger.ZERO</code>.
*<p>
* May also throw {@link tools.jackson.core.exc.StreamConstraintsException}
* if the scale of the underlying {@link BigDecimal} is too large to convert.
*
* @return {@link BigInteger} value this node contains, if numeric node; <code>BigInteger.ZERO</code> for non-number nodes.
*/
public BigInteger bigIntegerValue() { return BigInteger.ZERO; }

/*
/**********************************************************************
/* Public API, value access with conversion(s)/coercion(s)
/**********************************************************************
*/

/**
* Method that will return a valid String representation of
* the contained value, if the node is a value node
* (method {@link #isValueNode} returns true),
* otherwise empty String.
*<p>
* NOTE: this is NOT same as {@link #toString()} in that result is
* <p>NOT VALID ENCODED JSON</p> for all nodes (but is for some, like
* {@code NumberNode}s and {@code BooleanNode}s).
*/
public abstract String asString();

/**
* Returns the text value of this node or the provided {@code defaultValue} if this node
* does not have a text value. Useful for nodes that are {@link MissingNode} or
* {@link tools.jackson.databind.node.NullNode}, ensuring a default value is returned instead of null or missing indicators.
*
* @param defaultValue The default value to return if this node's text value is absent.
* @return The text value of this node, or {@code defaultValue} if the text value is absent.
*/
public String asString(String defaultValue) {
String str = asString();
return (str == null) ? defaultValue : str;
}

/**
* @deprecated Use {@link #asString()} instead.
*/
@Deprecated // since 3.0
public final String asText() {
return asString();
}

/**
* @deprecated Use {@link #asString(String)} instead.
*/
@Deprecated // since 3.0
public String asText(String defaultValue) {
return asString(defaultValue);
}

/**
* Method that will try to convert value of this node to a Java <b>int</b>.
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
Expand Down Expand Up @@ -728,6 +721,20 @@ public int asInt(int defaultValue) {
return defaultValue;
}

// // Scalar access: Numbers, Java long

/**
* Returns 64-bit long value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns 0.
* For floating-point numbers, value is truncated using default
* Java coercion, similar to how cast from double to long operates.
*
* @return Long value this node contains, if any; 0 for non-number
* nodes.
*/
public long longValue() { return 0L; }

/**
* Method that will try to convert value of this node to a Java <b>long</b>.
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
Expand Down Expand Up @@ -756,6 +763,46 @@ public long asLong(long defaultValue) {
return defaultValue;
}

// // Scalar access: Numbers, Java BigInteger

/**
* Returns integer value for this node (as {@link BigInteger}), <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns <code>BigInteger.ZERO</code>.
*<p>
* May also throw {@link tools.jackson.core.exc.StreamConstraintsException}
* if the scale of the underlying {@link BigDecimal} is too large to convert.
*
* @return {@link BigInteger} value this node contains, if numeric node; <code>BigInteger.ZERO</code> for non-number nodes.
*/
public BigInteger bigIntegerValue() { return BigInteger.ZERO; }

// // Scalar access: Numbers, Java float

/**
* Returns 32-bit floating value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns 0.0.
* For integer values, conversion is done using coercion; this means
* that an overflow is possible for `long` values
*
* @return 32-bit float value this node contains, if any; 0.0 for non-number nodes.
*/
public float floatValue() { return 0.0f; }

// // Scalar access: Numbers, Java double

/**
* Returns 64-bit floating point (double) value for this node, <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns 0.0.
* For integer values, conversion is done using coercion; this may result
* in overflows with {@link BigInteger} values.
*
* @return 64-bit double value this node contains, if any; 0.0 for non-number nodes.
*/
public double doubleValue() { return 0.0; }

/**
* Method that will try to convert value of this node to a Java <b>double</b>.
* Numbers are coerced using default Java rules; booleans convert to 0.0 (false)
Expand Down Expand Up @@ -784,48 +831,20 @@ public double asDouble(double defaultValue) {
return defaultValue;
}

/**
* Method that will try to convert value of this node to a Java <b>boolean</b>.
* JSON booleans map naturally; integer numbers other than 0 map to true, and
* 0 maps to false
* and Strings 'true' and 'false' map to corresponding values.
*<p>
* If representation cannot be converted to a boolean value (including structured types
* like Objects and Arrays),
* default value of <b>false</b> will be returned; no exceptions are thrown.
*/
public boolean asBoolean() {
return asBoolean(false);
}

/**
* Method that will try to convert value of this node to a Java <b>boolean</b>.
* JSON booleans map naturally; integer numbers other than 0 map to true, and
* 0 maps to false
* and Strings 'true' and 'false' map to corresponding values.
*<p>
* If representation cannot be converted to a boolean value (including structured types
* like Objects and Arrays),
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
*/
public boolean asBoolean(boolean defaultValue) {
return defaultValue;
}
// // Scalar access: Numbers, Java BigDecimal

/**
* Method that will return a {@link JsonNode} wrapped in Java's {@link Optional}.
* Returns floating point value for this node (as {@link BigDecimal}), <b>if and only if</b>
* this node is numeric ({@link #isNumber} returns true). For other
* types returns <code>BigDecimal.ZERO</code>.
*
* @return `Optional<JsonNode>` containing this node, or {@link Optional#empty()}
* if this is a {@link MissingNode}.
* @since 2.19
* @return {@link BigDecimal} value this node contains, if numeric node; <code>BigDecimal.ZERO</code> for non-number nodes.
*/
public Optional<JsonNode> asOptional() {
return Optional.of(this);
}
public BigDecimal decimalValue() { return BigDecimal.ZERO; }

/*
/**********************************************************************
/* Public API, extended traversal (2.10) with "required()"
/* Public API, extended traversal with "required()"
/**********************************************************************
*/

Expand Down Expand Up @@ -876,9 +895,7 @@ public <T extends JsonNode> T requireNonNull() {
* @throws IllegalArgumentException if this node is not an Object node or if it does not
* have value for specified property
*/
public JsonNode required(String propertyName) {
return _reportRequiredViolation("Node of type `%s` has no fields", getClass().getName());
}
public abstract JsonNode required(String propertyName);

/**
* Method is functionally equivalent to
Expand All @@ -898,9 +915,7 @@ public JsonNode required(String propertyName) {
* @throws IllegalArgumentException if this node is not an Array node or if it does not
* have value for specified index
*/
public JsonNode required(int index) {
return _reportRequiredViolation("Node of type `%s` has no indexed values", getClass().getName());
}
public abstract JsonNode required(int index);

/**
* Method is functionally equivalent to
Expand Down
Loading

0 comments on commit 4e9c268

Please sign in to comment.