com.google.bitcoin.core
Class Message

java.lang.Object
  com.google.bitcoin.core.Message

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AddressMessage, AlertMessage, Block, BloomFilter, ChildMessage, EmptyMessage, FilteredBlock, GetBlocksMessage, HeadersMessage, ListMessage, MemoryPoolMessage, PartialMerkleTree, Ping, Pong, VersionMessage

public abstract class Message
extends Object
implements Serializable

A Message is a data structure that can be serialized/deserialized using both the Bitcoin proprietary serialization format and built-in Java object serialization. Specific types of messages that are used both in the block chain, and on the wire, are derived from this class.

See Also:

Serialized Form

Nested Class Summary

static class

Message.LazyParseException

Field Summary

protected byte[]	bytes
protected byte[]	checksum
protected int	cursor
protected int	length
static int	MAX_SIZE
protected int	offset
protected NetworkParameters	params
protected boolean	parsed
protected boolean	parseLazy
protected boolean	parseRetain
protected int	protocolVersion
protected boolean	recached
static int	UNKNOWN_LENGTH

Constructor Summary

protected

Message() This exists for the Java serialization framework to use only.

Method Summary

protected void	adjustLength(int newArraySize, int adjustment)
byte[]	bitcoinSerialize() Returns a copy of the array returned by unsafeBitcoinSerialize(), which is safe to mutate.
void	bitcoinSerialize(OutputStream stream) Serialize this message to the provided OutputStream using the bitcoin wire format.
void	ensureParsed() In lazy parsing mode access to getters and setters may throw an unchecked LazyParseException.
Sha256Hash	getHash() This method is a NOP for all classes except Block and Transaction.
int	getMessageSize() This should be overridden to extract correct message size in the case of lazy parsing.
NetworkParameters	getParams() Network parameters this message was created with.
boolean	isCached() used for unit testing
boolean	isParsed() used for unit testing
boolean	isRecached()
protected void	maybeParse() Ensure the object is parsed if needed.
protected abstract void	parseLite() Perform the most minimal parse possible to calculate the length of the message.
protected void	unCache() To be called before any change of internal values including any setters.
byte[]	unsafeBitcoinSerialize() Serialize this message to a byte array that conforms to the bitcoin wire protocol.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_SIZE

public static final int MAX_SIZE

See Also:

Constant Field Values

UNKNOWN_LENGTH

public static final int UNKNOWN_LENGTH

See Also:

Constant Field Values

offset

protected transient int offset

cursor

protected transient int cursor

length

protected transient int length

bytes

protected transient byte[] bytes

parsed

protected transient boolean parsed

recached

protected transient boolean recached

parseLazy

protected final transient boolean parseLazy

parseRetain

protected final transient boolean parseRetain

protocolVersion

protected transient int protocolVersion

checksum

protected transient byte[] checksum

params

protected NetworkParameters params

Constructor Detail

Message

protected Message()

This exists for the Java serialization framework to use only.

Method Detail

parseLite

protected abstract void parseLite()
                           throws ProtocolException

Perform the most minimal parse possible to calculate the length of the message. This is only required for subclasses of ChildClass as root level messages will have their length passed into the constructor.

Implementations should adhere to the following contract: If parseLazy = true the 'length' field must be set before returning. If parseLazy = false the length field must be set either within the parseLite() method OR the parse() method. The overriding requirement is that length must be set to non UNKNOWN_MESSAGE value by the time the constructor exits.

Throws:

ProtocolException

maybeParse

protected void maybeParse()

Ensure the object is parsed if needed. This should be called in every getter before returning a value. If the lazy parse flag is not set this is a method returns immediately.

ensureParsed

public void ensureParsed()
                  throws ProtocolException

In lazy parsing mode access to getters and setters may throw an unchecked LazyParseException. If guaranteed safe access is required this method will force parsing to occur immediately thus ensuring LazyParseExeption will never be thrown from this Message. If the Message contains child messages (e.g. a Block containing Transaction messages) this will not force child messages to parse.

This could be overidden for Transaction and it's child classes to ensure the entire tree of Message objects is parsed.

Throws:

ProtocolException

unCache

protected void unCache()

To be called before any change of internal values including any setters. This ensures any cached byte array is removed after performing a lazy parse if necessary to ensure the object is fully populated.

Child messages of this object(e.g. Transactions belonging to a Block) will not have their internal byte caches invalidated unless they are also modified internally.

adjustLength

protected void adjustLength(int newArraySize,
                            int adjustment)

isParsed

public boolean isParsed()

used for unit testing

isCached

public boolean isCached()

used for unit testing

isRecached

public boolean isRecached()

bitcoinSerialize

public byte[] bitcoinSerialize()

Returns a copy of the array returned by unsafeBitcoinSerialize(), which is safe to mutate. If you need extra performance and can guarantee you won't write to the array, you can use the unsafe version.

Returns:

a freshly allocated serialized byte array

unsafeBitcoinSerialize

public byte[] unsafeBitcoinSerialize()

Serialize this message to a byte array that conforms to the bitcoin wire protocol.
This method may return the original byte array used to construct this message if the following conditions are met:

1. 1) The message was parsed from a byte array with parseRetain = true
2. 2) The message has not been modified
3. 3) The array had an offset of 0 and no surplus bytes

If condition 3 is not met then an copy of the relevant portion of the array will be returned. Otherwise a full serialize will occur. For this reason you should only use this API if you can guarantee you will treat the resulting array as read only.

Returns:

a byte array owned by this object, do NOT mutate it.

bitcoinSerialize

public final void bitcoinSerialize(OutputStream stream)
                            throws IOException

Serialize this message to the provided OutputStream using the bitcoin wire format.

Parameters:

stream -

Throws:

IOException

getHash

public Sha256Hash getHash()

This method is a NOP for all classes except Block and Transaction. It is only declared in Message so BitcoinSerializer can avoid 2 instanceof checks + a casting.

getMessageSize

public int getMessageSize()

This should be overridden to extract correct message size in the case of lazy parsing. Until this method is implemented in a subclass of ChildMessage lazy parsing may have no effect. This default implementation is a safe fall back that will ensure it returns a correct value by parsing the message.

getParams

public NetworkParameters getParams()

Network parameters this message was created with.