Message (bitcoinj 0.12 API)

java.lang.Object
- org.bitcoinj.core.Message

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AddressMessage, AlertMessage, Block, BloomFilter, ChildMessage, EmptyMessage, FilteredBlock, GetBlocksMessage, GetUTXOsMessage, HeadersMessage, ListMessage, MemoryPoolMessage, PartialMerkleTree, Ping, Pong, RejectMessage, UTXOsMessage, 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

Nested Classes
Modifier and Type Class and Description

static class Message.LazyParseException

Nested Classes
Modifier and Type	Class and Description
`static class`	`Message.LazyParseException`

Field Summary

Fields
Modifier and Type	Field and Description
`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 byte[]`	`payload`
`protected int`	`protocolVersion`
`protected boolean`	`recached`
`static int`	`UNKNOWN_LENGTH`

Constructor Summary

Constructors
Modifier Constructor and Description

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

Constructors
Modifier	Constructor and Description
`protected`	`Message()` This exists for the Java serialization framework to use only.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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 payload.
`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
```
  - payload
```
protected transient byte[] payload
```
  - 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 payload. This is only required for subclasses of ChildMessage 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.

Class Message

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_SIZE

UNKNOWN_LENGTH

offset

cursor

length

payload

parsed

recached

parseLazy

parseRetain

protocolVersion

checksum

params

Constructor Detail

Message

Method Detail

parseLite

maybeParse

ensureParsed

unCache

adjustLength

isParsed

isCached

isRecached

bitcoinSerialize

unsafeBitcoinSerialize

bitcoinSerialize

getHash

getMessageSize

getParams