com.google.bitcoin.jni
Class NativeWalletEventListener

java.lang.Object
  com.google.bitcoin.jni.NativeWalletEventListener

All Implemented Interfaces:

WalletEventListener

public class NativeWalletEventListener
extends Object
implements WalletEventListener

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

long

ptr

Constructor Summary

NativeWalletEventListener()

Method Summary

void	onCoinsReceived(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance) This is called when a transaction is seen that sends coins to this wallet, either because it was broadcast across the network or because a block was received.
void	onCoinsSent(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance) This is called when a transaction is seen that sends coins from this wallet, either because it was broadcast across the network or because a block was received.
void	onKeysAdded(Wallet wallet, List<ECKey> keys) Called whenever a new key is added to the wallet, whether that be via Wallet.addKeys(java.util.List) or due to some other automatic derivation.
void	onReorganize(Wallet wallet) This is called when a block is received that triggers a block chain re-organization.
void	onScriptsAdded(Wallet wallet, List<Script> scripts) Called whenever a new watched script is added to the wallet.
void	onTransactionConfidenceChanged(Wallet wallet, Transaction tx) Called when a transaction changes its confidence level.
void	onWalletChanged(Wallet wallet) Designed for GUI applications to refresh their transaction lists.

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

NativeWalletEventListener

public NativeWalletEventListener()

Method Detail

onCoinsReceived

public void onCoinsReceived(Wallet wallet,
                            Transaction tx,
                            BigInteger prevBalance,
                            BigInteger newBalance)

Description copied from interface: WalletEventListener

This is called when a transaction is seen that sends coins to this wallet, either because it was broadcast across the network or because a block was received. If a transaction is seen when it was broadcast, onCoinsReceived won't be called again when a block containing it is received. If you want to know when such a transaction receives its first confirmation, register a TransactionConfidence event listener using the object retrieved via Transaction.getConfidence(). It's safe to modify the wallet in this callback, for example, by spending the transaction just received.

Specified by:

onCoinsReceived in interface WalletEventListener

Parameters:

wallet - The wallet object that received the coins

tx - The transaction which sent us the coins.

prevBalance - Balance before the coins were received.

newBalance - Current balance of the wallet. This is the 'estimated' balance.

onCoinsSent

public void onCoinsSent(Wallet wallet,
                        Transaction tx,
                        BigInteger prevBalance,
                        BigInteger newBalance)

Description copied from interface: WalletEventListener

This is called when a transaction is seen that sends coins from this wallet, either because it was broadcast across the network or because a block was received. This may at first glance seem useless, because in the common case you already know about such transactions because you created them with the Wallets createSend/sendCoins methods. However when you have a wallet containing only keys, and you wish to replay the block chain to fill it with transactions, it's useful to find out when a transaction is discovered that sends coins from the wallet.

It's safe to modify the wallet from inside this callback, but if you're replaying the block chain you should be careful to avoid such modifications. Otherwise your changes may be overridden by new data from the chain.

Specified by:

onCoinsSent in interface WalletEventListener

Parameters:

wallet - The wallet object that this callback relates to (that sent the coins).

tx - The transaction that sent the coins to someone else.

prevBalance - The wallets balance before this transaction was seen.

newBalance - The wallets balance after this transaction was seen. This is the 'estimated' balance.

onReorganize

public void onReorganize(Wallet wallet)

Description copied from interface: WalletEventListener

This is called when a block is received that triggers a block chain re-organization.

A re-organize means that the consensus (chain) of the network has diverged and now changed from what we believed it was previously. Usually this won't matter because the new consensus will include all our old transactions assuming we are playing by the rules. However it's theoretically possible for our balance to change in arbitrary ways, most likely, we could lose some money we thought we had.

It is safe to use methods of wallet whilst inside this callback.

Specified by:

onReorganize in interface WalletEventListener

onTransactionConfidenceChanged

public void onTransactionConfidenceChanged(Wallet wallet,
                                           Transaction tx)

Description copied from interface: WalletEventListener

Called when a transaction changes its confidence level. You can also attach event listeners to the individual transactions, if you don't care about all of them. Usually you would save the wallet to disk after receiving this callback unless you already set up autosaving.

You should pay attention to this callback in case a transaction becomes dead, that is, a transaction you believed to be active (send or receive) becomes overridden by the network. This can happen if

1. You are sharing keys between wallets and accidentally create/broadcast a double spend.
2. Somebody is attacking the network and reversing transactions, ie, the user is a victim of fraud.
3. A bug: for example you create a transaction, broadcast it but fail to commit it. The Wallet will then re-use the same outputs when creating the next spend.

To find if the transaction is dead, you can use tx.getConfidence().getConfidenceType() == TransactionConfidence.ConfidenceType.DEAD. If it is, you should notify the user in some way so they know the thing they bought may not arrive/the thing they sold should not be dispatched.

Note that this callback will be invoked for every transaction in the wallet, for every new block that is received (because the depth has changed). If you want to update a UI view from the contents of the wallet it is more efficient to use onWalletChanged instead.

Specified by:

onTransactionConfidenceChanged in interface WalletEventListener

onWalletChanged

public void onWalletChanged(Wallet wallet)

Description copied from interface: WalletEventListener

Designed for GUI applications to refresh their transaction lists. This callback is invoked in the following situations:

1. A new block is received (and thus building transactions got more confidence)
2. A pending transaction is received
3. A pending transaction changes confidence due to some non-new-block related event, such as being announced by more peers or by a double-spend conflict being observed.
4. A re-organize occurs. Call occurs only if the re-org modified any of our transactions.
5. A new spend is committed to the wallet

When this is called you can refresh the UI contents from the wallet contents. It's more efficient to use this rather than onTransactionConfidenceChanged() + onReorganize() because you only get one callback per block rather than one per transaction per block. Note that this is not called when a key is added.

Specified by:

onWalletChanged in interface WalletEventListener

onKeysAdded

public void onKeysAdded(Wallet wallet,
                        List<ECKey> keys)

Description copied from interface: WalletEventListener

Called whenever a new key is added to the wallet, whether that be via Wallet.addKeys(java.util.List) or due to some other automatic derivation.

Specified by:

onKeysAdded in interface WalletEventListener

onScriptsAdded

public void onScriptsAdded(Wallet wallet,
                           List<Script> scripts)

Description copied from interface: WalletEventListener

Called whenever a new watched script is added to the wallet.

Specified by:

onScriptsAdded in interface WalletEventListener