Module convex.core

Package convex.etch

Class EtchStore

java.lang.Object

convex.core.store.AStore

convex.core.store.ACachedStore

convex.etch.EtchStore

All Implemented Interfaces:

Closeable, AutoCloseable

public class EtchStore
extends ACachedStore

Class implementing on-disk memory-mapped storage of Convex data. "There are only two hard things in Computer Science: cache invalidation and naming things." - Phil Karlton Objects are keyed by cryptographic hash. That solves naming. Objects are immutable. That solves cache invalidation. Garbage collection is left as an exercise for the reader.

Field Summary

Fields inherited from class convex.core.store.ACachedStore

encoder, refCache

Constructor Summary

Constructors

Constructor	Description
EtchStore(Etch etch)

Method Summary

Modifier and Type	Method	Description
protected <T extends ACell> void	addToCache(Ref<T> ref)
void	close()	Closes this store and frees associated resources
static EtchStore	create(File file)	Creates an EtchStore using a specified file.
static EtchStore	createTemp()	Create an Etch store using a new temporary file with a generated prefix
static EtchStore	createTemp(String prefix)	Create an Etch store using a new temporary file with the given prefix
void	flush()	Ensure the store is fully persisted to disk
Etch	getEtch()	Gets the underlying Etch instance
File	getFile()
String	getFileName()	Gets the database file name for this EtchStore
Hash	getRootHash()	Gets the hash of the root data from the store.
<T extends ACell> Ref<T>	readStoreRef(Hash hash)
<T extends ACell> Ref<T>	refForHash(Hash hash)	Gets the stored Ref for a given hash value, or null if not found in the store.
<T extends ACell> Ref<T>	setRootData(T data)	Sets the root data for this Store
String	shortName()
void	startGC()	Starts a GC cycle.
<T extends ACell> Ref<T>	storeRef(Ref<T> ref, int status, Consumer<Ref<ACell>> noveltyHandler)	Stores a @Ref in long term storage as defined by this store implementation.
<T extends ACell> Ref<T>	storeRef(Ref<T> ref, int requiredStatus, Consumer<Ref<ACell>> noveltyHandler, boolean topLevel)
<T extends ACell> Ref<T>	storeTopRef(Ref<T> ref, int status, Consumer<Ref<ACell>> noveltyHandler)	Stores a top level @Ref in long term storage as defined by this store implementation.
String	toString()

Methods inherited from class convex.core.store.ACachedStore

checkCache, decode, getEncoder

Methods inherited from class convex.core.store.AStore

getRootData, getRootRef

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

EtchStore

public EtchStore(Etch etch)

Method Details

startGC

public void startGC()
             throws IOException

Starts a GC cycle. Creates a new Etch file for collection, and directs all new writes to the new store

Throws:

IOException - If an IO exception occurs

create

public static EtchStore create(File file)
                        throws IOException

Creates an EtchStore using a specified file.

Parameters:

file - File to use for storage. Will be created it it does not already exist.

Returns:

EtchStore instance

Throws:

IOException - If an IO error occurs

createTemp

public static EtchStore createTemp(String prefix)
                            throws IOException

Create an Etch store using a new temporary file with the given prefix

Parameters:

prefix - String prefix for temporary file

Returns:

New EtchStore instance

Throws:

IOException - In case of IO error creating database

createTemp

public static EtchStore createTemp()
                            throws IOException

Create an Etch store using a new temporary file with a generated prefix

Returns:

New EtchStore instance

Throws:

IOException - In case of IO error creating database

refForHash

public <T extends ACell> Ref<T> refForHash(Hash hash)

Description copied from class: AStore

Gets the stored Ref for a given hash value, or null if not found in the store. If the result is non-null, the Ref will have a status equal to STORED at minimum. Calls to Ref.getValue() should therefore never throw MissingDataException.

Specified by:

refForHash in class AStore

Parameters:

hash - A hash value to look up in the persisted store

Returns:

The stored Ref, or null if the hash value is not persisted

readStoreRef

public <T extends ACell> Ref<T> readStoreRef(Hash hash)
                                      throws IOException

Throws:

IOException

storeRef

public <T extends ACell> Ref<T> storeRef(Ref<T> ref,
 int status,
 Consumer<Ref<ACell>> noveltyHandler)
                                  throws IOException

Description copied from class: AStore

Stores a @Ref in long term storage as defined by this store implementation. Will store nested Refs if required. Does not store embedded values. If it is necessary to persist an embedded value deliberately in the store, use storeTopRef(...) instead. If the persisted Ref represents novelty (i.e. not previously stored) Will call the provided noveltyHandler.

Specified by:

storeRef in class AStore

Parameters:

ref - A Ref to the given object. Should be either Direct or STORED at minimum to present risk of MissingDataException.

status - Status to store at

noveltyHandler - Novelty Handler function for Novelty detected. May be null.

Returns:

The persisted Ref, of status STORED at minimum

Throws:

IOException - in case of IO error during persistence

storeTopRef

public <T extends ACell> Ref<T> storeTopRef(Ref<T> ref,
 int status,
 Consumer<Ref<ACell>> noveltyHandler)
                                     throws IOException

Description copied from class: AStore

Stores a top level @Ref in long term storage as defined by this store implementation. Will store nested Refs if required. Will only store an embedded Ref if it is the top level item. If the persisted Ref represents novelty (i.e. not previously stored) Will call the provided noveltyHandler

Specified by:

storeTopRef in class AStore

Parameters:

ref - A Ref to the given object. Should be either Direct or STORED at minimum to present risk of MissingDataException.

status - Status to store at

noveltyHandler - Novelty Handler function for Novelty detected. May be null.

Returns:

The persisted Ref, of status STORED at minimum

Throws:

IOException - in case of IO error during persistence

storeRef

public <T extends ACell> Ref<T> storeRef(Ref<T> ref,
 int requiredStatus,
 Consumer<Ref<ACell>> noveltyHandler,
 boolean topLevel)
                                  throws IOException

Throws:

IOException

addToCache

protected <T extends ACell> void addToCache(Ref<T> ref)

toString

public String toString()

Overrides:

toString in class Object

getFileName

public String getFileName()

Gets the database file name for this EtchStore

Returns:

File name as a String

close

public void close()

Description copied from class: AStore

Closes this store and frees associated resources

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in class AStore

flush

public void flush()
           throws IOException

Ensure the store is fully persisted to disk

Throws:

IOException - If an IO error occurs

getFile

public File getFile()

getRootHash

public Hash getRootHash()
                 throws IOException

Description copied from class: AStore

Gets the hash of the root data from the store. In order to set the root hash, go via setRootData.

Specified by:

getRootHash in class AStore

Returns:

Root hash value from this store.

Throws:

IOException - In case of store IO error

setRootData

public <T extends ACell> Ref<T> setRootData(T data)
                                     throws IOException

Description copied from class: AStore

Sets the root data for this Store

Specified by:

setRootData in class AStore

Parameters:

data - Root data to set

Returns:

Ref to written root data

Throws:

IOException - In case of store IO error

getEtch

public Etch getEtch()

Gets the underlying Etch instance

Returns:

Etch instance

shortName

public String shortName()

Specified by:

shortName in class AStore