Package org.whiteflagprotocol.java

Class WfMessage

java.lang.Object
org.whiteflagprotocol.java.WfMessage
public class WfMessage extends Object
Whiteflag message class

This class represents a Whiteflag message. It provides static factory methods to create Whiteflag messages in different ways from various data, and it contains all methods to create, encode and decode a message.

The class builds upon the WfBasicMessage class that represents a Whiteflag message in its basic form with a header and a body containing pre-defined message fields. This class encapsulates the base message, adds metadata and additional methods. Metadata includes the message originmator and recipient (if any), to be provided through the WfAccount interface. The additional methods include message encryption and decryption using the `org.whiteflagprotocol.java.crypto` package.

Since:
1.1
Whiteflag version:
v1-draft.6

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    addMetadata(String key, String value)
    Adds metadata to the Whiteflag message if not already existing
    static final WfMessage
    compile(String[] fieldValues)
    Creates a new Whiteflag message object from field values
    final WfMessage
    copy()
    Copies the base of this message into a new message, without any metadata
    static final WfMessage
    create(String messageCode)
    Creates a new empty Whiteflag message object of the specified type
    static final WfMessage
    decode(byte[] binMessage)
    Creates a new Whiteflag message from a byte array with an binary encoded message
    static final WfMessage
    decode(String hexMessage)
    Creates a new Whiteflag message from a hexadecimal string represaentation of an encoded message
    static final WfMessage
    decode(WfBinaryBuffer encodedMsg)
    Creates a new Whiteflag message from a binary buffer
    static final WfMessage
    decrypt(byte[] encryptedMsg, WfAccount originator, WfAccount recipient, byte[] initVector)
    Creates a new Whiteflag message from an encyrpted binary buffer and metadata
    static final WfMessage
    decrypt(String encryptedMsg, WfAccount originator, WfAccount recipient, String initVector)
    Creates a new Whiteflag message from an encyrpted binary buffer and metadata
    static final WfMessage
    decrypt(WfBinaryBuffer encryptedMsg, WfAccount originator, WfAccount recipient, byte[] initVector)
    Creates a new Whiteflag message from an encyrpted binary buffer and metadata
    static final WfMessage
    deserialize(String serializedMsg)
    Creates a new Whiteflag message object from a serialized message
    static final WfMessage
    deserializeJson(String jsonMessage)
    Creates a new Whiteflag message object from a serialized JSON message
    final WfBinaryBuffer
    encode()
    Returns the cached encoded/encrypted message, or else it encodes/encrypts and caches the message
    final WfBinaryBuffer
    encrypt()
    Returns the encoded/encrypted message; identical to encode()
    String
    get(String fieldname)
    Gets the value of the specified field
    Set<String>
    getFieldNames()
    Gets the field names of this message
    final byte[]
    getInitVector()
    Gets the non-secret initialisation vector used for encryption and decryption
    String
    getMetadata(String key)
    Returns the requested metadata value of the Whiteflag message
    Set<String>
    getMetadataKeys()
    Returns metadata keys of the Whiteflag message
    final int
    getNoFields()
    Gets the number of fields in this message
    final WfAccount
    getOriginator()
    Gets the originator of this message by their account
    final WfAccount
    getRecipient()
    Gets the recipient of this message by theri account
    WfMessageType
    getType()
    Gets the type of this message
    boolean
    isValid()
    Checks if this message contains valid data
    final boolean
    isValid(String fieldname)
    Checks if the specified message field contains valid data
    final boolean
    isValid(String fieldname, String data)
    Checks if the provided data is valid for the specified message field
    final String
    serialize()
    Returns the cached serialized message, or else it serialzes and caches Whiteflag message
    boolean
    set(String fieldname, String data)
    Sets the value of the specified field
    final byte[]
    setInitVector(byte[] initVector)
    Sets the non-secret initialisation vector used for encryption and decryption, if not already set
    final byte[]
    setInitVector(String initVector)
    Sets the non-secret initialisation vector used for encryption and decryption, if not already set
    protected final void
    setMetadata(Map<String,String> metadata)
    Sets the metadata
    final String
    setOriginator(WfAccount originator)
    Sets the originator sending this message and adds its blockchain address to the metadata
    final String
    setRecipient(WfAccount recipient)
    Sets the intended recipient of this message (if any) and adds its blockchain address to the metadata
    final byte[]
    toByteArray()
    Returns a byte array with the binary encoded message
    final String
    toHexString()
    Returns a hexadimal string representation of the binary encoded message
    final String
    toJson()
    Returns the serialised JSON representation of the Whiteflag message
    String
    toString()
    Returns the message as a concatinated string of field values

    Methods inherited from class java.lang.Object

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

  • Method Details

    • create

      public static final WfMessage create(String messageCode) throws WfException
      Creates a new empty Whiteflag message object of the specified type
      Parameters:
      messageCode - a string with the code indicating the message type to be created
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be created

    • deserialize

      public static final WfMessage deserialize(String serializedMsg) throws WfException
      Creates a new Whiteflag message object from a serialized message
      Parameters:
      serializedMsg - the uncompressed serialized message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the serialization of the message is invalid
      Since:
      1.1

    • deserializeJson

      public static final WfMessage deserializeJson(String jsonMessage) throws WfException
      Creates a new Whiteflag message object from a serialized JSON message
      Parameters:
      jsonMessage - the serialized JSON message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the serialization of the message is invalid

    • decode

      public static final WfMessage decode(String hexMessage) throws WfException
      Creates a new Whiteflag message from a hexadecimal string represaentation of an encoded message
      Parameters:
      hexMessage - a hexadecimal string representation of the encoded message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be decoded
      Since:
      1.1

    • decode

      public static final WfMessage decode(byte[] binMessage) throws WfException
      Creates a new Whiteflag message from a byte array with an binary encoded message
      Parameters:
      binMessage - a byte array with the binary encoded message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be decoded
      Since:
      1.1

    • decode

      public static final WfMessage decode(WfBinaryBuffer encodedMsg) throws WfException
      Creates a new Whiteflag message from a binary buffer
      Parameters:
      encodedMsg - a binary buffer with the encoded message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be decoded
      Since:
      1.1

    • decrypt

      public static final WfMessage decrypt(String encryptedMsg, WfAccount originator, WfAccount recipient, String initVector) throws WfException
      Creates a new Whiteflag message from an encyrpted binary buffer and metadata
      Parameters:
      encryptedMsg - a hexadecimal string with the encrypted message
      originator - the originator of the message
      recipient - the intended recipient of the message
      initVector - the initialisation vector used to encrypt the message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be decrypted or decoded
      Since:
      1.1

    • decrypt

      public static final WfMessage decrypt(byte[] encryptedMsg, WfAccount originator, WfAccount recipient, byte[] initVector) throws WfException
      Creates a new Whiteflag message from an encyrpted binary buffer and metadata
      Parameters:
      encryptedMsg - a hexadecimal string with with the encrypted message
      originator - the originator of the message
      recipient - the intended recipient of the message
      initVector - a byte array with initialisation vector used to encrypt the message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be decrypted or decoded
      Since:
      1.1

    • decrypt

      public static final WfMessage decrypt(WfBinaryBuffer encryptedMsg, WfAccount originator, WfAccount recipient, byte[] initVector) throws WfException
      Creates a new Whiteflag message from an encyrpted binary buffer and metadata
      Parameters:
      encryptedMsg - a binary buffer with the encrypted message
      originator - the originator of the message
      recipient - the intended recipient of the message
      initVector - a byte array with the initialisation vector used to encrypt the message
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if the message cannot be decrypted or decoded
      Since:
      1.1

    • compile

      public static final WfMessage compile(String[] fieldValues) throws WfException
      Creates a new Whiteflag message object from field values
      Parameters:
      fieldValues - a string array with the values for the message fields
      Returns:
      a new Whiteflag message
      Throws:
      WfException - if any of the provided values is invalid

    • getType

      public WfMessageType getType()
      Gets the type of this message
      Returns:
      the message type

    • isValid

      public boolean isValid()
      Checks if this message contains valid data
      Returns:
      TRUE if all message fields contain valid data, else FALSE

    • isValid

      public final boolean isValid(String fieldname)
      Checks if the specified message field contains valid data
      Parameters:
      fieldname - the name of the field
      Returns:
      TRUE if the field contains valid data, else FALSE

    • isValid

      public final boolean isValid(String fieldname, String data)
      Checks if the provided data is valid for the specified message field
      Parameters:
      fieldname - the name of the field
      data - the value to be checked
      Returns:
      TRUE if the field contains valid data, else FALSE

    • getNoFields

      public final int getNoFields()
      Gets the number of fields in this message
      Returns:
      the number of message fields

    • getFieldNames

      public Set<String> getFieldNames()
      Gets the field names of this message
      Returns:
      a string set with all field names

    • get

      public String get(String fieldname)
      Gets the value of the specified field
      Parameters:
      fieldname - the name of the requested field
      Returns:
      the field value, or NULL if field does not exist

    • set

      public boolean set(String fieldname, String data)
      Sets the value of the specified field
      Parameters:
      fieldname - the name of the field
      data - data to be set as the field value
      Returns:
      TRUE if field value is set, FALSE if field does not exits, isalready set, or data is invalid

    • addMetadata

      public String addMetadata(String key, String value)
      Adds metadata to the Whiteflag message if not already existing
      Parameters:
      key - a string with the metadata key
      value - a string with the metadata value
      Returns:
      null if successful, otherwise the value of the already existing key

    • getMetadata

      public String getMetadata(String key)
      Returns the requested metadata value of the Whiteflag message
      Parameters:
      key - a string with the metadata key
      Returns:
      the value associated with the requested metadata key

    • getMetadataKeys

      public Set<String> getMetadataKeys()
      Returns metadata keys of the Whiteflag message
      Returns:
      a string set with all metadata keys

    • copy

      public final WfMessage copy()
      Copies the base of this message into a new message, without any metadata
      Returns:
      a base copy of this Whiteflag message
      Since:
      1.1

    • setOriginator

      public final String setOriginator(WfAccount originator)
      Sets the originator sending this message and adds its blockchain address to the metadata
      Parameters:
      originator - the originator information
      Returns:
      null if address newly added to metadata, otherwise the existing value that was replaced
      Since:
      1.1

    • getOriginator

      public final WfAccount getOriginator()
      Gets the originator of this message by their account
      Returns:
      the account of the originator
      Since:
      1.1

    • setRecipient

      public final String setRecipient(WfAccount recipient)
      Sets the intended recipient of this message (if any) and adds its blockchain address to the metadata
      Parameters:
      recipient - the account of the recipient of this message
      Returns:
      null if address newly added to metadata, otherwise the existing value that was replaced
      Since:
      1.1

    • getRecipient

      public final WfAccount getRecipient()
      Gets the recipient of this message by theri account
      Returns:
      the account of the recipient
      Since:
      1.1

    • setInitVector

      public final byte[] setInitVector(String initVector)
      Sets the non-secret initialisation vector used for encryption and decryption, if not already set
      Parameters:
      initVector - a hexadecimal string with the initialisation vector
      Returns:
      a byte array with the initialisation vector; if already set this is the existing initialisation vector
      Since:
      1.1

    • setInitVector

      public final byte[] setInitVector(byte[] initVector)
      Sets the non-secret initialisation vector used for encryption and decryption, if not already set
      Parameters:
      initVector - a byte array with the initialisation vector
      Returns:
      a byte array with the initialisation vector; if already set this is the existing initialisation vector
      Since:
      1.1

    • getInitVector

      public final byte[] getInitVector()
      Gets the non-secret initialisation vector used for encryption and decryption
      Returns:
      a byte array with the initialisation vector
      Since:
      1.1

    • toString

      public String toString()
      Returns the message as a concatinated string of field values
      Overrides:
      toString in class Object
      Returns:
      the serialized message

    • serialize

      public final String serialize() throws WfException
      Returns the cached serialized message, or else it serialzes and caches Whiteflag message
      Returns:
      the serialized message, i.e. the concatinated string of field values
      Throws:
      WfException - if any of the field does not contain valid data

    • encode

      public final WfBinaryBuffer encode() throws WfException
      Returns the cached encoded/encrypted message, or else it encodes/encrypts and caches the message
      Returns:
      a binary buffer with the encoded/endypted message
      Throws:
      WfException - if any field does not contain valid data
      Since:
      1.1

    • encrypt

      public final WfBinaryBuffer encrypt() throws WfException
      Returns the encoded/encrypted message; identical to encode()
      Returns:
      a byte array with the compressed binary encoded message
      Throws:
      WfException - if any field does not contain valid data
      Since:
      1.1

    • toByteArray

      public final byte[] toByteArray() throws WfException
      Returns a byte array with the binary encoded message
      Returns:
      a byte array with the binary encoded message
      Throws:
      WfException - if any field does not contain valid data
      Since:
      1.1

    • toHexString

      public final String toHexString() throws WfException
      Returns a hexadimal string representation of the binary encoded message
      Returns:
      a hexadecimal string representation of the binary encoded
      Throws:
      WfException - if any field does not contain valid data
      Since:
      1.1

    • toJson

      public final String toJson() throws WfException
      Returns the serialised JSON representation of the Whiteflag message
      Returns:
      the serialised JSON representation
      Throws:
      WfException - if the message cannot be serialised

    • setMetadata

      protected final void setMetadata(Map<String,String> metadata)
      Sets the metadata
      Parameters:
      metadata - the key-to-value mapping of the metadata