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:
StoreWAL - permanent record store with transactions
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.
| 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. |
| 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'.
|
| 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.
|
static final long RECID_NAME_CATALOG
Content of this map is manipulated by DB class.
DB and higher level functions. Those are preallocated when store is created.static final long RECID_CLASS_CATALOG
Points to class catalog. A list of classes used in SerializerPojo
to serialize java objects.
DB and higher level functions. Those are preallocated when store is created.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.
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
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.
static final Engine CLOSED_ENGINE
IllegalAccessError("already closed") on all accesslong preallocate()
<A> long put(A value,
Serializer<A> serializer)
value - records to be addedserializer - used to convert record into/from binary formNullPointerException - if serializer is null<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'
recid - (record identifier) under which record was persistedserializer - used to deserialize record from binary formNullPointerException - if serializer is null<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.
recid - (record identifier) under which record was persisted.value - new record value to be storedserializer - used to serialize record into binary formNullPointerException - if serializer is null<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:
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 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.
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 formNullPointerException - if serializer is null<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.
recid - (record identifier) under which was record persistedserializer - which may be used in some circumstances to deserialize and store old objectNullPointerException - if serializer is nullvoid 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.
close in interface AutoCloseableclose in interface Closeableboolean 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/enabledEngine getWrappedEngine()
void clearCache()
void compact()
Copyright © 2015. All Rights Reserved.