public abstract class FileSystem<ResourceIdT extends ResourceId>
extends java.lang.Object
It defines APIs for writing file systems agnostic code.
All methods are protected, and they are for file system providers to implement. Clients should
use the FileSystems
utility.
Constructor and Description |
---|
FileSystem() |
Modifier and Type | Method and Description |
---|---|
protected abstract void |
copy(java.util.List<ResourceIdT> srcResourceIds,
java.util.List<ResourceIdT> destResourceIds)
Copies a
List of file-like resources from one location to another. |
protected abstract java.nio.channels.WritableByteChannel |
create(ResourceIdT resourceId,
CreateOptions createOptions)
Returns a write channel for the given
ResourceIdT . |
protected abstract void |
delete(java.util.Collection<ResourceIdT> resourceIds)
Deletes a collection of resources.
|
protected abstract java.lang.String |
getScheme()
Get the URI scheme which defines the namespace of the
FileSystem . |
protected abstract java.util.List<MatchResult> |
match(java.util.List<java.lang.String> specs)
This is the entry point to convert user-provided specs to
ResourceIds . |
protected abstract ResourceIdT |
matchNewResource(java.lang.String singleResourceSpec,
boolean isDirectory)
Returns a new
ResourceId for this filesystem that represents the named resource. |
protected abstract java.nio.channels.ReadableByteChannel |
open(ResourceIdT resourceId)
Returns a read channel for the given
ResourceIdT . |
protected abstract void |
rename(java.util.List<ResourceIdT> srcResourceIds,
java.util.List<ResourceIdT> destResourceIds,
MoveOptions... moveOptions)
Renames a
List of file-like resources from one location to another. |
protected void |
reportLineage(ResourceIdT unusedId,
Lineage unusedLineage)
Report
Lineage metrics for resource id. |
protected abstract java.util.List<MatchResult> match(java.util.List<java.lang.String> specs) throws java.io.IOException
ResourceIds
.
Callers should use match(java.util.List<java.lang.String>)
to resolve users specs ambiguities before calling other
methods.
Implementation should handle the following ambiguities of a user-provided spec:
spec
could be a glob or a uri. match(java.util.List<java.lang.String>)
should be able to tell and choose
efficient implementations.
spec
might refer to files or directories. It is common that
users that wish to indicate a directory will omit the trailing /
, such as in a
spec of "/tmp/dir"
. The FileSystem
should be able to recognize a
directory with the trailing /
omitted, but should always return a correct ResourceIdT
(e.g., "/tmp/dir/"
inside the returned MatchResult
.
All FileSystem
implementations should support glob in the final hierarchical path
component of ResourceIdT
. This allows SDK libraries to construct file system agnostic
spec. FileSystems
can support additional patterns for user-provided specs.
List<MatchResult>
in the same order of the input specs.java.lang.IllegalArgumentException
- if specs are invalid.java.io.IOException
- if all specs failed to match due to issues like: network connection,
authorization. Exception for individual spec need to be deferred until callers retrieve
metadata with MatchResult.metadata()
.protected abstract java.nio.channels.WritableByteChannel create(ResourceIdT resourceId, CreateOptions createOptions) throws java.io.IOException
ResourceIdT
.
The resource is not expanded; it is used verbatim.
resourceId
- the reference of the file-like resource to createcreateOptions
- the configuration of the create operationjava.io.IOException
protected abstract java.nio.channels.ReadableByteChannel open(ResourceIdT resourceId) throws java.io.IOException
ResourceIdT
.
The resource is not expanded; it is used verbatim.
If seeking is supported, then this returns a SeekableByteChannel
.
resourceId
- the reference of the file-like resource to openjava.io.IOException
protected abstract void copy(java.util.List<ResourceIdT> srcResourceIds, java.util.List<ResourceIdT> destResourceIds) throws java.io.IOException
List
of file-like resources from one location to another.
The number of source resources must equal the number of destination resources. Destination resources will be created recursively.
srcResourceIds
- the references of the source resourcesdestResourceIds
- the references of the destination resourcesjava.io.FileNotFoundException
- if the source resources are missing. When copy throws, each
resource might or might not be copied. In such scenarios, callers can use match()
to determine the state of the resources.java.io.IOException
protected abstract void rename(java.util.List<ResourceIdT> srcResourceIds, java.util.List<ResourceIdT> destResourceIds, MoveOptions... moveOptions) throws java.io.IOException
List
of file-like resources from one location to another.
The number of source resources must equal the number of destination resources. Destination resources will be created recursively.
srcResourceIds
- the references of the source resourcesdestResourceIds
- the references of the destination resourcesmoveOptions
- move options specifying handling of error conditionsjava.lang.UnsupportedOperationException
- if move options are specified and not supported by the
FileSystemjava.io.FileNotFoundException
- if the source resources are missing. When rename throws, the
state of the resources is unknown but safe: for every (source, destination) pair of
resources, the following are possible: a) source exists, b) destination exists, c) source
and destination both exist. Thus no data is lost, however, duplicated resource are
possible. In such scenarios, callers can use match()
to determine the state of the
resource.java.io.IOException
protected abstract void delete(java.util.Collection<ResourceIdT> resourceIds) throws java.io.IOException
resourceIds
- the references of the resources to delete.java.io.FileNotFoundException
- if resources are missing. When delete throws, each resource might
or might not be deleted. In such scenarios, callers can use match()
to determine
the state of the resources.java.io.IOException
protected abstract ResourceIdT matchNewResource(java.lang.String singleResourceSpec, boolean isDirectory)
ResourceId
for this filesystem that represents the named resource. The
user supplies both the resource spec and whether it is a directory.
The supplied singleResourceSpec
is expected to be in a proper format, including any
necessary escaping, for this FileSystem
.
This function may throw an IllegalArgumentException
if given an invalid argument,
such as when the specified singleResourceSpec
is not a valid resource name.
protected abstract java.lang.String getScheme()
FileSystem
.protected void reportLineage(ResourceIdT unusedId, Lineage unusedLineage)
Lineage
metrics for resource id.
Unless override by FileSystem implementations, default to no-op.