com.google.bitcoin.kits
Class WalletAppKit

java.lang.Object
  com.google.common.util.concurrent.AbstractIdleService
      com.google.bitcoin.kits.WalletAppKit

All Implemented Interfaces:

com.google.common.util.concurrent.Service

public class WalletAppKit
extends com.google.common.util.concurrent.AbstractIdleService

Utility class that wraps the boilerplate needed to set up a new SPV bitcoinj app. Instantiate it with a directory and file prefix, optionally configure a few things, then use start or startAndWait. The object will construct and configure a BlockChain, SPVBlockStore, Wallet and PeerGroup. Depending on the value of the blockingStartup property, startup will be considered complete once the block chain has fully synchronized, so it can take a while.

To add listeners and modify the objects that are constructed, you can either do that by overriding the onSetupCompleted() method (which will run on a background thread) and make your changes there, or by waiting for the service to start and then accessing the objects from wherever you want. However, you cannot access the objects this class creates until startup is complete.

The asynchronous design of this class may seem puzzling (just use AbstractIdleService.startAndWait() if you don't want that). It is to make it easier to fit bitcoinj into GUI apps, which require a high degree of responsiveness on their main thread which handles all the animation and user interaction. Even when blockingStart is false, initializing bitcoinj means doing potentially blocking file IO, generating keys and other potentially intensive operations. By running it on a background thread, there's no risk of accidentally causing UI lag.

Note that AbstractIdleService.startAndWait() can throw an unchecked UncheckedExecutionException if anything goes wrong during startup - you should probably handle it and use Throwable.getCause() to figure out what went wrong more precisely. Same thing if you use the async start() method.

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service

com.google.common.util.concurrent.Service.Listener, com.google.common.util.concurrent.Service.State

Field Summary

protected boolean	autoStop
protected boolean	blockingStartup
protected InputStream	checkpoints
protected File	directory
protected PeerEventListener	downloadListener
protected String	filePrefix
protected NetworkParameters	params
protected PeerAddress[]	peerAddresses
protected boolean	useAutoSave
protected String	userAgent
protected BlockChain	vChain
protected String	version
protected PeerGroup	vPeerGroup
protected SPVBlockStore	vStore
protected Wallet	vWallet
protected File	vWalletFile

Constructor Summary

WalletAppKit(NetworkParameters params, File directory, String filePrefix)

Method Summary

protected void	addWalletExtensions() Override this to load all wallet extensions if any are necessary.
BlockChain	chain()
WalletAppKit	connectToLocalHost() Will only connect to localhost.
protected PeerGroup	createPeerGroup()
File	directory()
protected void	onSetupCompleted() This method is invoked on a background thread after all objects are initialised, but before the peer group or block chain download is started.
NetworkParameters	params()
PeerGroup	peerGroup()
WalletAppKit	setAutoSave(boolean value) If true, the wallet will save itself to disk automatically whenever it changes.
WalletAppKit	setAutoStop(boolean autoStop) If true, will register a shutdown hook to stop the library.
WalletAppKit	setBlockingStartup(boolean blockingStartup) If true (the default) then the startup of this service won't be considered complete until the network has been brought up, peer connections established and the block chain synchronised.
WalletAppKit	setCheckpoints(InputStream checkpoints) If set, the file is expected to contain a checkpoints file calculated with BuildCheckpoints.
WalletAppKit	setDownloadListener(PeerEventListener listener) If you want to learn about the sync process, you can provide a listener here.
WalletAppKit	setPeerNodes(PeerAddress... addresses) Will only connect to the given addresses.
WalletAppKit	setUserAgent(String userAgent, String version) Sets the string that will appear in the subver field of the version message.
protected void	shutDown()
protected void	startUp()
SPVBlockStore	store()
Wallet	wallet()

Methods inherited from class com.google.common.util.concurrent.AbstractIdleService

addListener, executor, isRunning, start, startAndWait, state, stop, stopAndWait, toString

Methods inherited from class java.lang.Object

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

Field Detail

filePrefix

protected final String filePrefix

params

protected final NetworkParameters params

vChain

protected volatile BlockChain vChain

vStore

protected volatile SPVBlockStore vStore

vWallet

protected volatile Wallet vWallet

vPeerGroup

protected volatile PeerGroup vPeerGroup

directory

protected final File directory

vWalletFile

protected volatile File vWalletFile

useAutoSave

protected boolean useAutoSave

peerAddresses

protected PeerAddress[] peerAddresses

downloadListener

protected PeerEventListener downloadListener

autoStop

protected boolean autoStop

checkpoints

protected InputStream checkpoints

blockingStartup

protected boolean blockingStartup

userAgent

protected String userAgent

version

protected String version

Constructor Detail

WalletAppKit

public WalletAppKit(NetworkParameters params,
                    File directory,
                    String filePrefix)

Method Detail

setPeerNodes

public WalletAppKit setPeerNodes(PeerAddress... addresses)

Will only connect to the given addresses. Cannot be called after startup.

connectToLocalHost

public WalletAppKit connectToLocalHost()

Will only connect to localhost. Cannot be called after startup.

setAutoSave

public WalletAppKit setAutoSave(boolean value)

If true, the wallet will save itself to disk automatically whenever it changes.

setDownloadListener

public WalletAppKit setDownloadListener(PeerEventListener listener)

If you want to learn about the sync process, you can provide a listener here. For instance, a DownloadListener is a good choice.

setAutoStop

public WalletAppKit setAutoStop(boolean autoStop)

If true, will register a shutdown hook to stop the library. Defaults to true.

setCheckpoints

public WalletAppKit setCheckpoints(InputStream checkpoints)

If set, the file is expected to contain a checkpoints file calculated with BuildCheckpoints. It makes initial block sync faster for new users - please refer to the documentation on the bitcoinj website for further details.

setBlockingStartup

public WalletAppKit setBlockingStartup(boolean blockingStartup)

If true (the default) then the startup of this service won't be considered complete until the network has been brought up, peer connections established and the block chain synchronised. Therefore AbstractIdleService.startAndWait() can potentially take a very long time. If false, then startup is considered complete once the network activity begins and peer connections/block chain sync will continue in the background.

setUserAgent

public WalletAppKit setUserAgent(String userAgent,
                                 String version)

Sets the string that will appear in the subver field of the version message.

Parameters:

userAgent - A short string that should be the name of your app, e.g. "My Wallet"

version - A short string that contains the version number, e.g. "1.0-BETA"

addWalletExtensions

protected void addWalletExtensions()
                            throws Exception

Override this to load all wallet extensions if any are necessary.

When this is called, chain(), store(), and peerGroup() will return the created objects, however they are not initialized/started

Throws:

Exception

onSetupCompleted

protected void onSetupCompleted()

This method is invoked on a background thread after all objects are initialised, but before the peer group or block chain download is started. You can tweak the objects configuration here.

startUp

protected void startUp()
                throws Exception

Specified by:

startUp in class com.google.common.util.concurrent.AbstractIdleService

Throws:

Exception

createPeerGroup

protected PeerGroup createPeerGroup()

shutDown

protected void shutDown()
                 throws Exception

Specified by:

shutDown in class com.google.common.util.concurrent.AbstractIdleService

Throws:

Exception

params

public NetworkParameters params()

chain

public BlockChain chain()

store

public SPVBlockStore store()

wallet

public Wallet wallet()

peerGroup

public PeerGroup peerGroup()

directory

public File directory()