org.mapdb

Interface Engine

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

Engine.CloseOnJVMShutdown, Engine.ReadOnly, Engine.ReadOnlyWrapper, Store, StoreAppend, StoreArchive, StoreCached, StoreDirect, StoreDirect.Snapshot, StoreHeap, StoreHeap.Snapshot, StoreWAL, TxEngine, TxEngine.Tx

public interface Engine
extends Closeable

Centerpiece for record management, Engine is simple key value store. Engine is low-level interface and is not meant to be used directly by user. For most operations user should use DB class.

In this store key is primitive long number, typically pointer to index table. Value is class instance. To turn value into/from binary form serializer is required as extra argument for most operations.

Unlike other DBs MapDB does not expect user to (de)serialize data before they are passed as arguments. Instead MapDB controls (de)serialization itself. This gives DB a lot of flexibility: for example instances may be held in cache to minimise number of deserializations, or modified instance can be placed into queue and asynchronously written on background thread.

There is Store subinterface for raw persistence

In default configuration MapDB runs with this Engine stack:

1. DISK - raw file or memory
2. StoreWAL - permanent record store with transactions
3. USER - DB and collections

TODO Engine Wrappers are sort of obsole, update this whole section

Engine uses recid to identify records. There is zero error handling in case recid is invalid (random number or already deleted record). Passing illegal recid may result into anything (return null, throw EOF or even corrupt store). Engine is considered low-level component and it is responsibility of upper layers (collections) to ensure recid is consistent. Lack of error handling is trade of for speed (similar way as manual memory management in C++)

Engine must support null record values. You may insert, update and fetch null records. Nulls play important role in recid preallocation and asynchronous writes.

Recid can be reused after it was deleted. If your application relies on unique being unique, you should update record with null value, instead of delete. Null record consumes only 8 bytes in store and is preserved during defragmentation.

Author:

Jan Kotek

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Engine.CloseOnJVMShutdown Closes Engine on JVM shutdown using shutdown hook: Runtime.addShutdownHook(Thread) If engine was closed by user before JVM shutdown, hook is removed to save memory.
static class	Engine.ReadOnly
static class	Engine.ReadOnlyWrapper Wraps an Engine and throws UnsupportedOperationException("Read-only") on any modification attempt.

Field Summary

Fields

Modifier and Type	Field and Description
static Engine	CLOSED_ENGINE throws IllegalAccessError("already closed") on all access
static long	RECID_CLASS_CATALOG Points to class catalog.
static long	RECID_FIRST There are 8 reserved record ids.
static long	RECID_LAST_RESERVED There are 8 reserved record ids.
static long	RECID_NAME_CATALOG Content of this map is manipulated by DB class.
static long	RECID_RECORD_CHECK Recid used for 'record check'.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRollback()
boolean	canSnapshot()
void	clearCache() clears any underlying cache
void	close() Close store/cache.
void	commit() Makes all changes made since the previous commit/rollback permanent.
void	compact()
<A> boolean	compareAndSwap(long recid, A expectedOldValue, A newValue, Serializer<A> serializer) Updates existing record in atomic (Compare And Swap) manner.
<A> void	delete(long recid, Serializer<A> serializer) Remove existing record from store/cache
<A> A	get(long recid, Serializer<A> serializer) Get existing record.
Engine	getWrappedEngine() if this is wrapper return underlying engine, or null
boolean	isClosed() Checks whether Engine was closed.
boolean	isReadOnly() Check if you can write into this Engine.
long	preallocate() Preallocates recid for not yet created record.
<A> long	put(A value, Serializer<A> serializer) Insert new record.
void	rollback() Undoes all changes made in the current transaction.
Engine	snapshot() Returns read-only snapshot of data in Engine.
<A> void	update(long recid, A value, Serializer<A> serializer) Update existing record with new value.

Field Detail

RECID_NAME_CATALOG

static final long RECID_NAME_CATALOG

Content of this map is manipulated by DB class.

There are 8 reserved record ids. They store information relevant to DB and higher level functions. Those are preallocated when store is created.

See Also:

Constant Field Values

RECID_CLASS_CATALOG

static final long RECID_CLASS_CATALOG

Points to class catalog. A list of classes used in SerializerPojo to serialize java objects.

There are 8 reserved record ids. They store information relevant to DB and higher level functions. Those are preallocated when store is created.

See Also:

Constant Field Values

RECID_RECORD_CHECK

static final long RECID_RECORD_CHECK

Recid used for 'record check'. This record is loaded when store is open, to ensure configuration such as encryption and compression is correctly set and \ data are read-able.

There are 8 reserved record ids. They store information relevant to DB and higher level functions. Those are preallocated when store is created.

See Also:

Constant Field Values

RECID_LAST_RESERVED

static final long RECID_LAST_RESERVED

There are 8 reserved record ids. They store information relevant to DB and higher level functions. Those are preallocated when store is created.

This value is last reserved record id. User ids (recids returned by put(Object, Serializer)) starts from RECID_LAST_RESERVED+1

See Also:

Constant Field Values

RECID_FIRST

static final long RECID_FIRST

There are 8 reserved record ids. They store information relevant to DB and higher level functions. Those are preallocated when store is created.

This constant is first recid available to user. It is first value returned by put(Object, Serializer) if store is empty.

See Also:

Constant Field Values

CLOSED_ENGINE

static final Engine CLOSED_ENGINE

throws IllegalAccessError("already closed") on all access

Method Detail

preallocate

long preallocate()

Preallocates recid for not yet created record. It does not insert any data into it.

Returns:

new recid

put

<A> long put(A value,
           Serializer<A> serializer)

Insert new record.

Parameters:

value - records to be added

serializer - used to convert record into/from binary form

Returns:

recid (record identifier) under which record is stored.

Throws:

NullPointerException - if serializer is null

get

<A> A get(long recid,
        Serializer<A> serializer)

Get existing record.

Recid must be a number returned by 'put' method. Behaviour for invalid recid (random number or already deleted record) is not defined, typically it returns null or throws 'EndOfFileException'

Parameters:

recid - (record identifier) under which record was persisted

serializer - used to deserialize record from binary form

Returns:

record matching given recid, or null if record is not found under given recid.

Throws:

NullPointerException - if serializer is null

update

<A> void update(long recid,
              A value,
              Serializer<A> serializer)

Update existing record with new value.

Recid must be a number returned by 'put' method. Behaviour for invalid recid (random number or already deleted record) is not defined, typically it throws 'EndOfFileException', but it may also corrupt store.

Parameters:

recid - (record identifier) under which record was persisted.

value - new record value to be stored

serializer - used to serialize record into binary form

Throws:

NullPointerException - if serializer is null

compareAndSwap

<A> boolean compareAndSwap(long recid,
                         A expectedOldValue,
                         A newValue,
                         Serializer<A> serializer)

Updates existing record in atomic (Compare And Swap) manner. Value is modified only if old value matches expected value. There are three ways to match values, MapDB may use any of them:

1. Equality check oldValue==expectedOldValue when old value is found in instance cache
2. Deserializing oldValue using serializer and checking oldValue.equals(expectedOldValue)
3. Serializing expectedOldValue using serializer and comparing binary array with already serialized oldValue

Recid must be a number returned by 'put' method. Behaviour for invalid recid (random number or already deleted record) is not defined, typically it throws 'EndOfFileException', but it may also corrupt store.

Parameters:

recid - (record identifier) under which record was persisted.

expectedOldValue - old value to be compared with existing record

newValue - to be written if values are matching

serializer - used to serialize record into binary form

Returns:

true if values matched and newValue was written

Throws:

NullPointerException - if serializer is null

delete

<A> void delete(long recid,
              Serializer<A> serializer)

Remove existing record from store/cache

Recid must be a number returned by 'put' method. Behaviour for invalid recid (random number or already deleted record) is not defined, typically it throws 'EndOfFileException', but it may also corrupt store.

Parameters:

recid - (record identifier) under which was record persisted

serializer - which may be used in some circumstances to deserialize and store old object

Throws:

NullPointerException - if serializer is null

close

void close()

Close store/cache. This method must be called before JVM exits to flush all caches and prevent store corruption. Also it releases resources used by MapDB (disk, memory..).

Engine can no longer be used after this method was called. If Engine is used after closing, it may throw any exception including NullPointerException

There is an configuration option DBMaker.Maker.closeOnJvmShutdown() which uses shutdown hook to automatically close Engine when JVM shutdowns.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

isClosed

boolean isClosed()

Checks whether Engine was closed.

Returns:

true if engine was closed

commit

void commit()

Makes all changes made since the previous commit/rollback permanent. In transactional mode (on by default) it means creating journal file and replaying it to storage. In other modes it may flush disk caches or do nothing at all (check your config options)

rollback

void rollback()
              throws UnsupportedOperationException

Undoes all changes made in the current transaction. If transactions are disabled it throws UnsupportedOperationException.

Throws:

UnsupportedOperationException - if transactions are disabled

isReadOnly

boolean isReadOnly()

Check if you can write into this Engine. It may be readonly in some cases (snapshot, read-only files).

Returns:

true if engine is read-only

canRollback

boolean canRollback()

Returns:

true if engine supports rollback

canSnapshot

boolean canSnapshot()

Returns:

true if engine can create read-only snapshots

snapshot

Engine snapshot()
                throws UnsupportedOperationException

Returns read-only snapshot of data in Engine.

Throws:

UnsupportedOperationException - if snapshots are not supported/enabled

getWrappedEngine

Engine getWrappedEngine()

if this is wrapper return underlying engine, or null

clearCache

void clearCache()

clears any underlying cache

compact

void compact()