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.

Since:

2.0

Author:

Bela Ban

Nested Class Summary

static class	Message.Flag
static class	Message.TransientFlag

Field Summary

protected byte[]	buf The payload
protected Address	dest_addr
static Message.Flag	DONT_BUNDLE
protected short	flags
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 Message.Flag	NO_FC
static Message.Flag	NO_RELAY
static Message.Flag	NO_RELIABILITY
static Message.Flag	NO_TOTAL_ORDER
protected int	offset The index into the payload (usually 0)
static Message.Flag	OOB
static Message.TransientFlag	OOB_DELIVERED
static Message.Flag	RSVP
static Message.Flag	SCOPED
protected Address	src_addr
protected byte	transient_flags

Constructor Summary

Message()

Message(Address dest)
Constructs a Message given a destination Address

Message(Address dest, Address src, byte[] buf)
Constructs a Message given a destination Address, a source Address and the payload byte buffer

Message(Address dest, Address src, byte[] buf, int offset, int length)
Constructs a message.

Message(Address dest, Address src, java.lang.Object obj)
Constructs a Message given a destination Address, a source Address and the payload Object

Message(Address dest, byte[] buf)

Message(Address dest, byte[] buf, int offset, int length)

Message(Address dest, java.lang.Object obj)

Message(boolean create_headers)

Method Summary

Message	clearFlag(Message.Flag... flags) Clears a number of flags in a message
Message	clearTransientFlag(Message.TransientFlag... flags)
protected static boolean	containsId(short id, short[] ids)
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
Message	copy(boolean copy_buffer, short starting_id, short... copy_only_ids) Copies a message.
protected static Headers	createHeaders(Headers m)
protected static Headers	createHeaders(int size)
Address	dest()
Message	dest(Address new_dest)
static java.lang.String	flagsToString(short flags)
byte[]	getBuffer() Returns a copy of the buffer if offset and length are used, otherwise a reference.
Address	getDest()
short	getFlags() Returns the internal representation of flags.
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()
short	getTransientFlags()
boolean	isFlagSet(Message.Flag flag) Checks if a given flag is set
static boolean	isFlagSet(short flags, Message.Flag flag)
boolean	isTransientFlagSet(Message.TransientFlag flag)
Message	makeReply()
java.lang.String	printHeaders()
java.lang.String	printObjectHeaders()
Message	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.DataInput in) Read the state of the current object (including superclasses) from instream Note that the input stream must not be closed
protected static Header	readHeader(java.io.DataInput in)
Message	setBuffer(Buffer buf) Note that the byte[] buffer passed as argument must not be modified.
Message	setBuffer(byte[] b)
Message	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)
Message	setFlag(Message.Flag... flags) Sets a number of flags in a message
Message	setFlag(short flag) Sets the flags from a short.
Message	setObject(java.lang.Object obj) Takes an object and uses Java serialization to generate the byte[] buffer which is set in the message.
Message	setScope(short scope)
void	setSrc(Address new_src)
Message	setTransientFlag(Message.TransientFlag... flags) Same as setFlag(Flag...) except that transient flags are not marshalled
boolean	setTransientFlagIfAbsent(Message.TransientFlag flag) Atomically checks if a given flag is set and - if not - sets it.
long	size() Returns the exact size of the marshalled message.
Address	src()
Message	src(Address new_src)
java.lang.String	toString()
java.lang.String	toStringAsObject() Tries to read an object from the message's buffer and prints it
java.lang.String	transientFlagsToString()
protected static void	writeHeader(Header hdr, java.io.DataOutput out)
void	writeTo(java.io.DataOutput 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

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

Field Detail

dest_addr

protected Address dest_addr

src_addr

protected Address src_addr

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 Headers headers

All headers are placed here

flags

protected volatile short flags

transient_flags

protected volatile byte transient_flags

log

protected static final Log log

OOB

public static final Message.Flag OOB

DONT_BUNDLE

public static final Message.Flag DONT_BUNDLE

NO_FC

public static final Message.Flag NO_FC

SCOPED

public static final Message.Flag SCOPED

NO_RELIABILITY

public static final Message.Flag NO_RELIABILITY

NO_TOTAL_ORDER

public static final Message.Flag NO_TOTAL_ORDER

NO_RELAY

public static final Message.Flag NO_RELAY

RSVP

public static final Message.Flag RSVP

OOB_DELIVERED

public static final Message.TransientFlag OOB_DELIVERED

Constructor Detail

Message

public Message(Address dest)

Constructs a Message given a destination Address

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)

Constructs a Message given a destination Address, a source Address and the payload 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 - 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,
               byte[] buf)

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,
               byte[] buf,
               int offset,
               int length)

Message

public Message(Address dest,
               Address src,
               java.lang.Object obj)

Constructs a Message given a destination Address, a source Address and the payload Object

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 has 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(Address dest,
               java.lang.Object obj)

Message

public Message()

Message

public Message(boolean create_headers)

Method Detail

getDest

public Address getDest()

dest

public Address dest()

setDest

public void setDest(Address new_dest)

dest

public Message dest(Address new_dest)

getSrc

public Address getSrc()

src

public Address src()

setSrc

public void setSrc(Address new_src)

src

public Message src(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 Message setBuffer(byte[] b)

setBuffer

public final Message 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 Message 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 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 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 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:

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:

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 of not the flag is curently set

setTransientFlag

public Message setTransientFlag(Message.TransientFlag... flags)

Same as setFlag(Flag...) except that transient flags are not marshalled

Parameters:

flag - The 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)

clearTransientFlag

public Message clearTransientFlag(Message.TransientFlag... flags)

isTransientFlagSet

public boolean isTransientFlagSet(Message.TransientFlag flag)

getTransientFlags

public short getTransientFlags()

setScope

public Message setScope(short scope)

getScope

public short getScope()

putHeader

public Message 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.)

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.

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

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.DataOutput out)
             throws java.lang.Exception

Streams all members (dest and src addresses, buffer and headers) to the output stream.

Specified by:

writeTo in interface Streamable

Parameters:

out -

Throws:

java.lang.Exception

writeToNoAddrs

public void writeToNoAddrs(Address src,
                           java.io.DataOutputStream out)
                    throws java.lang.Exception

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.lang.Exception

readFrom

public void readFrom(java.io.DataInput in)
              throws java.lang.Exception

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.lang.Exception

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(short flags)

transientFlagsToString

public java.lang.String transientFlagsToString()

writeHeader

protected static void writeHeader(Header hdr,
                                  java.io.DataOutput out)
                           throws java.lang.Exception

Throws:

java.lang.Exception

containsId

protected static boolean containsId(short id,
                                    short[] ids)

readHeader

protected static Header readHeader(java.io.DataInput in)
                            throws java.lang.Exception

Throws:

java.lang.Exception

createHeaders

protected static Headers createHeaders(int size)

createHeaders

protected static Headers createHeaders(Headers m)