org.bitcoinj.jni

Class NativeBlockChainListener

java.lang.Object

org.bitcoinj.jni.NativeBlockChainListener

All Implemented Interfaces:

BlockChainListener

public class NativeBlockChainListener
extends Object
implements BlockChainListener

An event listener that relays events to a native C++ object. A pointer to that object is stored in this class using JNI on the native side, thus several instances of this can point to different actual native implementations.

Field Summary

Fields

Modifier and Type	Field and Description
long	ptr

Constructor Summary

Constructors

Constructor and Description
NativeBlockChainListener()

Method Summary

Modifier and Type	Method and Description
boolean	isTransactionRelevant(Transaction tx) Returns true if the given transaction is interesting to the listener.
void	notifyNewBestBlock(StoredBlock block) Called when a new block on the best chain is seen, after relevant transactions are extracted and sent to us via either #receiveFromBlock(Transaction, StoredBlock, org.bitcoinj.core.BlockChain.NewBlockType, int) or #notifyTransactionIsInBlock(Sha256Hash, StoredBlock, org.bitcoinj.core.BlockChain.NewBlockType, int).
boolean	notifyTransactionIsInBlock(Sha256Hash txHash, StoredBlock block, AbstractBlockChain.NewBlockType blockType, int relativityOffset) Called by the BlockChain when we receive a new FilteredBlock that contains the given transaction hash in its merkle tree.
void	receiveFromBlock(Transaction tx, StoredBlock block, AbstractBlockChain.NewBlockType blockType, int relativityOffset) Called by the BlockChain when we receive a new block that contains a relevant transaction.
void	reorganize(StoredBlock splitPoint, List<StoredBlock> oldBlocks, List<StoredBlock> newBlocks) Called by the BlockChain when the best chain (representing total work done) has changed.

Methods inherited from class java.lang.Object

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

Field Detail

ptr

public long ptr

Constructor Detail

NativeBlockChainListener

public NativeBlockChainListener()

Method Detail

notifyNewBestBlock

public void notifyNewBestBlock(StoredBlock block)
                        throws VerificationException

Description copied from interface: BlockChainListener

Called when a new block on the best chain is seen, after relevant transactions are extracted and sent to us via either #receiveFromBlock(Transaction, StoredBlock, org.bitcoinj.core.BlockChain.NewBlockType, int) or #notifyTransactionIsInBlock(Sha256Hash, StoredBlock, org.bitcoinj.core.BlockChain.NewBlockType, int). If this block is causing a re-organise to a new chain, this method is NOT called even though the block may be the new best block: your reorganize implementation is expected to do whatever would normally be done do for a new best block in this case.

Specified by:

notifyNewBestBlock in interface BlockChainListener

Throws:

VerificationException

reorganize

public void reorganize(StoredBlock splitPoint,
                       List<StoredBlock> oldBlocks,
                       List<StoredBlock> newBlocks)
                throws VerificationException

Description copied from interface: BlockChainListener

Called by the BlockChain when the best chain (representing total work done) has changed. In this case, we need to go through our transactions and find out if any have become invalid. It's possible for our balance to go down in this case: money we thought we had can suddenly vanish if the rest of the network agrees it should be so.

The oldBlocks/newBlocks lists are ordered height-wise from top first to bottom last (i.e. newest blocks first).

Specified by:

reorganize in interface BlockChainListener

Throws:

VerificationException

isTransactionRelevant

public boolean isTransactionRelevant(Transaction tx)
                              throws ScriptException

Description copied from interface: BlockChainListener

Returns true if the given transaction is interesting to the listener. If yes, then the transaction will be provided via the receiveFromBlock method. This method is essentially an optimization that lets BlockChain bypass verification of a blocks merkle tree if no listeners are interested, which can save time when processing full blocks on mobile phones. It's likely the method will be removed in future and replaced with an alternative mechanism that involves listeners providing all keys that are interesting.

Specified by:

isTransactionRelevant in interface BlockChainListener

Throws:

ScriptException

receiveFromBlock

public void receiveFromBlock(Transaction tx,
                             StoredBlock block,
                             AbstractBlockChain.NewBlockType blockType,
                             int relativityOffset)
                      throws VerificationException

Description copied from interface: BlockChainListener

Called by the BlockChain when we receive a new block that contains a relevant transaction.

A transaction may be received multiple times if is included into blocks in parallel chains. The blockType parameter describes whether the containing block is on the main/best chain or whether it's on a presently inactive side chain.

The relativityOffset parameter is an arbitrary number used to establish an ordering between transactions within the same block. In the case where full blocks are being downloaded, it is simply the index of the transaction within that block. When Bloom filtering is in use, we don't find out the exact offset into a block that a transaction occurred at, so the relativity count is not reflective of anything in an absolute sense but rather exists only to order the transaction relative to the others.

Specified by:

receiveFromBlock in interface BlockChainListener

Throws:

VerificationException

notifyTransactionIsInBlock

public boolean notifyTransactionIsInBlock(Sha256Hash txHash,
                                          StoredBlock block,
                                          AbstractBlockChain.NewBlockType blockType,
                                          int relativityOffset)
                                   throws VerificationException

Description copied from interface: BlockChainListener

Called by the BlockChain when we receive a new FilteredBlock that contains the given transaction hash in its merkle tree.

A transaction may be received multiple times if is included into blocks in parallel chains. The blockType parameter describes whether the containing block is on the main/best chain or whether it's on a presently inactive side chain.

The relativityOffset parameter in this case is an arbitrary (meaningless) number, that is useful only when compared to the relativity count of another transaction received inside the same block. It is used to establish an ordering of transactions relative to one another.

This method should return false if the given tx hash isn't known about, e.g. because the the transaction was a Bloom false positive. If it was known about and stored, it should return true. The caller may need to know this to calculate the effective FP rate.

Specified by:

notifyTransactionIsInBlock in interface BlockChainListener

Returns:

whether the transaction is known about i.e. was considered relevant previously.

Throws:

VerificationException