Package net.algart.arrays

Interface DataFile.BufferHolder

Enclosing interface:

DataFile

public static interface DataFile.BufferHolder

An object allowing to access mapped data, returned by the DataFile.map(net.algart.arrays.DataFile.Range, boolean) method.

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

Method Summary

Modifier and Type	Method	Description
ByteBuffer	data()	Returns the mapped data.
boolean	dispose()	This method either performs the same actions as unmap(false) method and returns true, or performs some reduced form of unmapping (or even does nothing) and returns false.
void	flush(boolean forcePhysicalWriting)	Forces any changes made to this buffer's content to be written to the storage device containing the mapped object.
boolean	isLoadedFromCache()	Returns true if this object was not actually read from the file by DataFile.map(Range, boolean) method, but was quickly loaded from some cache.
void	load()	Makes an effort to ensure that this buffer's content will be resident in physical memory.
Object	mappingObject()	Returns the object which deallocation by the garbage collector allows all manipulations with the source mappable object, including deletion and any resizing.
DataFile.Range	range()	Returns the mapped region within the file, in bytes.
void	unmap(boolean forcePhysicalWriting)	Unmaps the data: releases all system resources associated with this mapping.

Method Details

range

DataFile.Range range()

Returns the mapped region within the file, in bytes. The result is identical to the first argument of DataFile.map(Range, boolean) method, which was called to create this instance.

Returns:

the mapped region within the file, in bytes.

data

ByteBuffer data()

Returns the mapped data. Usually returns MappedByteBuffer/

This method never throws exceptions.

Returns:

the mapped data.

mappingObject

Object mappingObject()

Returns the object which deallocation by the garbage collector allows all manipulations with the source mappable object, including deletion and any resizing. Usually returns the same result as data().

Used by implementation of AlgART arrays with Finalizer.invokeOnDeallocation(java.lang.Object, java.lang.Runnable) method.

This method never throws exceptions.

Returns:

the object which deallocation allows all manipulations with the source mappable object.

load

void load()

Makes an effort to ensure that this buffer's content will be resident in physical memory. In other words, this method tries to preload the content of this buffer into RAM to provide fastest access to its content in the nearest future.

flush

void flush(boolean forcePhysicalWriting)

Forces any changes made to this buffer's content to be written to the storage device containing the mapped object.

This method may not perform immediate writing data to the storage devices. But it guarantees that any changes in the buffer's content will not be lost. More precisely, it guarantees that:

• this data will be correctly read by possible next call of DataFile.map(net.algart.arrays.DataFile.Range, boolean) method;
• and, for non-temporary files (i.e. for any instances of DataFile which were not created by DataFileModel.createTemporary(boolean) method), the data will be really stored in the file and will be able to be loaded by another software, at least, after shutting down JVM. (There is no this guarantee for temporary files: such files are used by this application only and automatically deleted while JVM shutdown.)

If the forcePhysicalWriting argument is true, this method tries to write data to the storage device immediately. For data file models implemented in this package, it means that the data will be really stored on the disk and will be immediately available for reading by another applications.

Parameters:

forcePhysicalWriting - is it necessary to try forcing physical writing all associated resources to the external device.

Throws:

IOError - in a case of some disk errors.

unmap

void unmap(boolean forcePhysicalWriting)

Unmaps the data: releases all system resources associated with this mapping.

This method always performs, at least, the same actions as flush(forcePhysicalWriting) method with the same forcePhysicalWriting argument.

This method may do not actual unmapping. For example, its implementation for DefaultDataFileModel does not unmap the data.

After calling this method, this instance must not be used, excepting calling methods mappingObject(), isLoadedFromCache() and toString(). In particular, this method must not be called twice. Moreover, behavior of the ByteBuffer returned by the last call of data() method becomes undefined.

Parameters:

forcePhysicalWriting - is it necessary to try forcing physical writing all associated resources to the external device.

Throws:

IOError - in a case of some disk errors.

dispose

boolean dispose()

This method either performs the same actions as unmap(false) method and returns true, or performs some reduced form of unmapping (or even does nothing) and returns false.

This method is called by AlgART array manager for temporary data files when we are absolutely sure that the this buffer's content will never be useful in future and may be lost. Namely, it is called while array finalization and while system shutdown. (In all other cases, unmap(boolean) method is called instead.)

So, the implementation of this method should release all external resources, if there are such resources assosiated with this mapping buffer, but may not to force writing buffer's content to external device, if it requires long time.

In DefaultDataFileModel, this method is equivalent to unmap(false)} and always returns true. If StandardIODataFileModel (that does not associate any resources with every buffer), this method does nothing and always returns false.

After calling this method, this instance must not be used, excepting calling methods mappingObject(), isLoadedFromCache() and toString(). In particular, this method must not be called twice. Moreover, behavior of the ByteBuffer returned by the last call of data() method becomes undefined.

Returns:

true if this method has performed all actions that are performed by unmap(false). If (and only if) the result is true, we can be sure that the same data will be loaded by next call DataFile.map(net.algart.arrays.DataFile.Range, boolean) method.

Throws:

IOError - in a case of some disk errors.

isLoadedFromCache

boolean isLoadedFromCache()

Returns true if this object was not actually read from the file by DataFile.map(Range, boolean) method, but was quickly loaded from some cache.

This method is used only for debugging (logging).

This method never throws exceptions.

Returns:

true if this object was quickly loaded from some cache.