com.bigdata.rawstore
Interface IRawStore

All Superinterfaces:

IAddressManager, IStoreSerializer

All Known Subinterfaces:

IAtomicStore, IBufferStrategy, IDiskBasedStrategy, IJournal, IUpdateStore

All Known Implementing Classes:

AbstractBufferStrategy, AbstractJournal, AbstractRawStore, AbstractRawWormStore, BasicBufferStrategy, BufferedDiskStrategy, DirectBufferStrategy, DiskBackedBufferStrategy, DiskOnlyStrategy, IndexSegmentStore, Journal, MappedBufferStrategy, SimpleMemoryRawStore, StoreManager.ManagedJournal, TemporaryRawStore, TemporaryStore, TransientBufferStrategy

public interface IRawStore
extends IAddressManager, IStoreSerializer

A low-level interface for reading and writing data. This interface is not isolated and operations do not possess ACID semantics. Implementations may or may not be durable. All operations are expressed in terms of long integers that are often called "addresses" but which should be understood as opaque identifiers.

The AbstractJournal is the principal implementation of this interface and provides both transient and durable options and the facilities for atomic commit. BTree provides a higher level interface for operations on an IRawStore and uses a copy-on-write policy designed to support transactional semantics by making it possible to read from a consistent historical state. The AbstractJournal provides the necessary mechanisms to support transactions based on the copy-on-write semantics of the BTree.

The IRawStore supports write and read back on immutable addresses and does NOT directly support update of data for an immutable address once that data has been written. Applications seeking Create, Read, Update, Delete (CRUD) semantics should use a BTree to store their application data. Unlike this interface, the BTree can correctly support update and delete of application data using a persistent identifier (the key).

Version:

$Id: IRawStore.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

See Also:

AbstractJournal, BTree

TODO:

The existing implementations of this interface do NOT support the release and reuse of allocated records - that is, they are all Write Once Read Many stores rather than read/write stores. A read-write implementation of this interface is of course possible and will require a means to allocate, release, and reallocate chunks of varying sizes within the store. Those chunks may either be drawn from a set of fixed sized allocation pools spanning a variety of useful record sizes or can use a strategy where records are allocated on an exact fit basis the first time and reallocated on a best/good fit basis. A free list can offer fast best-fit or good fit access to chunks in the store that are available for reuse. Any such approach must serialize allocations by one means or another, even though different allocation pools might be used concurrently. A delete() operation on IRawStore should be defined so that we can release storage that is no longer required for data versions that can not be accessed by any current transaction (a gc strategy). This would make it possible for us to implement a scale up store based on a single monolithic file. FIXME The use of the ByteBuffer in this API has become limiting. It would be nicer to specify a byte[] with optional offset and length parameters. This would make it easier to wrap the byte[] in different ways for reading and writing. The ByteBuffer has an advantage when reading since it allows us to return a read-only view of the record, but in practice that is only effective for an in-memory store (with or without a backing file). The byte[] is more flexible. The caller is free to reuse the byte[] and the store always copies the data.

Field Summary

Fields inherited from interface com.bigdata.rawstore.IAddressManager

NULL

Method Summary

void	close() Close the store immediately, but does not clear any records for the store from the IGlobalLRU.
void	deleteResources() Deletes the backing file(s) (if any) and clears any records for the store from the IGlobalLRU.
void	destroy() Closes the store immediately, deletes its persistent resources, and clears any records for the store from the IGlobalLRU.
void	force(boolean metadata) Force the data to stable storage.
CounterSet	getCounters() Reports performance counters.
File	getFile() The backing file -or- null if there is no backing file for the store.
IResourceMetadata	getResourceMetadata() A description of this store in support of the scale-out architecture.
UUID	getUUID() Return the UUID which identifies this IRawStore.
boolean	isFullyBuffered() True iff the store is fully buffered (all reads are against memory).
boolean	isOpen() true iff the store is open.
boolean	isReadOnly() true iff the store does not allow writes.
boolean	isStable() True iff backed by stable storage.
ByteBuffer	read(long addr) Read the data (unisolated).
long	size() The #of application data bytes written on the store (does not count any headers or root blocks that may exist for the store).
long	write(ByteBuffer data) Write the data (unisolated).

Methods inherited from interface com.bigdata.rawstore.IAddressManager

getByteCount, getOffset, packAddr, toAddr, toString, unpackAddr

Methods inherited from interface com.bigdata.rawstore.IStoreSerializer

deserialize, deserialize, deserialize, serialize

Method Detail

write

long write(ByteBuffer data)

Write the data (unisolated).

Parameters:

data - The data. The bytes from the current Buffer.position() to the Buffer.limit() will be written and the Buffer.position() will be advanced to the Buffer.limit() . The caller may subsequently modify the contents of the buffer without changing the state of the store (i.e., the data are copied into the store).

Returns:

A long integer formed that encodes both the offset from which the data may be read and the #of bytes to be read. See IAddressManager.

Throws:

IllegalArgumentException - if data is null.

IllegalArgumentException - if data has zero bytes Buffer.remaining().

IllegalStateException - if the store is not open.

IllegalStateException - if the store does not allow writes.

TODO:

define exception if the maximum extent would be exceeded., the addresses need to reflect the ascending offset at which the data are written, at least for a class of append only store. some stores, such as the Journal, also have an offset from the start of the file to the start of the data region (in the case of the Journal it is used to hold the root blocks).

read

ByteBuffer read(long addr)

Read the data (unisolated).

Parameters:

addr - A long integer that encodes both the offset from which the data will be read and the #of bytes to be read. See IAddressManager.toAddr(int, long).

Returns:

The data read. The buffer will be flipped to prepare for reading (the position will be zero and the limit will be the #of bytes read).

Throws:

IllegalArgumentException - If the address is known to be invalid (never written or deleted). Note that the address 0L is always invalid.

IllegalStateException - if the store is not open.

isOpen

boolean isOpen()

true iff the store is open.

Returns:

true iff the store is open.

isReadOnly

boolean isReadOnly()

true iff the store does not allow writes.

Throws:

IllegalStateException - if the store is not open.

close

void close()

Close the store immediately, but does not clear any records for the store from the IGlobalLRU.

Throws:

IllegalStateException - if the store is not open.

deleteResources

void deleteResources()

Deletes the backing file(s) (if any) and clears any records for the store from the IGlobalLRU.

Throws:

IllegalStateException - if the store is open.

RuntimeException - if the backing file exists and could not be deleted.

destroy

void destroy()

Closes the store immediately, deletes its persistent resources, and clears any records for the store from the IGlobalLRU.

See Also:

deleteResources()

getFile

File getFile()

The backing file -or- null if there is no backing file for the store.

getUUID

UUID getUUID()

Return the UUID which identifies this IRawStore. This supports both getResourceMetadata() and the LRUNexus.

getResourceMetadata

IResourceMetadata getResourceMetadata()

A description of this store in support of the scale-out architecture.

isStable

boolean isStable()

True iff backed by stable storage.

Throws:

IllegalStateException - if the store is not open.

isFullyBuffered

boolean isFullyBuffered()

True iff the store is fully buffered (all reads are against memory). Implementations MAY change the value returned by this method over the life cycle of the store, e.g., to conserve memory a store may drop or decrease its buffer if it is backed by disk.

Note: This does not guarantee that the OS will not swap the buffer onto disk.

Throws:

IllegalStateException - if the store is not open.

force

void force(boolean metadata)

Force the data to stable storage. While this is NOT sufficient to guarantee an atomic commit, the data must be forced to disk as part of an atomic commit protocol.

Parameters:

metadata - If true, then force both the file contents and the file metadata to disk.

Throws:

IllegalStateException - if the store is not open.

size

long size()

The #of application data bytes written on the store (does not count any headers or root blocks that may exist for the store).

getCounters

CounterSet getCounters()

Reports performance counters.