Package org.apache.juneau.marshall

Enum Class BigNumberFormat

java.lang.Object

java.lang.Enum<BigNumberFormat>

org.apache.juneau.marshall.BigNumberFormat

All Implemented Interfaces:

Serializable, Comparable<BigNumberFormat>, Constable

public enum BigNumberFormat
extends Enum<BigNumberFormat>

Supported wire formats for BigInteger and BigDecimal values.

Used by MarshallingContext.Builder.bigNumberFormat(BigNumberFormat), Marshalled.bigNumberFormat(), MarshalledProp.bigNumberFormat(), and MarshalledConfig.bigNumberFormat() to control how BigInteger / BigDecimal values are written to text-based wire formats.

The default is NUMBER which preserves the historical wire output (a bare numeric token).

JS-interop motivation

JavaScript's Number.MAX_SAFE_INTEGER is 2^53 − 1 (= 9007199254740991). Values outside that range silently lose precision when parsed by a JavaScript client. STRING forces a quoted-string representation that round-trips losslessly. AUTO picks NUMBER for values that are JS-safe and STRING for everything else — the typical "safe default" for services that may be consumed by both JVM and browser clients.

Precedence (highest to lowest)

1. @MarshalledProp(bigNumberFormat=…) on the bean property.
2. @Marshalled(bigNumberFormat=…) on the bean class.
3. @MarshalledConfig(bigNumberFormat=…) on @Rest-annotated classes / methods.
4. Programmatic MarshallingContext.Builder.bigNumberFormat(BigNumberFormat).
5. Environment variable MarshallingContext.bigNumberFormat.
6. The default constant (NUMBER).

Parser leniency

Parsers SHALL accept both bare numeric and quoted-string input regardless of the parser-side BigNumberFormat setting. The configured constant is informational only.

Binary serializers

Binary serializers (BSON / CBOR / MsgPack / Prototext) emit native numeric types regardless of the configured BigNumberFormat; this setting only affects text-based serializers. BSON has decimal128 for exact decimal values; CBOR / MsgPack handle big-integer values via tag 2 / tag 3 with string fallback.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
AUTO	Hybrid — emit NUMBER when the value is JS-safe (fits in ±(2^53 − 1)), otherwise emit STRING.
NOT_SET	Sentinel meaning "no value configured" — falls through to the next-higher precedence level.
NUMBER	Bare numeric token (the default).
STRING	Quoted-string form for lossless precision.

Method Summary

Modifier and Type	Method	Description
static Object	format(BigDecimal value, BigNumberFormat format)	Formats the specified BigDecimal using this format.
static Object	format(BigInteger value, BigNumberFormat format)	Formats the specified BigInteger using this format.
boolean	isNumeric()	Returns true if this format always emits a numeric wire value.
static <T extends Number> T	parse(String value, BigNumberFormat format, Class<T> targetType)	Parses the specified wire value into a BigInteger or BigDecimal.
static BigNumberFormat	valueOf(String name)	Returns the enum constant of this class with the specified name.
static BigNumberFormat[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

NOT_SET

public static final BigNumberFormat NOT_SET

Sentinel meaning "no value configured" — falls through to the next-higher precedence level.

NUMBER

public static final BigNumberFormat NUMBER

Bare numeric token (the default).

Example:

12345678901234567890

This is the historical wire output and the natural form for server-to-server JVM clients.

STRING

public static final BigNumberFormat STRING

Quoted-string form for lossless precision.

Example:

"12345678901234567890"

Round-trips losslessly through any JSON / YAML / etc. parser, including JavaScript clients which would otherwise truncate to a 64-bit double.

AUTO

public static final BigNumberFormat AUTO

Hybrid — emit NUMBER when the value is JS-safe (fits in ±(2^53 − 1)), otherwise emit STRING.

For BigDecimal values, any non-zero scale forces STRING (a fractional value cannot be safely represented in a JS double regardless of magnitude).

The "safe default" for services that may be consumed by both JVM and browser clients.

Method Details

values

public static BigNumberFormat[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static BigNumberFormat valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null

format

public static Object format(BigInteger value,
 BigNumberFormat format)

Formats the specified BigInteger using this format.

Returns either a Number (when NUMBER or AUTO produces a JS-safe value) or a String (when STRING or AUTO produces an out-of-range value). Callers should branch on the runtime type:

• Number → emit as a bare numeric wire token.
• String → emit as a quoted string.

Parameters:

value - The value to format. Can be null (returns null).

format - The configured format. Can be null (treated as NUMBER).

Returns:

The formatted value (a BigInteger for numeric output, a String for string output), or null if value is null.

format

public static Object format(BigDecimal value,
 BigNumberFormat format)

Formats the specified BigDecimal using this format.

Returns either a Number (when NUMBER or AUTO produces a JS-safe value) or a String (when STRING or AUTO produces an out-of-range value).

For AUTO: any non-zero-scale BigDecimal (i.e. has a fractional part) forces STRING since fractional values cannot be safely represented in a JS double regardless of magnitude. Zero-scale values are tested against the integer ±(2^53 − 1) bound.

Parameters:

value - The value to format. Can be null (returns null).

format - The configured format. Can be null (treated as NUMBER).

Returns:

The formatted value (a BigDecimal for numeric output, a String for string output), or null if value is null.

parse

public static <T extends Number> T parse(String value,
 BigNumberFormat format,
 Class<T> targetType)

Parses the specified wire value into a BigInteger or BigDecimal.

Accepts both bare numeric and quoted-string input regardless of the format hint. The hint is informational only.

Type Parameters:

T - The target type (BigInteger or BigDecimal).

Parameters:

value - The wire value. Can be null or blank (returns null).

format - The configured format (informational only — parsing is format-agnostic). Can be null (ignored; parsing is format-agnostic).

targetType - The desired return type — BigInteger or BigDecimal.

Returns:

The parsed value, or null if value is null or blank.

Throws:

IllegalArgumentException - If the value cannot be parsed as a number or targetType is unsupported.

isNumeric

public boolean isNumeric()

Returns true if this format always emits a numeric wire value.

NUMBER returns true; STRING returns false. AUTO returns false conservatively — its format(...) return type varies per value, so serializers should branch on the actual runtime type returned by format(BigInteger, BigNumberFormat) / format(BigDecimal, BigNumberFormat) rather than this hint.

Returns:

true if this format emits a bare numeric wire value.