Skip to content

Commit

Permalink
More javadoc work
Browse files Browse the repository at this point in the history
  • Loading branch information
@cowtowncoder
cowtowncoder committed Jan 4, 2021
1 parent 29c7b71 commit 01d1e88
Showing 1 changed file with 104 additions and 6 deletions.
110 changes: 104 additions & 6 deletions src/main/java/com/fasterxml/jackson/core/ObjectCodec.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,16 @@ protected ObjectCodec() { }
* container ({@link java.util.Collection} or {@link java.util.Map}.
* The reason is that due to type erasure, key and value types
* can not be introspected when using this method.
*
* @param <T> Nominal parameter for target type
*
* @param p Parser to use for decoding content to bind
* @param valueType Java value type to bind content to
*
* @return Value deserialized
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
public abstract <T> T readValue(JsonParser p, Class<T> valueType)
throws IOException;
Expand All @@ -55,6 +65,16 @@ public abstract <T> T readValue(JsonParser p, Class<T> valueType)
* "super type token"
* and specifically needs to be used if the root type is a
* parameterized (generic) container type.
*
* @param <T> Nominal parameter for target type
*
* @param p Parser to use for decoding content to bind
* @param valueTypeRef Java value type to bind content to
*
* @return Value deserialized
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
public abstract <T> T readValue(JsonParser p, TypeReference<T> valueTypeRef)
throws IOException;
Expand All @@ -64,27 +84,67 @@ public abstract <T> T readValue(JsonParser p, TypeReference<T> valueTypeRef)
* with fully resolved type object (so it can be a generic type,
* including containers like {@link java.util.Collection} and
* {@link java.util.Map}).
*
* @param <T> Nominal parameter for target type
*
* @param p Parser to use for decoding content to bind
* @param valueType Java value type to bind content to
*
* @return Value deserialized
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
public abstract <T> T readValue(JsonParser p, ResolvedType valueType)
throws IOException;

/**
* Method for reading sequence of Objects from parser stream,
* all with same specified value type.
*
* @param <T> Nominal parameter for target type
*
* @param p Parser to use for decoding content to bind
* @param valueType Java value type to bind content to
*
* @return Iterator for incrementally deserializing values
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
public abstract <T> Iterator<T> readValues(JsonParser p, Class<T> valueType)
throws IOException;

/**
* Method for reading sequence of Objects from parser stream,
* all with same specified value type.
*
* @param <T> Nominal parameter for target type
*
* @param p Parser to use for decoding content to bind
* @param valueTypeRef Java value type to bind content to
*
* @return Iterator for incrementally deserializing values
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
public abstract <T> Iterator<T> readValues(JsonParser p, TypeReference<T> valueTypeRef)
throws IOException;

/**
* Method for reading sequence of Objects from parser stream,
* all with same specified value type.
*
* @param <T> Nominal parameter for target type
*
* @param p Parser to use for decoding content to bind
* @param valueType Java value type to bind content to
*
* @return Iterator for incrementally deserializing values
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
throws IOException;
Expand All @@ -98,6 +158,12 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
/**
* Method to serialize given Java Object, using generator
* provided.
*
* @param gen Generator to use for serializing value
* @param value Value to serialize
*
* @throws IOException for low-level write issues, or
* {@link JsonGenerationException} for decoding problems
*/
public abstract void writeValue(JsonGenerator gen, Object value) throws IOException;

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

/**
* Method to deserialize JSON content as tree expressed
* Method for deserializing JSON content as tree expressed
* using set of {@link TreeNode} instances. Returns
* root of the resulting tree (where root can consist
* of just a single node if the current event is a
* value event, not container). Empty or whitespace
* documents return null.
*
* @return next tree from p, or null if empty.
* @return next tree from {@code p}, or {@code null} if empty.
*
* @throws IOException for low-level read issues, or
* {@link JsonParseException} for decoding problems
*/
@Override
public abstract <T extends TreeNode> T readTree(JsonParser p) throws IOException;


/**
* Method for serializing JSON content from given Tree instance, using
* specified generator.
*
* @param gen Generator to use for serializing value
* @param tree Tree to serialize
*
* @throws IOException for low-level write issues, or
* {@link JsonGenerationException} for decoding problems
*/
@Override
public abstract void writeTree(JsonGenerator gen, TreeNode tree) throws IOException;

/**
* Method for construct root level Object nodes
* for Tree Model instances.
*
* @return Object node created
*/
@Override
public abstract TreeNode createObjectNode();

/**
* Method for construct root level Array nodes
* for Tree Model instances.
*
* @return Array node created
*/
@Override
public abstract TreeNode createArrayNode();
Expand All @@ -141,6 +224,10 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
* Method for constructing a {@link JsonParser} for reading
* contents of a JSON tree, as if it was external serialized
* JSON content.
*
* @param n Content to traverse over
*
* @return Parser constructed for traversing over contents of specified node
*/
@Override
public abstract JsonParser treeAsTokens(TreeNode n);
Expand All @@ -155,6 +242,15 @@ public abstract <T> Iterator<T> readValues(JsonParser p, ResolvedType valueType)
* Convenience method for converting given JSON tree into instance of specified
* value type. This is equivalent to first constructing a {@link JsonParser} to
* iterate over contents of the tree, and using that parser for data binding.
*
* @param <T> Nominal parameter for target type
*
* @param n Tree to convert
* @param valueType Java target value type to convert content to
*
* @return Converted value instance
*
* @throws JsonProcessingException if structural conversion fails
*/
public abstract <T> T treeToValue(TreeNode n, Class<T> valueType)
throws JsonProcessingException;
Expand All @@ -166,16 +262,18 @@ public abstract <T> T treeToValue(TreeNode n, Class<T> valueType)
*/

/**
* @deprecated Since 2.1: Use {@link #getFactory} instead.
* @deprecated Use {@link #getFactory} instead.
*
* @return Underlying {@link JsonFactory} instance
*/
@Deprecated
public JsonFactory getJsonFactory() { return getFactory(); }

/**
* Accessor for finding underlying data format factory
* ({@link JsonFactory}) codec will use for data binding.
*
* @since 2.1
*
* @return Underlying {@link JsonFactory} instance
*/
public JsonFactory getFactory() { return getJsonFactory(); }
}

0 comments on commit 01d1e88

Please sign in to comment.