[jira] [Updated] (IO-772) Confusing doc on IOUtils::resourceToURL

["Dan Ziemba (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/IO-772?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Dan Ziemba updated IO-772:
--------------------------
    Description: 
The Javadoc for IOUtils::resourceToURL (and the String and byte[] variants) says that the "name" parameter is expected to be absolute and is not well defined otherwise. When this is called without a ClassLoader, using an absolute path makes sense as Class::getResource is called against a class that is not the caller's, so a non-absolute path would be looking inside the commons-io package.  But when called with a ClassLoader, instead the ClassLoader::getResource method is called, and using an absolute path with that does not work the same way. 

For example, both of these work the same for a file sitting at the root of the classpath (src/main/resources in typical Maven/Gradle build):
 * {{IOUtils.resourceToString("/file.txt");}}
 * {{IOUtils.resourceToString("file.txt", getClass().getClassLoader());}}

But this does not work:
 * {{IOUtils.resourceToString("/file.txt", getClass().getClassLoader());}}

That behavior is consistent with the explanation in this [accepted StackOverflow answer|[https://stackoverflow.com/a/51645482/1270447].]

I believe the doc on the method variants that take a ClassLoader should call this out.

  was:
The Javadoc for IOUtils::resourceToURL (and the String and byte[]) varients) says that the "name" parameter is expected to be absolute and is not well defined otherwise. When this is called without a ClassLoader, using an absolute path makes sense as Class::getResource is called against a class that is not the caller's, so a non-absolute path would be looking inside the commons-io package.  But when called with a ClassLoader, instead the ClassLoader::getResource method is called, and using an absolute path with that does not work the same way. 

For example, both of these work the same for a file sitting at the root of the classpath (src/main/resources in typical Maven/Gradle build):
 * {{IOUtils.resourceToString("/file.txt");}}
 * {{IOUtils.resourceToString("file.txt", getClass().getClassLoader());}}

But this does not work:
 * {{IOUtils.resourceToString("/file.txt", getClass().getClassLoader());}}

That behavior is consistent with the explanation in this [accepted StackOverflow answer|[https://stackoverflow.com/a/51645482/1270447].]

I believe the doc on the method variants that take a ClassLoader should call this out.


> Confusing doc on IOUtils::resourceToURL
> ---------------------------------------
>
>                 Key: IO-772
>                 URL: https://issues.apache.org/jira/browse/IO-772
>             Project: Commons IO
>          Issue Type: Bug
>          Components: Utilities
>    Affects Versions: 2.11.0
>            Reporter: Dan Ziemba
>            Priority: Trivial
>
> The Javadoc for IOUtils::resourceToURL (and the String and byte[] variants) says that the "name" parameter is expected to be absolute and is not well defined otherwise. When this is called without a ClassLoader, using an absolute path makes sense as Class::getResource is called against a class that is not the caller's, so a non-absolute path would be looking inside the commons-io package.  But when called with a ClassLoader, instead the ClassLoader::getResource method is called, and using an absolute path with that does not work the same way. 
> For example, both of these work the same for a file sitting at the root of the classpath (src/main/resources in typical Maven/Gradle build):
>  * {{IOUtils.resourceToString("/file.txt");}}
>  * {{IOUtils.resourceToString("file.txt", getClass().getClassLoader());}}
> But this does not work:
>  * {{IOUtils.resourceToString("/file.txt", getClass().getClassLoader());}}
> That behavior is consistent with the explanation in this [accepted StackOverflow answer|[https://stackoverflow.com/a/51645482/1270447].]
> I believe the doc on the method variants that take a ClassLoader should call this out.



--
This message was sent by Atlassian Jira
(v8.20.7#820007)