org.jgroups

Class Message

public class Message extends Object implements 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.

Author: Bela Ban

Field Summary
protected Addressdest_addr
protected Mapheaders
Map
protected intlength
The number of bytes in the buffer (usually buf.length is buf not equal to null).
protected static Loglog
protected intoffset
The index into the payload (usually 0)
protected Addresssrc_addr
Constructor Summary
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, Serializable obj)
Public constructor
Message()
Message(boolean create_headers)
Method Summary
protected Objectclone()
Messagecopy()
Messagecopy(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.
AddressgetDest()
HeadergetHeader(String key)
MapgetHeaders()
intgetLength()
Returns the number of bytes in the buffer
ObjectgetObject()
intgetOffset()
Returns the offset into the buffer at which the data starts
byte[]getRawBuffer()
Returns a reference to the payload (byte buffer).
AddressgetSrc()
MessagemakeReply()
StringprintObjectHeaders()
voidputHeader(String key, Header hdr)
Puts a header given a key into the hashmap.
voidreadExternal(ObjectInput in)
voidreadFrom(DataInputStream in)
HeaderremoveHeader(String key)
voidremoveHeaders()
voidreset()
Nulls all fields of this message so that the message can be reused.
voidsetBuffer(byte[] b)
voidsetBuffer(byte[] b, int offset, int length)
Set the internal buffer to point to a subset of a given buffer
voidsetDest(Address new_dest)
voidsetObject(Serializable obj)
voidsetSrc(Address new_src)
longsize()
Returns size of buffer, plus some constant overhead for src and dest, plus number of headers time some estimated size/header.
StringtoString()
StringtoStringAsObject()
Tries to read an object from the message's buffer and prints it
voidwriteExternal(ObjectOutput out)
voidwriteTo(DataOutputStream out)
Streams all members (dest and src addresses, buffer and headers) to the output stream.

Field Detail

dest_addr

protected Address dest_addr

headers

protected Map headers
Map

length

protected transient int length
The number of bytes in the buffer (usually buf.length is buf not equal to null).

log

protected static final Log log

offset

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

src_addr

protected Address src_addr

Constructor Detail

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

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

Message

public Message(boolean create_headers)

Method Detail

clone

protected Object clone()

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

getBuffer

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

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)

readFrom

public void readFrom(DataInputStream in)

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 hashmap, but keeps the hashmap

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)

writeTo

public void writeTo(DataOutputStream out)
Streams all members (dest and src addresses, buffer and headers) to the output stream.

Parameters: out

Throws: IOException

Copyright ? 1998-2005 Bela Ban. All Rights Reserved.