SakerDirectory

public interface SakerDirectory extends SakerFile

saker.build.file.SakerDirectory

saker.build.file.SakerFile

saker.build.file.FileHandle

saker.build.file.StreamWritable

Interface for directory file representation in the build system.

Directories contain children files which can be manipulated with the appropriate methods.

Unlike SakerFile, none of the methods in this interface will cause implicit synchronizations. Trying to retrieve contents of a directory will result in an IOException with unsupported message.

Directories track their children and employ lazy loading for populating their table. When the build execution is started, the root directories are determined by the execution configuration. The directories do not load their contained files immediately at construction time, but employ a lazy loading to fill this table. This behaviour is called populating the directory, and is always happening implicitly.

Populating can occur in the following ways:

Partial population
Full population

Partial populating occurs when a specific file is accessed by name. This results in reading the attributes of the file from the file system and adding the file to the table if it exists. Partial population does not occur if a directory is already fully populated.

Full populating occurs in any other cases, e.g. retrieving all children, removing a file). Full populating can occur for a directory at most once in its execution lifetime.

The populating behaviour only affects files which have not yet been modified by the user. If a task decides to overwrite a file with a new directory, then that directory will be treated as an empty fully populated directory.

During synchronization of directories, a file system folder will be created at the specified path. A snapshot of the files will be taken, and those will be synchronized accordingly. The synchronization methods can accept a DirectoryVisitPredicate as a parameter to control which files and subdirectories should be synchronized. Synchronizing a directory will delete any files at the child path that is not present in the in-memory representation of the directory, unless the DirectoryVisitPredicate.getSynchronizeFilesToKeep() specifies othervise.

The synchronization of directories are often executed in parallel, using a thread pool.

Instances of SakerFile can be checked if they represent a directory by using the (file instanceof SakerDirectory) expression on them.

When designing tasks for remote execution it is strongly recommended that directories are accessed through methods of the SakerPathFiles utility class.

Clients should not implement this interface, at all. Directories should not be treated in any other way, as just a container for files.

SakerFile

Methods

public SakerFile	add(SakerFile file) Adds a file to this directory.
public SakerFile	addIfAbsent(SakerFile file) Adds a file to this directory only if there is no file present yet with the same name.
public SakerDirectory	addOverwriteIfNotDirectory(SakerFile file) Adds a file to this directory only if there is no directory present with the same name.
public void	clear() Removes all child files from this directory.
public SakerFile	get(String name) Gets the child file for the specified name.
public NavigableMap<String, ? extends SakerFile>	getChildren() Gets a snapshot of the children of this directory.
public NavigableMap<String, ? extends SakerFileContentInformationHolder>	getChildrenContentInformation(DirectoryVisitPredicate childpredicate) Gets a snapshot of the children of this directory mapped to an SakerFileContentInformationHolder instance.
public default ContentDescriptor	getContentDescriptor() Gets the content descriptor of this file.
public default SakerDirectory	getDirectory(String name) Gets the child directory for the specified name.
public SakerDirectory	getDirectoryCreate(String name) Gets a child directory with the specified name or creates one if not found.
public SakerDirectory	getDirectoryCreateIfAbsent(String name) Gets a child directory with the specified name or creates one if not found, but does not overwrite existing files.
public NavigableMap<SakerPath, SakerFile>	getFilesRecursiveByPath(SakerPath basepath, DirectoryVisitPredicate filepredicate) Gets the children of this directory tree with for a given predicate.
public default boolean	isEmpty() Checks if the directory contains any children.
public void	synchronize() Synchronizes this directory and all of its children, recursively.
public void	synchronize(DirectoryVisitPredicate synchpredicate) Synchronizes this directory and all of its children using the given predicate.
public default void	synchronize(ProviderHolderPathKey pathkey) Synchronizes this directory and all of its children, recursively.
public void	synchronize(ProviderHolderPathKey pathkey, DirectoryVisitPredicate synchpredicate) Synchronizes this directory and all of its children using the given predicate.

Inherited methods
From: SakerFile getBytes, getBytesImpl, getContent, getContentImpl, getEfficientOpeningMethods, getParent, getPosixFilePermissions, getRemoteExecutionRMIWrapper, getSakerPath, openByteSource, openByteSourceImpl, openInputStream, openInputStreamImpl, remove, synchronizeImpl, synchronizeImpl, writeTo, writeTo, writeToStreamImpl
From: FileHandle getName

public abstract SakerFile add(@RMIWrap(RemoteExecutionSakerFileRMIWrapper.class)SakerFile file) throws NullPointerException, IllegalStateException

Adds a file to this directory.

This method will overwrite any files that exist with the same name.

Important: When designing tasks for remote execution, it should be noted that the argument file which is passed to this function will not have its parent adjusted. This means that if you add a file to a directory, calling SakerFile.getParent() after this method finishes, will not return this directory. It is recommended to make files RMI-transferrable when executing remote tasks by overriding SakerFile.getRemoteExecutionRMIWrapper().

During calling this, a delegate file will be added to the directory by default. That file will have a reference to the actual argument over RMI, and that file will be the one having this as a parent. In order to have a reference to the delegate file, use TaskExecutionUtilities.addFile(SakerDirectory, SakerFile), which returns the file object that is actually added to the directory.

fileThe file to add.

The file that was overwritten by the argument or null if there was no such file.

NullPointerExceptionIf the file is null.

IllegalStateExceptionIf the file already has a parent or it has been already removed from its previous one.

public abstract SakerFile addIfAbsent(@RMIWrap(RemoteExecutionSakerFileRMIWrapper.class)SakerFile file) throws NullPointerException, IllegalStateException

Adds a file to this directory only if there is no file present yet with the same name.

This method will not overwrite any files, and is a no-op if the operation cannot be completed.

The same remote execution related design notes apply as in add(SakerFile).

fileThe file to add.

The file that is present in this directory with the same name or null if the argument file was successfully added.

NullPointerExceptionIf the file is null.

IllegalStateExceptionIf the file already has a parent or it has been already removed from its previous one.

TaskExecutionUtilities.addFileIfAbsent(SakerDirectory, SakerFile)

public abstract SakerDirectory addOverwriteIfNotDirectory(@RMIWrap(RemoteExecutionSakerFileRMIWrapper.class)SakerFile file) throws NullPointerException, IllegalStateException

Adds a file to this directory only if there is no directory present with the same name.

This method will add the argument file to the directory, and overwrite any files which are present with the same name. However, it will not overwrite directories which are present with the same name.

If a directory is present with the same name, this method call is no-op.

The same remote execution related design notes apply as in add(SakerFile).

fileThe file to add.

The directory that is present in this directory with the same name or null if the argument file was successfully added. If a non-directory file was overwritten during this method call, still null will be returned.

NullPointerExceptionIf the file is null.

IllegalStateExceptionIf the file already has a parent or it has been already removed from its previous one.

TaskExecutionUtilities.addFileOverwriteIfNotDirectory(SakerDirectory, SakerFile)

public abstract void clear()

Removes all child files from this directory.

The directory will be set as fully populated during this call.

public abstract SakerFile get(String name) throws IllegalArgumentException

Gets the child file for the specified name.

A partial population will be executed if the file is not found and the directory is not yet fully populated.

nameThe name of the file.

The file, or null if not found.

IllegalArgumentExceptionIf the file name is invalid or null.

@RMIWrap(RMITreeMapSerializeKeyRemoteValueWrapper.class)

public abstract NavigableMap<String, ? extends SakerFile> getChildren()

Gets a snapshot of the children of this directory.

The directory will be fully populated.

The returned map might be unmodifiable, but is not required to be. Modifications to the return value will not be propagated back to the directory.

The children of this directory mapped by their names.

@RMIWrap(RMITreeMapWrapper.class)

public abstract NavigableMap<String, ? extends SakerFileContentInformationHolder> getChildrenContentInformation(DirectoryVisitPredicate childpredicate)

Gets a snapshot of the children of this directory mapped to an SakerFileContentInformationHolder instance.

The method returns the children of the directory the same way as getChildren(), but includes additional information alongside the SakerFile instance.

The argument predicate is used to determine for which files to include additional information. If visitFile returns false, then only the SakerFile instance will be contained in the associated SakerFileContentInformationHolder.

childpredicateThe predicate to use. May be null, in which case DirectoryVisitPredicate.everything() is used.

The directory children mapped to their content information holders.

saker.build 0.8.15

@RMIDefaultOnFailure

@RMIForbidden

@RMISerialize

public default ContentDescriptor getContentDescriptor()

Gets the content descriptor of this file.

See ContentDescriptor. Content descriptors are used to determine if the file contents need to be persisted to the file system.

Subclasses should note that if they use posix file permissions then they should return a content descriptor that reflects this behaviour. They are recommended to use PosixFilePermissionsDelegateContentDescriptor to construct the actual content descriptor.

Always returns DirectoryContentDescriptor.INSTANCE for directories.

The content descriptor. Never null.

public default SakerDirectory getDirectory(String name) throws IllegalArgumentException

Gets the child directory for the specified name.

Works the same way as get(String), but returns null if the file is not a directory.

nameThe name of the directory.

The directory, or null if no directory found for the specified name.

IllegalArgumentExceptionIf the file name is invalid or null.

public abstract SakerDirectory getDirectoryCreate(String name) throws IllegalArgumentException

Gets a child directory with the specified name or creates one if not found.

Works the same way as getDirectory(String), but adds a new directory with the specified name if not found.

The newly added directory will replace any file that is present and not a directory.

nameThe name of the directory.

The child directory with the specified file name. Never null.

IllegalArgumentExceptionIf the file name is invalid or null.

getDirectoryCreateIfAbsent(String)

public abstract SakerDirectory getDirectoryCreateIfAbsent(String name) throws IllegalArgumentException

Gets a child directory with the specified name or creates one if not found, but does not overwrite existing files.

Works the same way as getDirectoryCreate(String), but does not overwrite if a non-directory file is present with the specified name.

nameThe name of the directory.

The child directory with the specified name, or null if there is a non-directory file in its place.

IllegalArgumentExceptionIf the file name is invalid or null.

@RMIWrap(RMITreeMapSerializeKeyRemoteValueWrapper.class)

public abstract NavigableMap<SakerPath, SakerFile> getFilesRecursiveByPath(SakerPath basepath, DirectoryVisitPredicate filepredicate) throws NullPointerException

Gets the children of this directory tree with for a given predicate.

This methods accepts a base path as a parameter which is used to resolve the relative paths of the children. This can be used to efficiently construct a map that contains the files based on the needs of the caller.

The result map doesn't include this directory instance.

Pass SakerPath.EMPTY to have the key paths remain relative to this directory, or pass the result of SakerFile.getSakerPath() to construct a map with absolute key paths.

Convenience functions with less parameters available in SakerPathFiles.getFilesRecursiveByPath(SakerDirectory)

basepathThe base path to resolve the relative paths against.

filepredicateThe predicate to define the files to visit. If this is null, DirectoryVisitPredicate.everything() will be used.

The collected children. The returned map is mutable.

NullPointerExceptionIf base path is null.

public default boolean isEmpty()

Checks if the directory contains any children.

A full population will occur if no file has been added, or no file has been partially populated for this directory yet.

true if this directory has no children.

public abstract void synchronize() throws IOException

Synchronizes this directory and all of its children, recursively.

The synchronization algorithm is described in the documentation of SakerDirectory interface.

The DirectoryVisitPredicate.everything() predicate will be used for synchronization.

IOExceptionIn case of I/O error or if the file doesn't have a parent.

public abstract void synchronize(DirectoryVisitPredicate synchpredicate) throws IOException

Synchronizes this directory and all of its children using the given predicate.

The synchronization algorithm is described in the documentation of SakerDirectory interface.

synchpredicateThe synchronization predicate or null to use DirectoryVisitPredicate.everything().

IOExceptionIn case of I/O error or if the file doesn't have a parent.

public default void synchronize(ProviderHolderPathKey pathkey) throws IOException, NullPointerException

Synchronizes this directory and all of its children, recursively.

The synchronization algorithm is described in the documentation of SakerDirectory interface.

Same as:

 synchronize(pathkey, DirectoryVisitPredicate.everything());

pathkeyThe target location of the synchronization.

IOExceptionIn case of I/O error.

NullPointerExceptionIf the target location is null.

public abstract void synchronize(ProviderHolderPathKey pathkey, DirectoryVisitPredicate synchpredicate) throws IOException, NullPointerException

Synchronizes this directory and all of its children using the given predicate.

The synchronization algorithm is described in the documentation of SakerDirectory interface.

pathkeyThe target location of the synchronization.

synchpredicateThe predicate to use for synchronization. It this is null, DirectoryVisitPredicate.everything() will be used.

IOExceptionIn case of I/O error.

NullPointerExceptionIf the target location is null.