Skip to content

Commit 01d1e88

Browse files
cowtowncodercowtowncoder
committed
More javadoc work
1 parent 29c7b71 commit 01d1e88

File tree

1 file changed

+104
-6
lines changed

1 file changed

+104
-6
lines changed

‎src/main/java/com/fasterxml/jackson/core/ObjectCodec.java‎

Lines changed: 104 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,16 @@ protected ObjectCodec() { }
4545
* container ({@link java.util.Collection} or {@link java.util.Map}.
4646
* The reason is that due to type erasure, key and value types
4747
* can not be introspected when using this method.
48+
*
49+
* @param <T> Nominal parameter for target type
50+
*
51+
* @param p Parser to use for decoding content to bind
52+
* @param valueType Java value type to bind content to
53+
*
54+
* @return Value deserialized
55+
*
56+
* @throws IOException for low-level read issues, or
57+
* {@link JsonParseException} for decoding problems
4858
*/
4959
public abstract <T> T readValue(JsonParser p, Class<T> valueType)
5060
throws IOException;
@@ -55,6 +65,16 @@ public abstract <T> T readValue(JsonParser p, Class<T> valueType)
5565
* "super type token"
5666
* and specifically needs to be used if the root type is a
5767
* parameterized (generic) container type.
68+
*
69+
* @param <T> Nominal parameter for target type
70+
*
71+
* @param p Parser to use for decoding content to bind
72+
* @param valueTypeRef Java value type to bind content to
73+
*
74+
* @return Value deserialized
75+
*
76+
* @throws IOException for low-level read issues, or
77+
* {@link JsonParseException} for decoding problems
5878
*/
5979
public abstract <T> T readValue(JsonParser p, TypeReference<T> valueTypeRef)
6080
throws IOException;
@@ -64,27 +84,67 @@ public abstract <T> T readValue(JsonParser p, TypeReference<T> valueTypeRef)
6484
* with fully resolved type object (so it can be a generic type,
6585
* including containers like {@link java.util.Collection} and
6686
* {@link java.util.Map}).
87+
*
88+
* @param <T> Nominal parameter for target type
89+
*
90+
* @param p Parser to use for decoding content to bind
91+
* @param valueType Java value type to bind content to
92+
*
93+
* @return Value deserialized
94+
*
95+
* @throws IOException for low-level read issues, or
96+
* {@link JsonParseException} for decoding problems
6797
*/
6898
public abstract <T> T readValue(JsonParser p, ResolvedType valueType)
6999
throws IOException;
70100

71101
/**
72102
* Method for reading sequence of Objects from parser stream,
73103
* all with same specified value type.
104+
*
105+
* @param <T> Nominal parameter for target type
106+
*
107+
* @param p Parser to use for decoding content to bind
108+
* @param valueType Java value type to bind content to
109+
*
110+
* @return Iterator for incrementally deserializing values
111+
*
112+
* @throws IOException for low-level read issues, or
113+
* {@link JsonParseException} for decoding problems
74114
*/
75115
public abstract <T> Iterator<T> readValues(JsonParser p, Class<T> valueType)
76116
throws IOException;
77117

78118
/**
79119
* Method for reading sequence of Objects from parser stream,
80120
* all with same specified value type.
121+
*
122+
* @param <T> Nominal parameter for target type
123+
*
124+
* @param p Parser to use for decoding content to bind
125+
* @param valueTypeRef Java value type to bind content to
126+
*
127+
* @return Iterator for incrementally deserializing values
128+
*
129+
* @throws IOException for low-level read issues, or
130+
* {@link JsonParseException} for decoding problems
81131
*/
82132
public abstract <T> Iterator<T> readValues(JsonParser p, TypeReference<T> valueTypeRef)
83133
throws IOException;
84134

85135
/**
86136
* Method for reading sequence of Objects from parser stream,
87137
* all with same specified value type.
138+
*
139+
* @param <T> Nominal parameter for target type
140+
*
141+
* @param p Parser to use for decoding content to bind
142+
* @param valueType Java value type to bind content to
143+
*
144+
* @return Iterator for incrementally deserializing values
145+
*
146+
* @throws IOException for low-level read issues, or
147+
* {@link JsonParseException} for decoding problems
88148
*/
89149
public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
90150
throws IOException;
@@ -98,6 +158,12 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
98158
/**
99159
* Method to serialize given Java Object, using generator
100160
* provided.
161+
*
162+
* @param gen Generator to use for serializing value
163+
* @param value Value to serialize
164+
*
165+
* @throws IOException for low-level write issues, or
166+
* {@link JsonGenerationException} for decoding problems
101167
*/
102168
public abstract void writeValue(JsonGenerator gen, Object value) throws IOException;
103169

@@ -108,31 +174,48 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
108174
*/
109175

110176
/**
111-
* Method to deserialize JSON content as tree expressed
177+
* Method for deserializing JSON content as tree expressed
112178
* using set of {@link TreeNode} instances. Returns
113179
* root of the resulting tree (where root can consist
114180
* of just a single node if the current event is a
115181
* value event, not container). Empty or whitespace
116182
* documents return null.
117183
*
118-
* @return next tree from p, or null if empty.
184+
* @return next tree from {@code p}, or {@code null} if empty.
185+
*
186+
* @throws IOException for low-level read issues, or
187+
* {@link JsonParseException} for decoding problems
119188
*/
120189
@Override
121190
public abstract <T extends TreeNode> T readTree(JsonParser p) throws IOException;
122-
191+
192+
/**
193+
* Method for serializing JSON content from given Tree instance, using
194+
* specified generator.
195+
*
196+
* @param gen Generator to use for serializing value
197+
* @param tree Tree to serialize
198+
*
199+
* @throws IOException for low-level write issues, or
200+
* {@link JsonGenerationException} for decoding problems
201+
*/
123202
@Override
124203
public abstract void writeTree(JsonGenerator gen, TreeNode tree) throws IOException;
125204

126205
/**
127206
* Method for construct root level Object nodes
128207
* for Tree Model instances.
208+
*
209+
* @return Object node created
129210
*/
130211
@Override
131212
public abstract TreeNode createObjectNode();
132213

133214
/**
134215
* Method for construct root level Array nodes
135216
* for Tree Model instances.
217+
*
218+
* @return Array node created
136219
*/
137220
@Override
138221
public abstract TreeNode createArrayNode();
@@ -141,6 +224,10 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
141224
* Method for constructing a {@link JsonParser} for reading
142225
* contents of a JSON tree, as if it was external serialized
143226
* JSON content.
227+
*
228+
* @param n Content to traverse over
229+
*
230+
* @return Parser constructed for traversing over contents of specified node
144231
*/
145232
@Override
146233
public abstract JsonParser treeAsTokens(TreeNode n);
@@ -155,6 +242,15 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
155242
* Convenience method for converting given JSON tree into instance of specified
156243
* value type. This is equivalent to first constructing a {@link JsonParser} to
157244
* iterate over contents of the tree, and using that parser for data binding.
245+
*
246+
* @param <T> Nominal parameter for target type
247+
*
248+
* @param n Tree to convert
249+
* @param valueType Java target value type to convert content to
250+
*
251+
* @return Converted value instance
252+
*
253+
* @throws JsonProcessingException if structural conversion fails
158254
*/
159255
public abstract <T> T treeToValue(TreeNode n, Class<T> valueType)
160256
throws JsonProcessingException;
@@ -166,16 +262,18 @@ public abstract <T> T treeToValue(TreeNode n, Class<T> valueType)
166262
*/
167263

168264
/**
169-
* @deprecated Since 2.1: Use {@link #getFactory} instead.
265+
* @deprecated Use {@link #getFactory} instead.
266+
*
267+
* @return Underlying {@link JsonFactory} instance
170268
*/
171269
@Deprecated
172270
public JsonFactory getJsonFactory() { return getFactory(); }
173271

174272
/**
175273
* Accessor for finding underlying data format factory
176274
* ({@link JsonFactory}) codec will use for data binding.
177-
*
178-
* @since 2.1
275+
*
276+
* @return Underlying {@link JsonFactory} instance
179277
*/
180278
public JsonFactory getFactory() { return getJsonFactory(); }
181279
}

0 commit comments

Comments
 (0)