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.

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.

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.

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".

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.

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.

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.

Ensures a write request for the given path and opens an output stream to it.

The method works the same way as if ensureWriteRequest(SakerPath, int, int) and openOutput(SakerPath, OpenOption...) are called subsequently. This corresponds to the default implementation of:

 ensureWriteRequest(path, FileEntry.TYPE_FILE, operationflag);
 return openOutput(path, openoptions);
 

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.

Gets all of the byte contents of the file at the specified path.

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.

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.

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.

Gets the names of the files present in the directory denoted by the specified path.

This method doesn't follow symbolic links.

Gets the attributes of the file at the specified path.

Gets the posix file permissions of the file at the given path.

The method will query the posix file permissions of the specified file if the underlying file system supports them.

The method does not throw an exception if the underlying filesystem doesn't support posix file permissions.

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.

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.

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.

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 and provide an implementation resolveWrappedPath(SakerPath).

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.

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.

Modifies the posix file permissions for the file at the given path.

The method takes two permission set arguments which control how the permissions should be modified. First all permissions in the add argument are added, then all permissions in the remove argument are removed.

The adding and removal are performed in a single filesystem operation.

If a permission is present in both add and remove permission sets, then it will be removed.

The method does not throw an exception if the underlying filesystem doesn't support posix file permissions.

Moves a file from on location to another.

Opens an input stream to the file at the specified path.

The OpenOption argument must contain elements which are enumerations.

The returned stream is not thread-safe.

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. If the stream is not closed, the data may not have been written to the disk. Implementations may cache the written bytes and flush them when close() is called.

If this method successfully returns, that doesn't necessarily mean that the file has been opened. Opening related exceptions may be thrown by the writing or closing methods of the returned stream.

The OpenOption argument must contain elements which are enumerations.

The returned stream is not thread-safe.

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.

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.

Writes the specified bytes to the file at the given path.

Sets the last modified time of the file at the given path.

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

Sets the posix file permissions for the file at the given path.

This method will only set the file permissions if the underlying filesystem supports it. In that case the method will return true. Otherwise false.

The method does not throw an exception if the underlying filesystem doesn't support posix file permissions.

Writes the contents of the file at the given path to the specified output stream.

Writes the contents from the given input stream to the specified output file path.