Close #1121 - Improve numeric values support

[cchantep]

Pull Request Checklist

• Have you read through the contributor guidelines?
• Have you squashed your commits?
• Have you added copyright headers to new files?
• Have you updated the documentation?
• Have you added tests for any changed functionality?

Purpose

Improve performance about the JSON numbers for the following use cases:

• parsing/deserialization
• in-memory instantiation
• validation
• serialization

Background Context

The 2 main points of the design are described below.

• Laziness: until it's evaluated (directly accessing the JsNumber.value) or validated (using Reads), a deserialized JsNumber only kept the raw representation from the JSON parser, without more processing/conversion.
• Specialization: Refactor JsNumber as a sealed family with different specifialized implementation class according to use cases and underlying value precision/representation, allow to implement feature efficiently according to each one.

JsValue
 |
 +- JsNumber
      |
      +- JsLazy (only from parsing)
      +- JsBigDecimal
      +- JsBigInteger
      +- JsLong
      +- JsNumericInt (Byte, Short, Int)
      +- JsNumericFloat (Float, Double)

All the implementations,

• are mutually comparable (consistent equals/hashCode),
• transparent/invisible, only JsNumber is visible in the API, to stay compatible.

Benchmarks

New benchmarks have been added in benchmarks/src/main/scala/play/api/libs/json/JsonNumberBench.scala to measure and compare the performance of different kinds of JSON numbers across the following use cases.

Parse

Basically Json.parse(x).asInstanceOf[JsNumber], where x is a JSON raw number (integer, float, double, big decimal, ...).

Stable scores for BigInteger, Decimal and LargeDecimal, with significant improvements for Int, Long and SmallInteger.

Eval parsed

Accessing the value: BigDecimal field of a parsed JsNumber; basically Json.parse(x).asInstanceOf[JsNumber].value.

Stable scores for BigInteger and LargeDecimal, degradation for Decimal (float or double), and improvements for Int, Long and SmallInteger.

Instantiation

The JsNumber(..) factories, creating JsNumber instances using the specialized implementation classes.

Overall improvements across all cases.

Validation

From JSON parsing to Reads, basically Json.parse(..).as[Int/Float/Double/BigDecimal/..].

Stable scores for BigDecimal, BigInt, Double and Float, with significant improvements for Byte, Short, Int and Long.

Write

Using Writes matching the specialized implementations; basically Json.toJson(..).

Overall improvements across all cases, except for the stable score for Byte.

Serialization

Basically Json.toJson(aJsNumber).

Stable scores for BigDecimal, BigInt and LargeBigDecimal, with improvements for the other cases.

Overall

The specialized JsNumber implementations provide noticeable performance improvements for several numeric types, particularly Byte, Short, Int, Long and SmallInteger. The other numeric representations remain broadly stable, with some trade-offs depending on the operation and representation.

The benchmarks show improvements across most operations, while also highlighting a regression for Decimal when evaluating its BigDecimal representation.

Overall, the changes improve performance for the common integer cases while keeping the impact on the other numeric types limited.

References

#1121

[cchantep]

Deprecated

[cchantep]

Specialize

[cchantep]

Update according to size changes due to specific implementation classes

[cchantep]

Check consistency

[cchantep]

Exception thrown as soon as .parse

[cchantep]

Such instantiation was really too slow

[cchantep]

Extractors used by Reads according JsNumber implementations

[cchantep]

Refactor as sealed family

[cchantep]

New Writes

[cchantep]

Note that if update to Jackson 3, the JsonParser would directly provides distinction between the decimal, with the new JsonParser.getNumberTypeFP with returns a dedicated JsonParser.NumberTypeFP enum:

UNKNOWN (default for untyped JSON floating numbers, unless parsed into exact representations)

FLOAT16 (IEEE 754 half-precision)

FLOAT32 (Float)

DOUBLE64 (Double)

BIG_DECIMAL (BigDecimal)

That would possibly make the JacksonJson mapper much more efficient.