Package org.jgroups
Class Message
- java.lang.Object
-
- org.jgroups.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 herestatic 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
-
Constructor Summary
Constructors Constructor Description Message()
Message(boolean create_headers)
Message(Address dest)
Public constructorMessage(Address dest, Address src, byte[] buf)
Public constructorMessage(Address dest, Address src, byte[] buf, int offset, int length)
Constructs a message.Message(Address dest, Address src, java.io.Serializable obj)
Public constructor
-
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 bufferint
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 startsbyte[]
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 yetvoid
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 closedHeader
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 buffervoid
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 itvoid
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.
-
-
-
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
-
OOB
public static final byte OOB
- See Also:
- Constant Field Values
-
LOW_PRIO
public static final byte LOW_PRIO
- See Also:
- Constant Field Values
-
HIGH_PRIO
public static final byte HIGH_PRIO
- 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 senderbuf
- 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 senderbuf
- A reference to a byte bufferoffset
- The index into the byte bufferlength
- 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 senderobj
- 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 serializeobj
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)
-
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 nulloffset
- The initial positionlength
- 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()
-
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 classjava.lang.Object
- Throws:
java.lang.CloneNotSupportedException
-
makeReply
public Message makeReply()
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.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 interfacejava.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 interfacejava.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 interfaceStreamable
- 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 interfaceStreamable
- Throws:
java.io.IOException
java.lang.IllegalAccessException
java.lang.InstantiationException
-
-