Package org.jgroups

Class BytesMessage

java.lang.Object
org.jgroups.BaseMessage
org.jgroups.BytesMessage
All Implemented Interfaces:
Constructable<Message>, Message, SizeStreamable, Streamable
Direct Known Subclasses:
FragmentedMessage
public class BytesMessage extends BaseMessage
A Message containing a byte array as payload.

The byte array can point to a reference, and we can subset it using index and length. When the message is serialized, only the bytes between index and length are written.

Since:
5.0

  • Field Details

    • array

      protected byte[] array
      The payload

    • offset

      protected int offset
      The index into the payload

    • length

      protected int length
      The number of bytes in the array

  • Constructor Details

    • BytesMessage

      public BytesMessage()

    • BytesMessage

      public BytesMessage(Address dest)
      Constructs a message given a destination address
      Parameters:
      dest - The Address of the receiver. If it is null, then the message is sent to all cluster members. Otherwise, it is sent to a single member.

    • BytesMessage

      public BytesMessage(Address dest, byte[] array)
      Constructs a message given a destination and source address and the payload byte array
      Parameters:
      dest - The Address of the receiver. If it is null, then the message is sent to all cluster members. Otherwise, it is sent to a single member.
      array - The payload. Note that this array must not be modified (e.g. buf[0]='x' is not allowed) since we don't copy the contents.

    • BytesMessage

      public BytesMessage(Address dest, byte[] array, int offset, int length)
      Constructs a message. The index and length parameters provide a reference to a byte array, rather than a copy, and refer to a subset of the array. This is important when we want to avoid copying. When the message is serialized, only the subset is serialized.

      Note that the byte array passed as argument must not be modified. Reason: if we retransmit the message, it would still have a ref to the original byte array passed in as argument, and so we would retransmit a changed byte array !

      Parameters:
      dest - The Address of the receiver. If it is null, then the message is sent to all cluster members. Otherwise, it is sent to a single member.
      array - A reference to a byte array
      offset - The index into the byte array
      length - The number of bytes to be used from buf. Both index and length are checked for array index violations and an ArrayIndexOutOfBoundsException will be thrown if invalid

    • BytesMessage

      public BytesMessage(Address dest, ByteArray array)

    • BytesMessage

      public BytesMessage(Address dest, Object obj)
      Constructs a message given a destination and source address and the payload object
      Parameters:
      dest - The Address of the receiver. If it is null, then the message is sent to all cluster members. Otherwise, it is sent to a single member.
      obj - The object that will be marshalled into the byte array. Has to be serializable (e.g. implementing Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).

  • Method Details

    • setFlag

      public BytesMessage setFlag(Message.Flag... flags)
      Description copied from class: BaseMessage
      Sets a number of flags in a message
      Specified by:
      setFlag in interface Message
      Overrides:
      setFlag in class BaseMessage
      Parameters:
      flags - The flag or flags
      Returns:
      A reference to the message

    • create

      public Supplier<Message> create()
      Description copied from interface: Constructable
      Creates an instance of the class implementing this interface

    • getType

      public short getType()
      Description copied from interface: Message
      Returns the type of the message, e.g. BYTES_MSG, OBJ_MSG etc

    • hasPayload

      public boolean hasPayload()
      Description copied from interface: Message
      Returns true if the message has a payload, e.g. a byte[] array in a BytesMessage or an object in an ObjectMessage. This is more generic than Message.hasArray(), as it is not just applicable to a byte array.
      Returns:
      True if the message has a payload

    • hasArray

      public boolean hasArray()
      Description copied from interface: Message
      Returns true if this message has a byte[] array as payload (even if it's null!), false otherwise

    • getOffset

      public int getOffset()
      Description copied from interface: Message
      Returns the offset of the byte[] array at which user data starts. Throws an exception if the message does not have a byte[] array payload (if Message.hasArray() is false).

      Note that this is a convenience method, as most messages are of type BytesMessage.

    • getLength

      public int getLength()
      Description copied from interface: Message
      Returns the length of the byte[] array payload. If the message does not have a byte[] array payload (Message.hasArray() is false), then the serialized size may be returned, or an implementation may choose to throw an exception

    • getArray

      public byte[] getArray()
      Returns a reference to the payload (byte array). Note that this array should not be modified as we do not copy the array on copy() or clone(): the array of the copied message is simply a reference to the old array.

      Even if offset and length are used: we return the entire array, not a subset.

    • setArray

      public BytesMessage setArray(byte[] b, int offset, int length)
      Sets the internal array to point to a subset of a given array.

      Note that the byte array passed as argument must not be modified. Reason: if we retransmit the message, it would still have a ref to the original byte array passed in as argument, and so we would retransmit a changed byte array !

      Parameters:
      b - The reference to a given array. If null, we'll reset the array to null
      offset - The initial position
      length - The number of bytes

    • setArray

      public BytesMessage setArray(ByteArray buf)
      Sets the array

      Note that the byte array passed as argument must not be modified. Reason: if we retransmit the message, it would still have a ref to the original byte array passed in as argument, and so we would retransmit a changed byte array !

    • setObject

      public BytesMessage setObject(Object obj)
      Takes an object and uses Java serialization to generate the byte array which is set in the message. Parameter 'obj' has to be serializable (e.g. implementing Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).

    • getObject

      public <T> T getObject()
      Description copied from interface: Message
      Gets an object from the payload. If the payload is a byte[] array (e.g. as in BytesMessage), an attempt to de-serialize the array into an object is made, and the object returned.

      If the payload is an object (e.g. as is the case in ObjectMessage), the object will be returned directly.

    • getObject

      public <T> T getObject(ClassLoader loader)
      Uses custom serialization to create an object from the array of the message. Note that this is dangerous when using your own classloader, e.g. inside of an application server ! Most likely, JGroups will use the system classloader to deserialize the array into an object, whereas (for example) a web application will want to use the webapp's classloader, resulting in a ClassCastException. The recommended way is for the application to use their own serialization and only pass byte array to JGroups.

      As of 3.5, a classloader can be passed in. It will be used first to find a class, before contacting the other classloaders in the list. If null, the default list of classloaders will be used.

      Returns:
      the object

    • size

      public int size()
      Description copied from interface: Message
      Returns the exact size of the marshalled message
      Specified by:
      size in interface Message
      Overrides:
      size in class BaseMessage
      Returns:
      The number of bytes for the marshalled message

    • copyPayload

      protected Message copyPayload(Message copy)
      Copies the byte array. If offset and length are used (to refer to another array), the copy will contain only the subset that offset and length point to, copying the subset into the new copy.

      Note that for headers, only the arrays holding references to the headers are copied, not the headers themselves ! The consequence is that the headers array of the copy hold the *same* references as the original, so do *not* modify the headers ! If you want to change a header, copy it and call BaseMessage.putHeader(short,Header) again.

      Overrides:
      copyPayload in class BaseMessage

    • sizeOfPayload

      protected int sizeOfPayload()

    • writePayload

      public void writePayload(DataOutput out) throws IOException
      Throws:
      IOException

    • readPayload

      public void readPayload(DataInput in) throws IOException
      Throws:
      IOException

    • createMessage

      protected <T extends BytesMessage> T createMessage()