public final class FileClient extends Object
Path
objects
only point to a (possible) location in an associated
file system. A FileClient
provides methods for checking
whether the location actually exists and accessing the contents
of the referenced file.
A given FileClient
encompasses an authorization context
for accesses. A FileMetaConfiguration
supplies the
accessor with any configuration required to authenticate with
file systems and gain authorization to perform requested actions.
While a number of file systems require no additional access rights
beyond those inherited from the JVM's execution environment,
others, such as cloud storage providers, require additional
information to grant access.
Path
,
FileMetaConfiguration
Modifier and Type | Method and Description |
---|---|
static FileClient |
basicClient()
Creates a new client only using the OS-level credentials
inherited from the JVM's execution environment.
|
static FileClient |
configuredClient(FileMetaConfiguration configuration,
ModuleConfiguration moduleConfiguration)
Creates a new client, authorized according to the given configuration.
|
static FileClient |
configuredClient(FileMetaConfiguration configuration,
ModuleConfiguration moduleConfiguration,
File indexPathBase,
Path[] tempFsRootDirs)
Creates a new client, authorized according to the given configuration.
|
void |
copy(Path from,
Path to)
Copies a file or directory from one location to another.
|
Path |
createDirectories(Path path)
Creates the directory identified by the given path,
creating any necessary parent directories.
|
Path |
createDirectory(Path path)
Creates the directory identified by the given path.
|
boolean |
createNewFile(Path path)
Creates the file identified by the given path.
|
Path |
createTemporaryStorage()
Creates a temporary storage location using default
configuration.
|
Path |
createTemporaryStorage(File indexPath,
Path[] storagePaths)
Creates a temporary storage location using the specified
configuration.
|
static File |
defaultIndexPathBase()
The default value for index path base.
|
void |
delete(Path path)
Deletes the file or directory identified by the specified
path.
|
void |
delete(Path path,
boolean recursively)
Deletes the file or directory identified by the specified
path.
|
boolean |
exists(Path path)
Indicates whether the specified path represents an
existing file or directory.
|
FileMetaConfiguration |
getConfiguration()
Returns the meta-configuration containing the configuration of this file client.
|
PathDetails |
getDetails(Path path)
Returns metadata associated with the specified path.
|
Object |
getFileSystemImplementation(Path path)
Returns the underlying implementation object for the file system implementation
of the given path.
|
String |
getFileSystemType(Path path)
Returns an identifier for the filesystem type.
|
long |
getLength(Path path)
Returns the length of the file represented by the given path
|
ModuleConfiguration |
getModuleConfiguration()
Returns the module configuration for this file client
|
IOMonitoringContext |
getMonitoring()
Returns the monitoring used to instrument I/O operations by the client.
|
NetworkConfiguration |
getNetworkConfiguration()
Returns the network configuration to use
|
SplitIterator |
getSplitIterator(Path path)
Computes data splits over the specified file.
|
SplitIterator |
getSplitIterator(Path path,
SplitOptions options)
Computes data splits over the specified file.
|
Path[] |
getTempFilesystemRootDirectories()
Returns the root directories used by default for temp storage by this client
|
FileClient |
instrumentWith(IOMonitoringContext monitor)
Creates a new client which instrumented I/O operations using the specified context.
|
boolean |
isCreatable(Path path)
Indicates whether the specified path can be created.
|
boolean |
isDirectory(Path path)
Indicates whether the specified path represents a directory.
|
boolean |
isFile(Path path)
Indicates whether the specified path represents a file.
|
boolean |
isHidden(Path path)
Indicates whether the associated path is hidden by the file system.
|
boolean |
isReadable(Path path)
Indicates whether the specified path can be read.
|
boolean |
isWritable(Path path)
Indicates whether the specified path can be written.
|
List<Path> |
listAllFiles(Path path,
DirectoryFilter filter)
Gets the contents of the specified directory including hidden files,
applying a filter.
|
List<PathDetails> |
listDirectory(Path path)
Gets the contents of the specified directory.
|
List<PathDetails> |
listDirectory(Path path,
DirectoryFilter filter)
Gets the contents of the specified directory, applying
a filter.
|
List<Path> |
listFiles(Path path)
Gets the contents of the specified directory.
|
List<Path> |
listFiles(Path path,
DirectoryFilter filter)
Gets the contents of the specified directory, applying
a filter.
|
List<PathDetails> |
listMatches(String pattern)
Finds all paths matching the specified pattern.
|
List<Path> |
matchPaths(String pattern)
Finds all paths matching the specified pattern.
|
void |
move(Path from,
Path to)
Moves a file or directory from one location to
another.
|
FileChannel |
newFileChannel(Path path)
Opens the specified file for random access.
|
InputStream |
newInputStream(Path path)
Opens the specified file for reading.
|
OutputStream |
newOutputStream(Path path,
WriteMode mode)
Opens the specified file for writing.
|
boolean |
supportsDirectories(Path path)
Indicates whether the filesystem corresponding to this path supports directories
|
boolean |
supportsRandomAccess(Path path)
Indicates whether the filesystem corresponding to this path supports random access
|
void |
unzip(Path from,
Path to)
Recursively unzips the given file to a given directory/file
|
FileClient |
withNetworkConfiguration(NetworkConfiguration networkConfiguration)
Creates a new client with the specified network configuration.
|
boolean |
zipRecursively(Path from,
OutputStream out,
boolean ignoreNonReadable)
Recursively zips the given input file/directory to the given stream
|
public static File defaultIndexPathBase()
public static FileClient basicClient()
This client is sufficiently authorized for local file system access, but may not work for accessing remote systems.
public static FileClient configuredClient(FileMetaConfiguration configuration, ModuleConfiguration moduleConfiguration)
configuration
- the configurationpublic static FileClient configuredClient(FileMetaConfiguration configuration, ModuleConfiguration moduleConfiguration, File indexPathBase, Path[] tempFsRootDirs)
configuration
- the configurationindexPathBase
- the base path to use for temporary index filestempFsRootDirs
- the root directories to use by default for temp storagepublic FileClient instrumentWith(IOMonitoringContext monitor)
monitor
- the monitoring context to use. null
disables monitoring
for the client.public FileClient withNetworkConfiguration(NetworkConfiguration networkConfiguration)
networkConfiguration
- the network configuration to usepublic FileMetaConfiguration getConfiguration()
public ModuleConfiguration getModuleConfiguration()
public NetworkConfiguration getNetworkConfiguration()
public IOMonitoringContext getMonitoring()
null
if none is active.public Path[] getTempFilesystemRootDirectories()
public boolean supportsRandomAccess(Path path)
path
- the pathFileSystem.supportsRandomAccess()
public boolean supportsDirectories(Path path)
path
- the pathFileSystem.supportsDirectories()
public Path createDirectories(Path path) throws IOException
path
- the directory to createIOException
- if I/O errors occur or if
any parent directories could not be createdFileSystem.createDirectories(Path)
public Path createDirectory(Path path) throws IOException
createDirectories(Path)
if nonexistent
parents need to be created.path
- the directory to createIOException
- if I/O errors occur or if the
parent directory does not existFileSystem.createDirectory(Path)
public boolean createNewFile(Path path) throws IOException
createDirectories(Path)
if nonexistent
parents need to be created.
If the underlying file system does not provide an
atomic test-and-create, a race condition where
two callers return true
is possible.
path
- the directory to createtrue
if the file was created,
false
if the file already existed.IOException
- if I/O errors occur or if the
parent directory does not existpublic void delete(Path path) throws IOException
path
- the file or directory to deleteIOException
- if I/O errors occur or if the
path identifies a non-empty directorypublic void delete(Path path, boolean recursively) throws IOException
path
- the file or directory to deleterecursively
- indicates whether deletes of directories
should recursively delete the contentsIOException
- if I/O errors occur or if the
path identifies a non-empty directory and a recursive
delete was not requestedFileSystem.delete(Path,boolean)
public InputStream newInputStream(Path path) throws IOException
listFiles(Path)
. The read starts at the first byte of the
(first) file. The returned stream is generally not buffered;
consult specific path scheme implementations for details.
If the FileClient
has been instrumented with
monitoring, the resulting stream will be registered
in statistics for the file system type.
path
- the file or directory to readIOException
- if I/O errors occurFileNotFoundException
- if the specified path does not existFileSystem.newInputStream(Path)
public OutputStream newOutputStream(Path path, WriteMode mode) throws IOException
CREATE_NEW
, an
error is raised.OVERWRITE
, the
existing file is replaced with the byte written to the resulting
stream.APPEND
, the resulting
stream is positioned after the last byte of the existing file.The returned stream is generally not buffered; consult specific path scheme implementations for details.
If the FileClient
has been instrumented with
monitoring, the resulting stream will be registered
in statistics for the file system type.
path
- the file to writemode
- how to handle writes to existing filesIOException
- if I/O errors occur or if the target is
a directoryIllegalArgumentException
- if the path is not
is not for a scheme supported by the providerFileSystem.newOutputStream(Path,WriteMode)
public FileChannel newFileChannel(Path path) throws IOException
If the FileClient
has been instrumented with
monitoring, the resulting channel will be registered
in statistics for the file system type.
path
- the file or directory to readIOException
- if I/O errors occurFileNotFoundException
- if the specified path does not existIllegalArgumentException
- if the path is not
is not for a scheme supported by the providerFileSystem.newFileChannel(Path)
public boolean exists(Path path) throws IOException
path
- the path to testtrue
the path exists, false
otherwise.IOException
- if I/O errors occurFileSystem.exists(Path)
public PathDetails getDetails(Path path) throws IOException
If a number of queries on the metadata for a path are going to be made, it can be more efficient to use this method to get a "snapshot", as only one request is performed instead of many.
path
- the path for which to get metadatanull
if it does not exist.IOException
- if I/O errors occurFileSystem.getDetails(Path)
public long getLength(Path path) throws IOException
path
- the path to testIOException
- if I/O errors occurFileSystem.getLength(Path)
public boolean isDirectory(Path path) throws IOException
path
- the path to testtrue
the path represents a directory,IOException
- if I/O errors occurFileSystem.isDirectory(Path)
public boolean isFile(Path path) throws IOException
path
- the path to testtrue
the path represents a file,IOException
- if I/O errors occurFileSystem.isFile(Path)
public boolean isReadable(Path path) throws IOException
path
- the path to testtrue
the path represents a readable
file or directory, false
otherwise.IOException
- if I/O errors occurFileSystem.isReadable(Path)
public boolean isWritable(Path path) throws IOException
path
- the path to testtrue
the path represents a writable
file or directory, false
otherwise.IOException
- if I/O errors occurFileSystem.isWritable(Path)
public boolean isCreatable(Path path) throws IOException
path
- the path to testtrue
the path represents a nonexistent
file or directory which could be created, false
otherwise.IOException
- if I/O errors occurFileSystem.isCreatable(Path)
public boolean isHidden(Path path) throws IOException
path
- the path to testtrue
if the path is hidden,
false
otherwise.IOException
- if I/O errors occurFileSystem.isHidden(Path)
public SplitIterator getSplitIterator(Path path) throws IOException
path
- the file for which to get splitsIOException
- if an I/O error occursgetSplitIterator(Path, SplitOptions)
public SplitIterator getSplitIterator(Path path, SplitOptions options) throws IOException
path
- the file for which to get splitsoptions
- configuration for the process
of dividing the fileIOException
- if an I/O error occursFileSystem.getSplits(Path, SplitOptions)
public List<Path> listFiles(Path path) throws IOException
In cases where metadata will be accessed immediately,
it is more efficient to use listDirectory(Path)
and make metadata calls against the returned PathDetails
objects.
path
- the directory for which to get a content listIOException
- if I/O errors occur or if the
path identifies a fileFileSystem#listFiles(Path)
public List<Path> listFiles(Path path, DirectoryFilter filter) throws IOException
In cases where metadata will be accessed immediately,
it is more efficient to use listDirectory(Path)
and make metadata calls against the returned PathDetails
objects.
path
- the directory for which to get a filtered content listfilter
- a filter to apply to the contentsIOException
- if I/O errors occur or if the
path identifies a fileFileSystem#listFiles(Path,DirectoryFilter)
public List<Path> listAllFiles(Path path, DirectoryFilter filter) throws IOException
In cases where metadata will be accessed immediately,
it is more efficient to use listDirectory(Path)
and make metadata calls against the returned PathDetails
objects.
path
- the directory for which to get a filtered content listfilter
- a filter to apply to the contentsIOException
- if I/O errors occur or if the
path identifies a fileFileSystem#listFiles(Path,DirectoryFilter)
public List<PathDetails> listDirectory(Path path) throws IOException
path
- the directory for which to get a content listIOException
- if I/O errors occur or if the
path identifies a fileFileSystem#listFiles(Path)
public List<PathDetails> listDirectory(Path path, DirectoryFilter filter) throws IOException
path
- the directory for which to get a filtered content listfilter
- a filter to apply to the contentsIOException
- if I/O errors occur or if the
path identifies a fileFileSystem#listFiles(Path,DirectoryFilter)
public void move(Path from, Path to) throws IOException
from
- the source locationto
- the target locationIOException
- if I/O errors occurFileSystem.move(FileSystem, Path, Path)
public void copy(Path from, Path to) throws IOException
from
- the source locationto
- the target locationIOException
- if I/O errors occurpublic List<Path> matchPaths(String pattern) throws IOException
In cases where metadata will be accessed immediately,
it is more efficient to use listMatches(String)
and make metadata calls against the returned PathDetails
objects.
pattern
- a scheme prefixed matching patternIOException
- if an I/O error occurs while resolving
the patternDRException
- if no configured provider could be found
for the schemepublic List<PathDetails> listMatches(String pattern) throws IOException
pattern
- a scheme prefixed matching patternIOException
- if an I/O error occurs while resolving
the patternDRException
- if no configured provider could be found
for the schemepublic Path createTemporaryStorage()
It is the caller's responsibility to delete temporary storage when it is no longer required. Failure to do so may leave files on the local file system.
public Path createTemporaryStorage(File indexPath, Path[] storagePaths)
Temporary storage consists of two logical spaces, the index space and the data space. The data space is defined by one or more root directories, under which data files are stored. The data space is flat; it does not reflect the hierarchical structure in paths. The index space is a single root directory, with directories in the index space corresponding to directories in temporary storage and files being indexes to data files containing the contents of temporary files. This indirection expands the amount of temporary storage available as well as spreads I/O activity across more disks.
It is the caller's responsibility to delete temporary storage when it is no longer required. Failure to do so may leave files on the local file system.
indexPath
- the root directory to use for indexing temporary files.
A unique directory for this storage will be created under the root;
multiple temporary locations may safely share the same value.storagePaths
- root directories to use for storing data files.
Unique files will be created under these directories as needed;
multiple temporary locations may safely share the same values.public String getFileSystemType(Path path)
path
- the pathpublic Object getFileSystemImplementation(Path path)
path
- the pathpublic boolean zipRecursively(Path from, OutputStream out, boolean ignoreNonReadable) throws IOException
from
- may be a file or a directoryout
- the destination output stream. Will not be closed as part of this operation.ignoreNonReadable
- ignore files that we don't have permission to readIOException
- if an error occurspublic void unzip(Path from, Path to) throws IOException
from
- must be a fileto
- must not be a fileIOException
- if an error occursCopyright © 2015 Actian Corporation. All Rights Reserved.