jetbrains.exodus.io

Interface DataWriter

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

public interface DataWriter
extends java.io.Closeable

DataWriter defines the way how data is written to Log, how blocks appear in the log and how they are removed from the log. Log blocks can be mutable and immutable. All blocks having length equal to maximum log block size are immutable. In any moment, only one block can be mutable. This has maximum address. DataWriter always writes to a single mutable block, that makes log appendable.

Since:

1.3.0

See Also:

Block, DataReader, DataReaderWriterProvider

Method Summary

Modifier and Type	Method and Description
void	clear() Clears Log by location specified as a parameter to DataReaderWriterProvider.newReaderWriter(String).
void	close() Closes the data writer.
boolean	isOpen() Returns true is the DataWriter is open.
boolean	lock(long timeout) If applicable, tries to acquire writer's lock in specified time.
java.lang.String	lockInfo() For debugging purposes, returns detailed information about current lock owner.
Block	openOrCreateBlock(long address, long length) Open existing block for writing or creates the new one by specified address with specified length.
boolean	release() Releases writer's lock.
void	removeBlock(long blockAddress, @NotNull RemoveBlockType rbt) Removes existing immutable block.
void	sync() If applicable, forces flush of written data to underlying storage device.
void	syncDirectory() If applicable, forces flush of changes in directory structure to underlying storage device.
void	truncateBlock(long blockAddress, long length) Truncates existing block to specified length.
Block	write(byte[] b, int off, int len) Writes (appends) binary data to Log.

Method Detail

isOpen

boolean isOpen()

Returns true is the DataWriter is open. i.e. there is an incomplete mutable block having length less than maximum log block size.

Returns:

true is the DataWriter is open

write

Block write(byte[] b,
            int off,
            int len)

Writes (appends) binary data to Log. Returns new Block instance representing mutable block.

Parameters:

b - binary data array

off - starting offset in the array

len - number of byte to write

Returns:

mutable Block instance

See Also:

Block

sync

void sync()

If applicable, forces flush of written data to underlying storage device. Transaction durability depends on the implementation of this method.

syncDirectory

void syncDirectory()

If applicable, forces flush of changes in directory structure to underlying storage device.

close

void close()

Closes the data writer. Log closes the data writer each time when mutable block becomes immutable, i.e. reaches its maximum log block size.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

clear

void clear()

Clears Log by location specified as a parameter to DataReaderWriterProvider.newReaderWriter(String). The database becomes empty.

openOrCreateBlock

Block openOrCreateBlock(long address,
                        long length)

Open existing block for writing or creates the new one by specified address with specified length. This method is used in the log recovery procedure, so DataWriter should truncate existing block if its physical length is greater than specified one. This method is always applied to a mutable block.

Parameters:

address - address of block to open or create

length - valid block length

Returns:

mutable Block instance

removeBlock

void removeBlock(long blockAddress,
                 @NotNull
                 @NotNull RemoveBlockType rbt)

Removes existing immutable block. If applicable, this method can rename block (file on a file system) instead of removing it if specified RemoveBlockType rbt is equal to RemoveBlockType.Rename.

Parameters:

blockAddress - address of block to remove

rbt - RemoveBlockType.Rename to rename block instead of removing it.

See Also:

RemoveBlockType

truncateBlock

void truncateBlock(long blockAddress,
                   long length)

Truncates existing block to specified length. Does nothing is specified length is greater than or equal to physical block length.

Parameters:

blockAddress - address of block to truncate

length - block length

lock

boolean lock(long timeout)

If applicable, tries to acquire writer's lock in specified time. If the lock is acquired, returns true. Successfully acquired lock guarantees that Log cannot be opened in parallel (within same JVM or not) unless it is released by the writer.

Parameters:

timeout - - time to wait for lock acquisition

Returns:

true if the lock is acquired

See Also:

release(), lockInfo()

release

boolean release()

Releases writer's lock.

Returns:

true if released successfully

See Also:

lock(long)

lockInfo

java.lang.String lockInfo()

For debugging purposes, returns detailed information about current lock owner. If lock(long) return false, Log throws an ExodusException with the lock info in its message.

Returns:

Human-readable information about lock owner

See Also:

lock(long)