1 /* 2 * Copyright (C) 2021 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.gson; 18 19 import com.google.gson.stream.JsonReader; 20 import java.io.IOException; 21 22 /** 23 * A strategy that is used to control how numbers should be deserialized for {@link Object} and {@link Number} 24 * when a concrete type of the deserialized number is unknown in advance. By default, Gson uses the following 25 * deserialization strategies: 26 * 27 * <ul> 28 * <li>{@link Double} values are returned for JSON numbers if the deserialization type is declared as 29 * {@code Object}, see {@link ToNumberPolicy#DOUBLE};</li> 30 * <li>Lazily parsed number values are returned if the deserialization type is declared as {@code Number}, 31 * see {@link ToNumberPolicy#LAZILY_PARSED_NUMBER}.</li> 32 * </ul> 33 * 34 * <p>For historical reasons, Gson does not support deserialization of arbitrary-length numbers for 35 * {@code Object} and {@code Number} by default, potentially causing precision loss. However, 36 * <a href="https://tools.ietf.org/html/rfc8259#section-6">RFC 8259</a> permits this: 37 * 38 * <pre> 39 * This specification allows implementations to set limits on the range 40 * and precision of numbers accepted. Since software that implements 41 * IEEE 754 binary64 (double precision) numbers [IEEE754] is generally 42 * available and widely used, good interoperability can be achieved by 43 * implementations that expect no more precision or range than these 44 * provide, in the sense that implementations will approximate JSON 45 * numbers within the expected precision. A JSON number such as 1E400 46 * or 3.141592653589793238462643383279 may indicate potential 47 * interoperability problems, since it suggests that the software that 48 * created it expects receiving software to have greater capabilities 49 * for numeric magnitude and precision than is widely available. 50 * </pre> 51 * 52 * <p>To overcome the precision loss, use for example {@link ToNumberPolicy#LONG_OR_DOUBLE} or 53 * {@link ToNumberPolicy#BIG_DECIMAL}.</p> 54 * 55 * @see ToNumberPolicy 56 * @see GsonBuilder#setObjectToNumberStrategy(ToNumberStrategy) 57 * @see GsonBuilder#setNumberToNumberStrategy(ToNumberStrategy) 58 * @since 2.8.9 59 */ 60 public interface ToNumberStrategy { 61 62 /** 63 * Reads a number from the given JSON reader. A strategy is supposed to read a single value from the 64 * reader, and the read value is guaranteed never to be {@code null}. 65 * 66 * @param in JSON reader to read a number from 67 * @return number read from the JSON reader. 68 */ readNumber(JsonReader in)69 public Number readNumber(JsonReader in) throws IOException; 70 } 71