This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new e043fb8a [IO-772] Confusing Javadoc on IOUtils#resourceToURL() and
other resource* methods.
e043fb8a is described below
commit e043fb8ad1e7677cd888170100fae43ae24f66c1
Author: Gary Gregory <gardgreg...@gmail.com>
AuthorDate: Sun Jun 19 10:25:25 2022 -0400
[IO-772] Confusing Javadoc on IOUtils#resourceToURL() and other
resource* methods.
---
src/changes/changes.xml | 3 +
src/main/java/org/apache/commons/io/IOUtils.java | 73 +++++++++++-------------
2 files changed, 35 insertions(+), 41 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index efc3fe4a..8bdb663c 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -180,6 +180,9 @@ The <action> type attribute can be add,update,fix,remove.
<action issue="IO-762" dev="ggregory" type="fix" due-to="Leonidas
Chiron, Gary Gregory">
FileSystem.WINDOWS.isReservedFileName doesn't check for file extension.
</action>
+ <action issue="IO-772" dev="ggregory" type="fix" due-to="Dan Ziemba,
Gary Gregory">
+ Confusing Javadoc on IOUtils#resourceToURL() and other resource*
methods.
+ </action>
<!-- ADD -->
<action type="add" dev="ggregory" due-to="Gary Gregory">
Add GitHub coverage.yml.
diff --git a/src/main/java/org/apache/commons/io/IOUtils.java
b/src/main/java/org/apache/commons/io/IOUtils.java
index 3b5e82db..1e1b2a95 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -2082,16 +2082,15 @@ public class IOUtils {
}
/**
- * Gets the contents of a classpath resource as a byte array.
+ * Gets the contents of a resource as a byte array.
* <p>
- * It is expected the given {@code name} to be absolute. The
- * behavior is not well-defined otherwise.
+ * Delegates to {@link #resourceToByteArray(String, ClassLoader)
resourceToByteArray(String, null)}.
* </p>
*
- * @param name name of the desired resource
+ * @param name The resource name.
* @return the requested byte array
- * @throws IOException if an I/O error occurs.
- *
+ * @throws IOException if an I/O error occurs or the resource is not found.
+ * @see #resourceToByteArray(String, ClassLoader)
* @since 2.6
*/
public static byte[] resourceToByteArray(final String name) throws
IOException {
@@ -2099,17 +2098,16 @@ public class IOUtils {
}
/**
- * Gets the contents of a classpath resource as a byte array.
+ * Gets the contents of a resource as a byte array.
* <p>
- * It is expected the given {@code name} to be absolute. The
- * behavior is not well-defined otherwise.
+ * Delegates to {@link #resourceToURL(String, ClassLoader)}.
* </p>
*
- * @param name name of the desired resource
+ * @param name The resource name.
* @param classLoader the class loader that the resolution of the resource
is delegated to
* @return the requested byte array
- * @throws IOException if an I/O error occurs.
- *
+ * @throws IOException if an I/O error occurs or the resource is not found.
+ * @see #resourceToURL(String, ClassLoader)
* @since 2.6
*/
public static byte[] resourceToByteArray(final String name, final
ClassLoader classLoader) throws IOException {
@@ -2117,18 +2115,16 @@ public class IOUtils {
}
/**
- * Gets the contents of a classpath resource as a String using the
- * specified character encoding.
+ * Gets the contents of a resource as a String using the specified
character encoding.
* <p>
- * It is expected the given {@code name} to be absolute. The
- * behavior is not well-defined otherwise.
+ * Delegates to {@link #resourceToString(String, Charset, ClassLoader)
resourceToString(String, Charset, null)}.
* </p>
*
- * @param name name of the desired resource
+ * @param name The resource name.
* @param charset the charset to use, null means platform default
* @return the requested String
- * @throws IOException if an I/O error occurs.
- *
+ * @throws IOException if an I/O error occurs or the resource is not found.
+ * @see #resourceToString(String, Charset, ClassLoader)
* @since 2.6
*/
public static String resourceToString(final String name, final Charset
charset) throws IOException {
@@ -2136,19 +2132,17 @@ public class IOUtils {
}
/**
- * Gets the contents of a classpath resource as a String using the
- * specified character encoding.
+ * Gets the contents of a resource as a String using the specified
character encoding.
* <p>
- * It is expected the given {@code name} to be absolute. The
- * behavior is not well-defined otherwise.
+ * Delegates to {@link #resourceToURL(String, ClassLoader)}.
* </p>
*
- * @param name name of the desired resource
- * @param charset the charset to use, null means platform default
+ * @param name The resource name.
+ * @param charset the Charset to use, null means platform default
* @param classLoader the class loader that the resolution of the resource
is delegated to
* @return the requested String
* @throws IOException if an I/O error occurs.
- *
+ * @see #resourceToURL(String, ClassLoader)
* @since 2.6
*/
public static String resourceToString(final String name, final Charset
charset, final ClassLoader classLoader) throws IOException {
@@ -2156,16 +2150,14 @@ public class IOUtils {
}
/**
- * Gets a URL pointing to the given classpath resource.
+ * Gets a URL pointing to the given resource.
* <p>
- * It is expected the given {@code name} to be absolute. The
- * behavior is not well-defined otherwise.
+ * Delegates to {@link #resourceToURL(String, ClassLoader)
resourceToURL(String, null)}.
* </p>
*
- * @param name name of the desired resource
- * @return the requested URL
- * @throws IOException if an I/O error occurs.
- *
+ * @param name The resource name.
+ * @return A URL object for reading the resource.
+ * @throws IOException if the resource is not found.
* @since 2.6
*/
public static URL resourceToURL(final String name) throws IOException {
@@ -2173,17 +2165,16 @@ public class IOUtils {
}
/**
- * Gets a URL pointing to the given classpath resource.
+ * Gets a URL pointing to the given resource.
* <p>
- * It is expected the given {@code name} to be absolute. The
- * behavior is not well-defined otherwise.
+ * If the {@code classLoader} is not null, call {@link
ClassLoader#getResource(String)}, otherwise call
+ * {@link Class#getResource(String) IOUtils.class.getResource(name)}.
* </p>
*
- * @param name name of the desired resource
- * @param classLoader the class loader that the resolution of the resource
is delegated to
- * @return the requested URL
- * @throws IOException if an I/O error occurs.
- *
+ * @param name The resource name.
+ * @param classLoader Delegate to this class loader if not null
+ * @return A URL object for reading the resource.
+ * @throws IOException if the resource is not found.
* @since 2.6
*/
public static URL resourceToURL(final String name, final ClassLoader
classLoader) throws IOException {
