org.bitcoinj.store

Class DatabaseFullPrunedBlockStore

java.lang.Object

org.bitcoinj.store.DatabaseFullPrunedBlockStore

All Implemented Interfaces:

UTXOProvider, BlockStore, FullPrunedBlockStore

Direct Known Subclasses:

H2FullPrunedBlockStore, MySQLFullPrunedBlockStore, PostgresFullPrunedBlockStore

public abstract class DatabaseFullPrunedBlockStore
extends java.lang.Object
implements FullPrunedBlockStore

A generic full pruned block store for a relational database. This generic class requires certain table structures for the block store.

The following are the tables and field names/types that are assumed:

setting table

Field Name	Type (generic)
name	string
value	binary

headers table

Field Name	Type (generic)
hash	binary
chainwork	binary
height	integer
header	binary
wasundoable	boolean

undoableblocks table

Field Name	Type (generic)
hash	binary
height	integer
txoutchanges	binary
transactions	binary

openoutputs table

Field Name	Type (generic)
hash	binary
index	integer
height	integer
value	integer
scriptbytes	binary
toaddress	string
addresstargetable	integer
coinbase	boolean

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<java.sql.Connection>	allConnections
protected StoredBlock	chainHeadBlock
protected Sha256Hash	chainHeadHash
protected java.lang.ThreadLocal<java.sql.Connection>	conn
protected java.lang.String	connectionURL
protected int	fullStoreDepth
protected NetworkParameters	params
protected java.lang.String	password
protected java.lang.String	schemaName
protected java.lang.String	username
protected StoredBlock	verifiedChainHeadBlock
protected Sha256Hash	verifiedChainHeadHash

Constructor Summary

Constructors

Constructor and Description
DatabaseFullPrunedBlockStore(NetworkParameters params, java.lang.String connectionURL, int fullStoreDepth, java.lang.String username, java.lang.String password, java.lang.String schemaName) Create a new DatabaseFullPrunedBlockStore, using the full connection URL instead of a hostname and password, and optionally allowing a schema to be specified.

Method Summary

Modifier and Type	Method and Description
void	abortDatabaseBatchWrite()
void	addUnspentTransactionOutput(UTXO out) Adds a UTXO to the list of unspent TransactionOutputs
void	beginDatabaseBatchWrite() Begins/Commits/Aborts a database transaction.
java.math.BigInteger	calculateBalanceForAddress(Address address) Calculate the balance for a coinbase, to-address, or p2sh address.
void	close() Closes the store.
void	commitDatabaseBatchWrite()
void	deleteStore() Deletes the store by deleting the tables within the database.
void	dumpSizes() Dumps information about the size of actual data in the database to standard output The only truly useless data counted is printed in the form "N in id indexes" This does not take database indexes into account.
StoredBlock	get(Sha256Hash hash) Returns the StoredBlock given a hash.
StoredBlock	get(Sha256Hash hash, boolean wasUndoableOnly)
protected java.lang.String	getBalanceSelectSQL() Get the SQL to select the total balance for a given address.
StoredBlock	getChainHead() Returns the StoredBlock that represents the top of the chain of greatest total work.
int	getChainHeadHeight() Get the height of the chain head.
protected java.util.List<java.lang.String>	getCompatibilitySQL() Get the SQL statements to check if the database is compatible.
protected abstract java.util.List<java.lang.String>	getCreateIndexesSQL() Get the SQL statements that create the indexes (DDL).
protected abstract java.util.List<java.lang.String>	getCreateSchemeSQL() Get the SQL statements that create the schema (DDL).
protected abstract java.util.List<java.lang.String>	getCreateTablesSQL() Get the SQL statements that create the tables (DDL).
protected abstract java.lang.String	getDatabaseDriverClass() Get the database driver class,
protected java.lang.String	getDeleteOpenoutputsSQL() Get the SQL to delete a openoutputs record.
protected java.lang.String	getDeleteUndoableBlocksSQL() Get the SQL to delete a undoableblocks record.
protected java.util.List<java.lang.String>	getDropTablesSQL() Get the SQL to drop all the tables (DDL).
protected abstract java.lang.String	getDuplicateKeyErrorCode() Get the database specific error code that indicated a duplicate key error when inserting a record.
protected java.lang.String	getInsertHeadersSQL() Get the SQL to insert a headers record.
protected java.lang.String	getInsertOpenoutputsSQL() Get the SQL to insert a openoutputs record.
protected java.lang.String	getInsertSettingsSQL() Get the SQL to insert a settings record.
protected java.lang.String	getInsertUndoableBlocksSQL() Get the SQL to insert a undoableblocks record.
StoredBlock	getOnceUndoableStoredBlock(Sha256Hash hash) Returns the StoredBlock that was added as a StoredUndoableBlock given a hash.
java.util.List<UTXO>	getOpenTransactionOutputs(java.util.List<ECKey> keys) Get the list of UTXO's for given keys.
NetworkParameters	getParams() Get the NetworkParameters of this store.
protected java.lang.String	getSelectHeadersDumpSQL() Get the SQL to select the headers dump fields for sizing/statistics.
protected java.lang.String	getSelectHeadersSQL() Get the SQL to select a headers record.
protected java.lang.String	getSelectOpenoutputsCountSQL() Get the SQL to select count of openoutputs.
protected java.lang.String	getSelectopenoutputsDumpSQL() Get the SQL to select the openoutouts dump fields for sizing/statistics.
protected java.lang.String	getSelectOpenoutputsSQL() Get the SQL to select a openoutputs record.
protected java.lang.String	getSelectSettingsDumpSQL() Get the SQL to select the setting dump fields for sizing/statistics.
protected java.lang.String	getSelectSettingsSQL() Get the SQL to select a setting value.
protected java.lang.String	getSelectUndoableblocksDumpSQL() Get the SQL to select the undoableblocks dump fields for sizing/statistics.
protected java.lang.String	getSelectUndoableBlocksSQL() Get the SQL to select an undoableblocks record.
protected java.lang.String	getTablesExistSQL() Get the SQL statement that checks if tables exist.
UTXO	getTransactionOutput(Sha256Hash hash, long index) Gets a UTXO with the given hash and index, or null if none is found
protected java.lang.String	getTransactionOutputSelectSQL() Get the SQL to select the transaction outputs for a given address.
StoredUndoableBlock	getUndoBlock(Sha256Hash hash) Returns a StoredUndoableBlock whose block.getHash() method will be equal to the parameter.
protected java.lang.String	getUpdateHeadersSQL() Get the SQL to update a headers record.
protected java.lang.String	getUpdateSettingsSLQ() Get the SQL to update a setting value.
protected java.lang.String	getUpdateUndoableBlocksSQL() Get the SQL to update a undoableblocks record.
StoredBlock	getVerifiedChainHead() Returns the StoredBlock that represents the top of the chain of greatest total work that has been fully verified and the point in the chain at which the unspent transaction output set in this store represents.
boolean	hasUnspentOutputs(Sha256Hash hash, int numOutputs) True if this store has any unspent outputs from a transaction with a hash equal to the first parameter
protected void	maybeConnect() If there isn't a connection on the ThreadLocal then create and store it.
void	put(StoredBlock storedBlock) Saves the given block header+extra data.
void	put(StoredBlock storedBlock, StoredUndoableBlock undoableBlock) Saves the given StoredUndoableBlock and StoredBlock.
protected void	putUpdateStoredBlock(StoredBlock storedBlock, boolean wasUndoable)
void	removeUnspentTransactionOutput(UTXO out) Removes a UTXO from the list of unspent TransactionOutputs Note that the coinbase of the genesis block should NEVER be spendable and thus never in the list.
void	resetStore() Resets the store by deleting the contents of the tables and reinitialising them.
void	setChainHead(StoredBlock chainHead) Sets the StoredBlock that represents the top of the chain of greatest total work.
void	setVerifiedChainHead(StoredBlock chainHead) Sets the StoredBlock that represents the top of the chain of greatest total work that has been fully verified.

Methods inherited from class java.lang.Object

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

Field Detail

chainHeadHash

protected Sha256Hash chainHeadHash

chainHeadBlock

protected StoredBlock chainHeadBlock

verifiedChainHeadHash

protected Sha256Hash verifiedChainHeadHash

verifiedChainHeadBlock

protected StoredBlock verifiedChainHeadBlock

params

protected NetworkParameters params

conn

protected java.lang.ThreadLocal<java.sql.Connection> conn

allConnections

protected java.util.List<java.sql.Connection> allConnections

connectionURL

protected java.lang.String connectionURL

fullStoreDepth

protected int fullStoreDepth

username

protected java.lang.String username

password

protected java.lang.String password

schemaName

protected java.lang.String schemaName

Constructor Detail

DatabaseFullPrunedBlockStore

public DatabaseFullPrunedBlockStore(NetworkParameters params,
                                    java.lang.String connectionURL,
                                    int fullStoreDepth,
                                    @Nullable
                                    java.lang.String username,
                                    @Nullable
                                    java.lang.String password,
                                    @Nullable
                                    java.lang.String schemaName)
                             throws BlockStoreException

Create a new DatabaseFullPrunedBlockStore, using the full connection URL instead of a hostname and password, and optionally allowing a schema to be specified.

Parameters:

params - A copy of the NetworkParameters used.

connectionURL - The jdbc url to connect to the database.

fullStoreDepth - The number of blocks of history stored in full (something like 1000 is pretty safe).

username - The database username.

password - The password to the database.

schemaName - The name of the schema to put the tables in. May be null if no schema is being used.

Throws:

BlockStoreException - If there is a failure to connect and/or initialise the database.

Method Detail

getDatabaseDriverClass

protected abstract java.lang.String getDatabaseDriverClass()

Get the database driver class,

i.e org.postgresql.Driver.

Returns:

The fully qualified database driver class.

getCreateSchemeSQL

protected abstract java.util.List<java.lang.String> getCreateSchemeSQL()

Get the SQL statements that create the schema (DDL).

Returns:

The list of SQL statements.

getCreateTablesSQL

protected abstract java.util.List<java.lang.String> getCreateTablesSQL()

Get the SQL statements that create the tables (DDL).

Returns:

The list of SQL statements.

getCreateIndexesSQL

protected abstract java.util.List<java.lang.String> getCreateIndexesSQL()

Get the SQL statements that create the indexes (DDL).

Returns:

The list of SQL statements.

getDuplicateKeyErrorCode

protected abstract java.lang.String getDuplicateKeyErrorCode()

Get the database specific error code that indicated a duplicate key error when inserting a record.

This is the code returned by SQLException.getSQLState()

Returns:

The database duplicate error code.

getBalanceSelectSQL

protected java.lang.String getBalanceSelectSQL()

Get the SQL to select the total balance for a given address.

Returns:

The SQL prepared statement.

getTablesExistSQL

protected java.lang.String getTablesExistSQL()

Get the SQL statement that checks if tables exist.

Returns:

The SQL prepared statement.

getCompatibilitySQL

protected java.util.List<java.lang.String> getCompatibilitySQL()

Get the SQL statements to check if the database is compatible.

Returns:

The SQL prepared statements.

getTransactionOutputSelectSQL

protected java.lang.String getTransactionOutputSelectSQL()

Get the SQL to select the transaction outputs for a given address.

Returns:

The SQL prepared statement.

getDropTablesSQL

protected java.util.List<java.lang.String> getDropTablesSQL()

Get the SQL to drop all the tables (DDL).

Returns:

The SQL drop statements.

getSelectSettingsSQL

protected java.lang.String getSelectSettingsSQL()

Get the SQL to select a setting value.

Returns:

The SQL select statement.

getInsertSettingsSQL

protected java.lang.String getInsertSettingsSQL()

Get the SQL to insert a settings record.

Returns:

The SQL insert statement.

getUpdateSettingsSLQ

protected java.lang.String getUpdateSettingsSLQ()

Get the SQL to update a setting value.

Returns:

The SQL update statement.

getSelectHeadersSQL

protected java.lang.String getSelectHeadersSQL()

Get the SQL to select a headers record.

Returns:

The SQL select statement.

getInsertHeadersSQL

protected java.lang.String getInsertHeadersSQL()

Get the SQL to insert a headers record.

Returns:

The SQL insert statement.

getUpdateHeadersSQL

protected java.lang.String getUpdateHeadersSQL()

Get the SQL to update a headers record.

Returns:

The SQL update statement.

getSelectUndoableBlocksSQL

protected java.lang.String getSelectUndoableBlocksSQL()

Get the SQL to select an undoableblocks record.

Returns:

The SQL select statement.

getInsertUndoableBlocksSQL

protected java.lang.String getInsertUndoableBlocksSQL()

Get the SQL to insert a undoableblocks record.

Returns:

The SQL insert statement.

getUpdateUndoableBlocksSQL

protected java.lang.String getUpdateUndoableBlocksSQL()

Get the SQL to update a undoableblocks record.

Returns:

The SQL update statement.

getDeleteUndoableBlocksSQL

protected java.lang.String getDeleteUndoableBlocksSQL()

Get the SQL to delete a undoableblocks record.

Returns:

The SQL delete statement.

getSelectOpenoutputsSQL

protected java.lang.String getSelectOpenoutputsSQL()

Get the SQL to select a openoutputs record.

Returns:

The SQL select statement.

getSelectOpenoutputsCountSQL

protected java.lang.String getSelectOpenoutputsCountSQL()

Get the SQL to select count of openoutputs.

Returns:

The SQL select statement.

getInsertOpenoutputsSQL

protected java.lang.String getInsertOpenoutputsSQL()

Get the SQL to insert a openoutputs record.

Returns:

The SQL insert statement.

getDeleteOpenoutputsSQL

protected java.lang.String getDeleteOpenoutputsSQL()

Get the SQL to delete a openoutputs record.

Returns:

The SQL delete statement.

getSelectSettingsDumpSQL

protected java.lang.String getSelectSettingsDumpSQL()

Get the SQL to select the setting dump fields for sizing/statistics.

Returns:

The SQL select statement.

getSelectHeadersDumpSQL

protected java.lang.String getSelectHeadersDumpSQL()

Get the SQL to select the headers dump fields for sizing/statistics.

Returns:

The SQL select statement.

getSelectUndoableblocksDumpSQL

protected java.lang.String getSelectUndoableblocksDumpSQL()

Get the SQL to select the undoableblocks dump fields for sizing/statistics.

Returns:

The SQL select statement.

getSelectopenoutputsDumpSQL

protected java.lang.String getSelectopenoutputsDumpSQL()

Get the SQL to select the openoutouts dump fields for sizing/statistics.

Returns:

The SQL select statement.

maybeConnect

protected final void maybeConnect()
                           throws BlockStoreException

If there isn't a connection on the ThreadLocal then create and store it.

This will also automatically set up the schema if it does not exist within the DB.

Throws:

BlockStoreException - if successful connection to the DB couldn't be made.

close

public void close()

Description copied from interface: BlockStore

Closes the store.

Specified by:

close in interface BlockStore

putUpdateStoredBlock

protected void putUpdateStoredBlock(StoredBlock storedBlock,
                                    boolean wasUndoable)
                             throws java.sql.SQLException

Throws:

java.sql.SQLException

put

public void put(StoredBlock storedBlock)
         throws BlockStoreException

Description copied from interface: BlockStore

Saves the given block header+extra data. The key isn't specified explicitly as it can be calculated from the StoredBlock directly. Can throw if there is a problem with the underlying storage layer such as running out of disk space.

Specified by:

put in interface BlockStore

Throws:

BlockStoreException

put

public void put(StoredBlock storedBlock,
                StoredUndoableBlock undoableBlock)
         throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Saves the given StoredUndoableBlock and StoredBlock. Calculates keys from the StoredBlock

Though not required for proper function of a FullPrunedBlockStore, any user of a FullPrunedBlockStore should ensure that a StoredUndoableBlock for each block up to the fully verified chain head has been added to this block store using this function (not put(StoredBlock)), so that the ability to perform reorgs is maintained.

Specified by:

put in interface FullPrunedBlockStore

Throws:

BlockStoreException - if there is a problem with the underlying storage layer, such as running out of disk space.

get

public StoredBlock get(Sha256Hash hash,
                       boolean wasUndoableOnly)
                throws BlockStoreException

Throws:

BlockStoreException

get

public StoredBlock get(Sha256Hash hash)
                throws BlockStoreException

Description copied from interface: BlockStore

Returns the StoredBlock given a hash. The returned values block.getHash() method will be equal to the parameter. If no such block is found, returns null.

Specified by:

get in interface BlockStore

Throws:

BlockStoreException

getOnceUndoableStoredBlock

public StoredBlock getOnceUndoableStoredBlock(Sha256Hash hash)
                                       throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Returns the StoredBlock that was added as a StoredUndoableBlock given a hash. The returned values block.getHash() method will be equal to the parameter. If no such block is found, returns null.

Specified by:

getOnceUndoableStoredBlock in interface FullPrunedBlockStore

Throws:

BlockStoreException

getUndoBlock

public StoredUndoableBlock getUndoBlock(Sha256Hash hash)
                                 throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Returns a StoredUndoableBlock whose block.getHash() method will be equal to the parameter. If no such block is found, returns null. Note that this may return null more often than get(Sha256Hash hash) as not all StoredBlocks have a StoredUndoableBlock copy stored as well.

Specified by:

getUndoBlock in interface FullPrunedBlockStore

Throws:

BlockStoreException

getChainHead

public StoredBlock getChainHead()
                         throws BlockStoreException

Description copied from interface: BlockStore

Returns the StoredBlock that represents the top of the chain of greatest total work. Note that this can be arbitrarily expensive, you probably should use AbstractBlockChain.getChainHead() or perhaps AbstractBlockChain.getBestChainHeight() which will run in constant time and not take any heavyweight locks.

Specified by:

getChainHead in interface BlockStore

Throws:

BlockStoreException

setChainHead

public void setChainHead(StoredBlock chainHead)
                  throws BlockStoreException

Description copied from interface: BlockStore

Sets the StoredBlock that represents the top of the chain of greatest total work.

Specified by:

setChainHead in interface BlockStore

Throws:

BlockStoreException

getVerifiedChainHead

public StoredBlock getVerifiedChainHead()
                                 throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Returns the StoredBlock that represents the top of the chain of greatest total work that has been fully verified and the point in the chain at which the unspent transaction output set in this store represents.

Specified by:

getVerifiedChainHead in interface FullPrunedBlockStore

Throws:

BlockStoreException

setVerifiedChainHead

public void setVerifiedChainHead(StoredBlock chainHead)
                          throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Sets the StoredBlock that represents the top of the chain of greatest total work that has been fully verified. It should generally be set after a batch of updates to the transaction unspent output set, before a call to commitDatabaseBatchWrite. If chainHead has a greater height than the non-verified chain head (ie that set with BlockStore.setChainHead(org.bitcoinj.core.StoredBlock)) the non-verified chain head should be set to the one set here. In this way a class using a FullPrunedBlockStore only in full-verification mode can ignore the regular BlockStore functions implemented as a part of a FullPrunedBlockStore.

Specified by:

setVerifiedChainHead in interface FullPrunedBlockStore

Throws:

BlockStoreException

getTransactionOutput

public UTXO getTransactionOutput(Sha256Hash hash,
                                 long index)
                          throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Gets a UTXO with the given hash and index, or null if none is found

Specified by:

getTransactionOutput in interface FullPrunedBlockStore

Throws:

BlockStoreException

addUnspentTransactionOutput

public void addUnspentTransactionOutput(UTXO out)
                                 throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Adds a UTXO to the list of unspent TransactionOutputs

Specified by:

addUnspentTransactionOutput in interface FullPrunedBlockStore

Throws:

BlockStoreException

removeUnspentTransactionOutput

public void removeUnspentTransactionOutput(UTXO out)
                                    throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Removes a UTXO from the list of unspent TransactionOutputs Note that the coinbase of the genesis block should NEVER be spendable and thus never in the list.

Specified by:

removeUnspentTransactionOutput in interface FullPrunedBlockStore

Throws:

BlockStoreException - if there is an underlying storage issue, or out was not in the list.

beginDatabaseBatchWrite

public void beginDatabaseBatchWrite()
                             throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

Begins/Commits/Aborts a database transaction.

If abortDatabaseBatchWrite() is called by the same thread that called beginDatabaseBatchWrite(), any data writes between this call and abortDatabaseBatchWrite() made by the same thread should be discarded.

Furthermore, any data written after a call to beginDatabaseBatchWrite() should not be readable by any other threads until commitDatabaseBatchWrite() has been called by this thread. Multiple calls to beginDatabaseBatchWrite() in any given thread should be ignored and treated as one call.

Specified by:

beginDatabaseBatchWrite in interface FullPrunedBlockStore

Throws:

BlockStoreException

commitDatabaseBatchWrite

public void commitDatabaseBatchWrite()
                              throws BlockStoreException

Specified by:

commitDatabaseBatchWrite in interface FullPrunedBlockStore

Throws:

BlockStoreException

abortDatabaseBatchWrite

public void abortDatabaseBatchWrite()
                             throws BlockStoreException

Specified by:

abortDatabaseBatchWrite in interface FullPrunedBlockStore

Throws:

BlockStoreException

hasUnspentOutputs

public boolean hasUnspentOutputs(Sha256Hash hash,
                                 int numOutputs)
                          throws BlockStoreException

Description copied from interface: FullPrunedBlockStore

True if this store has any unspent outputs from a transaction with a hash equal to the first parameter

Specified by:

hasUnspentOutputs in interface FullPrunedBlockStore

numOutputs - the number of outputs the given transaction has

Throws:

BlockStoreException

getParams

public NetworkParameters getParams()

Description copied from interface: BlockStore

Get the NetworkParameters of this store.

Specified by:

getParams in interface UTXOProvider

Specified by:

getParams in interface BlockStore

Returns:

The network params.

getChainHeadHeight

public int getChainHeadHeight()
                       throws UTXOProviderException

Description copied from interface: UTXOProvider

Get the height of the chain head.

Specified by:

getChainHeadHeight in interface UTXOProvider

Returns:

The chain head height.

Throws:

UTXOProviderException - If there is an error.

resetStore

public void resetStore()
                throws BlockStoreException

Resets the store by deleting the contents of the tables and reinitialising them.

Throws:

BlockStoreException - If the tables couldn't be cleared and initialised.

deleteStore

public void deleteStore()
                 throws BlockStoreException

Deletes the store by deleting the tables within the database.

Throws:

BlockStoreException - If tables couldn't be deleted.

calculateBalanceForAddress

public java.math.BigInteger calculateBalanceForAddress(Address address)
                                                throws BlockStoreException

Calculate the balance for a coinbase, to-address, or p2sh address.

The balance getBalanceSelectSQL() returns the balance (summed) as an number, then use calculateClientSide=false

The balance getBalanceSelectSQL() returns the all the openoutputs as stored in the DB (binary), then use calculateClientSide=true

Parameters:

address - The address to calculate the balance of

Returns:

The balance of the address supplied. If the address has not been seen, or there are no outputs open for this address, the return value is 0.

Throws:

BlockStoreException - If there is an error getting the balance.

getOpenTransactionOutputs

public java.util.List<UTXO> getOpenTransactionOutputs(java.util.List<ECKey> keys)
                                               throws UTXOProviderException

Description copied from interface: UTXOProvider

Get the list of UTXO's for given keys.

Specified by:

getOpenTransactionOutputs in interface UTXOProvider

Parameters:

keys - List of keys.

Returns:

The list of transaction outputs.

Throws:

UTXOProviderException - If there is an error.

dumpSizes

public void dumpSizes()
               throws java.sql.SQLException,
                      BlockStoreException

Dumps information about the size of actual data in the database to standard output The only truly useless data counted is printed in the form "N in id indexes" This does not take database indexes into account.

Throws:

java.sql.SQLException

BlockStoreException