org.jgroups
Class Message

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

Author:
Bela Ban
See Also:
Serialized Form

Field Summary
protected  Address dest_addr
           
protected  java.util.Map headers
          Map
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
           
protected  int offset
          The index into the payload (usually 0)
protected  Address src_addr
           
 
Constructor Summary
Message()
           
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.io.Serializable obj)
          Public constructor
Message(boolean create_headers)
           
 
Method Summary
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()
           
 Header getHeader(java.lang.String key)
           
 java.util.Map getHeaders()
           
 int getLength()
          Returns the number of bytes in the buffer
 java.lang.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()
           
 java.lang.String printObjectHeaders()
           
 void putHeader(java.lang.String key, Header hdr)
          Puts a header given a key into the hashmap.
 void 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 closed
 Header removeHeader(java.lang.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(java.io.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.
 java.lang.String toString()
           
 java.lang.String toStringAsObject()
          Tries to read an object from the message's buffer and prints it
 void 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.
 
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 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 java.util.Map headers
Map


log

protected static final org.apache.commons.logging.Log log
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,
               java.io.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

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

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

setObject

public void setObject(java.io.Serializable obj)

getObject

public java.lang.Object getObject()

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


putHeader

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


removeHeader

public Header removeHeader(java.lang.String key)

removeHeaders

public void removeHeaders()

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


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.


printObjectHeaders

public java.lang.String printObjectHeaders()

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Specified by:
writeExternal in interface java.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 interface java.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 interface Streamable
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 interface Streamable
Throws:
java.io.IOException
java.lang.IllegalAccessException
java.lang.InstantiationException


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