com.google.bitcoin.store
Class WalletProtobufSerializer

java.lang.Object
  com.google.bitcoin.store.WalletProtobufSerializer

public class WalletProtobufSerializer
extends Object

Serialize and de-serialize a wallet to a byte stream containing a protocol buffer. Protocol buffers are a data interchange format developed by Google with an efficient binary representation, a type safe specification language and compilers that generate code to work with those data structures for many languages. Protocol buffers can have their format evolved over time: conceptually they represent data using (tag, length, value) tuples. The format is defined by the bitcoin.proto file in the bitcoinj source distribution.

This class is used through its static methods. The most common operations are writeWallet and readWallet, which do the obvious operations on Output/InputStreams. You can use a ByteArrayInputStream and equivalent ByteArrayOutputStream if you'd like byte arrays instead. The protocol buffer can also be manipulated in its object form if you'd like to modify the flattened data structure before serialization to binary.

You can extend the wallet format with additional fields specific to your application if you want, but make sure to either put the extra data in the provided extension areas, or select tag numbers that are unlikely to be used by anyone else.

Author:

Miron Cuperman

Field Summary

protected Map<com.google.protobuf.ByteString,Transaction>

txMap

Constructor Summary

WalletProtobufSerializer()

Method Summary

static Sha256Hash	byteStringToHash(com.google.protobuf.ByteString bs)
static com.google.protobuf.ByteString	hashToByteString(Sha256Hash hash)
static boolean	isWallet(InputStream is) Cheap test to see if input stream is a wallet.
static Protos.Wallet	parseToProto(InputStream input) Returns the loaded protocol buffer from the given byte stream.
Wallet	readWallet(InputStream input) Parses a wallet from the given stream, using the provided Wallet instance to load data into.
void	readWallet(Protos.Wallet walletProto, Wallet wallet) Loads wallet data from the given protocol buffer and inserts it into the given Wallet object.
void	setRequireMandatoryExtensions(boolean value) If this property is set to false, then unknown mandatory extensions will be ignored instead of causing load errors.
Protos.Wallet	walletToProto(Wallet wallet) Converts the given wallet to the object representation of the protocol buffers.
String	walletToText(Wallet wallet) Returns the given wallet formatted as text.
void	writeWallet(Wallet wallet, OutputStream output) Formats the given wallet (transactions and keys) to the given output stream in protocol buffer format.

Methods inherited from class java.lang.Object

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

Field Detail

txMap

protected Map<com.google.protobuf.ByteString,Transaction> txMap

Constructor Detail

WalletProtobufSerializer

public WalletProtobufSerializer()

Method Detail

setRequireMandatoryExtensions

public void setRequireMandatoryExtensions(boolean value)

If this property is set to false, then unknown mandatory extensions will be ignored instead of causing load errors. You should only use this if you know exactly what you are doing, as the extension data will NOT be round-tripped, possibly resulting in a corrupted wallet if you save it back out again.

writeWallet

public void writeWallet(Wallet wallet,
                        OutputStream output)
                 throws IOException

Formats the given wallet (transactions and keys) to the given output stream in protocol buffer format.

Equivalent to walletToProto(wallet).writeTo(output);

Throws:

IOException

walletToText

public String walletToText(Wallet wallet)

Returns the given wallet formatted as text. The text format is that used by protocol buffers and although it can also be parsed using TextFormat.merge(CharSequence, com.google.protobuf.Message.Builder), it is designed more for debugging than storage. It is not well specified and wallets are largely binary data structures anyway, consisting as they do of keys (large random numbers) and Transactions which also mostly contain keys and hashes.

walletToProto

public Protos.Wallet walletToProto(Wallet wallet)

Converts the given wallet to the object representation of the protocol buffers. This can be modified, or additional data fields set, before serialization takes place.

hashToByteString

public static com.google.protobuf.ByteString hashToByteString(Sha256Hash hash)

byteStringToHash

public static Sha256Hash byteStringToHash(com.google.protobuf.ByteString bs)

readWallet

public Wallet readWallet(InputStream input)
                  throws UnreadableWalletException

Parses a wallet from the given stream, using the provided Wallet instance to load data into. This is primarily used when you want to register extensions. Data in the proto will be added into the wallet where applicable and overwrite where not.

A wallet can be unreadable for various reasons, such as inability to open the file, corrupt data, internally inconsistent data, a wallet extension marked as mandatory that cannot be handled and so on. You should always handle UnreadableWalletException and communicate failure to the user in an appropriate manner.

Throws:

UnreadableWalletException - thrown in various error conditions (see description).

readWallet

public void readWallet(Protos.Wallet walletProto,
                       Wallet wallet)
                throws UnreadableWalletException

Loads wallet data from the given protocol buffer and inserts it into the given Wallet object. This is primarily useful when you wish to pre-register extension objects. Note that if loading fails the provided Wallet object may be in an indeterminate state and should be thrown away.

A wallet can be unreadable for various reasons, such as inability to open the file, corrupt data, internally inconsistent data, a wallet extension marked as mandatory that cannot be handled and so on. You should always handle UnreadableWalletException and communicate failure to the user in an appropriate manner.

Throws:

UnreadableWalletException - thrown in various error conditions (see description).

parseToProto

public static Protos.Wallet parseToProto(InputStream input)
                                  throws IOException

Returns the loaded protocol buffer from the given byte stream. You normally want Wallet.loadFromFile(java.io.File) instead - this method is designed for low level work involving the wallet file format itself.

Throws:

IOException

isWallet

public static boolean isWallet(InputStream is)

Cheap test to see if input stream is a wallet. This checks for a magic value at the beginning of the stream.

Parameters:

is - input stream to test

Returns:

true if input stream is a wallet