mukund-thakur commented on a change in pull request #2684: URL: https://github.com/apache/hadoop/pull/2684#discussion_r571829494
########## File path: hadoop-common-project/hadoop-common/src/site/markdown/filesystem/abortable.md ########## @@ -0,0 +1,112 @@ + <!--- + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. See accompanying LICENSE file. +--> + + +<!-- ============================================================= --> +<!-- CLASS: FileSystem --> +<!-- ============================================================= --> + +# interface `org.apache.hadoop.fs.Abortable` + +<!-- MACRO{toc|fromDepth=1|toDepth=2} --> + +Abort the active operation such that the output does not become +manifest. + +Specifically, if supported on an output stream, a successful `abort()` +MUST guarantee that the stream will not be made visible in the close() +operation. + +```java [email protected] [email protected] +public interface Abortable { + void abort(); +} +``` + +## Method `abort()` + +Aborts the ongoing operation such that no output will become visible +when the operation is completed. + +Unless and until other File System classes implement `Abortable`, the +interface is specified purely for output streams. + +## Method `abort()` on an output stream + +`Abortable.abort()` MUST only be supported on output streams +whose output is only made visible when `close()` is called, +for example. output streams returned by the S3A FileSystem. + +## Preconditions + +The stream MUST implement `Abortable` and `StreamCapabilities`. + +```python + if unsupported: + throw UnsupportedException + +if not isOpen(stream): + no-op + +StreamCapabilities.hasCapability("abortable") == True + +``` + + + +## Postconditions + +There is no limit on how long `abortable.abort()` may take; it may +initiate network operations to attempt cancel the upload. + +After `abort()` returns, the filesystem MUST be unchanged: + +``` +FS' = FS +``` + +* Even if any cleanup operations failed, the `abort()` call MUST succeed +to the extent that when the file is closed the output is manifest + +* If is temporary data stored in the local filesystem or in the store's upload +infrastructure then this SHOULD be cleaned up; best-effort is expected here. + +* If any file was present at the destination path, it remains unchanged. + +Strictly then: + +> if `Abortable.abort()` does not raise `UnsupportedOperationException` +> then returns, then it guarantees that the write SHALL NOT become visible Review comment: then -> and ? ---------------------------------------------------------------- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
