org.jgroups

Class Message

Implemented Interfaces:
Externalizable

public class Message
extends java.lang.Object
implements Externalizable

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
protected HashMap
headers
protected int
length
The number of bytes in the buffer (usually buf.length is buf != null)
protected static Log
log
protected int
offset
The index into the payload (usually 0)
protected Address
src_addr

Constructor Summary

Message()
Only used for Externalization (creating an initial object)
Message(Address dest, Address src, Serializable obj)
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.

Method Summary

protected 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()
Header
getHeader(String key)
Map
getHeaders()
int
getLength()
Returns the number of bytes in the buffer
Object
getObject()
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()
Message
makeReply()
String
printObjectHeaders()
void
putHeader(String key, Header hdr)
Puts a header given a key into the hashmap.
void
readExternal(ObjectInput in)
Header
removeHeader(String key)
void
removeHeaders()
void
reset()
Nulls all fields of this message so that the message can be reused.
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
setObject(Serializable obj)
void
setSrc(Address new_src)
long
size()
Returns size of buffer, plus some constant overhead for src and dest, plus number of headers time some estimated size/header.
String
toString()
String
toStringAsObject()
Tries to read an object from the message's buffer and prints it
void
writeExternal(ObjectOutput out)

Field Details

dest_addr

protected Address dest_addr

headers

protected HashMap headers

length

protected int length
The number of bytes in the buffer (usually buf.length is buf != null)

log

protected static Log log

offset

protected int offset
The index into the payload (usually 0)

src_addr

protected Address src_addr

Constructor Details

Message

public Message()
Only used for Externalization (creating an initial object)

Message

public Message(Address dest,
               Address src,
               Serializable obj)
Public constructor
Parameters:
dest - Address of receiver. If it is null or a string, then it is sent to the group (either to current group or to the group as given in the string). If it is a Vector, then it contains a number of addresses to which it must be sent. Otherwise, it contains a single destination.

Addresses are generally untyped (all are of type Object. A channel instance must know what types of addresses it expects and downcast accordingly.

src - Address of sender
obj - The object will be serialized into the byte buffer. Object has to be serializable ! Note that 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,
               Address src,
               byte[] buf)
Public constructor
Parameters:
dest - Address of receiver. If it is null or a string, then it is sent to the group (either to current group or to the group as given in the string). If it is a Vector, then it contains a number of addresses to which it must be sent. Otherwise, it contains a single destination.

Addresses are generally untyped (all are of type Object. A channel instance must know what types of addresses it expects and downcast accordingly.

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.
Parameters:
dest - Address of receiver. If it is null or a string, then it is sent to the group (either to current group or to the group as given in the string). If it is a Vector, then it contains a number of addresses to which it must be sent. Otherwise, it contains a single destination.

Addresses are generally untyped (all are of type Object. A channel instance must know what types of addresses it expects and downcast accordingly.

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

Method Details

clone

protected Object clone()
            throws CloneNotSupportedException

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:

getBuffer

public byte[] getBuffer()
Returns a copy of the buffer if offset and length are used, otherwise a reference
Returns:

getDest

public Address getDest()

getHeader

public Header getHeader(String key)

getHeaders

public Map getHeaders()

getLength

public int getLength()
Returns the number of bytes in the buffer

getObject

public Object getObject()

getOffset

public int getOffset()
Returns the offset into the buffer at which the data starts

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.

getSrc

public Address getSrc()

makeReply

public Message makeReply()

printObjectHeaders

public String printObjectHeaders()

putHeader

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

readExternal

public void readExternal(ObjectInput in)
            throws IOException,
                   ClassNotFoundException

removeHeader

public Header removeHeader(String key)

removeHeaders

public void removeHeaders()

reset

public void reset()
Nulls all fields of this message so that the message can be reused. Removes all headers from the stack, but keeps the stack

setBuffer

public void setBuffer(byte[] b)

setBuffer

public 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

setDest

public void setDest(Address new_dest)

setObject

public void setObject(Serializable obj)

setSrc

public void setSrc(Address new_src)

size

public long size()
Returns size of buffer, plus some constant overhead for src and dest, plus number of headers time some estimated size/header. The latter is needed because we don't want to marshal all headers just to find out their size requirements. If a header implements Sizeable, the we can get the correct size.

Size estimations don't have to be very accurate since this is mainly used by FRAG to determine whether to fragment a message or not. Fragmentation will then serialize the message, therefore getting the correct value.


toString

public String toString()

toStringAsObject

public String toStringAsObject()
Tries to read an object from the message's buffer and prints it

writeExternal

public void writeExternal(ObjectOutput out)
            throws IOException

Copyright B) 2001,2002 www.jgroups.com . All Rights Reserved.