Package org.jgroups

Class Message

  • All Implemented Interfaces:
    Constructable<Message>, Streamable
    public class Message
extends java.lang.Object
implements Streamable, Constructable<Message>
    A Message encapsulates data sent to members of a group. It contains among other things the address of the sender, the destination address, a payload (byte buffer) and a list of headers. Headers are added by protocols on the sender side and removed by protocols on the receiver's side.

    The byte buffer can point to a reference, and we can subset it using index and length. However, when the message is serialized, we only write the bytes between index and length.

    Since:
    2.0
    Author:
    Bela Ban

    • Field Detail

      • buf

        protected byte[] buf
        The payload

      • offset

        protected int offset
        The index into the payload (usually 0)

      • length

        protected int length
        The number of bytes in the buffer (usually buf.length is buf not equal to null).

      • headers

        protected volatile Header[] headers
        All headers are placed here

      • flags

        protected volatile short flags

      • transient_flags

        protected volatile byte transient_flags

    • Constructor Detail

      • Message

        public Message​(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 the group. Otherwise, it is sent to a single member.

      • Message

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

      • Message

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

        Note that the byte[] buffer passed as argument must not be modified. Reason: if we retransmit the message, it would still have a ref to the original byte[] buffer passed in as argument, and so we would retransmit a changed byte[] buffer !
        Parameters:
        dest - The Address of the receiver. If it is null, then the message is sent to the group. Otherwise, it is sent to a single member.
        buf - A reference to a byte buffer
        offset - The index into the byte buffer
        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

      • Message

        public Message​(Address dest,
               java.lang.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 the group. Otherwise, it is sent to a single member.
        obj - The object that will be marshalled into the byte buffer. Has to be serializable (e.g. implementing Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).

      • Message

        public Message()

      • Message

        public Message​(boolean create_headers)

    • Method Detail

      • create

        public java.util.function.Supplier<? extends Message> create()
        Description copied from interface: Constructable
        Creates an instance of the class implementing this interface
        Specified by:
        create in interface Constructable<Message>

      • getDest

        public Address getDest()

      • getOffset

        public int getOffset()

      • offset

        public int offset()

      • getLength

        public int getLength()

      • length

        public int length()

      • getRawBuffer

        public byte[] getRawBuffer()
        Returns a reference to the payload (byte buffer). Note that this buffer should not be modified as we do not copy the buffer on copy() or clone(): the buffer of the copied message is simply a reference to the old buffer.
        Even if offset and length are used: we return the entire buffer, not a subset.

      • rawBuffer

        public byte[] rawBuffer()

      • buffer

        public byte[] buffer()

      • buffer2

        public Buffer buffer2()

      • buffer

        public Message buffer​(byte[] b)

      • getNumHeaders

        public int getNumHeaders()

      • numHeaders

        public int numHeaders()

      • getBuffer

        public byte[] getBuffer()
        Returns a copy of the buffer if offset and length are used, otherwise a reference.
        Returns:
        byte array with a copy of the buffer.

      • getBuffer2

        public Buffer getBuffer2()

      • setBuffer

        public Message setBuffer​(byte[] b)
        Sets the buffer.

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

      • setBuffer

        public Message setBuffer​(byte[] b,
                         int offset,
                         int length)
        Sets the internal buffer to point to a subset of a given buffer.

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

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

      • setBuffer

        public Message setBuffer​(Buffer buf)
        Sets the buffer

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

      • getHeaders

        public java.util.Map<java.lang.Short,​Header> getHeaders()
        Returns a reference to the headers hashmap, which is immutable. Any attempt to modify the returned map will cause a runtime exception

      • printHeaders

        public java.lang.String printHeaders()

      • setObject

        public Message setObject​(java.lang.Object obj)
        Takes an object and uses Java serialization to generate the byte[] buffer 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()

      • getObject

        public <T> T getObject​(java.lang.ClassLoader loader)
        Uses custom serialization to create an object from the buffer 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 buffer 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[] buffer 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

      • setFlag

        public Message setFlag​(Message.Flag... flags)
        Sets a number of flags in a message
        Parameters:
        flags - The flag or flags
        Returns:
        A reference to the message

      • setFlag

        public Message setFlag​(short flag)
        Sets the flags from a short. Not recommended (use setFlag(org.jgroups.Message.Flag...) instead), as the internal representation of flags might change anytime.
        Parameters:
        flag -
        Returns:

      • setTransientFlag

        public Message setTransientFlag​(short flag)

      • getFlags

        public short getFlags()
        Returns the internal representation of flags. Don't use this, as the internal format might change at any time ! This is only used by unit test code
        Returns:

      • getTransientFlags

        public short getTransientFlags()

      • clearFlag

        public Message clearFlag​(Message.Flag... flags)
        Clears a number of flags in a message
        Parameters:
        flags - The flags
        Returns:
        A reference to the message

      • isFlagSet

        public static boolean isFlagSet​(short flags,
                                Message.Flag flag)

      • isFlagSet

        public boolean isFlagSet​(Message.Flag flag)
        Checks if a given flag is set
        Parameters:
        flag - The flag
        Returns:
        Whether or not the flag is currently set

      • isTransientFlagSet

        public static boolean isTransientFlagSet​(short flags,
                                         Message.TransientFlag flag)

      • setTransientFlagIfAbsent

        public boolean setTransientFlagIfAbsent​(Message.TransientFlag flag)
        Atomically checks if a given flag is set and - if not - sets it. When multiple threads concurrently call this method with the same flag, only one of them will be able to set the flag
        Parameters:
        flag -
        Returns:
        True if the flag could be set, false if not (was already set)

      • putHeader

        public Message putHeader​(short id,
                         Header hdr)
        Puts a header given an ID into the hashmap. Overwrites potential existing entry.

      • getHeader

        public <T extends Header> T getHeader​(short id)

      • getHeader

        public <T extends Header> T getHeader​(short... ids)
        Returns a header for a range of IDs, or null if not found

      • copy

        public Message copy​(boolean copy_buffer)
        Create a copy of the message. If offset and length are used (to refer to another buffer), the copy will contain only the subset offset and length point to, copying the subset into the new copy.
        Parameters:
        copy_buffer -
        Returns:
        Message with specified data

      • copy

        public Message copy​(boolean copy_buffer,
                    boolean copy_headers)
        Create a copy of the message. If offset and length are used (to refer to another buffer), the copy will contain only the subset 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 putHeader(short,Header) again.

        Parameters:
        copy_buffer -
        copy_headers - Copy the headers
        Returns:
        Message with specified data

      • copy

        public Message copy​(boolean copy_buffer,
                    short starting_id)
        Doesn't copy any headers except for those with ID >= copy_headers_above
        Parameters:
        copy_buffer -
        starting_id -
        Returns:
        A message with headers whose ID are >= starting_id

      • copy

        public Message copy​(boolean copy_buffer,
                    short starting_id,
                    short... copy_only_ids)
        Copies a message. Copies only headers with IDs >= starting_id or IDs which are in the copy_only_ids list
        Parameters:
        copy_buffer -
        starting_id -
        copy_only_ids -
        Returns:

      • makeReply

        public Message makeReply()

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • printObjectHeaders

        public java.lang.String printObjectHeaders()

      • writeTo

        public void writeTo​(java.io.DataOutput out)
             throws java.io.IOException
        Writes the message to the output stream
        Specified by:
        writeTo in interface Streamable
        Throws:
        java.io.IOException

      • writeToNoAddrs

        public void writeToNoAddrs​(Address src,
                           java.io.DataOutput out,
                           short... excluded_headers)
                    throws java.io.IOException
        Writes the message to the output stream, but excludes the dest and src addresses unless the src address given as argument is different from the message's src address
        Parameters:
        excluded_headers - Don't marshal headers that are part of excluded_headers
        Throws:
        java.io.IOException

      • readFrom

        public void readFrom​(java.io.DataInput in)
              throws java.io.IOException,
                     java.lang.ClassNotFoundException
        Reads the message's contents from an input stream
        Specified by:
        readFrom in interface Streamable
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException

      • readFromSkipPayload

        public int readFromSkipPayload​(ByteArrayDataInputStream in)
                        throws java.io.IOException,
                               java.lang.ClassNotFoundException
        Reads the message's contents from an input stream, but skips the buffer and instead returns the position (offset) at which the buffer starts
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException

      • size

        public long size()
        Returns the exact size of the marshalled message. Uses method size() of each header to compute the size, so if a Header subclass doesn't implement size() we will use an approximation. However, most relevant header subclasses have size() implemented correctly. (See org.jgroups.tests.SizeTest).

        The return type is a long as this is the length of the payload (getLength()) plus metadata (e.g. flags, headers, source and dest addresses etc). Since the largest payload can be Integer.MAX_VALUE, adding the metadata might lead to an int overflow, that's why we use a long.

        Returns:
        The number of bytes for the marshalled message

      • flagsToString

        public static java.lang.String flagsToString​(short flags)

      • transientFlagsToString

        public static java.lang.String transientFlagsToString​(short flags)

      • writeHeader

        protected static void writeHeader​(Header hdr,
                                  java.io.DataOutput out)
                           throws java.io.IOException
        Throws:
        java.io.IOException

      • readHeader

        protected static Header readHeader​(java.io.DataInput in)
                            throws java.io.IOException,
                                   java.lang.ClassNotFoundException
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException

      • createHeaders

        protected static Header[] createHeaders​(int size)