Replace WalletEventListener.onDeadTransaction with a generic confidence changed callb...
[elbandi:fedoracoinj.git] / src / com / google / bitcoin / core / AbstractWalletEventListener.java
1 /**
2  * Copyright 2011 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *    http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package com.google.bitcoin.core;
18
19 import java.math.BigInteger;
20
21 /**
22  * Implementing a subclass WalletEventListener allows you to learn when the contents of the wallet changes due to
23  * receiving money or a block chain re-organize. Methods are called with the event listener object locked so your
24  * implementation does not have to be thread safe. The default method implementations simply call onChange().
25  */
26 public abstract class AbstractWalletEventListener implements WalletEventListener {
27     /**
28      * This is called on a Peer thread when a block is received that sends some coins to you. Note that this will
29      * also be called when downloading the block chain as the wallet balance catches up so if you don't want that
30      * register the event listener after the chain is downloaded. It's safe to use methods of wallet during the
31      * execution of this callback.
32      *
33      * @param wallet      The wallet object that received the coins/
34      * @param tx          The transaction which sent us the coins.
35      * @param prevBalance Balance before the coins were received.
36      * @param newBalance  Current balance of the wallet.
37      */
38     public void onCoinsReceived(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance) {
39         onChange();
40     }
41
42     /**
43      * This is called on a Peer thread when a transaction is seen that sends coins <b>from</b> this wallet, either
44      * because it was broadcast across the network or because a block was received. This may at first glance seem
45      * useless, because in the common case you already know about such transactions because you created them with
46      * the Wallets createSend/sendCoins methods. However when you have a wallet containing only keys, and you wish
47      * to replay the block chain to fill it with transactions, it's useful to find out when a transaction is discovered
48      * that sends coins from the wallet.<p>
49      *
50      * It's safe to modify the wallet from inside this callback, but if you're replaying the block chain you should
51      * be careful to avoid such modifications. Otherwise your changes may be overridden by new data from the chain.
52      *
53      * @param wallet       The wallet object that this callback relates to (that sent the coins).
54      * @param tx           The transaction that sent the coins to someone else.
55      * @param prevBalance  The wallets balance before this transaction was seen.
56      * @param newBalance   The wallets balance after this transaction was seen (should be less than prevBalance).
57      */
58     public void onCoinsSent(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance) {
59         onChange();
60     }
61
62     /**
63      * This is called on a Peer thread when a block is received that triggers a block chain re-organization.<p>
64      *
65      * A re-organize means that the consensus (chain) of the network has diverged and now changed from what we
66      * believed it was previously. Usually this won't matter because the new consensus will include all our old
67      * transactions assuming we are playing by the rules. However it's theoretically possible for our balance to
68      * change in arbitrary ways, most likely, we could lose some money we thought we had.<p>
69      *
70      * It is safe to use methods of wallet whilst inside this callback.
71      *
72      * TODO: Finish this interface.
73      */
74     public void onReorganize(Wallet wallet) {
75         onChange();
76     }
77
78     /**
79      * Called on a Peer thread when a transaction changes its confidence level. You can also attach event listeners to
80      * the individual transactions, if you don't care about all of them. Usually you would save the wallet to disk after
81      * receiving this callback.<p>
82      *
83      * You should pay attention to this callback in case a transaction becomes <i>dead</i>, that is, somebody
84      * successfully executed a double spend against you. This is a (very!) rare situation but the user should be
85      * notified that money they thought they had, was taken away from them.<p>
86      *
87      * @param wallet
88      * @param tx
89      */
90     public void onTransactionConfidenceChanged(Wallet wallet, Transaction tx) {
91         onChange();
92     }
93
94     /**
95      * Called by the other default method implementations when something (anything) changes in the wallet.
96      */
97     public void onChange() {
98     }
99 }