saker.build Documentation TaskDoc JavaDoc
public interface SakerFileProvider
Interface for providing direct access to the file system files.

Important: tasks in the build system should use this interface to read from or write to the file system as this interface is RMI compatible. Client code can use this to transparently access files on computers which are available through network.

This interface is similar in functionality that FileSystemProvider would provide. It allows clients to access the file system in a similar way, while allowing RMI compatibility.

Each file provider bears a key to itself which uniquely identifiers its location. If two file provider keys equal, clients can be sure that they will operate on the same files if their functions are called with the same paths. See getProviderKey() and FileProviderKey.

If a function name contains the phrase "Recursively" then client should expect that it will not throw a DirectoryNotEmptyException if the deleted directory is not empty.

Clients can install file event listeners for a file provider to get notified about changes in the file system. Build system task implementations are usually not recommended to do this, unless very specific use-cases. If they do, use it with the caching support of SakerEnvironment.

File providers can be used to wrap each other, providing restricted or enhanced functionality for a subject file provider. An example for this is a file provider that mounts a directory therefor limits access to a directory on a subject by allowing access to it using a specified root. File providers are considered root file providers if they do not wrap a subject file provider. Root file providers are required to return a RootFileProviderKey instance from getProviderKey().

File providers operate exclusively on absolute paths. Passing a relative path to them can result in an IllegalArgumentException.

Any method is allowed to throw NullPointerException if a null path is passed to them.

Fields
public static final CopyOption[]
Singleton instance for an empty copy options array.
public static final LinkOption[]
Singleton instance for an empty link options array.
public static final OpenOption[]
Singleton instance for an empty open options array.
public static final int
Operation flag to specify that if directories are being recursively created, then intermediate already existing files should be deleted.
public static final int
Operation flag constant specifying no flags.
public static final int
Operation flag to specify that if a directory is encountered, it shouldn't be recursively deleted.
public static final int
Operation result flag representing that some directories were created.
public static final int
Operation result flag representing that some files were deleted.
public static final int
Operation result flag representing that no changes were issued.
Methods
public ListenerToken
Adds a file event listener for the specified directory.
public default void
Clears the directory and all subdirectories at the specified path.
public void
Creates the directory and necessary parent directors at the given path.
public void
Deletes a file or directory at the given path.
public default Set<String>
Deletes the children of a directory recursively, if the name of a given child is not in the specified set.
public void
Deletes a file or directory at the given path, recursively if it is a directory.
public default int
Deletes the file at the given path if the type of it is not the specified one.
public int
ensureWriteRequest(SakerPath path, int filetype, int operationflag)
Ensures that a write request to the given path can be initiated with the given type.
public default ByteArrayRegion
getAllBytes(SakerPath path, OpenOption... openoptions)
Gets all of the byte contents of the file at the specified path.
public NavigableMap<String, ? extends FileEntry>
Gets the entries in the directory denoted by the argument path.
public NavigableMap<SakerPath, ? extends FileEntry>
Collects the entries in the specified directory, recursively.
public default Entry<String, ? extends FileEntry>
Gets the attributes of a file in the directory specified by the argument path.
public default Set<String>
Gets the names of the files present in the directory denoted by the specified path.
public FileEntry
getFileAttributes(SakerPath path, LinkOption... linkoptions)
Gets the attributes of the file at the specified path.
public FileProviderKey
Gets the file provider key for this file provider.
public Set<String>
Gets the file system roots of this file provider.
public default Set<String>
Gets the names of subdirectories in the directory denoted by the specified path.
public default SakerFileProvider
Gets the file provider this file provider wraps.
public default FileHashResult
hash(SakerPath path, String algorithm, OpenOption... openoptions)
Creates a hash using the specified algorithm based on the contents of the file at the specified path.
public default boolean
isChanged(SakerPath path, long size, long modificationmillis, LinkOption... linkoptions)
Checks if the given attributes of a file at the specified path are the same or not.
public void
moveFile(SakerPath source, SakerPath target, CopyOption... copyoptions)
Moves a file from on location to another.
public ByteSource
openInput(SakerPath path, OpenOption... openoptions)
Opens an input stream to the file at the specified path.
public ByteSink
openOutput(SakerPath path, OpenOption... openoptions)
Opens an output stream to the file at the specified path.
public default void
Removes the file listeners in a bulk operation.
public default SakerPath
Resolves the parameter path in a way that the result can be used to access the same files using the file provider returned from getWrappedProvider().
public default void
setFileBytes(SakerPath path, ByteArrayRegion data, OpenOption... openoptions)
Writes the specified bytes to the file at the given path.
public void
setLastModifiedMillis(SakerPath path, long millis)
Sets the last modified time of the file at the given path.
public default long
writeTo(SakerPath path, ByteSink out, OpenOption... openoptions)
Writes the contents of the file at the given path to the specified output stream.
public default long
writeToFile(ByteSource is, SakerPath path, OpenOption... openoptions)
Writes the contents from the given input stream to the specified output file path.
public static final CopyOption[] EMPTY_COPY_OPTIONS
Singleton instance for an empty copy options array.
public static final OpenOption[] EMPTY_OPEN_OPTIONS
Singleton instance for an empty open options array.
public static final int OPERATION_FLAG_DELETE_INTERMEDIATE_FILES = 2
Operation flag to specify that if directories are being recursively created, then intermediate already existing files should be deleted.

Used by:
ensureWriteRequest(SakerPath, int, int)

public static final int OPERATION_FLAG_NONE = 0
Operation flag constant specifying no flags.
Operation flag to specify that if a directory is encountered, it shouldn't be recursively deleted.

This flag doesn't necessary prevent the deletion of empty directories.

Used by:
ensureWriteRequest(SakerPath, int, int)

public static final int RESULT_FLAG_DIRECTORY_CREATED = 1
Operation result flag representing that some directories were created.
public static final int RESULT_FLAG_FILES_DELETED = 2
Operation result flag representing that some files were deleted.
public static final int RESULT_NO_CHANGES = 0
Operation result flag representing that no changes were issued.
Adds a file event listener for the specified directory.

If the specified directory doesn't exist, the provider can either fail or succeed for installing the listener.

Callers should keep a strong reference to the returned token, and call FileEventListener.ListenerToken.removeListener() when the listener is no longer needed. Removing all references to the returned token is not sufficient for removing the listener from the provider.

Listeners might receive events before this method finishes.

The listener will receive file event changes with file names which are a children of the specified directory.

directoryThe directory to install the listener to.
listenerThe listener to install.
The token for the installed listener.
IOExceptionIf the provider failed to install the listener.
Clears the directory and all subdirectories at the specified path.

This method follows symbolic links for retrieving the children, but doesn't when deleting the entries. Meaning, if a directory contains a link, the link will be deleted and the directory at the end of the link will not be cleared.

pathThe path to the directory to clear.
IOExceptionIn case of I/O error.
Creates the directory and necessary parent directors at the given path.

If the directories cannot be created due to a non-directory file is already present at the path or at one of its parent paths, the method will fail.

pathThe path to create the directory at.
IOExceptionIn case of I/O error.
FileAlreadyExistsExceptionIf there is already a non-directory file at the path (or any parent paths).
Deletes a file or directory at the given path.

The method will fail if the path denotes a directory and it is not empty.

If the path denotes a symbolic link, only the link will be deleted.

If there is no file at the given path, the method will succeed, and won't throw an exception. Therefore this methods works in the manner of "delete if exists".

pathThe path to delete.
IOExceptionIn case of I/O error.
DirectoryNotEmptyExceptionIf the path denotes a file and it's not empty.
Deletes the children of a directory recursively, if the name of a given child is not in the specified set.

If a directory child is a directory, it will be recursively deleted, meaning any of its subdirectories will be deleted too.

This method doesn't follow symbolic links. Meaning, if a directory contains a link, the link will be deleted and the directory at the end of the link will not be cleared.

pathThe path to the directory.
childfilenamesA set of names in the specified directory to not delete.
The names of the actually deleted files.
IOExceptionIn case of I/O error.
PartiallyDeletedChildrenExceptionIf the deletion was aborted because the deletion of a given child threw an exception.
Deletes a file or directory at the given path, recursively if it is a directory.

This method will delete all files at the given path, clearing the directory beforehand if necessary.

This method doesn't follow symbolic links. Links to directories will be deleted, the directories won't be cleared if they are not under the specified path.

pathThe path to delete.
IOExceptionIn case of I/O error.
Deletes the file at the given path if the type of it is not the specified one.

This method reads the attributes at the given path, and deletes the file recursively if it doesn't match the expected.

The attribute reading follows symbolic links, the deletion doesn't.

The file type argument should be one of the file type constants in FileEntry.

pathThe path to the file.
filetypeThe expected file type.
The current file type at the path. Either same as the argument, or FileEntry.TYPE_NULL to signal that it was deleted.
IOExceptionIn case of I/O error.
public abstract int ensureWriteRequest(SakerPath path, int filetype, int operationflag) throws IOException, IllegalArgumentException
Ensures that a write request to the given path can be initiated with the given type.

This method examines the current file at the given path, and ensures that the file is either has the same type, or a write request can be initiated to it.

The argument file type and behaviour based on it is the following:

  • FileEntry.TYPE_FILE: If there is a directory at the path, it will be deleted recursively*. If there is a file at the path, no operation will be done as it can be overwritten. If not all parent directories exist at the path, the parent directories will be created recursively. This ensures that a following openOutput(SakerPath, OpenOption...) can succeed.
    * If the OPERATION_FLAG_NO_RECURSIVE_DIRECTORY_DELETE is specified, the encountered directory will only be deleted if it is empty. An exception is thrown instead if it is not empty.
  • FileEntry.TYPE_DIRECTORY: If there is a non-directory file at the path, it will be deleted. If there is a directory at the path, no operation will be done. If there is no file at the path, all directories will be created, including the one at the path as well.
The directory creation for parent paths in the above behaviours works the same way as createDirectories(SakerPath).

This method is mainly useful to batch the attribute reading-deletion-file creation operations into one call, therefore ensuring that a given path is writeable for the given file type.

Note that this function is not atomic. The checking of the currently present file, deletions, and creation are not done atomically, therefore this method may fail if concurrent modifications distrupt it. It is recommended for callers to ensure private and synchronized access to the given path.

pathThe path.
filetypeThe file type to ensure the write request for.
operationflagThe operation flag to take into account. Acceptable flags: OPERATION_FLAG_NO_RECURSIVE_DIRECTORY_DELETE, OPERATION_FLAG_DELETE_INTERMEDIATE_FILES.
The result flags describing the changes made by this method. See RESULT_NO_CHANGES, RESULT_FLAG_FILES_DELETED, RESULT_FLAG_DIRECTORY_CREATED.
IOExceptionIn case of I/O error.
Gets all of the byte contents of the file at the specified path.
pathThe path to the file.
openoptionsThe opening options for the input.
The byte contents of the file.
IOExceptionIn case of I/O error.
Gets the entries in the directory denoted by the argument path.

The result contains the file names mapped to their attributes.

This method follows symbolic links when determining the attributes.

pathThe path to the directory.
The directory entries.
IOExceptionIn case of I/O error.
Collects the entries in the specified directory, recursively.

This method contains every file entry that is under the specified directory and its subdirectories.

Use this method judiciously as a large number of files might be queried.

The file attribute values in the result map are mapped to their relative path based on the argument path.

This method follows symbolic links for directories and when determining attributes.

pathThe path to the directory.
The recursively collected file entries mapped to their paths relative to the argument.
IOExceptionIn case of I/O error.
Gets the attributes of a file in the directory specified by the argument path.

This method only returns non-null if there is a directory at the denoted path, and in that directory there is only one file. The attributes for the file is returned.

This method follows symbolic links when determining the attribute.

pathThe directory to get the entry for.
A map entry where the key is the name of the found file, the value is the attributes of the file. null if no file or more than one was found.
IOExceptionIn case of I/O error.
Gets the names of the files present in the directory denoted by the specified path.

This method doesn't follow symbolic links.

pathThe path to the directory.
A set of file names which are present in the given directory.
IOExceptionIn case of I/O error.
Gets the attributes of the file at the specified path.
pathThe path to the file.
linkoptionsLink options to use when retrieving the attributes.
The attributes of the file.
IOExceptionIn case of I/O error.
Gets the file provider key for this file provider.

If this file provider is a root provider, then the result will be an instance of RootFileProviderKey.

The file provider key.
Gets the file system roots of this file provider.

File system roots do not change during the lifetime of a file provider. They are normalized according to the rules of SakerPath.normalizeRoot(String).

Note: It can happen that some file system drives are changed during the lifetime of a file provider. (E.g. USB drive inserted/removed, etc...) The file provider implementations are not required to recognize these changes, and restarting the build system process might be required to handle the file system changes.

An unmodifiable set of root names for this file provider.
IOExceptionIn case of I/O error.
Gets the names of subdirectories in the directory denoted by the specified path.

This method follows symbolic links when determining if an entry is considered a directory.

pathThe path to the directory.
A set of directory names which are present in the given directory.
IOExceptionIn case of I/O error.
Gets the file provider this file provider wraps.

Wrapping file providers can be useful to extend the wrapped file providers functionality.

If this method returns null, then getProviderKey() should return an instance of RootFileProviderKey.

If this method returns non-null, then the file provider implementation must override resolveWrappedPath(SakerPath).

The wrapped file provider or null if this file provider is a root provider.
Creates a hash using the specified algorithm based on the contents of the file at the specified path.

This method will read the contents of the file at the specified path and use the appropriate MessageDigest to create a hash of its contents.

When using RMI, it is preferable to call this method instead of opening the stream on client side and reading the contents, as it can avoid transferring the whole content of the file over the network.

pathThe path to the file.
algorithmThe algorithm to use for hashing.
openoptionsThe opening options to use when opening the file.
The computed hash.
NoSuchAlgorithmExceptionIf the hashing algorithm not found.
IOExceptionIn case of I/O error.
public default boolean isChanged(SakerPath path, long size, long modificationmillis, @RMIWriter(EnumArrayRMIObjectWriteHandler.class)LinkOption... linkoptions)
Checks if the given attributes of a file at the specified path are the same or not.

This method retrieves the attributes of the file at the path and compares the specified attributes.

pathThe path to the file.
sizeThe expected size of the file.
modificationmillisThe expected modification time of the file.
linkoptionsThe link options to use.
true if failed to retrieve the attributes, or the attributes changed.
Moves a file from on location to another.
sourceThe file to move.
targetThe path to move the file to.
copyoptionsThe copy options to use.
IOExceptionIn case of I/O error.
Opens an input stream to the file at the specified path.

The OpenOption argument must contain elements which are enumerations.

pathThe path to the file.
openoptionsThe opening options for the input.
An opened stream.
IOExceptionIn case of I/O error.
Opens an output stream to the file at the specified path.

The caller must close the returned stream to properly persist the written bytes to the stream. If the caller doesn't close the stream, data corruption might occur.

The OpenOption argument must contain elements which are enumerations.

pathThe path to the file.
openoptionsThe opening options for the output.
An opened output stream.
IOExceptionIn case of I/O error.
Removes the file listeners in a bulk operation.

To remove a single file listener call FileEventListener.ListenerToken.removeListener().

The file listeners might still receive some events after this call, as the events can occur out of order. Listeners should handle that scenario gracefully.

The method will silently ignore any null elements in the argument.

listenersThe file listeners to remove.
IllegalArgumentExceptionIf any of the argument listener tokens were not issued by this file provider.
Resolves the parameter path in a way that the result can be used to access the same files using the file provider returned from getWrappedProvider().

This method will throw an UnsupportedOperationException if and only if this file provider is root file provider.

The returned path will access the same file using the wrapped file provider as this file provider would with the argument path.

pathThe path to resolve.
The resolved path in the domain of the wrapped file provider.
UnsupportedOperationExceptionIf this is a root file provider. I.e. getWrappedProvider() returns null.
IllegalArgumentExceptionIf the path doesn't have a root that this file provider handles.
Writes the specified bytes to the file at the given path.
pathThe output file path.
dataThe bytes to write to the file.
openoptionsThe opening options for the output.
IOExceptionIn case of I/O error.
public abstract void setLastModifiedMillis(SakerPath path, long millis) throws IOException
Sets the last modified time of the file at the given path.

The milliseconds are converted using FileTime.fromMillis(long).

pathThe file path.
millisThe modification time in milliseconds.
IOExceptionIn case of I/O error.
Writes the contents of the file at the given path to the specified output stream.
pathThe path to the file.
outThe output to write the file contents to.
openoptionsThe opening options for the input.
The amount of bytes written to the output stream.
IOExceptionIn case of I/O error.
Writes the contents from the given input stream to the specified output file path.
isThe input to get the bytes from.
pathThe output file path.
openoptionsThe opening options for the output.
The amount of bytes written to the file.
IOExceptionIn case of I/O error.