public interface Engine
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
Most of MapDB features comes from EngineWrapper
s, which are stacked on
top of each other to provide asynchronous writes, instance cache, encryption etc..
`Engine` stack is very elegant and uniform way to handle additional functionality.
Other DBs need an ORM framework to achieve similar features.
In default configuration MapDB runs with this `Engine` stack:
* **DISK** - raw file or memory
* StoreWAL
- permanent record store with transactions
* Caches.HashTable
- instance cache
* **USER** - DB
and collections
TODO document more examples of Engine wrappers
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.Modifier and Type | Field and Description |
---|---|
static long |
CATALOG_RECID |
static long |
CHECK_RECORD |
static long |
CLASS_INFO_RECID |
static long |
LAST_RESERVED_RECID |
Modifier and Type | Method and Description |
---|---|
boolean |
canRollback() |
boolean |
canSnapshot() |
void |
clearCache()
clears any underlying cache
|
void |
close()
Close store/cache.
|
void |
closeListenerRegister(Runnable closeListener) |
void |
closeListenerUnregister(Runnable closeListener) |
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
Recid must be a number returned by 'put' method.
|
<A> A |
get(long recid,
Serializer<A> serializer)
Get existing record.
|
SerializerPojo |
getSerializerPojo()
Deprecated.
|
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.
|
void |
preallocate(long[] recids)
Preallocates recids 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.
|
static final long CATALOG_RECID
static final long CLASS_INFO_RECID
static final long CHECK_RECORD
static final long LAST_RESERVED_RECID
long preallocate()
void preallocate(long[] recids)
recids
- array to put result into<A> long put(A value, Serializer<A> serializer)
value
- records to be addedserializer
- used to convert record into/from binary form<A> A get(long recid, Serializer<A> serializer)
recid
- (record identifier) under which record was persistedserializer
- used to deserialize record from binary form<A> void update(long recid, A value, Serializer<A> serializer)
recid
- (record identifier) under which record was persisted.value
- new record value to be storedserializer
- used to serialize record into binary form<A> boolean compareAndSwap(long recid, A expectedOldValue, A newValue, Serializer<A> serializer)
oldValue==expectedOldValue
when old value is found in instance cacheoldValue
using serializer
and checking oldValue.equals(expectedOldValue)
expectedOldValue
using serializer
and comparing binary array with already serialized oldValue
recid
- (record identifier) under which record was persisted.expectedOldValue
- old value to be compared with existing recordnewValue
- to be written if values are matchingserializer
- used to serialize record into binary form<A> void delete(long recid, Serializer<A> serializer)
recid
- (record identifier) under which was record persistedserializer
- which may be used in some circumstances to deserialize and store old objectvoid close()
NullPointerException
There is an configuration option DBMaker.closeOnJvmShutdown()
which uses shutdown hook to automatically
close Engine when JVM shutdowns.boolean isClosed()
void commit()
void rollback() throws UnsupportedOperationException
UnsupportedOperationException
.UnsupportedOperationException
- if transactions are disabledboolean isReadOnly()
boolean canRollback()
boolean canSnapshot()
Engine snapshot() throws UnsupportedOperationException
UnsupportedOperationException
- if snapshots are not supported/enabledEngineWrapper.canSnapshot()
void clearCache()
void compact()
@Deprecated SerializerPojo getSerializerPojo()
void closeListenerRegister(Runnable closeListener)
void closeListenerUnregister(Runnable closeListener)
Copyright © 2019. All rights reserved.