net.algart.arrays
Interface DataFile

public interface DataFile

Some "data file" (usually disk file) that supports file-mapping operation. Used by the large memory model.

The instances of this class are returned by methods of DataFileModel interface.

Note: all implementations of this interface from this package do not override standard equals and hashCode methods of Object class. Illegal overriding these methods may lead to losing some file instances by DataFileModel.allTemporaryFiles() method.

Objects implementing this interface may be not immutable and not thread-safe, but must be thread-compatible (allow manual synchronization for multithread access).

AlgART Laboratory 2007-2013

Since:

JDK 1.5

Version:

1.2

Author:

Daniel Alievsky

byteOrder

java.nio.ByteOrder byteOrder()

Returns the byte order in all byte buffers returned by map(Range, boolean) method.

This method never throws exceptions.

Returns:

the byte order in all returned byte buffers.

open

DataFile.OpenResult open(boolean readOnly)

Opens the data file. Does nothing if it is already opened. Must be called before any calls of map(Range, boolean), length(), length(long), DataFile.BufferHolder.unmap(boolean), DataFile.BufferHolder.flush(boolean) methods. It is not necessary to call this method before deletion the file by DataFileModel.delete(DataFile) method.

If readOnly argument is true, this file will be used only for reading data. In particular, the length(long) method will not be called. The read-only mode will be actual until closing file; the next open method may change this mode.

If the file does not exist yet, then behavior of this method depends on readOnly argument. If it is false (read/write mode), this method tries to create it at the position theModelWhichCreatedThisFile.getPath(thisFile). If it is true (read-only mode), this method just throws IOError with the corresponding cause (usually FileNotFoundException). In the first case, the length of the newly created file is always 0.

This method returns DataFile.OpenResult.CREATED if and only if readOnly argument is false and the data file was successfully created. In all other cases this method returns DataFile.OpenResult.OPENED.

Parameters:

readOnly - if true, the file data will be read but will not be changed.

Returns:

DataFile.OpenResult.CREATED if this method has successfully created the new file, DataFile.OpenResult.OPENED in all other cases.

Throws:

java.io.IOError - in a case of some disk errors or if the argument is true and there is no file with the given position.

See Also:

close()

close

void close()

Closes data file. Does nothing if it is already closed. It disables all other further operations, besides open(boolean) and DataFileModel.delete(DataFile) methods.

Please note that there are no guarantees that this method completely releases all system resources, associated with this data file. Please see comments to classes DefaultDataFileModel and StandardIODataFileModel about behavior of this method in that data file models.

Throws:

java.io.IOError - in a case of some disk errors.

See Also:

open(boolean)

force

void force()

Tries to write any updates of this data file to the storage device that contains it.

isReadOnly

boolean isReadOnly()

Returns the argument passed to last open(boolean) method.

This method never throws exceptions.

Returns:

true if the file is opened in read-only mode.

map

DataFile.BufferHolder map(DataFile.Range range,
                          boolean notLoadDataFromFile)

Maps a region of this data file directly into memory. It is an analog (usually a wrapper) of standard FileChannel.map method. The mapping mode (read-write or read-only) may depend on the argument of the previous call of the open(boolean) method.

This method is used by this package in very restricted manner. If you implement this method in your own DataFileModel, you can be sure that the arguments the following conditions are true:

1. range.position()=bankSize*k, where bankSize is the result of DataFileModel.recommendedBankSize(boolean) method of your data file model and k is some non-negative integer;
2. range.length()<=bankSize;
3. the same positions are never mapped 2 or more times simultaneously for one file: DataFile.BufferHolder.unmap(boolean) method is always called before the same position will be mapped again.

In particular, it means that the regions mapped by this package never overlap.

If notLoadDataFromFile argument is true, this method may ignore the current data in this data file. This method is called by this package with notLoadDataFromFile==true if the returned buffer will be immediately filled by some values, not depending on the previous file content.

Parameters:

range - the position within the file at which the mapped region starts and the size of the region to be mapped. In current version, the region size (range.length() must not be greater than Integer.MAX_VALUE.

notLoadDataFromFile - if true, this method may discard the previous content of the specified region of the data file.

Returns:

an object allowing to access mapped data.

Throws:

java.io.IOError - in a case of some disk errors.

length

long length()

Returns the current length of the data file.

Returns:

the current length of the data file.

Throws:

java.io.IOError - in a case of some disk errors.

length

void length(long newLength)

Resizes the data file.

Parameters:

newLength - new length of data file.

Throws:

java.io.IOError - in a case of some disk errors.