Skip to content

Commit 4e9c268

Browse files
cowtowncodercowtowncoder
committed
Re-ordering of JsonNode methods to prep for #4958 
1 parent 7c2c6a0 commit 4e9c268

File tree

2 files changed

+166
-145
lines changed

2 files changed

+166
-145
lines changed

‎src/main/java/tools/jackson/databind/JsonNode.java

+159-144
Original file line numberDiff line numberDiff line change
@@ -522,10 +522,26 @@ public boolean canConvertToExactIntegral() {
522522

523523
/*
524524
/**********************************************************************
525-
/* Public API, straight value access
525+
/* Public API, scalar value access (exact, converting)
526526
/**********************************************************************
527527
*/
528528

529+
// // Scalar access: generic
530+
531+
/**
532+
* Method that will return a {@link JsonNode} wrapped in Java's {@link Optional}.
533+
* All nodes except of {@link MissingNode} will return non-empty {@link Optional};
534+
* {@link MissingNode} will return empty {@link Optional}.
535+
*
536+
* @return {@code Optional<JsonNode>} containing this node, or {@link Optional#empty()}
537+
* if this is a {@link MissingNode}.
538+
*/
539+
public Optional<JsonNode> asOptional() {
540+
return Optional.of(this);
541+
}
542+
543+
// // Scalar access: Strings
544+
529545
/**
530546
* Method to use for accessing String values.
531547
* Does <b>NOT</b> do any conversions for non-String value nodes;
@@ -540,6 +556,49 @@ public boolean canConvertToExactIntegral() {
540556
*/
541557
public String stringValue() { return null; }
542558

559+
/**
560+
* Method that will return a valid String representation of
561+
* the contained value, if the node is a value node
562+
* (method {@link #isValueNode} returns true),
563+
* otherwise empty String.
564+
*<p>
565+
* NOTE: this is NOT same as {@link #toString()} in that result is
566+
* <p>NOT VALID ENCODED JSON</p> for all nodes (but is for some, like
567+
* {@code NumberNode}s and {@code BooleanNode}s).
568+
*/
569+
public abstract String asString();
570+
571+
/**
572+
* Returns the text value of this node or the provided {@code defaultValue} if this node
573+
* does not have a text value. Useful for nodes that are {@link MissingNode} or
574+
* {@link tools.jackson.databind.node.NullNode}, ensuring a default value is returned instead of null or missing indicators.
575+
*
576+
* @param defaultValue The default value to return if this node's text value is absent.
577+
* @return The text value of this node, or {@code defaultValue} if the text value is absent.
578+
*/
579+
public String asString(String defaultValue) {
580+
String str = asString();
581+
return (str == null) ? defaultValue : str;
582+
}
583+
584+
/**
585+
* @deprecated Use {@link #asString()} instead.
586+
*/
587+
@Deprecated // since 3.0
588+
public final String asText() {
589+
return asString();
590+
}
591+
592+
/**
593+
* @deprecated Use {@link #asString(String)} instead.
594+
*/
595+
@Deprecated // since 3.0
596+
public String asText(String defaultValue) {
597+
return asString(defaultValue);
598+
}
599+
600+
// // Scalar access: Binary
601+
543602
/**
544603
* Method to use for accessing binary content of binary nodes (nodes
545604
* for which {@link #isBinary} returns true); or for String Nodes
@@ -554,6 +613,8 @@ public byte[] binaryValue() {
554613
return null;
555614
}
556615

616+
// // Scalar access: Boolean
617+
557618
/**
558619
* Method to use for accessing JSON boolean values (value
559620
* literals 'true' and 'false').
@@ -564,6 +625,36 @@ public byte[] binaryValue() {
564625
*/
565626
public boolean booleanValue() { return false; }
566627

628+
/**
629+
* Method that will try to convert value of this node to a Java <b>boolean</b>.
630+
* JSON booleans map naturally; integer numbers other than 0 map to true, and
631+
* 0 maps to false
632+
* and Strings 'true' and 'false' map to corresponding values.
633+
*<p>
634+
* If representation cannot be converted to a boolean value (including structured types
635+
* like Objects and Arrays),
636+
* default value of <b>false</b> will be returned; no exceptions are thrown.
637+
*/
638+
public boolean asBoolean() {
639+
return asBoolean(false);
640+
}
641+
642+
/**
643+
* Method that will try to convert value of this node to a Java <b>boolean</b>.
644+
* JSON booleans map naturally; integer numbers other than 0 map to true, and
645+
* 0 maps to false
646+
* and Strings 'true' and 'false' map to corresponding values.
647+
*<p>
648+
* If representation cannot be converted to a boolean value (including structured types
649+
* like Objects and Arrays),
650+
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
651+
*/
652+
public boolean asBoolean(boolean defaultValue) {
653+
return defaultValue;
654+
}
655+
656+
// // Scalar access: Numbers, generic
657+
567658
/**
568659
* Returns numeric value for this node, <b>if and only if</b>
569660
* this node is numeric ({@link #isNumber} returns true); otherwise
@@ -574,6 +665,8 @@ public byte[] binaryValue() {
574665
*/
575666
public Number numberValue() { return null; }
576667

668+
// // Scalar access: Numbers, Java short
669+
577670
/**
578671
* Returns 16-bit short value for this node, <b>if and only if</b>
579672
* this node is numeric ({@link #isNumber} returns true). For other
@@ -586,6 +679,8 @@ public byte[] binaryValue() {
586679
*/
587680
public short shortValue() { return 0; }
588681

682+
// // Scalar access: Numbers, Java int
683+
589684
/**
590685
* Returns integer value for this node, <b>if and only if</b>
591686
* this node is numeric ({@link #isNumber} returns true). For other
@@ -598,108 +693,6 @@ public byte[] binaryValue() {
598693
*/
599694
public int intValue() { return 0; }
600695

601-
/**
602-
* Returns 64-bit long value for this node, <b>if and only if</b>
603-
* this node is numeric ({@link #isNumber} returns true). For other
604-
* types returns 0.
605-
* For floating-point numbers, value is truncated using default
606-
* Java coercion, similar to how cast from double to long operates.
607-
*
608-
* @return Long value this node contains, if any; 0 for non-number
609-
* nodes.
610-
*/
611-
public long longValue() { return 0L; }
612-
613-
/**
614-
* Returns 32-bit floating value for this node, <b>if and only if</b>
615-
* this node is numeric ({@link #isNumber} returns true). For other
616-
* types returns 0.0.
617-
* For integer values, conversion is done using coercion; this means
618-
* that an overflow is possible for `long` values
619-
*
620-
* @return 32-bit float value this node contains, if any; 0.0 for non-number nodes.
621-
*/
622-
public float floatValue() { return 0.0f; }
623-
624-
/**
625-
* Returns 64-bit floating point (double) value for this node, <b>if and only if</b>
626-
* this node is numeric ({@link #isNumber} returns true). For other
627-
* types returns 0.0.
628-
* For integer values, conversion is done using coercion; this may result
629-
* in overflows with {@link BigInteger} values.
630-
*
631-
* @return 64-bit double value this node contains, if any; 0.0 for non-number nodes.
632-
*/
633-
public double doubleValue() { return 0.0; }
634-
635-
/**
636-
* Returns floating point value for this node (as {@link BigDecimal}), <b>if and only if</b>
637-
* this node is numeric ({@link #isNumber} returns true). For other
638-
* types returns <code>BigDecimal.ZERO</code>.
639-
*
640-
* @return {@link BigDecimal} value this node contains, if numeric node; <code>BigDecimal.ZERO</code> for non-number nodes.
641-
*/
642-
public BigDecimal decimalValue() { return BigDecimal.ZERO; }
643-
644-
/**
645-
* Returns integer value for this node (as {@link BigInteger}), <b>if and only if</b>
646-
* this node is numeric ({@link #isNumber} returns true). For other
647-
* types returns <code>BigInteger.ZERO</code>.
648-
*<p>
649-
* May also throw {@link tools.jackson.core.exc.StreamConstraintsException}
650-
* if the scale of the underlying {@link BigDecimal} is too large to convert.
651-
*
652-
* @return {@link BigInteger} value this node contains, if numeric node; <code>BigInteger.ZERO</code> for non-number nodes.
653-
*/
654-
public BigInteger bigIntegerValue() { return BigInteger.ZERO; }
655-
656-
/*
657-
/**********************************************************************
658-
/* Public API, value access with conversion(s)/coercion(s)
659-
/**********************************************************************
660-
*/
661-
662-
/**
663-
* Method that will return a valid String representation of
664-
* the contained value, if the node is a value node
665-
* (method {@link #isValueNode} returns true),
666-
* otherwise empty String.
667-
*<p>
668-
* NOTE: this is NOT same as {@link #toString()} in that result is
669-
* <p>NOT VALID ENCODED JSON</p> for all nodes (but is for some, like
670-
* {@code NumberNode}s and {@code BooleanNode}s).
671-
*/
672-
public abstract String asString();
673-
674-
/**
675-
* Returns the text value of this node or the provided {@code defaultValue} if this node
676-
* does not have a text value. Useful for nodes that are {@link MissingNode} or
677-
* {@link tools.jackson.databind.node.NullNode}, ensuring a default value is returned instead of null or missing indicators.
678-
*
679-
* @param defaultValue The default value to return if this node's text value is absent.
680-
* @return The text value of this node, or {@code defaultValue} if the text value is absent.
681-
*/
682-
public String asString(String defaultValue) {
683-
String str = asString();
684-
return (str == null) ? defaultValue : str;
685-
}
686-
687-
/**
688-
* @deprecated Use {@link #asString()} instead.
689-
*/
690-
@Deprecated // since 3.0
691-
public final String asText() {
692-
return asString();
693-
}
694-
695-
/**
696-
* @deprecated Use {@link #asString(String)} instead.
697-
*/
698-
@Deprecated // since 3.0
699-
public String asText(String defaultValue) {
700-
return asString(defaultValue);
701-
}
702-
703696
/**
704697
* Method that will try to convert value of this node to a Java <b>int</b>.
705698
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
@@ -728,6 +721,20 @@ public int asInt(int defaultValue) {
728721
return defaultValue;
729722
}
730723

724+
// // Scalar access: Numbers, Java long
725+
726+
/**
727+
* Returns 64-bit long value for this node, <b>if and only if</b>
728+
* this node is numeric ({@link #isNumber} returns true). For other
729+
* types returns 0.
730+
* For floating-point numbers, value is truncated using default
731+
* Java coercion, similar to how cast from double to long operates.
732+
*
733+
* @return Long value this node contains, if any; 0 for non-number
734+
* nodes.
735+
*/
736+
public long longValue() { return 0L; }
737+
731738
/**
732739
* Method that will try to convert value of this node to a Java <b>long</b>.
733740
* Numbers are coerced using default Java rules; booleans convert to 0 (false)
@@ -756,6 +763,46 @@ public long asLong(long defaultValue) {
756763
return defaultValue;
757764
}
758765

766+
// // Scalar access: Numbers, Java BigInteger
767+
768+
/**
769+
* Returns integer value for this node (as {@link BigInteger}), <b>if and only if</b>
770+
* this node is numeric ({@link #isNumber} returns true). For other
771+
* types returns <code>BigInteger.ZERO</code>.
772+
*<p>
773+
* May also throw {@link tools.jackson.core.exc.StreamConstraintsException}
774+
* if the scale of the underlying {@link BigDecimal} is too large to convert.
775+
*
776+
* @return {@link BigInteger} value this node contains, if numeric node; <code>BigInteger.ZERO</code> for non-number nodes.
777+
*/
778+
public BigInteger bigIntegerValue() { return BigInteger.ZERO; }
779+
780+
// // Scalar access: Numbers, Java float
781+
782+
/**
783+
* Returns 32-bit floating value for this node, <b>if and only if</b>
784+
* this node is numeric ({@link #isNumber} returns true). For other
785+
* types returns 0.0.
786+
* For integer values, conversion is done using coercion; this means
787+
* that an overflow is possible for `long` values
788+
*
789+
* @return 32-bit float value this node contains, if any; 0.0 for non-number nodes.
790+
*/
791+
public float floatValue() { return 0.0f; }
792+
793+
// // Scalar access: Numbers, Java double
794+
795+
/**
796+
* Returns 64-bit floating point (double) value for this node, <b>if and only if</b>
797+
* this node is numeric ({@link #isNumber} returns true). For other
798+
* types returns 0.0.
799+
* For integer values, conversion is done using coercion; this may result
800+
* in overflows with {@link BigInteger} values.
801+
*
802+
* @return 64-bit double value this node contains, if any; 0.0 for non-number nodes.
803+
*/
804+
public double doubleValue() { return 0.0; }
805+
759806
/**
760807
* Method that will try to convert value of this node to a Java <b>double</b>.
761808
* Numbers are coerced using default Java rules; booleans convert to 0.0 (false)
@@ -784,48 +831,20 @@ public double asDouble(double defaultValue) {
784831
return defaultValue;
785832
}
786833

787-
/**
788-
* Method that will try to convert value of this node to a Java <b>boolean</b>.
789-
* JSON booleans map naturally; integer numbers other than 0 map to true, and
790-
* 0 maps to false
791-
* and Strings 'true' and 'false' map to corresponding values.
792-
*<p>
793-
* If representation cannot be converted to a boolean value (including structured types
794-
* like Objects and Arrays),
795-
* default value of <b>false</b> will be returned; no exceptions are thrown.
796-
*/
797-
public boolean asBoolean() {
798-
return asBoolean(false);
799-
}
800-
801-
/**
802-
* Method that will try to convert value of this node to a Java <b>boolean</b>.
803-
* JSON booleans map naturally; integer numbers other than 0 map to true, and
804-
* 0 maps to false
805-
* and Strings 'true' and 'false' map to corresponding values.
806-
*<p>
807-
* If representation cannot be converted to a boolean value (including structured types
808-
* like Objects and Arrays),
809-
* specified <b>defaultValue</b> will be returned; no exceptions are thrown.
810-
*/
811-
public boolean asBoolean(boolean defaultValue) {
812-
return defaultValue;
813-
}
834+
// // Scalar access: Numbers, Java BigDecimal
814835

815836
/**
816-
* Method that will return a {@link JsonNode} wrapped in Java's {@link Optional}.
837+
* Returns floating point value for this node (as {@link BigDecimal}), <b>if and only if</b>
838+
* this node is numeric ({@link #isNumber} returns true). For other
839+
* types returns <code>BigDecimal.ZERO</code>.
817840
*
818-
* @return `Optional<JsonNode>` containing this node, or {@link Optional#empty()}
819-
* if this is a {@link MissingNode}.
820-
* @since 2.19
841+
* @return {@link BigDecimal} value this node contains, if numeric node; <code>BigDecimal.ZERO</code> for non-number nodes.
821842
*/
822-
public Optional<JsonNode> asOptional() {
823-
return Optional.of(this);
824-
}
843+
public BigDecimal decimalValue() { return BigDecimal.ZERO; }
825844

826845
/*
827846
/**********************************************************************
828-
/* Public API, extended traversal (2.10) with "required()"
847+
/* Public API, extended traversal with "required()"
829848
/**********************************************************************
830849
*/
831850

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

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

905920
/**
906921
* Method is functionally equivalent to

0 commit comments

Comments
 (0)