Skip to content

Commit 26695a2

Browse files
cowtowncodercowtowncoder
committed
javadoc fix backport
1 parent 5ea8878 commit 26695a2

File tree

2 files changed

+318
-1
lines changed

2 files changed

+318
-1
lines changed

‎src/main/java/com/fasterxml/jackson/databind/DeserializationFeature.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@ public enum DeserializationFeature implements ConfigFeature
231231
* kinds of JSON values); if enable, empty JSON String can be taken
232232
* to be equivalent of JSON null.
233233
*<p>
234-
* Feature is enabled by default.
234+
* Feature is disabled by default.
235235
*/
236236
ACCEPT_EMPTY_STRING_AS_NULL_OBJECT(false),
237237

‎src/main/java/com/fasterxml/jackson/databind/DeserializationFeature.java.orig

+317
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
package com.fasterxml.jackson.databind;
2+
3+
import com.fasterxml.jackson.databind.cfg.ConfigFeature;
4+
5+
/**
6+
* Enumeration that defines simple on/off features that affect
7+
* the way Java objects are deserialized from JSON
8+
*<p>
9+
* Note that features can be set both through
10+
* {@link ObjectMapper} (as sort of defaults) and through
11+
* {@link ObjectReader}.
12+
* In first case these defaults must follow "config-then-use" patterns
13+
* (i.e. defined once, not changed afterwards); all per-call
14+
* changes must be done using {@link ObjectReader}.
15+
*/
16+
public enum DeserializationFeature implements ConfigFeature
17+
{
18+
/*
19+
/******************************************************
20+
/* Type conversion features
21+
/******************************************************
22+
*/
23+
24+
/**
25+
* Feature that determines whether JSON floating point numbers
26+
* are to be deserialized into {@link java.math.BigDecimal}s
27+
* if only generic type description (either {@link Object} or
28+
* {@link Number}, or within untyped {@link java.util.Map}
29+
* or {@link java.util.Collection} context) is available.
30+
* If enabled such values will be deserialized as {@link java.math.BigDecimal}s;
31+
* if disabled, will be deserialized as {@link Double}s.
32+
* <p>
33+
* Feature is disabled by default, meaning that "untyped" floating
34+
* point numbers will by default be deserialized as {@link Double}s
35+
* (choice is for performance reason -- BigDecimals are slower than
36+
* Doubles).
37+
*/
38+
USE_BIG_DECIMAL_FOR_FLOATS(false),
39+
40+
/**
41+
* Feature that determines whether JSON integral (non-floating-point)
42+
* numbers are to be deserialized into {@link java.math.BigInteger}s
43+
* if only generic type description (either {@link Object} or
44+
* {@link Number}, or within untyped {@link java.util.Map}
45+
* or {@link java.util.Collection} context) is available.
46+
* If enabled such values will be deserialized as
47+
* {@link java.math.BigInteger}s;
48+
* if disabled, will be deserialized as "smallest" available type,
49+
* which is either {@link Integer}, {@link Long} or
50+
* {@link java.math.BigInteger}, depending on number of digits.
51+
* <p>
52+
* Feature is disabled by default, meaning that "untyped" floating
53+
* point numbers will by default be deserialized using whatever
54+
* is the most compact integral type, to optimize efficiency.
55+
*/
56+
USE_BIG_INTEGER_FOR_INTS(false),
57+
58+
// [JACKSON-652]
59+
/**
60+
* Feature that determines whether JSON Array is mapped to
61+
* <code>Object[]</code> or <code>List&lt;Object></code> when binding
62+
* "untyped" objects (ones with nominal type of <code>java.lang.Object</code>).
63+
* If true, binds as <code>Object[]</code>; if false, as <code>List&lt;Object></code>.
64+
*<p>
65+
* Feature is disabled by default, meaning that JSON arrays are bound as
66+
* {@link java.util.List}s.
67+
*/
68+
USE_JAVA_ARRAY_FOR_JSON_ARRAY(false),
69+
70+
/**
71+
* Feature that determines standard deserialization mechanism used for
72+
* Enum values: if enabled, Enums are assumed to have been serialized using
73+
* return value of <code>Enum.toString()</code>;
74+
* if disabled, return value of <code>Enum.name()</code> is assumed to have been used.
75+
*<p>
76+
* Note: this feature should usually have same value
77+
* as {@link SerializationFeature#WRITE_ENUMS_USING_TO_STRING}.
78+
*<p>
79+
* Feature is disabled by default.
80+
*/
81+
READ_ENUMS_USING_TO_STRING(false),
82+
83+
/*
84+
/******************************************************
85+
* Error handling features
86+
/******************************************************
87+
*/
88+
89+
/**
90+
* Feature that determines whether encountering of unknown
91+
* properties (ones that do not map to a property, and there is
92+
* no "any setter" or handler that can handle it)
93+
* should result in a failure (by throwing a
94+
* {@link JsonMappingException}) or not.
95+
* This setting only takes effect after all other handling
96+
* methods for unknown properties have been tried, and
97+
* property remains unhandled.
98+
*<p>
99+
* Feature is enabled by default (meaning that a
100+
* {@link JsonMappingException} will be thrown if an unknown property
101+
* is encountered).
102+
*/
103+
FAIL_ON_UNKNOWN_PROPERTIES(true),
104+
105+
/**
106+
* Feature that determines whether encountering of JSON null
107+
* is an error when deserializing into Java primitive types
108+
* (like 'int' or 'double'). If it is, a JsonProcessingException
109+
* is thrown to indicate this; if not, default value is used
110+
* (0 for 'int', 0.0 for double, same defaulting as what JVM uses).
111+
*<p>
112+
* Feature is disabled by default.
113+
*/
114+
FAIL_ON_NULL_FOR_PRIMITIVES(false),
115+
116+
/**
117+
* Feature that determines whether JSON integer numbers are valid
118+
* values to be used for deserializing Java enum values.
119+
* If set to 'false' numbers are acceptable and are used to map to
120+
* ordinal() of matching enumeration value; if 'true', numbers are
121+
* not allowed and a {@link JsonMappingException} will be thrown.
122+
* Latter behavior makes sense if there is concern that accidental
123+
* mapping from integer values to enums might happen (and when enums
124+
* are always serialized as JSON Strings)
125+
*<p>
126+
* Feature is disabled by default.
127+
*/
128+
FAIL_ON_NUMBERS_FOR_ENUMS(false),
129+
130+
/**
131+
* Feature that determines what happens when type of a polymorphic
132+
* value (indicated for example by {@link com.fasterxml.jackson.annotation.JsonTypeInfo})
133+
* can not be found (missing) or resolved (invalid class name, unmappable id);
134+
* if enabled, an exception ir thrown; if false, null value is used instead.
135+
*<p>
136+
* Feature is enabled by default so that exception is thrown for missing or invalid
137+
* type information.
138+
*
139+
* @since 2.2
140+
*/
141+
FAIL_ON_INVALID_SUBTYPE(true),
142+
143+
/**
144+
* Feature that determines what happens when reading JSON content into tree
145+
* ({@link com.fasterxml.jackson.core.TreeNode}) and a duplicate key
146+
* is encountered (property name that was already seen for the JSON Object).
147+
* If enabled, {@link JsonMappingException} will be thrown; if disabled, no exception
148+
* is thrown and the new (later) value overwrites the earlier value.
149+
*<p>
150+
* Note that this property does NOT affect other aspects of data-binding; that is,
151+
* no detection is done with respect to POJO properties or {@link java.util.Map}
152+
* keys. New features may be added to control additional cases.
153+
*<p>
154+
* Feature is disabled by default so that no exception is thrown.
155+
*
156+
* @since 2.3
157+
*/
158+
FAIL_ON_READING_DUP_TREE_KEY(false),
159+
160+
/**
161+
* Feature that determines what happens when a property that has been explicitly
162+
* marked as ignorable is encountered in input: if feature is enabled,
163+
* {@link JsonMappingException} is thrown; if false, property is quietly skipped.
164+
*<p>
165+
* Feature is disabled by default so that no exception is thrown.
166+
*
167+
* @since 2.3
168+
*/
169+
FAIL_ON_IGNORED_PROPERTIES(false),
170+
171+
/**
172+
* Feature that determines whether Jackson code should catch
173+
* and wrap {@link Exception}s (but never {@link Error}s!)
174+
* to add additional information about
175+
* location (within input) of problem or not. If enabled,
176+
* most exceptions will be caught and re-thrown (exception
177+
* specifically being that {@link java.io.IOException}s may be passed
178+
* as is, since they are declared as throwable); this can be
179+
* convenient both in that all exceptions will be checked and
180+
* declared, and so there is more contextual information.
181+
* However, sometimes calling application may just want "raw"
182+
* unchecked exceptions passed as is.
183+
*<p>
184+
* Feature is enabled by default.
185+
*/
186+
WRAP_EXCEPTIONS(true),
187+
188+
/*
189+
/******************************************************
190+
/* Structural conversion features
191+
/******************************************************
192+
*/
193+
194+
/**
195+
* Feature that determines whether it is acceptable to coerce non-array
196+
* (in JSON) values to work with Java collection (arrays, java.util.Collection)
197+
* types. If enabled, collection deserializers will try to handle non-array
198+
* values as if they had "implicit" surrounding JSON array.
199+
* This feature is meant to be used for compatibility/interoperability reasons,
200+
* to work with packages (such as XML-to-JSON converters) that leave out JSON
201+
* array in cases where there is just a single element in array.
202+
*<p>
203+
* Feature is disabled by default.
204+
*/
205+
ACCEPT_SINGLE_VALUE_AS_ARRAY(false),
206+
207+
/**
208+
* Feature to allow "unwrapping" root-level JSON value, to match setting of
209+
* {@link SerializationFeature#WRAP_ROOT_VALUE} used for serialization.
210+
* Will verify that the root JSON value is a JSON Object, and that it has
211+
* a single property with expected root name. If not, a
212+
* {@link JsonMappingException} is thrown; otherwise value of the wrapped property
213+
* will be deserialized as if it was the root value.
214+
*<p>
215+
* Feature is disabled by default.
216+
*/
217+
UNWRAP_ROOT_VALUE(false),
218+
219+
/*
220+
/******************************************************
221+
/* Value conversion features
222+
/******************************************************
223+
*/
224+
225+
/**
226+
* Feature that can be enabled to allow JSON empty String
227+
* value ("") to be bound to POJOs as null.
228+
* If disabled, standard POJOs can only be bound from JSON null or
229+
* JSON Object (standard meaning that no custom deserializers or
230+
* constructors are defined; both of which can add support for other
231+
* kinds of JSON values); if enable, empty JSON String can be taken
232+
* to be equivalent of JSON null.
233+
*<p>
234+
* Feature is enabled by default.
235+
*/
236+
ACCEPT_EMPTY_STRING_AS_NULL_OBJECT(false),
237+
238+
/**
239+
* Feature that allows unknown Enum values to be parsed as null values.
240+
* If disabled, unknown Enum values will throw exceptions.
241+
*<p>
242+
* Note that in some cases this will basically ignore unknown Enum values;
243+
* this is the keys for keys of {@link java.util.EnumMap} and values
244+
* of {@link java.util.EnumSet} (because nulls are not accepted in these
245+
* cases).
246+
*<p>
247+
* Feature is disabled by default.
248+
*
249+
* @since 2.0
250+
*/
251+
READ_UNKNOWN_ENUM_VALUES_AS_NULL(false),
252+
253+
/**
254+
* Feature that controls whether numeric timestamp values are expected
255+
* to be written using nanosecond timestamps (enabled) or not (disabled),
256+
* <b>if and only if</b> datatype supports such resolution.
257+
* Only newer datatypes (such as Java8 Date/Time) support such resolution --
258+
* older types (pre-Java8 <b>java.util.Date</b> etc) and Joda do not --
259+
* and this setting <b>has no effect</b> on such types.
260+
*<p>
261+
* If disabled, standard millisecond timestamps are assumed.
262+
* This is the counterpart to {@link SerializationFeature#WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS}.
263+
*<p>
264+
* Feature is enabled by default, to support most accurate time values possible.
265+
*
266+
* @since 2.2
267+
*/
268+
READ_DATE_TIMESTAMPS_AS_NANOSECONDS(true),
269+
270+
/**
271+
* Feature that specifies whether context provided {@link java.util.TimeZone}
272+
* ({@link DeserializationContext#getTimeZone()} should be used to adjust Date/Time
273+
* values on deserialization, even if value itself contains timezone information.
274+
* If enabled, contextual <code>TimeZone</code> will essentially override any other
275+
* TimeZone information; if disabled, it will only be used if value itself does not
276+
* contain any TimeZone information.
277+
*
278+
* @since 2.2
279+
*/
280+
ADJUST_DATES_TO_CONTEXT_TIME_ZONE(true),
281+
282+
/*
283+
/******************************************************
284+
/* Other
285+
/******************************************************
286+
*/
287+
288+
/**
289+
* Feature that determines whether {@link ObjectReader} should
290+
* try to eagerly fetch necessary {@link JsonDeserializer} when
291+
* possible. This improves performance in cases where similarly
292+
* configured {@link ObjectReader} instance is used multiple
293+
* times; and should not significantly affect single-use cases.
294+
*<p>
295+
* Note that there should not be any need to normally disable this
296+
* feature: only consider that if there are actual perceived problems.
297+
*<p>
298+
* Feature is enabled by default.
299+
*
300+
* @since 2.1
301+
*/
302+
EAGER_DESERIALIZER_FETCH(true)
303+
304+
;
305+
306+
private final boolean _defaultState;
307+
308+
private DeserializationFeature(boolean defaultState) {
309+
_defaultState = defaultState;
310+
}
311+
312+
@Override
313+
public boolean enabledByDefault() { return _defaultState; }
314+
315+
@Override
316+
public int getMask() { return (1 << ordinal()); }
317+
}

0 commit comments

Comments
 (0)