javadoc improvement

FasterXML · Mar 15, 2019 · c0cd01a · c0cd01a
1 parent 25e69ed
commit c0cd01a
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 11 deletions.
diff --git a/src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java b/src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java
@@ -2570,6 +2570,12 @@ public JsonNode readTree(File file)
     /**
      * Same as {@link #readTree(InputStream)} except content read from
      * passed-in {@link URL}.
+     *<p>
+     * NOTE: handling of {@link java.net.URL} is delegated to
+     * {@link JsonFactory#createParser(java.net.URL)} and usually simply
+     * calls {@link java.net.URL#openStream()}, meaning no special handling
+     * is done. If different HTTP connection options are needed you will need
+     * to create {@link java.io.InputStream} separately.
      */
     public JsonNode readTree(URL source) throws IOException {
         return _readTreeAndClose(_jsonFactory.createParser(source));
@@ -2897,6 +2903,12 @@ public <T> T readValue(File src, JavaType valueType)
 
     /**
      * Method to deserialize JSON content from given resource into given Java type.
+     *<p>
+     * NOTE: handling of {@link java.net.URL} is delegated to
+     * {@link JsonFactory#createParser(java.net.URL)} and usually simply
+     * calls {@link java.net.URL#openStream()}, meaning no special handling
+     * is done. If different HTTP connection options are needed you will need
+     * to create {@link java.io.InputStream} separately.
      * 
      * @throws IOException if a low-level I/O problem (unexpected end-of-input,
      *   network error) occurs (passed through as-is without additional wrapping -- note
@@ -2915,16 +2927,7 @@ public <T> T readValue(URL src, Class<T> valueType)
     } 
 
     /**
-     * Method to deserialize JSON content from given resource into given Java type.
-     * 
-     * @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)
-     * @throws JsonMappingException if the input JSON structure does not match structure
-     *   expected for result type (or has other mismatch issues)
+     * Same as {@link #readValue(java.net.URL, Class)} except that target specified by {@link TypeReference}.
      */
     @SuppressWarnings({ "unchecked" })
     public <T> T readValue(URL src, TypeReference<T> valueTypeRef)
@@ -2933,12 +2936,15 @@ public <T> T readValue(URL src, TypeReference<T> valueTypeRef)
         return (T) _readMapAndClose(_jsonFactory.createParser(src), _typeFactory.constructType(valueTypeRef));
     } 
 
+    /**
+     * Same as {@link #readValue(java.net.URL, Class)} except that target specified by {@link JavaType}.
+     */
     @SuppressWarnings("unchecked")
     public <T> T readValue(URL src, JavaType valueType)
         throws IOException, JsonParseException, JsonMappingException
     {
         return (T) _readMapAndClose(_jsonFactory.createParser(src), valueType);
-    } 
+    }
 
     /**
      * Method to deserialize JSON content from given JSON content String.

diff --git a/src/main/java/com/fasterxml/jackson/databind/ObjectReader.java b/src/main/java/com/fasterxml/jackson/databind/ObjectReader.java
@@ -1286,6 +1286,13 @@ public <T> T readValue(File src)
      * using configuration of this reader.
      * Value return is either newly constructed, or root value that
      * was specified with {@link #withValueToUpdate(Object)}.
+     *<p>
+     *<p>
+     * NOTE: handling of {@link java.net.URL} is delegated to
+     * {@link JsonFactory#createParser(java.net.URL)} and usually simply
+     * calls {@link java.net.URL#openStream()}, meaning no special handling
+     * is done. If different HTTP connection options are needed you will need
+     * to create {@link java.io.InputStream} separately.
      */
     @SuppressWarnings("unchecked")
     public <T> T readValue(URL src)
@@ -1550,6 +1557,12 @@ public <T> MappingIterator<T> readValues(File src)
 
     /**
      * Overloaded version of {@link #readValue(InputStream)}.
+     *<p>
+     * NOTE: handling of {@link java.net.URL} is delegated to
+     * {@link JsonFactory#createParser(java.net.URL)} and usually simply
+     * calls {@link java.net.URL#openStream()}, meaning no special handling
+     * is done. If different HTTP connection options are needed you will need
+     * to create {@link java.io.InputStream} separately.
      * 
      * @param src URL to read to access JSON content to parse.
      */