This abstract class provides the basic implementation for the functionality of SakerFile and is the basis of the in-memory file hierarchy for the build system. Clients should extend this instead of implementing SakerFile directly.
This class holds a reference to the enclosing parent directory, and has a backing field name for the file name.
The class manages the implicit synchronization behaviour described in SakerFile.
Subclasses are required to implement the functionality required for retrieving the content descriptor, and the functionality to retrieve the actual contents of the file. It is recommended that subclasses override getEfficientOpeningMethods() along with the appropriate content retrieval methods.
| public | SakerFileBase( Creates a new instance with the given file name. |
| public final ByteArrayRegion | getBytes() Gets the raw contents of the file as a byte array.
|
| public final String | Gets the contents of the file as a String.
|
| public int | Gets the efficient opening methods flag of this file. |
| public final String | getName() Gets the name of the file. |
| public final SakerDirectory | Gets the parent of this file. |
| public final SakerPath | Gets the path of this file. |
| public final ByteSource | Opens a ByteSource to the contents of the file.
|
| public final InputStream | Opens an InputStream to the contents of the file.
|
| public final void | remove() Removes this file from its parent. |
| public final void | Synchronizes the contents of this file with the file system. |
| public final void | synchronize( Synchronizes the contents of this file to the target file system location. |
| public void | synchronizeImpl( Synchronizing implementation for persisting the contents of this file to the target file system location. |
| public boolean | synchronizeImpl( Overloaded synchronizing method with additional output stream to write the contents to. |
| public final String | toString() Returns a string representation of the object. |
| public final void | writeTo( Writes the contents to the parameter stream.
|
null.This method implicitly synchronizes the contents of the file, unless SakerFile.getEfficientOpeningMethods() reports otherwise.
It is recommended to use TaskExecutionUtilities.getBytes(
The default implementation converts the raw byte contents of the file is to string by decoding it as UTF-8 encoded data.
This method implicitly synchronizes the contents of the file, unless SakerFile.getEfficientOpeningMethods() reports otherwise.
It is recommended to use TaskExecutionUtilities.getContent(
An opening method is considered (performance-wise) efficient if it generally takes less resources (time and memory) to call the appropriate content method instead of trying to employ caching to the disk.
If an opening method is reported as efficient, then the implicit synchronizations will not take place specified by the documentation of SakerFile interface.
If an opening method is not reported as efficient, then calling content retrieval methods which do not end
with Impl will check if the file system already has the contents of this file persisted, and will
read the contents from there if it has. If not, then the contents will be synchronized with to the disk, and the
contents will be retrieved in the most efficient manner. (This manner depends on the nature of the opening
method.)
The default implementation returns SakerFile.OPENING_METHODS_NONE.
The name of the file should be considered final and not change during the lifetime of the object.
The name may not be null, empty, "." or "..", must not contain slash
characters ('/', '\\'), and must not contain the colon (':') and semicolon
(';') characters.
Note that in some cases the above restriction may be violated, when root directories need to be represented. They
will have a name according to the root path name they represent. I.e. They can be "/", or drive
names in "drive:" format. These root directories cannot be added to other directories.
The parent of a file can change during the lifetime of an object.
The path of this file is based on its parent path, appended with its name. If the file has no parent, then a relative path will be returned with a single path name which is the name of this file.
The path identifies the synchronization location of this file based on the current path configuration.
This method implicitly synchronizes the contents of the file, unless SakerFile.getEfficientOpeningMethods() reports otherwise.
It is recommended to use TaskExecutionUtilities.openByteSource(
This method implicitly synchronizes the contents of the file, unless SakerFile.getEfficientOpeningMethods() reports otherwise.
It is recommended to use TaskExecutionUtilities.openInputStream(
Calling this is a no-op if the file has no current parent.
The synchronization algorithm is described in the documentation of SakerFile interface.
The synchronization algorithm is described in the documentation of SakerFile interface.
File implementations generally should not override this method, but
SakerFile.synchronizeImpl(
This method will not check if the contents of the disk have been changes in relation to this file, but will always persist it to the given location.
Subclasses should implement this method to persist its contents to the location specified by the parameter.
If subclasses override this method, they must override SakerFile.synchronizeImpl(false.)
Subclasses should set any posix file permissions there are associated with the file during synchronization.
This method will not check if the contents of the disk have been changes in relation to this file, but will always persist it to the given location.
This method exists for performance optimization. Subclasses should override this method and attempt to concurrently persist the contents of the file to the target location and write the contents to the additional stream.
Subclasses must not throw an IOException if the writing to the additional stream failed, but rethrow them as a SecondaryStreamException. If a SecondaryStreamException is thrown, the synchronization is going to be considered as successful, and only the writing to the secondary stream is considered as failure. If an IOException is thrown, both stream writings is considered to be failed.
The implementations are not required to handle concurrent writing. This method should return true if
it was able to concurrently synchronize and write the contents to the additional stream. The
PriorityMultiplexOutputStream utility class can help implementations in implementing this functionality.
Overriding this method will improve the overall synchronization performance.
If subclasses override this method, they must override SakerFile.synchronizeImpl(
Subclasses should set any posix file permissions there are associated with the file during synchronization.
true if the contents of the file was successfully written to the additional stream.toString method returns a string that
"textually represents" this object. The result should be a concise but informative representation that is easy
for a person to read. It is recommended that all subclasses override this method.
The toString method for class Object returns a string consisting of the name of the class of
which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation
of the hash code of the object. In other words, this method returns a string equal to the value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
The method implementations mustn't close the argument output.
This method implicitly synchronizes the contents of the file, unless SakerFile.getEfficientOpeningMethods() reports otherwise.
It is recommended to use TaskExecutionUtilities.writeTo(