Class Message

java.lang.Object
cl.netswitch.lib.message.Message
All Implemented Interfaces:
Serializable
public class Message extends Object implements Serializable
Unit of communication between endpoints in a distributed environment. A Message is composed of the following required and optional fields:
  1. A required message Type: used by the communication protocol.
  2. A required status code: indicates successful or error completion.
  3. An optional set of labels: used by the communication protocol.
  4. An optional text value: used to send a unicode string such as XML content.
  5. An optional bytes value: used to send an array of bytes such as a PDF file.
  6. An optional object value: used to send a Serializable object.
  7. An optional set of properties: used to send a set of name-value pairs.
Warning: a Message is not synchronized. If multiple threads access a Message instance concurrently, and at least one of the threads modifies the Message, it should be synchronized externally. This is typically accomplished by synchronizing on some object that naturally encapsulates the Message.
See Also:

  • Field Details

    • SUCCESS

      public static final int SUCCESS
      Completion status indicating success.
      See Also:

    • ERROR

      public static final int ERROR
      Completion status indicating error.
      See Also:

  • Constructor Details

    • Message

      public Message()
      Creates a new Message instance.

    • Message

      public Message(Message.Type type)
      Creates a new Message with supplied type.
      Parameters:
      type - the initial message type (can be null).

    • Message

      public Message(String text)
      Creates a new Message with supplied text.
      Parameters:
      text - the initial text data (can be null).

    • Message

      public Message(byte[] bytes)
      Creates a new Message with supplied bytes.
      Parameters:
      bytes - the initial bytes data (can be null).

    • Message

      public Message(Serializable object)
      Creates a new Message with supplied object.
      Parameters:
      object - the initial object data (can be null).

  • Method Details

    • clear

      public final void clear()
      Resets all the fields of this Message to their default value.

    • getType

      public final Message.Type getType()
      Returns the type of this Message.
      Returns:
      the type of this Message.

    • setType

      public final void setType(Message.Type type)
      Changes the type of this Message.
      Parameters:
      type - the new type of this Message.
      Throws:
      NullPointerException - if type is null.

    • getStatus

      public final int getStatus()
      Returns the status of this Message.
      Returns:
      the status of the Message.

    • setStatus

      public final void setStatus(int status)
      Changes the status of this Message.
      Parameters:
      status - the new status of the Message.

    • getLabelKeys

      public final Set<Message.Label> getLabelKeys()
      Returns an unmodifiable set with all defined label keys.
      Returns:
      an unmodifiable set with all defined label keys.

    • hasLabel

      public final boolean hasLabel(Message.Label key)
      Returns true if the label indexed by key is defined.
      Parameters:
      key - the index of the label.
      Returns:
      true if the label indexed by key is defined.
      Throws:
      NullPointerException - if key is null.

    • getLabel

      public final String getLabel(Message.Label key)
      Returns the value of the label indexed by key.
      Parameters:
      key - the index of the label.
      Returns:
      a string or null if the label is not defined.
      Throws:
      NullPointerException - if key is null.

    • putLabel

      public final void putLabel(Message.Label key, String value)
      Changes the value of the label indexed by key. If value is null the label is removed.
      Parameters:
      key - the index of the label.
      value - the new value of the label (can be null).
      Throws:
      NullPointerException - if key is null.

    • removeLabel

      public final void removeLabel(Message.Label key)
      Removes the label indexed by the key.
      Parameters:
      key - the index of the label.
      Throws:
      NullPointerException - if key is null.

    • clearLabels

      public final void clearLabels()
      Removes all defined labels from this Message.

    • getPropertyNames

      public final Set<String> getPropertyNames()
      Returns an unmodifiable set with all defined property names.
      Returns:
      an unmodifiable set with all defined property names.

    • getPropertyEntries

      public Set<Map.Entry<String, Serializable>> getPropertyEntries()
      Returns an unmodifiable set with all defined property names and values.
      Returns:
      an unmodifiable set with all defined property names and values.

    • getPropertyType

      public final PropertyType getPropertyType(String name)
      Returns the type of the value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the type of the value of the property indexed by name.
      Throws:
      NullPointerException - if name is null.
      IllegalArgumentException - if the property value is invalid.

    • hasProperty

      public final boolean hasProperty(String name)
      Returns true if the property indexed by name is defined.
      Parameters:
      name - the name of the property.
      Returns:
      true if the property indexed by name is defined.
      Throws:
      NullPointerException - if name is null.

    • putProperties

      public final void putProperties(Message message)
      Copies all the properties of a message to this Message.
      Parameters:
      message - the message whose properties will be copied.
      Throws:
      NullPointerException - if message is null.

    • removeProperty

      public final void removeProperty(String name)
      Removes the property indexed by name.
      Parameters:
      name - the name of the property.
      Throws:
      NullPointerException - if name is null.

    • clearProperties

      public final void clearProperties()
      Removes all defined properties from this Message.

    • getBigDecimal

      public final BigDecimal getBigDecimal(String name)
      Returns the big decimal value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the big decimal value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not a BigDecimal.

    • putBigDecimal

      public final void putBigDecimal(String name, BigDecimal value)
      Changes the big decimal value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new big decimal value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getBigInteger

      public final BigInteger getBigInteger(String name)
      Returns the big integer value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the big integer value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not a BigInteger.

    • putBigInteger

      public final void putBigInteger(String name, BigInteger value)
      Changes the big integer value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new big integer value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getBoolean

      public final Boolean getBoolean(String name)
      Returns the boolean value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the boolean value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if the value is not a Boolean.

    • putBoolean

      public final void putBoolean(String name, Boolean value)
      Changes the boolean value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new boolean value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getByte

      public final Byte getByte(String name)
      Returns the byte value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the byte value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not a Byte.

    • putByte

      public final void putByte(String name, Byte value)
      Changes the byte value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new byte value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getBytes

      public final byte[] getBytes()
      Returns an array of bytes containing the data of this Message.

      Warning: to reduce memory consumption, this method returns a reference to (not a copy of) the mutable object stored in this Message. If the returned object is later modified, the Message object will be modified.

      Returns:
      the byte array data or null if not defined.

    • setBytes

      public final void setBytes(byte[] bytes)
      Changes the array of bytes containing the data of this Message.

      Warning: to reduce memory consumption, this Message stores a reference to (not a copy of) the supplied mutable object. If the supplied object is later modified, the Message object will be modified.

      Parameters:
      bytes - the new bytes data of the Message (can be null).

    • getBytes

      public final byte[] getBytes(String name)
      Returns the bytes value of the property indexed by name.

      Warning: to reduce memory consumption, this method returns a reference to (not a copy of) the mutable object stored in this Message. If the returned object is later modified, the Message object will be modified.

      Parameters:
      name - the name of the property.
      Returns:
      the bytes value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if the value is not a byte[].

    • putBytes

      public final void putBytes(String name, byte[] value)
      Changes the bytes value of the property indexed by name. If value is null the property is removed.

      Warning: to reduce memory consumption, this Message stores a reference to (not a copy of) the supplied mutable object. If the supplied object is later modified, the Message object will be modified.

      Parameters:
      name - the name of the property.
      value - the new bytes value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getDate

      public final Date getDate(String name)
      Returns the date value of the property indexed by name.

      Warning: to reduce memory consumption, this method returns a reference to (not a copy of) the mutable object stored in this Message. If the returned object is later modified, the Message object will be modified.

      Parameters:
      name - the name of the property.
      Returns:
      the date value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if the value is not a Date.

    • putDate

      public final void putDate(String name, Date value)
      Changes the date value of the property indexed by name. If value is null the property is removed.

      Warning: to reduce memory consumption, this Message stores a reference to (not a copy of) the supplied mutable object. If the supplied object is later modified, the Message object will be modified.

      Parameters:
      name - the name of the property.
      value - the new date value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getDouble

      public final Double getDouble(String name)
      Returns the double value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the double value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not a Double.

    • putDouble

      public final void putDouble(String name, Double value)
      Changes the double value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new double value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getFloat

      public final Float getFloat(String name)
      Returns the float value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the float value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not a Float.

    • putFloat

      public final void putFloat(String name, Float value)
      Changes the float value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new float value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getInteger

      public final Integer getInteger(String name)
      Returns the integer value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the integer value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not an Integer.

    • putInteger

      public final void putInteger(String name, Integer value)
      Changes the integer value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new integer value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getLong

      public final Long getLong(String name)
      Returns the long value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the long value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not an Long.

    • putLong

      public final void putLong(String name, Long value)
      Changes the long value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new long value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getObject

      public final <T extends Serializable> T getObject(Class<T> type)
      Returns the object containing the data of this Message.

      Warning: to reduce memory consumption, this method returns a reference to (not a copy of) the mutable object stored in this Message. If the returned object is later modified, the Message object will be modified.

      Type Parameters:
      T - the type of the returned object.
      Parameters:
      type - the class type of the required object.
      Returns:
      the required object or null if not defined.
      Throws:
      NullPointerException - if type is null.
      ClassCastException - if object is not an instance of type.

    • setObject

      public final void setObject(Serializable object)
      Changes the object containing the data of this Message.

      Warning: to reduce memory consumption, this Message stores a reference to (not a copy of) the supplied mutable object. If the supplied object is later modified, the Message object will be modified.

      Parameters:
      object - the new object data of the Message (can be null).

    • getObject

      public final <T extends Serializable> T getObject(String name, Class<T> type)
      Returns the object value of the property indexed by name.

      Warning: to reduce memory consumption, this method returns a reference to (not a copy of) the mutable object stored in this Message. If the returned object is later modified, the Message object will be modified.

      Type Parameters:
      T - the type of the returned object.
      Parameters:
      name - the name of the property.
      type - the class of the returned object.
      Returns:
      the typed object value or null if not defined.
      Throws:
      NullPointerException - if an argument is null.
      ClassCastException - if object is not an instance of type.

    • putObject

      public final void putObject(String name, Serializable value)
      Changes the object value of the property indexed by name. If value is null the property is removed.

      Warning: to reduce memory consumption, this Message stores a reference to (not a copy of) the supplied mutable object. If the supplied object is later modified, the Message object will be modified.

      Parameters:
      name - the name of the property.
      value - the new object value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getShort

      public final Short getShort(String name)
      Returns the short value of the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the short value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      NumberFormatException - if string value of property is invalid.
      ClassCastException - if the value is not an Short.

    • putShort

      public final void putShort(String name, Short value)
      Changes the short value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new short value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • getText

      public final String getText()
      Returns a string containing the data of this Message.
      Returns:
      the text data or null if not defined.

    • setText

      public final void setText(String text)
      Changes the string containing the data of this Message.
      Parameters:
      text - the new text data of the Message (can be null).

    • getText

      public final String getText(String name)
      Returns the string value the property indexed by name.
      Parameters:
      name - the name of the property.
      Returns:
      the string value or null if not defined.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if the value is not a String.

    • putText

      public final void putText(String name, String value)
      Changes the string value of the property indexed by name. If value is null the property is removed.
      Parameters:
      name - the name of the property.
      value - the new string value of the property (can be null).
      Throws:
      NullPointerException - if name is null.

    • toString

      public String toString()
      Returns a string representation of this Message.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this Message.

    • toBuffer

      public final ByteBuffer toBuffer(int compressionThreshold) throws Exception
      Encodes all the fields of this Message into a ByteBuffer. The encoded message is compressed if its size is greater or equal to the specified compression threshold. No compression occurs if the size of the encoded message is less than 100 bytes.
      Parameters:
      compressionThreshold - the minimum size in bytes that a encoded message must have before it is compressed.
      Returns:
      a byte buffer with the encoded Message.
      Throws:
      Exception - if an encoding error occurs.

    • fromBuffer

      public final void fromBuffer(ByteBuffer buffer) throws Exception
      Decodes all the fields of this Message from supplied ByteBuffer.
      Parameters:
      buffer - a byte buffer with an encoded Message.
      Throws:
      NullPointerException - if buffer is null.
      BufferUnderflowException - if buffer is missing bytes.
      Exception - if another decoding error occurs.

    • valueOf

      public static Message valueOf(Serializable data)
      Returns a Message built using the supplied object data. If data is null, a new Message without data is returned. If data is itself a Message, it is returned directly without creating a new Message. Otherwise data is used to create a new Message, in which case data must be either a String, a Serializable or a byte[].
      Parameters:
      data - the data used to build a Message (can be null).
      Returns:
      a Message built using the supplied object data.
      Throws:
      IllegalArgumentException - if the type of data is invalid.