com.bigdata.rawstore
Interface IRawStore

All Superinterfaces:

IAddressManager, ICounterSetAccess

All Known Subinterfaces:

IAllocationManagerStore, IAtomicStore, IBufferStrategy, IDiskBasedStrategy, IHABufferStrategy, IJournal, IRWStrategy

All Known Implementing Classes:

AbstractBufferStrategy, AbstractJournal, AbstractRawStore, AbstractRawWormStore, BasicBufferStrategy, DirectBufferStrategy, DiskBackedBufferStrategy, DiskOnlyStrategy, IndexSegmentStore, Journal, JournalDelegate, MappedBufferStrategy, MemStore, MemStrategy, RWStrategy, SimpleMemoryRawStore, StoreManager.ManagedJournal, TemporaryRawStore, TemporaryStore, TransientBufferStrategy, WORMStrategy

public interface IRawStore
extends IAddressManager, ICounterSetAccess

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 6369 2012-06-28 16:16:59Z thompsonbry $

Author:

Bryan Thompson

See Also:

AbstractJournal, FIXME This should be restated in terms of {@link IByteArrayBuffer}. The use of the {@link 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 {@link 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. In practice, we tend to work around this by copying to an array backed {@link ByteBuffer} or to a byte[] wrapped as an {@link IByteArrayBuffer} .

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	delete(long addr) Delete the data (unisolated).
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 (if open), deletes its persistent resources, and clears any records for the store from the IGlobalLRU.
void	force(boolean metadata) Force the data to stable storage.
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, getPhysicalAddress, toAddr, toString

Methods inherited from interface com.bigdata.counters.ICounterSetAccess

getCounters

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).

delete

void delete(long addr)

Delete the data (unisolated).

After this operation subsequent reads on the address MAY fail and the caller MUST NOT depend on the ability to read at that address.

Parameters:

addr - A long integer formed using Addr that encodes both the offset at which the data was written and the #of bytes that were written.

Throws:

IllegalArgumentException - If the address is known to be invalid (never written or deleted). Note that the address 0L is always invalid. It is only applicable in the context of a garbage collection strategy. With an append only store and with eviction of btrees into index segments there is no reason to delete anything on the store - and nothing to keep track of the delete. However, with a Read-Write store it is a requirement, and a void implementation is provided for other stores.

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 (if open), deletes its persistent resources, and clears any records for the store from the IGlobalLRU. Does NOT throw an IllegalStateException if the store is already closed, but still deletes the backing resources.

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).