alluxio.client.file

Interface FileSystem

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

BaseFileSystem, DelegatingFileSystem, FileSystemCache.InstanceCachingFileSystem, LocalCacheFileSystem, MetadataCachingBaseFileSystem

@PublicApi
public interface FileSystem
extends Closeable

Basic file system interface supporting metadata operations and data operations. Developers should not implement this class but extend the default implementation provided by BaseFileSystem instead. This ensures any new methods added to the interface will be provided by the default implementation.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	FileSystem.Factory Factory for FileSystem.

Method Summary

Modifier and Type	Method and Description
void	checkAccess(AlluxioURI path, CheckAccessPOptions options) Checks access to a path.
default void	createDirectory(AlluxioURI path) Convenience method for createDirectory(AlluxioURI, CreateDirectoryPOptions) with default options.
void	createDirectory(AlluxioURI path, CreateDirectoryPOptions options) Creates a directory.
default FileOutStream	createFile(AlluxioURI path) Convenience method for createFile(AlluxioURI, CreateFilePOptions) with default options.
FileOutStream	createFile(AlluxioURI path, CreateFilePOptions options) Creates a file.
default void	delete(AlluxioURI path) Convenience method for delete(AlluxioURI, DeletePOptions) with default options.
void	delete(AlluxioURI path, DeletePOptions options) Deletes a file or a directory.
default boolean	exists(AlluxioURI path) Convenience method for exists(AlluxioURI, ExistsPOptions) with default options.
boolean	exists(AlluxioURI path, ExistsPOptions options) Checks whether a path exists in Alluxio space.
default void	free(AlluxioURI path) Convenience method for free(AlluxioURI, FreePOptions) with default options.
void	free(AlluxioURI path, FreePOptions options) Evicts any data under the given path from Alluxio space, but does not delete the data from the UFS.
List<BlockLocationInfo>	getBlockLocations(AlluxioURI path) Builds a list of BlockLocationInfo for the given file.
AlluxioConfiguration	getConf()
Map<String,MountPointInfo>	getMountTable() Lists all mount points and their corresponding under storage addresses.
default URIStatus	getStatus(AlluxioURI path) Convenience method for getStatus(AlluxioURI, GetStatusPOptions) with default options.
URIStatus	getStatus(AlluxioURI path, GetStatusPOptions options) Gets the URIStatus object that represents the metadata of an Alluxio path.
List<SyncPointInfo>	getSyncPathList() Lists all the actively synced paths.
boolean	isClosed() If there are operations currently running and close is called concurrently the behavior is undefined.
default void	iterateStatus(AlluxioURI path, java.util.function.Consumer<? super URIStatus> action) Performs a specific action on each URIStatus in the result of listStatus(alluxio.AlluxioURI).
void	iterateStatus(AlluxioURI path, ListStatusPOptions options, java.util.function.Consumer<? super URIStatus> action) Performs a specific action on each URIStatus in the result of listStatus(alluxio.AlluxioURI).
default List<URIStatus>	listStatus(AlluxioURI path) Convenience method for listStatus(AlluxioURI, ListStatusPOptions) with default options.
List<URIStatus>	listStatus(AlluxioURI path, ListStatusPOptions options) If the path is a directory, returns the URIStatus of all the direct entries in it.
default void	loadMetadata(AlluxioURI path) Convenience method for loadMetadata(AlluxioURI, ListStatusPOptions) with default options.
void	loadMetadata(AlluxioURI path, ListStatusPOptions options) Loads metadata about a path in the UFS to Alluxio.
default void	mount(AlluxioURI alluxioPath, AlluxioURI ufsPath) Convenience method for mount(AlluxioURI, AlluxioURI, MountPOptions) with default options.
void	mount(AlluxioURI alluxioPath, AlluxioURI ufsPath, MountPOptions options) Mounts a UFS subtree to the given Alluxio path.
default FileInStream	openFile(AlluxioURI path) Convenience method for openFile(AlluxioURI, OpenFilePOptions) with default options.
FileInStream	openFile(AlluxioURI path, OpenFilePOptions options) Opens a file for reading.
FileInStream	openFile(URIStatus status, OpenFilePOptions options) Opens a file for reading.
default void	persist(AlluxioURI path) Convenience method for persist(AlluxioURI, ScheduleAsyncPersistencePOptions) which uses the default ScheduleAsyncPersistencePOptions.
void	persist(AlluxioURI path, ScheduleAsyncPersistencePOptions options) Schedules the given path to be asynchronously persisted to the under file system.
default void	rename(AlluxioURI src, AlluxioURI dst) Convenience method for rename(AlluxioURI, AlluxioURI, RenamePOptions) with default options.
void	rename(AlluxioURI src, AlluxioURI dst, RenamePOptions options) Renames an existing Alluxio path to another Alluxio path in Alluxio.
AlluxioURI	reverseResolve(AlluxioURI ufsUri) Reverse resolve a ufs uri.
default void	setAcl(AlluxioURI path, SetAclAction action, List<AclEntry> entries) Convenience method for setAcl(AlluxioURI, SetAclAction, List, SetAclPOptions) with default options.
void	setAcl(AlluxioURI path, SetAclAction action, List<AclEntry> entries, SetAclPOptions options) Sets the ACL for a path.
default void	setAttribute(AlluxioURI path) Convenience method for setAttribute(AlluxioURI, SetAttributePOptions) with default options.
void	setAttribute(AlluxioURI path, SetAttributePOptions options) Sets any number of a path's attributes, such as TTL and pin status.
void	startSync(AlluxioURI path) Starts the active syncing process on an Alluxio path.
void	stopSync(AlluxioURI path) Stops the active syncing process on an Alluxio path.
default void	unmount(AlluxioURI path) Convenience method for unmount(AlluxioURI, UnmountPOptions) with default options.
void	unmount(AlluxioURI path, UnmountPOptions options) Unmounts a UFS subtree identified by the given Alluxio path.
void	updateMount(AlluxioURI alluxioPath, MountPOptions options) Updates the options for an existing mount point.

Methods inherited from interface java.io.Closeable

close

Method Detail

isClosed

boolean isClosed()

If there are operations currently running and close is called concurrently the behavior is undefined. After closing a FileSystem, any operations that are performed result in undefined behavior.

Returns:

whether or not this FileSystem has been closed

checkAccess

void checkAccess(AlluxioURI path,
                 CheckAccessPOptions options)
          throws InvalidPathException,
                 IOException,
                 AlluxioException

Checks access to a path.

Parameters:

path - the path of the directory to create in Alluxio space

options - options to associate with this operation

Throws:

InvalidPathException - if the path is invalid

AccessControlException - if the access is denied

IOException

AlluxioException

createDirectory

default void createDirectory(AlluxioURI path)
                      throws FileAlreadyExistsException,
                             InvalidPathException,
                             IOException,
                             AlluxioException

Convenience method for createDirectory(AlluxioURI, CreateDirectoryPOptions) with default options.

Parameters:

path - the path of the directory to create in Alluxio space

Throws:

FileAlreadyExistsException - if there is already a file or directory at the given path

InvalidPathException - if the path is invalid

IOException

AlluxioException

createDirectory

void createDirectory(AlluxioURI path,
                     CreateDirectoryPOptions options)
              throws FileAlreadyExistsException,
                     InvalidPathException,
                     IOException,
                     AlluxioException

Creates a directory.

Parameters:

path - the path of the directory to create in Alluxio space

options - options to associate with this operation

Throws:

FileAlreadyExistsException - if there is already a file or directory at the given path

InvalidPathException - if the path is invalid

IOException

AlluxioException

createFile

default FileOutStream createFile(AlluxioURI path)
                          throws FileAlreadyExistsException,
                                 InvalidPathException,
                                 IOException,
                                 AlluxioException

Convenience method for createFile(AlluxioURI, CreateFilePOptions) with default options.

Parameters:

path - the path of the file to create in Alluxio space

Returns:

a FileOutStream which will write data to the newly created file

Throws:

FileAlreadyExistsException - if there is already a file at the given path

InvalidPathException - if the path is invalid

IOException

AlluxioException

createFile

FileOutStream createFile(AlluxioURI path,
                         CreateFilePOptions options)
                  throws FileAlreadyExistsException,
                         InvalidPathException,
                         IOException,
                         AlluxioException

Creates a file.

Parameters:

path - the path of the file to create in Alluxio space

options - options to associate with this operation

Returns:

a FileOutStream which will write data to the newly created file

Throws:

FileAlreadyExistsException - if there is already a file at the given path

InvalidPathException - if the path is invalid

IOException

AlluxioException

delete

default void delete(AlluxioURI path)
             throws DirectoryNotEmptyException,
                    FileDoesNotExistException,
                    IOException,
                    AlluxioException

Convenience method for delete(AlluxioURI, DeletePOptions) with default options.

Parameters:

path - the path to delete in Alluxio space

Throws:

FileDoesNotExistException - if the given path does not exist

DirectoryNotEmptyException - if recursive is false and the path is a nonempty directory

IOException

AlluxioException

delete

void delete(AlluxioURI path,
            DeletePOptions options)
     throws DirectoryNotEmptyException,
            FileDoesNotExistException,
            IOException,
            AlluxioException

Deletes a file or a directory.

Parameters:

path - the path to delete in Alluxio space

options - options to associate with this operation

Throws:

FileDoesNotExistException - if the given path does not exist

DirectoryNotEmptyException - if recursive is false and the path is a nonempty directory

IOException

AlluxioException

exists

default boolean exists(AlluxioURI path)
                throws InvalidPathException,
                       IOException,
                       AlluxioException

Convenience method for exists(AlluxioURI, ExistsPOptions) with default options.

Parameters:

path - the path in question

Returns:

true if the path exists, false otherwise

Throws:

InvalidPathException - if the path is invalid

IOException

AlluxioException

exists

boolean exists(AlluxioURI path,
               ExistsPOptions options)
        throws InvalidPathException,
               IOException,
               AlluxioException

Checks whether a path exists in Alluxio space.

Parameters:

path - the path in question

options - options to associate with this operation

Returns:

true if the path exists, false otherwise

Throws:

InvalidPathException - if the path is invalid

IOException

AlluxioException

free

default void free(AlluxioURI path)
           throws FileDoesNotExistException,
                  IOException,
                  AlluxioException

Convenience method for free(AlluxioURI, FreePOptions) with default options.

Parameters:

path - the path to free in Alluxio space

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

free

void free(AlluxioURI path,
          FreePOptions options)
   throws FileDoesNotExistException,
          IOException,
          AlluxioException

Evicts any data under the given path from Alluxio space, but does not delete the data from the UFS. The metadata will still be present in Alluxio space after this operation.

Parameters:

path - the path to free in Alluxio space

options - options to associate with this operation

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

getBlockLocations

List<BlockLocationInfo> getBlockLocations(AlluxioURI path)
                                   throws FileDoesNotExistException,
                                          IOException,
                                          AlluxioException

Builds a list of BlockLocationInfo for the given file. Each list item contains a list of WorkerNetAddress which allows a user to determine the physical location of a block of the given file stored within Alluxio. In the case where data is stored in a UFS, but not in Alluxio this function will only include a WorkerNetAddress if the block stored in the UFS is co-located with an Alluxio worker. However if there are no co-located Alluxio workers for the block, then the behavior is controlled by the PropertyKey.USER_UFS_BLOCK_LOCATION_ALL_FALLBACK_ENABLED . If this property is set to true then every Alluxio worker will be returned. Blocks which are stored in the UFS and are *not* co-located with any Alluxio worker will return an empty list. If the file block is within Alluxio *and* the UFS then this will only return Alluxio workers which currently store the block.

Parameters:

path - the path to get block info for

Returns:

a list of blocks with the workers whose hosts have the blocks. The blocks may not necessarily be stored in Alluxio. The blocks are returned in the order of their sequences in file.

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

getConf

AlluxioConfiguration getConf()

Returns:

the configuration which the FileSystem is using to connect to Alluxio

getStatus

default URIStatus getStatus(AlluxioURI path)
                     throws FileDoesNotExistException,
                            IOException,
                            AlluxioException

Convenience method for getStatus(AlluxioURI, GetStatusPOptions) with default options.

Parameters:

path - the path to obtain information about

Returns:

the URIStatus of the file

Throws:

FileDoesNotExistException - if the path does not exist

IOException

AlluxioException

getStatus

URIStatus getStatus(AlluxioURI path,
                    GetStatusPOptions options)
             throws FileDoesNotExistException,
                    IOException,
                    AlluxioException

Gets the URIStatus object that represents the metadata of an Alluxio path.

Parameters:

path - the path to obtain information about

options - options to associate with this operation

Returns:

the URIStatus of the file

Throws:

FileDoesNotExistException - if the path does not exist

IOException

AlluxioException

iterateStatus

default void iterateStatus(AlluxioURI path,
                           java.util.function.Consumer<? super URIStatus> action)
                    throws FileDoesNotExistException,
                           IOException,
                           AlluxioException

Performs a specific action on each URIStatus in the result of listStatus(alluxio.AlluxioURI). This method is preferred when iterating over directories with a large number of files or sub-directories inside. The caller can proceed with partial result without waiting for all result returned.

Parameters:

path - the path to list information about

action - action to apply on each URIStatus

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

iterateStatus

void iterateStatus(AlluxioURI path,
                   ListStatusPOptions options,
                   java.util.function.Consumer<? super URIStatus> action)
            throws FileDoesNotExistException,
                   IOException,
                   AlluxioException

Performs a specific action on each URIStatus in the result of listStatus(alluxio.AlluxioURI). This method is preferred when iterating over directories with a large number of files or sub-directories inside. The caller can proceed with partial result without waiting for all result returned.

Parameters:

path - the path to list information about

options - options to associate with this operation

action - action to apply on each URIStatus

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

listStatus

default List<URIStatus> listStatus(AlluxioURI path)
                            throws FileDoesNotExistException,
                                   IOException,
                                   AlluxioException

Convenience method for listStatus(AlluxioURI, ListStatusPOptions) with default options.

Parameters:

path - the path to list information about

Returns:

a list of URIStatuss containing information about the files and directories which are children of the given path

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

listStatus

List<URIStatus> listStatus(AlluxioURI path,
                           ListStatusPOptions options)
                    throws FileDoesNotExistException,
                           IOException,
                           AlluxioException

If the path is a directory, returns the URIStatus of all the direct entries in it. Otherwise returns a list with a single URIStatus element for the file.

Parameters:

path - the path to list information about

options - options to associate with this operation

Returns:

a list of URIStatuss containing information about the files and directories which are children of the given path

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

loadMetadata

default void loadMetadata(AlluxioURI path)
                   throws FileDoesNotExistException,
                          IOException,
                          AlluxioException

Convenience method for loadMetadata(AlluxioURI, ListStatusPOptions) with default options.

Parameters:

path - the path for which to load metadata from UFS

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

loadMetadata

void loadMetadata(AlluxioURI path,
                  ListStatusPOptions options)
           throws FileDoesNotExistException,
                  IOException,
                  AlluxioException

Loads metadata about a path in the UFS to Alluxio. No data will be transferred.

Parameters:

path - the path for which to load metadata from UFS

options - options to associate with this operation

Throws:

FileDoesNotExistException - if the given path does not exist

IOException

AlluxioException

mount

default void mount(AlluxioURI alluxioPath,
                   AlluxioURI ufsPath)
            throws IOException,
                   AlluxioException

Convenience method for mount(AlluxioURI, AlluxioURI, MountPOptions) with default options.

Parameters:

alluxioPath - an Alluxio path to mount the data to

ufsPath - a UFS path to mount the data from

Throws:

IOException

AlluxioException

mount

void mount(AlluxioURI alluxioPath,
           AlluxioURI ufsPath,
           MountPOptions options)
    throws IOException,
           AlluxioException

Mounts a UFS subtree to the given Alluxio path. The Alluxio path is expected not to exist as the method creates it. If the path already exists, a AlluxioException will be thrown. This method does not transfer any data or metadata from the UFS. It simply establishes the connection between the given Alluxio path and UFS path.

Parameters:

alluxioPath - an Alluxio path to mount the data to

ufsPath - a UFS path to mount the data from

options - options to associate with this operation

Throws:

IOException

AlluxioException

updateMount

void updateMount(AlluxioURI alluxioPath,
                 MountPOptions options)
          throws IOException,
                 AlluxioException

Updates the options for an existing mount point.

Parameters:

alluxioPath - the Alluxio path of the mount point

options - options for this mount point

Throws:

IOException

AlluxioException

getMountTable

Map<String,MountPointInfo> getMountTable()
                                  throws IOException,
                                         AlluxioException

Lists all mount points and their corresponding under storage addresses.

Returns:

a map from String to MountPointInfo

Throws:

IOException

AlluxioException

getSyncPathList

List<SyncPointInfo> getSyncPathList()
                             throws IOException,
                                    AlluxioException

Lists all the actively synced paths.

Returns:

a list of actively synced paths

Throws:

IOException

AlluxioException

openFile

default FileInStream openFile(AlluxioURI path)
                       throws FileDoesNotExistException,
                              OpenDirectoryException,
                              FileIncompleteException,
                              IOException,
                              AlluxioException

Convenience method for openFile(AlluxioURI, OpenFilePOptions) with default options.

Parameters:

path - the file to read from

Returns:

a FileInStream for the given path

Throws:

FileDoesNotExistException - when path does not exist

OpenDirectoryException - when path is a directory

FileIncompleteException - when path is a file and is not completed yet

IOException

AlluxioException

openFile

FileInStream openFile(AlluxioURI path,
                      OpenFilePOptions options)
               throws FileDoesNotExistException,
                      OpenDirectoryException,
                      FileIncompleteException,
                      IOException,
                      AlluxioException

Opens a file for reading.

Parameters:

path - the file to read from

options - options to associate with this operation

Returns:

a FileInStream for the given path

Throws:

FileDoesNotExistException - when path does not exist

OpenDirectoryException - when path is a directory

FileIncompleteException - when path is a file and is not completed yet

IOException

AlluxioException

openFile

FileInStream openFile(URIStatus status,
                      OpenFilePOptions options)
               throws FileDoesNotExistException,
                      OpenDirectoryException,
                      FileIncompleteException,
                      IOException,
                      AlluxioException

Opens a file for reading.

Parameters:

status - status of the file to read from

options - options to associate with this operation

Returns:

a FileInStream for the given path

Throws:

FileDoesNotExistException - when path does not exist

OpenDirectoryException - when path is a directory

FileIncompleteException - when path is a file and is not completed yet

IOException

AlluxioException

persist

default void persist(AlluxioURI path)
              throws FileDoesNotExistException,
                     IOException,
                     AlluxioException

Convenience method for persist(AlluxioURI, ScheduleAsyncPersistencePOptions) which uses the default ScheduleAsyncPersistencePOptions.

Parameters:

path - the uri of the file to persist

Throws:

FileDoesNotExistException

IOException

AlluxioException

persist

void persist(AlluxioURI path,
             ScheduleAsyncPersistencePOptions options)
      throws FileDoesNotExistException,
             IOException,
             AlluxioException

Schedules the given path to be asynchronously persisted to the under file system. To persist synchronously please see FileSystemUtils.persistAndWait(FileSystem, AlluxioURI, long).

Parameters:

path - the uri of the file to persist

options - the options to use when submitting persist the path

Throws:

FileDoesNotExistException

IOException

AlluxioException

rename

default void rename(AlluxioURI src,
                    AlluxioURI dst)
             throws FileDoesNotExistException,
                    IOException,
                    AlluxioException

Convenience method for rename(AlluxioURI, AlluxioURI, RenamePOptions) with default options.

Parameters:

src - the path of the source, this must already exist

dst - the path of the destination, this path should not exist

Throws:

FileDoesNotExistException - if the given file does not exist

IOException

AlluxioException

rename

void rename(AlluxioURI src,
            AlluxioURI dst,
            RenamePOptions options)
     throws FileDoesNotExistException,
            IOException,
            AlluxioException

Renames an existing Alluxio path to another Alluxio path in Alluxio. This operation will be propagated in the underlying storage if the path is persisted.

Parameters:

src - the path of the source, this must already exist

dst - the path of the destination, this path should not exist

options - options to associate with this operation

Throws:

FileDoesNotExistException - if the given file does not exist

IOException

AlluxioException

reverseResolve

AlluxioURI reverseResolve(AlluxioURI ufsUri)
                   throws IOException,
                          AlluxioException

Reverse resolve a ufs uri.

Parameters:

ufsUri - the ufs uri

Returns:

the alluxio path for the ufsUri

Throws:

AlluxioStatusException

IOException

AlluxioException

setAcl

default void setAcl(AlluxioURI path,
                    SetAclAction action,
                    List<AclEntry> entries)
             throws FileDoesNotExistException,
                    IOException,
                    AlluxioException

Convenience method for setAcl(AlluxioURI, SetAclAction, List, SetAclPOptions) with default options.

Parameters:

path - the path to set the ACL for

action - the set action to perform

entries - the ACL entries

Throws:

FileDoesNotExistException - if the given file does not exist

IOException

AlluxioException

setAcl

void setAcl(AlluxioURI path,
            SetAclAction action,
            List<AclEntry> entries,
            SetAclPOptions options)
     throws FileDoesNotExistException,
            IOException,
            AlluxioException

Sets the ACL for a path.

Parameters:

path - the path to set the ACL for

action - the set action to perform

entries - the ACL entries

options - options to associate with this operation

Throws:

FileDoesNotExistException - if the given file does not exist

IOException

AlluxioException

startSync

void startSync(AlluxioURI path)
        throws FileDoesNotExistException,
               IOException,
               AlluxioException

Starts the active syncing process on an Alluxio path.

Parameters:

path - the path to sync

Throws:

FileDoesNotExistException

IOException

AlluxioException

stopSync

void stopSync(AlluxioURI path)
       throws FileDoesNotExistException,
              IOException,
              AlluxioException

Stops the active syncing process on an Alluxio path.

Parameters:

path - the path to stop syncing

Throws:

FileDoesNotExistException

IOException

AlluxioException

setAttribute

default void setAttribute(AlluxioURI path)
                   throws FileDoesNotExistException,
                          IOException,
                          AlluxioException

Convenience method for setAttribute(AlluxioURI, SetAttributePOptions) with default options.

Parameters:

path - the path to set attributes for

Throws:

FileDoesNotExistException - if the given file does not exist

IOException

AlluxioException

setAttribute

void setAttribute(AlluxioURI path,
                  SetAttributePOptions options)
           throws FileDoesNotExistException,
                  IOException,
                  AlluxioException

Sets any number of a path's attributes, such as TTL and pin status.

Parameters:

path - the path to set attributes for

options - options to associate with this operation

Throws:

FileDoesNotExistException - if the given file does not exist

IOException

AlluxioException

unmount

default void unmount(AlluxioURI path)
              throws IOException,
                     AlluxioException

Convenience method for unmount(AlluxioURI, UnmountPOptions) with default options.

Parameters:

path - an Alluxio path, this must be a mount point

Throws:

IOException

AlluxioException

unmount

void unmount(AlluxioURI path,
             UnmountPOptions options)
      throws IOException,
             AlluxioException

Unmounts a UFS subtree identified by the given Alluxio path. The Alluxio path match a previously mounted path. The contents of the subtree rooted at this path are removed from Alluxio but the corresponding UFS subtree is left untouched.

Parameters:

path - an Alluxio path, this must be a mount point

options - options to associate with this operation

Throws:

IOException

AlluxioException