+ * + * 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 {@link java.io.ByteArrayInputStream} and equivalent + * {@link java.io.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
*/
@@ -53,22 +57,35 @@ public class WalletProtobufSerializer {
// Used for de-serialization
private Map
+ *
+ * Equivalent to walletToProto(wallet).writeTo(output);
+ */
public static void writeWallet(Wallet wallet, OutputStream output) throws IOException {
Protos.Wallet walletProto = walletToProto(wallet);
-
walletProto.writeTo(output);
}
+ /**
+ * Returns the given wallet formatted as text. The text format is that used by protocol buffers and although it
+ * can also be parsed using {@link TextFormat.merge()}, 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 {@link Transaction}s which also mostly contain keys and hashes.
+ */
public static String walletToText(Wallet wallet) {
Protos.Wallet walletProto = walletToProto(wallet);
-
return TextFormat.printToString(walletProto);
}
+ /**
+ * 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.
+ */
public static Protos.Wallet walletToProto(Wallet wallet) {
Protos.Wallet.Builder walletBuilder = Protos.Wallet.newBuilder();
walletBuilder
@@ -180,14 +197,27 @@ public class WalletProtobufSerializer {
return ByteString.copyFrom(hash.getBytes());
}
- public static Wallet readWallet(InputStream input, NetworkParameters params)
- throws IOException {
+ /**
+ * Parses a wallet from the given stream. The stream is expected to contain a binary serialization of a
+ * {@link Protos.Wallet} object. You must also specify the {@link NetworkParameters} the wallet will use,
+ * it will be checked against the stream to ensure the right params have been specified. In future this
+ * parameter will probably go away.
+ *
+ * If the stream is invalid or the serialized wallet contains unsupported features,
+ * {@link IllegalArgumentException} is thrown.
+ *
+ * @param input
+ * @param params
+ * @return
+ * @throws IOException
+ */
+ public static Wallet readWallet(InputStream input, NetworkParameters params) throws IOException {
+ // TODO: This method should throw more specific exception types than IllegalArgumentException.
WalletProtobufSerializer serializer = new WalletProtobufSerializer();
Protos.Wallet walletProto = Protos.Wallet.parseFrom(input);
if (!params.getId().equals(walletProto.getNetworkIdentifier()))
- throw new IllegalArgumentException(
- "Trying to read a wallet with a different network id " +
- walletProto.getNetworkIdentifier());
+ throw new IllegalArgumentException("Trying to read a wallet with a different network id " +
+ walletProto.getNetworkIdentifier());
Wallet wallet = new Wallet(params);
@@ -304,9 +334,8 @@ public class WalletProtobufSerializer {
return new WalletTransaction(pool, tx);
}
- private void readConfidence(
- Transaction tx, Protos.TransactionConfidence confidenceProto,
- TransactionConfidence confidence) {
+ private void readConfidence(Transaction tx, Protos.TransactionConfidence confidenceProto,
+ TransactionConfidence confidence) {
// We are lenient here because tx confidence is not an essential part of the wallet.
// If the tx has an unknown type of confidence, ignore.
if (!confidenceProto.hasType()) {