Package org.jgroups

Class Message

  • All Implemented Interfaces:
    java.io.Externalizable, java.io.Serializable, Streamable

    public class Message
    extends java.lang.Object
    implements java.io.Externalizable, 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.

    Version:
    $Id: Message.java,v 1.76.2.9 2008/09/16 13:09:12 belaban Exp $
    Author:
    Bela Ban
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Address dest_addr  
      protected Headers headers
      All headers are placed here
      static byte HIGH_PRIO  
      protected int length
      The number of bytes in the buffer (usually buf.length is buf not equal to null).
      protected static org.apache.commons.logging.Log log  
      static byte LOW_PRIO  
      protected int offset
      The index into the payload (usually 0)
      static byte OOB  
      protected Address src_addr  
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clearFlag​(byte flag)  
      protected java.lang.Object clone()  
      Message copy()  
      Message copy​(boolean copy_buffer)
      Create a copy of the message.
      byte[] getBuffer()
      Returns a copy of the buffer if offset and length are used, otherwise a reference.
      Address getDest()  
      byte getFlags()  
      Header getHeader​(java.lang.String key)  
      java.util.Map<java.lang.String,​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 Java 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).
      Address getSrc()  
      boolean isFlagSet​(byte flag)  
      Message makeReply()  
      java.lang.String printHeaders()  
      java.lang.String printObjectHeaders()  
      void putHeader​(java.lang.String key, Header hdr)
      Puts a header given a key into the hashmap.
      Header putHeaderIfAbsent​(java.lang.String key, Header hdr)
      Puts a header given a key into the map, only if the key doesn't exist yet
      void readExternal​(java.io.ObjectInput in)  
      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​(java.lang.String key)
      Deprecated.
      Use getHeader() instead.
      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 setBuffer​(Buffer buf)
      Note that the byte[] buffer passed as argument must not be modified.
      void setDest​(Address new_dest)  
      void setFlag​(byte flag)  
      void setObject​(java.io.Serializable obj)
      Takes an object and uses Java serialization to generate the byte[] buffer which is set in the message.
      void setSrc​(Address new_src)  
      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
      void writeExternal​(java.io.ObjectOutput out)  
      void writeTo​(java.io.DataOutputStream out)
      Streams all members (dest and src addresses, buffer and headers) to the output stream.
      • 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 transient int offset
        The index into the payload (usually 0)
      • length

        protected transient 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 org.apache.commons.logging.Log log
    • 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.io.Serializable 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 serialized into the byte buffer. Object has to be serializable ! 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().

        Note that this is a convenience method and JGroups will use default Java serialization to serialize obj into a byte buffer.

      • Message

        public Message()
      • Message

        public Message​(boolean create_headers)
    • Method Detail

      • getDest

        public Address getDest()
      • setDest

        public void setDest​(Address new_dest)
      • 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.String,​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.io.Serializable obj)
        Takes an object and uses Java serialization to generate the byte[] buffer which is set in the message.
      • getObject

        public final java.lang.Object getObject()
        Uses Java 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)
      • getFlags

        public byte getFlags()
      • putHeader

        public void putHeader​(java.lang.String key,
                              Header hdr)
        Puts a header given a key into the hashmap. Overwrites potential existing entry.
      • putHeaderIfAbsent

        public Header putHeaderIfAbsent​(java.lang.String key,
                                        Header hdr)
        Puts a header given a key into the map, only if the key doesn't exist yet
        Parameters:
        key -
        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​(java.lang.String key)
        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 assoaicted with key
      • getHeader

        public Header getHeader​(java.lang.String key)
      • 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
      • 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
      • 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
      • printObjectHeaders

        public java.lang.String printObjectHeaders()
      • writeExternal

        public void writeExternal​(java.io.ObjectOutput out)
                           throws java.io.IOException
        Specified by:
        writeExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException
      • readExternal

        public void readExternal​(java.io.ObjectInput in)
                          throws java.io.IOException,
                                 java.lang.ClassNotFoundException
        Specified by:
        readExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException
      • 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
      • 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