[
https://issues.apache.org/jira/browse/HDFS-5387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Leif Wickland updated HDFS-5387:
--------------------------------
Description:
The documentation for FileSystem.createNewFile() indicates that it will return
false if it failed to create the requested file. In fact, it will only return
false if the file existed before the function was called. Also the function
fails to mention that a race condition can result in an exception be thrown if
another process attempts to create the file at the same time.
Here's my suggested improvement to the documentation's wording:
{code}
/**
- * Creates the given Path as a brand-new zero-length file. If
- * create fails, or if it already existed, return false.
- *
+ * Creates the given Path as a brand-new zero-length file.
+ * A race condition can occur inside this function if f is created by another
+ * process after this function has checked for the existence of f. In some
+ * implementations that will result in an exception being thrown.
* @param f path to use for create
+ * @return true if the file was created; false if the path already exists.
+ * @throws IOException
*/
public boolean createNewFile(Path f) throws IOException {
{code}
The same change is attached as a patch.
was:
The documentation for FileSystem.createNewFile() indicates that it will return
false if it failed to create the requested file. In fact, it will only return
false if the file existed before the function was called. Also the function
fails to mention that a race condition can result in an exception be thrown if
another process attempts to create the file at the same time.
Here's my suggested improvement to the documentation's wording:
{code}
/**
- * Creates the given Path as a brand-new zero-length file. If
- * create fails, or if it already existed, return false.
- *
+ * Creates the given Path as a brand-new zero-length file.
+ * A race condition can occur inside this function if f is created by another
+ * process after this function has checked for the existence of f. In some
+ * implementations that will result in an exception being thrown.
* @param f path to use for create
+ * @return true if the file was created; false if the path already exists.
+ * @throws IOException
*/
public boolean createNewFile(Path f) throws IOException {
{code}
> Documentation on FileSystem.createNewFile() is misleading
> ---------------------------------------------------------
>
> Key: HDFS-5387
> URL: https://issues.apache.org/jira/browse/HDFS-5387
> Project: Hadoop HDFS
> Issue Type: Improvement
> Reporter: Leif Wickland
> Priority: Trivial
> Attachments: FileSystem.java.patch
>
>
> The documentation for FileSystem.createNewFile() indicates that it will
> return false if it failed to create the requested file. In fact, it will
> only return false if the file existed before the function was called. Also
> the function fails to mention that a race condition can result in an
> exception be thrown if another process attempts to create the file at the
> same time.
> Here's my suggested improvement to the documentation's wording:
> {code}
> /**
> - * Creates the given Path as a brand-new zero-length file. If
> - * create fails, or if it already existed, return false.
> - *
> + * Creates the given Path as a brand-new zero-length file.
> + * A race condition can occur inside this function if f is created by
> another
> + * process after this function has checked for the existence of f. In some
> + * implementations that will result in an exception being thrown.
> * @param f path to use for create
> + * @return true if the file was created; false if the path already exists.
> + * @throws IOException
> */
> public boolean createNewFile(Path f) throws IOException {
> {code}
> The same change is attached as a patch.
--
This message was sent by Atlassian JIRA
(v6.1#6144)
