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.
@InterfaceAudience.Public @InterfaceStability.Unstable public interface Abortable { /** * Abort the active operation without the output becoming visible. * * This is to provide ability to cancel the write on stream; once * a stream is aborted, the write MUST NOT become visible. * * @throws UnsupportedOperationException if the operation is not supported. * @return the result. */ AbortableResult abort(); /** * Interface for the result of aborts; allows subclasses to extend * (IOStatistics etc) or for future enhancements if ever needed. */ interface AbortableResult { /** * Was the stream already closed/aborted? * @return true if a close/abort operation had already * taken place. */ boolean alreadyClosed(); /** * Any exception caught during cleanup operations, * exceptions whose raising/catching does not change * the semantics of the abort. * @return an exception or null. */ IOException anyCleanupException(); } }
Aborts the ongoing operation such that no output SHALL become visible when the operation is completed.
Unless and until other File System classes implement Abortable, the interface is specified purely for output streams.
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.
The stream MUST implement Abortable and StreamCapabilities.
if unsupported: throw UnsupportedException if not isOpen(stream): no-op StreamCapabilities.hasCapability("fs.capability.outputstream.abortable") == True
After abort() returns, the filesystem MUST be unchanged:
FS' = FS
A successful abort() operation MUST guarantee that when the streamclose() is invoked no output shall be manifest.
Strictly then:
if Abortable.abort() does not raise UnsupportedOperationException then returns, then it guarantees that the write SHALL NOT become visible and that any existing data in the filesystem at the destination path SHALL continue to be available.
That is, the postconditions of close() becomes:
FS' = FS
An application MUST be able to verify that a stream supports the Abortable.abort() operation without actually calling it. This is done through the StreamCapabilities interface.
If a stream instance supports Abortable then it MUST return true in the probe hasCapability("fs.capability.outputstream.abortable")
If a stream instance does not support Abortable then it MUST return false in the probe hasCapability("fs.capability.outputstream.abortable")
That is: if a stream declares its support for the feature, a call to abort() SHALL meet the defined semantics of the operation.
FileSystem/FileContext implementations SHOULD declare support similarly, to allow for applications to probe for the feature in the destination directory/path.
If a filesystem supports Abortable under a path P then it SHOULD return true to PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable") This is to allow applications to verify that the store supports the feature.
If a filesystem does not support Abortable under a path P then it MUST return false to PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")