Package org.jgroups

Class Message

java.lang.Object
org.jgroups.Message
All Implemented Interfaces:
Streamable
public class Message extends Object implements Streamable
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.

Author:
Bela Ban

  • Field Details

    • dest_addr

      protected Address dest_addr

    • src_addr

      protected Address src_addr

    • 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 Headers headers
      All headers are placed here

    • log

      protected static final Log log

    • OOB

      public static final byte OOB
      See Also:

    • DONT_BUNDLE

      public static final byte DONT_BUNDLE
      See Also:

    • NO_FC

      public static final byte NO_FC
      See Also:

    • SCOPED

      public static final byte SCOPED
      See Also:

    • NO_RELIABILITY

      public static final byte NO_RELIABILITY
      See Also:

    • NO_TOTAL_ORDER

      public static final byte NO_TOTAL_ORDER
      See Also:

    • NO_RELAY

      public static final byte NO_RELAY
      See Also:

    • OOB_DELIVERED

      public static final byte OOB_DELIVERED
      See Also:

  • Constructor Details

    • Message

      public Message(Address dest)
      Public constructor
      Parameters:
      dest - Address of receiver. If it is null then the message sent to the group. Otherwise, it contains a single destination and is sent to that member.

    • Message

      public Message(Address dest, Address src, byte[] buf)
      Public constructor
      Parameters:
      dest - Address of receiver. If it is null then the message sent to the group. Otherwise, it contains a single destination and is sent to that member.

      src - Address of sender
      buf - Message to be sent. Note that this buffer must not be modified (e.g. buf[0]=0 is not allowed), since we don't copy the contents on clopy() or clone().

    • Message

      public Message(Address dest, Address src, byte[] buf, int offset, int length)
      Constructs a message. The index and length parameters allow to 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 - Address of receiver. If it is null then the message sent to the group. Otherwise, it contains a single destination and is sent to that member.

      src - Address of sender
      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, Address src, Object obj)
      Public constructor
      Parameters:
      dest - Address of receiver. If it is null then the message sent to the group. Otherwise, it contains a single destination and is sent to that member.

      src - Address of sender
      obj - The object will be marshalled into the byte buffer. Obj to be serializable (e.g. implementing Serializable, Externalizable or Streamable, or be a basic type (e.g. Integer, Short etc)).! The resulting buffer must not be modified (e.g. buf[0]=0 is not allowed), since we don't copy the contents on clopy() or clone().

    • Message

      public Message()

    • Message

      public Message(boolean create_headers)

  • Method Details

    • getDest

      public Address getDest()

    • setDest

      public void setDest(Address new_dest)

    • getSrc

      public Address getSrc()

    • setSrc

      public void setSrc(Address new_src)

    • 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.

    • getBuffer

      public final 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.

    • setBuffer

      public final void setBuffer(byte[] b)

    • setBuffer

      public final void setBuffer(byte[] b, int offset, int length)
      Set the internal buffer to point to a subset of a given 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 final void setBuffer(Buffer buf)
      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 !

    • getOffset

      public int getOffset()
      Returns the offset into the buffer at which the data starts

    • getLength

      public int getLength()
      Returns the number of bytes in the buffer

    • getHeaders

      public Map<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 String printHeaders()

    • getNumHeaders

      public int getNumHeaders()

    • setObject

      public final void setObject(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 final Object getObject()
      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.
      Returns:

    • setFlag

      public void setFlag(byte flag)

    • clearFlag

      public void clearFlag(byte flag)

    • isFlagSet

      public boolean isFlagSet(byte flag)

    • setTransientFlag

      public void setTransientFlag(byte flag)
      Same as setFlag(byte) but transient flags are never marshalled
      Parameters:
      flag -

    • setTransientFlagIfAbsent

      public boolean setTransientFlagIfAbsent(byte 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)

    • clearTransientFlag

      public void clearTransientFlag(byte flag)

    • isTransientFlagSet

      public boolean isTransientFlagSet(byte flag)

    • isFlagSet

      protected static boolean isFlagSet(byte flags, byte flag)

    • getFlags

      public byte getFlags()

    • getTransientFlags

      public byte getTransientFlags()

    • setScope

      public void setScope(short scope)

    • getScope

      public short getScope()

    • putHeader

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

    • putHeaderIfAbsent

      public Header putHeaderIfAbsent(short id, Header hdr)
      Puts a header given a key into the map, only if the key doesn't exist yet
      Parameters:
      id -
      hdr -
      Returns:
      the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)

    • removeHeader

      public Header removeHeader(short id)
      Deprecated.
      Use getHeader() instead. The issue with removing a header is described in http://jira.jboss.com/jira/browse/JGRP-393
      Parameters:
      key -
      Returns:
      the header associated with key

    • getHeader

      public Header getHeader(short id)

    • copy

      public Message copy()

    • 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.
      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

    • clone

      protected Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException

    • makeReply

      public Message makeReply()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toStringAsObject

      public String toStringAsObject()
      Tries to read an object from the message's buffer and prints it

    • printObjectHeaders

      public String printObjectHeaders()

    • writeTo

      public void writeTo(DataOutputStream out) throws IOException
      Streams all members (dest and src addresses, buffer and headers) to the output stream.
      Specified by:
      writeTo in interface Streamable
      Parameters:
      out -
      Throws:
      IOException

    • writeToNoAddrs

      public void writeToNoAddrs(Address src, DataOutputStream out) throws 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:
      src -
      out -
      Throws:
      IOException

    • readFrom

      public void readFrom(DataInputStream in) throws IOException, IllegalAccessException, InstantiationException
      Description copied from interface: Streamable
      Read the state of the current object (including superclasses) from instream Note that the input stream must not be closed
      Specified by:
      readFrom in interface Streamable
      Throws:
      IOException
      IllegalAccessException
      InstantiationException

    • 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).
      Returns:
      The number of bytes for the marshalled message

    • flagsToString

      public static String flagsToString(byte flags)

    • transientFlagsToString

      public static String transientFlagsToString(byte flags)