org.jgroups

## Class Message

- java.lang.Object
- - org.jgroups.Message

- All Implemented Interfaces:
    Streamable

      public class Message
      extends java.lang.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 Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Address` | `dest_addr`
    `static byte` | `DONT_BUNDLE`
    `protected Headers` | `headers` All headers are placed here
    `protected int` | `length` The number of bytes in the buffer (usually buf.length is buf not equal to null).
    `protected static Log` | `log`
    `static byte` | `NO_FC`
    `static byte` | `NO_RELAY`
    `static byte` | `NO_RELIABILITY`
    `static byte` | `NO_TOTAL_ORDER`
    `protected int` | `offset` The index into the payload (usually 0)
    `static byte` | `OOB`
    `static byte` | `OOB_DELIVERED`
    `static byte` | `SCOPED`
    `protected Address` | `src_addr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Message()`
    `Message(Address dest)` Public constructor
    `Message(Address dest, Address src, byte[] buf)` Public constructor
    `Message(Address dest, Address src, byte[] buf, int offset, int length)` Constructs a message.
    `Message(Address dest, Address src, java.lang.Object obj)` Public constructor
    `Message(boolean create_headers)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearFlag(byte flag)`
    `void` | `clearTransientFlag(byte flag)`
    `protected java.lang.Object` | `clone()`
    `Message` | `copy()`
    `Message` | `copy(boolean copy_buffer)` Create a copy of the message.
    `Message` | `copy(boolean copy_buffer, boolean copy_headers)` Create a copy of the message.
    `Message` | `copy(boolean copy_buffer, short starting_id)` Doesn't copy any headers except for those with ID >= copy_headers_above
    `static java.lang.String` | `flagsToString(byte flags)`
    `byte[]` | `getBuffer()` Returns a copy of the buffer if offset and length are used, otherwise a reference.
    `Address` | `getDest()`
    `byte` | `getFlags()`
    `Header` | `getHeader(short id)`
    `java.util.Map<java.lang.Short,Header>` | `getHeaders()` Returns a reference to the headers hashmap, which is immutable.
    `int` | `getLength()` Returns the number of bytes in the buffer
    `int` | `getNumHeaders()`
    `java.lang.Object` | `getObject()` Uses custom serialization to create an object from the buffer of the message.
    `int` | `getOffset()` Returns the offset into the buffer at which the data starts
    `byte[]` | `getRawBuffer()` Returns a reference to the payload (byte buffer).
    `short` | `getScope()`
    `Address` | `getSrc()`
    `byte` | `getTransientFlags()`
    `boolean` | `isFlagSet(byte flag)`
    `protected static boolean` | `isFlagSet(byte flags, byte flag)`
    `boolean` | `isTransientFlagSet(byte flag)`
    `Message` | `makeReply()`
    `java.lang.String` | `printHeaders()`
    `java.lang.String` | `printObjectHeaders()`
    `void` | `putHeader(short id, Header hdr)` Puts a header given an ID into the hashmap.
    `Header` | `putHeaderIfAbsent(short id, Header hdr)` Puts a header given a key into the map, only if the key doesn't exist yet
    `void` | `readFrom(java.io.DataInputStream in)` Read the state of the current object (including superclasses) from instream Note that the input stream must not be closed
    `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
    `void` | `setBuffer(Buffer buf)` Note that the byte[] buffer passed as argument must not be modified.
    `void` | `setBuffer(byte[] b)`
    `void` | `setBuffer(byte[] b, int offset, int length)` Set the internal buffer to point to a subset of a given buffer
    `void` | `setDest(Address new_dest)`
    `void` | `setFlag(byte flag)`
    `void` | `setObject(java.lang.Object obj)` Takes an object and uses Java serialization to generate the byte[] buffer which is set in the message.
    `void` | `setScope(short scope)`
    `void` | `setSrc(Address new_src)`
    `void` | `setTransientFlag(byte flag)` Same as `setFlag(byte)` but transient flags are never marshalled
    `boolean` | `setTransientFlagIfAbsent(byte flag)` Atomically checks if a given flag is set and - if not - sets it.
    `long` | `size()` Returns the exact size of the marshalled message.
    `java.lang.String` | `toString()`
    `java.lang.String` | `toStringAsObject()` Tries to read an object from the message's buffer and prints it
    `static java.lang.String` | `transientFlagsToString(byte flags)`
    `void` | `writeTo(java.io.DataOutputStream out)` Streams all members (dest and src addresses, buffer and headers) to the output stream.
    `void` | `writeToNoAddrs(Address src, java.io.DataOutputStream out)` 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

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### 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:
        Constant Field Values

    - #### DONT_BUNDLE

          public static final byte DONT_BUNDLE

      See Also:
        Constant Field Values

    - #### NO_FC

          public static final byte NO_FC

      See Also:
        Constant Field Values

    - #### SCOPED

          public static final byte SCOPED

      See Also:
        Constant Field Values

    - #### NO_RELIABILITY

          public static final byte NO_RELIABILITY

      See Also:
        Constant Field Values

    - #### NO_TOTAL_ORDER

          public static final byte NO_TOTAL_ORDER

      See Also:
        Constant Field Values

    - #### NO_RELAY

          public static final byte NO_RELAY

      See Also:
        Constant Field Values

    - #### OOB_DELIVERED

          public static final byte OOB_DELIVERED

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### 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,
                 java.lang.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 Detail

    - #### 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 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()

    - #### getNumHeaders

          public int getNumHeaders()

    - #### setObject

          public final void 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 final java.lang.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 java.lang.Object clone()
                                    throws java.lang.CloneNotSupportedException

      Overrides:
        `clone` in class `java.lang.Object`
      Throws:
        `java.lang.CloneNotSupportedException`

    - #### makeReply

          public Message makeReply()

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### toStringAsObject

          public java.lang.String toStringAsObject()

      Tries to read an object from the message's buffer and prints it

    - #### printObjectHeaders

          public java.lang.String printObjectHeaders()

    - #### writeTo

          public void writeTo(java.io.DataOutputStream out)
                       throws java.io.IOException

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

    - #### writeToNoAddrs

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

    - #### readFrom

          public void readFrom(java.io.DataInputStream in)
                        throws java.io.IOException,
                               java.lang.IllegalAccessException,
                               java.lang.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:
        `java.io.IOException`
        `java.lang.IllegalAccessException`
        `java.lang.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 java.lang.String flagsToString(byte flags)

    - #### transientFlagsToString

          public static java.lang.String transientFlagsToString(byte flags)

Copyright © 1998-2009 Bela Ban / Red Hat. All Rights Reserved.