hadoop-yetus commented on a change in pull request #743: HADOOP-11452 make
rename/3 public
URL: https://github.com/apache/hadoop/pull/743#discussion_r279596433
##########
File path:
hadoop-common-project/hadoop-common/src/site/markdown/filesystem/filesystem.md
##########
@@ -1211,9 +1224,184 @@ HDFS fails without raising an exception; `rename()`
merely returns false.
FS' = FS
result = false
-The behavior of HDFS here should not be considered a feature to replicate.
-`FileContext` explicitly changed the behavior to raise an exception, and the
retrofitting of that action
-to the `DFSFileSystem` implementation is an ongoing matter for debate.
+The behavior of HDFS here must not be considered a feature to replicate.
+
+
+### `void rename(Path source, Path dest, Rename...options)`
+
+This is a stricter version of `rename(src, dest)`, which:
+
+1. Defines the policy on overwriting paths.
+1. Defines the policy on nonexistent source paths.
+1. MUST raise an exception on all failure conditions.
+1. Has no return code. If the method does not raise an exception, it has
+succeeded.
+
+The semantics of this method are simpler and more clearly defined.
+
+- The final path of the rename is always that of the `dest` argument; there
+is no attempt to generate a new path underneath a target directory.
+- If that destination exists, unless the `Rename.OVERWRITE` is set, an
exception
+is raised.
+- The parent directory MUST exist.
+
+This avoids the "quirks" of `rename(source, dest)` where the behaviour
+of the rename depends on the type and state of the destination.
+
+
+The `Rename` enumeration has three values:
+
+* `NONE`: This is a no-op entry.
+* `OVERWRITE`: overwrite any destination file or empty destination directory.
+* `TRASH`: flag to indicate that the destination is the trash portion of
+ the filesystem. This flag is used in HDFS to verify that the caller has
+ the appropriate delete permission as well as the rename permission.
+
+As multiple entries can be supplied, all probes for features are done by
+checking for the specific flag in the options list. There is no requirement of
+ordering, and it is not an error if there are duplicate entries.
+
+```python
+let overwrite = Rename.OVERWRITE in options
+```
+
+#### Preconditions
+
+Source `source` MUST exist:
+
+```python
+exists(FS, source) else raise FileNotFoundException
+```
+
+
+`source` MUST NOT be root:
+
+```python
+if isRoot(FS, source)): raise IOException
+```
+
+`dest` MUST NOT equal `source`
+
+```python
+source != dest else raise FileAlreadyExistsException
+```
+
+`dest` MUST NOT be a descendant of `source`:
+
+```python
+if isDescendant(FS, source, dest) : raise IOException
+```
+
+`dest` MUST NOT be root:
+
+```python
+if isRoot(FS, dest)): raise IOException
+```
+
+
+The parent directory of `dest` MUST exist:
+
+```python
+exists(FS, parent(dest)) else raise FileNotFoundException
+```
+
+
+The parent path of a destination MUST be a directory:
+
+```python
+isDirectory(FS, parent(dest)) else raise ParentNotDirectoryException
+```
+
+This implicitly covers all the ancestors of the parent.
+
+If `dest` exists the type of the entry MUST match
+that of the source.
+
+```python
+if exists(FS, dest) and isFile(FS, dest) and not isFile(FS, src): raise
IOException
+if exists(FS, dest) and isDirectory(FS, dest) and not isDirectory(FS, src):
raise IOException
+```
+
+
+There must be not be an existing file at the end of the destination path unless
+`Rename.OVERWRITE` was set.
+
+```python
+if isFile(FS, dest) and not overwrite: raise FileAlreadyExistsException
+```
+
+
+If the source is a directory, there must be not be an existing directory at
the end of
+the destination path unless `Rename.OVERWRITE` was set.
+
+```python
+if isDirectory(FS, dest) and not overwrite and isDirectory(FS, source): raise
FileAlreadyExistsException
+```
+
+
+
+If there is a directory at the end of the path, it must be empty:
+
+```python
+if isDirectory(FS, source) and isDirectory(FS, dest) and len(listStatus(FS,
dest)) > 0:
+ raise IOException
+```
+
+Note how this is different from `rename(src, dest)`.
+
+
+#### Postconditions
+
+##### Renaming a file onto an empty path or an existing file
+
+Renaming a file to a path where there is no entry moves the file to the
+destination path. If the destination exists, the operation MUST fail unless the
+`overwrite` option is not set. If `overwrite` is set the semantics are the same
+as renaming onto an empty path.
+
+```python
+if isFile(FS, source) and not exists(dest) or (isFile(dest) and overwrite):
+ FS' where:
+ exists(FS', dest)
+ and data(FS', dest) == data(FS, source)
+ and not exists(FS', source)
+```
+
+##### Renaming a directory
+
+If `source` is a directory then all its children will then exist under `dest`,
while the path
+`source` and its descendants will no longer exist. The names of the paths under
+`dest` will match those under `source`, as will the contents:
+
+```python
+if isDirectory(FS, source) :
+ FS' where:
+ isDirectory(FS, dest)
+ and forall c in descendants(FS, source) where isDirectory(FS, c):
+ isDirectory(FS', dest + childElements(source, c))
+ and forall c in descendants(FS, source) where not isDirectory(FS, c):
+ data(FS', dest + childElements(s, c)) == data(FS, c)
+ and not exists(FS', source)
+ and forall c in descendants(FS, source):
+ not exists(FS', c))
+```
+
+##### Concurrency requirements
+
+* The core operation of `rename()`, moving one entry in the filesystem to
+another, SHOULD be atomic. Many applications rely on this as a way to commit
operations.
+
+* However, the base implementation is *not* atomic; some of the precondition
checks
+are performed separately.
Review comment:
whitespace:end of line
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
