com.google.bitcoin.core
Class WalletEventListener

java.lang.Object
  extended by com.google.bitcoin.core.WalletEventListener

public abstract class WalletEventListener
extends Object

Implementing a subclass WalletEventListener allows you to learn when the contents of the wallet changes due to receiving money or a block chain re-organize. Methods are called with the event listener object locked so your implementation does not have to be thread safe. The default method implementations do nothing.


Constructor Summary
WalletEventListener()
           
 
Method Summary
 void onCoinsReceived(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance)
          This is called on a Peer thread when a block is received that sends some coins to you.
 void onDeadTransaction(Transaction deadTx, Transaction replacementTx)
          This is called on a Peer thread when a transaction becomes dead.
 void onReorganize()
          This is called on a Peer thread when a block is received that triggers a block chain re-organization.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WalletEventListener

public WalletEventListener()
Method Detail

onCoinsReceived

public void onCoinsReceived(Wallet wallet,
                            Transaction tx,
                            BigInteger prevBalance,
                            BigInteger newBalance)
This is called on a Peer thread when a block is received that sends some coins to you. Note that this will also be called when downloading the block chain as the wallet balance catches up so if you don't want that register the event listener after the chain is downloaded. It's safe to use methods of wallet during the execution of this callback.

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.

onReorganize

public void onReorganize()
This is called on a Peer thread 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. TODO: Finish this interface.


onDeadTransaction

public void onDeadTransaction(Transaction deadTx,
                              Transaction replacementTx)
This is called on a Peer thread when a transaction becomes dead. A dead transaction is one that has been overridden by a double spend from the network and so will never confirm no matter how long you wait.

A dead transaction can occur if somebody is attacking the network, or by accident if keys are being shared. You can use this event handler to inform the user of the situation. A dead spend will show up in the BitCoin C++ client of the recipient as 0/unconfirmed forever, so if it was used to purchase something, the user needs to know their goods will never arrive.

Parameters:
deadTx - The transaction that is newly dead.
replacementTx - The transaction that killed it.


Copyright © 2011. All Rights Reserved.