Skip to content

Commit

Permalink
Javadoc improvements wrt #2211
Browse files Browse the repository at this point in the history
  • Loading branch information
@cowtowncoder
cowtowncoder committed Jan 23, 2019
1 parent f0abe41 commit 21220ee
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 114 deletions.
118 changes: 20 additions & 98 deletions src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2367,11 +2367,14 @@ public <T> T readValue(JsonParser p, JavaType valueType)
}

/**
* Method to deserialize JSON content as tree expressed
* using set of {@link JsonNode} 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).
* Method to deserialize JSON content as a tree {@link JsonNode}.
* Returns {@link JsonNode} that represents the root of the resulting tree, if there
* was content to read, or {@code null} if no more content is accessible
* via passed {@link JsonParser}.
*<p>
* NOTE! Behavior with end-of-input (no more content) differs between this
* {@code readTree} method, and all other methods that take input source: latter
* will return "missing node", NOT {@code null}
*
* @return a {@link JsonNode}, if valid JSON content found; null
* if input has no content to bind -- note, however, that if
Expand Down Expand Up @@ -2523,105 +2526,40 @@ public JsonNode readTree(InputStream in) throws IOException
}

/**
* Method to deserialize JSON content as tree expressed
* using set of {@link JsonNode} 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).
*<p>
* If a low-level I/O problem (missing input, network error) occurs,
* a {@link IOException} will be thrown.
* If a parsing problem occurs (invalid JSON),
* {@link JsonParseException} will be thrown.
* If no content is found from input (end-of-input), Java
* <code>null</code> will be returned.
*
* @param r Reader used to read JSON content
* for building the JSON tree.
*
* @return a {@link JsonNode}, if valid JSON content found; null
* if input has no content to bind -- note, however, that if
* JSON <code>null</code> token is found, it will be represented
* as a non-null {@link JsonNode} (one that returns <code>true</code>
* for {@link JsonNode#isNull()}
* Same as {@link #readTree(InputStream)} except content accessed through
* passed-in {@link Reader}
*/
public JsonNode readTree(Reader r) throws IOException {
return _readTreeAndClose(_jsonFactory.createParser(r));
}

/**
* Method to deserialize JSON content as tree expressed using set of {@link JsonNode} 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).
*<p>
* If a low-level I/O problem (missing input, network error) occurs,
* a {@link IOException} will be thrown.
* If a parsing problem occurs (invalid JSON),
* {@link JsonParseException} will be thrown.
* If no content is found from input (end-of-input), Java
* <code>null</code> will be returned.
*
* @param content JSON content to parse to build the JSON tree.
*
* @return a {@link JsonNode}, if valid JSON content found; null
* if input has no content to bind -- note, however, that if
* JSON <code>null</code> token is found, it will be represented
* as a non-null {@link JsonNode} (one that returns <code>true</code>
* for {@link JsonNode#isNull()}
*
* @throws JsonParseException if underlying input contains invalid content
* of type {@link JsonParser} supports (JSON for default case)
* Same as {@link #readTree(InputStream)} except content read from
* passed-in {@link String}
*/
public JsonNode readTree(String content) throws IOException {
return _readTreeAndClose(_jsonFactory.createParser(content));
}

/**
* Method to deserialize JSON content as tree expressed using set of {@link JsonNode} 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).
*
* @param content JSON content to parse to build the JSON tree.
*
* @return a {@link JsonNode}, if valid JSON content found; null
* if input has no content to bind -- note, however, that if
* JSON <code>null</code> token is found, it will be represented
* as a non-null {@link JsonNode} (one that returns <code>true</code>
* for {@link JsonNode#isNull()}
*
* @throws JsonParseException if underlying input contains invalid content
* of type {@link JsonParser} supports (JSON for default case)
* Same as {@link #readTree(InputStream)} except content read from
* passed-in byte array.
*/
public JsonNode readTree(byte[] content) throws IOException {
return _readTreeAndClose(_jsonFactory.createParser(content));
}

/**
* @since 2.10
* Same as {@link #readTree(InputStream)} except content read from
* passed-in byte array.
*/
public JsonNode readTree(byte[] content, int offset, int len) throws IOException {
return _readTreeAndClose(_jsonFactory.createParser(content, offset, len));
}

/**
* Method to deserialize JSON content as tree expressed using set of {@link JsonNode} 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).
*
* @param file File of which contents to parse as JSON for building a tree instance
*
* @return a {@link JsonNode}, if valid JSON content found; null
* if input has no content to bind -- note, however, that if
* JSON <code>null</code> token is found, it will be represented
* as a non-null {@link JsonNode} (one that returns <code>true</code>
* for {@link JsonNode#isNull()}
*
* @throws IOException if a low-level I/O problem (unexpected end-of-input,
* network error) occurs (passed through as-is without additional wrapping -- note
* that this is one case where {@link DeserializationFeature#WRAP_EXCEPTIONS}
* does NOT result in wrapping of exception even if enabled)
* @throws JsonParseException if underlying input contains invalid content
* of type {@link JsonParser} supports (JSON for default case)
* Same as {@link #readTree(InputStream)} except content read from
* passed-in {@link File}.
*/
public JsonNode readTree(File file)
throws IOException, JsonProcessingException
Expand All @@ -2630,24 +2568,8 @@ public JsonNode readTree(File file)
}

/**
* Method to deserialize JSON content as tree expressed using set of {@link JsonNode} 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).
*
* @param source URL to use for fetching contents to parse as JSON for building a tree instance
*
* @return a {@link JsonNode}, if valid JSON content found; null
* if input has no content to bind -- note, however, that if
* JSON <code>null</code> token is found, it will be represented
* as a non-null {@link JsonNode} (one that returns <code>true</code>
* for {@link JsonNode#isNull()}
*
* @throws IOException if a low-level I/O problem (unexpected end-of-input,
* network error) occurs (passed through as-is without additional wrapping -- note
* that this is one case where {@link DeserializationFeature#WRAP_EXCEPTIONS}
* does NOT result in wrapping of exception even if enabled)
* @throws JsonParseException if underlying input contains invalid content
* of type {@link JsonParser} supports (JSON for default case)
* Same as {@link #readTree(InputStream)} except content read from
* passed-in {@link URL}.
*/
public JsonNode readTree(URL source) throws IOException {
return _readTreeAndClose(_jsonFactory.createParser(source));
Expand Down
43 changes: 27 additions & 16 deletions src/main/java/com/fasterxml/jackson/databind/ObjectReader.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1149,6 +1149,13 @@ public JsonParser treeAsTokens(TreeNode n) {
* Convenience method that binds content read using given parser, using
* configuration of this reader, except that content is bound as
* JSON tree instead of configured root value type.
* Returns {@link JsonNode} that represents the root of the resulting tree, if there
* was content to read, or {@code null} if no more content is accessible
* via passed {@link JsonParser}.
*<p>
* NOTE! Behavior with end-of-input (no more content) differs between this
* {@code readTree} method, and all other methods that take input source: latter
* will return "missing node", NOT {@code null}
*<p>
* Note: if an object was specified with {@link #withValueToUpdate}, it
* will be ignored.
Expand Down Expand Up @@ -1316,6 +1323,14 @@ public <T> T readValue(DataInput src) throws IOException
/**
* Method that reads content from given input source,
* using configuration of this reader, and binds it as JSON Tree.
* Returns {@link JsonNode} that represents the root of the resulting tree, if there
* was content to read, or "missing node" (instance of {@JsonNode} for which
* {@link JsonNode#isMissingNode()} returns true, and behaves otherwise similar to
* "null node") if no more content is accessible through passed-in input source.
*<p>
* NOTE! Behavior with end-of-input (no more content) differs between this
* {@code readTree} method, and {@link #readTree(JsonParser)} -- latter returns
* {@code null} for "no content" case.
*<p>
* Note that if an object was specified with a call to
* {@link #withValueToUpdate(Object)}
Expand All @@ -1331,13 +1346,8 @@ public JsonNode readTree(InputStream in) throws IOException
}

/**
* Method that reads content from given input source,
* using configuration of this reader, and binds it as JSON Tree.
*<p>
* Note that if an object was specified with a call to
* {@link #withValueToUpdate(Object)}
* it will just be ignored; result is always a newly constructed
* {@link JsonNode} instance.
* Same as {@link #readTree(InputStream)} except content accessed through
* passed-in {@link Reader}
*/
public JsonNode readTree(Reader r) throws IOException
{
Expand All @@ -1348,13 +1358,8 @@ public JsonNode readTree(Reader r) throws IOException
}

/**
* Method that reads content from given JSON input String,
* using configuration of this reader, and binds it as JSON Tree.
*<p>
* Note that if an object was specified with a call to
* {@link #withValueToUpdate(Object)}
* it will just be ignored; result is always a newly constructed
* {@link JsonNode} instance.
* Same as {@link #readTree(InputStream)} except content read from
* passed-in {@link String}
*/
public JsonNode readTree(String json) throws IOException
{
Expand All @@ -1365,7 +1370,8 @@ public JsonNode readTree(String json) throws IOException
}

/**
* @since 2.10
* Same as {@link #readTree(InputStream)} except content read from
* passed-in byte array.
*/
public JsonNode readTree(byte[] json) throws IOException
{
Expand All @@ -1376,7 +1382,8 @@ public JsonNode readTree(byte[] json) throws IOException
}

/**
* @since 2.10
* Same as {@link #readTree(InputStream)} except content read from
* passed-in byte array.
*/
public JsonNode readTree(byte[] json, int offset, int len) throws IOException
{
Expand All @@ -1386,6 +1393,10 @@ public JsonNode readTree(byte[] json, int offset, int len) throws IOException
return _bindAndCloseAsTree(_considerFilter(_parserFactory.createParser(json, offset, len), false));
}

/**
* Same as {@link #readTree(InputStream)} except content read using
* passed-in {@link DataInput}.
*/
public JsonNode readTree(DataInput src) throws IOException
{
if (_dataFormatReaders != null) {
Expand Down

0 comments on commit 21220ee

Please sign in to comment.