org.jgroups
Class Message

java.lang.Object
  extended by 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
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
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
 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.