jgroup.util
Class OutMessage

java.lang.Object
  java.io.OutputStream
      jgroup.util.OutMessage

All Implemented Interfaces:

java.io.Closeable, java.io.DataOutput, java.io.Externalizable, java.io.Flushable, java.io.ObjectOutput, java.io.Serializable

public final class OutMessage
extends java.io.OutputStream
implements java.io.ObjectOutput, java.io.Externalizable

The OutMessage class is an output stream specially designed to be used with a transport layer which fragments messages. Messages are stored in fragments, each fragment being composed by an header, a payload and a trailer. The length of these fields may be configured when creating a new OutMessage. Data written in the message are stored in the payload field of the fragments.

Since:

Jgroup 0.8

Author:

Alberto Montresor, Hein Meling

See Also:

Serialized Form

Constructor Summary

OutMessage()
Default constructor for externalization.

OutMessage(InMessage msg)
Construct a OutMessage starting from an InMessage.

OutMessage(int payload)
Construct a message with header and trailer of length zero.

OutMessage(int payload, int header, int trailer)
This constructor builds a message output stream subdivided in fragments of length header + payload + trailer.

OutMessage(int payload, int header, int trailer, int maxsize)
This constructor builds a message output stream subdivided in fragments.

Method Summary

void	clear(int newmaxsize) Clear and reset the OutMessage to the given new maxsize.
int	computeChecksum() Compute the checksum of the bytes stored in the message
int	getByteCount() Returns the total number of bytes stored in this message.
int	getFragmentCount() Returns the number of fragments composing the message.
byte[][]	getFragments() Returns an array of byte arrays which contains the fragments composing the message.
int	getHeader() Return the length of the header for this message.
int	getLastPayload() Returns the length of the payload of the last fragment composing the message.
int	getPayload() Return the length of the payload for this message.
int	getPosition() Return the current position in this message.
int	getTrailer() Return the length of the trailer for this message.
void	readExternal(java.io.ObjectInput in) Restores the content of this object from the marshalled data contained in the specified input stream.
void	reset() Reset the byte array
void	seek(int position) Move the current position in the stream to the specified position.
int	size() Returns the current value of the counter written, the number of bytes written to this data output stream so far.
byte[]	toByteArray() Converts the whole OutMessage into a byte array.
java.lang.String	toString() Returns a string representation of this object
java.lang.String	toString(boolean all) Returns a string representation of this object (used only for debugging)
void	write(byte[] b) Writes b.length bytes from the specified byte array to this output stream.
void	write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to this msg output stream.
void	write(int b) Writes the specified byte to this byte array output stream.
void	write(OutMessage msg) Write the content of another OutMessage into the current message.
void	write2(int v) Write a short integer value v into the stream at the current position.
void	write4(int v) Write an integer value v into the stream at the current position.
void	write8(long v) Write a long value v into the stream at the current position.
void	writeBoolean(boolean v) Writes a boolean value to this output stream.
void	writeByte(int v) Writes to the output stream the eight low- order bits of the argument v.
void	writeBytes(java.lang.String s) Writes a string to the output stream.
void	writeChar(int v) Writes a char value, wich is comprised of two bytes, to the output stream.
void	writeChars(java.lang.String s) Writes every character in the string s, to the output stream, in order, two bytes per character.
void	writeDouble(double v) Writes a double value, which is comprised of eight bytes, to the output stream.
void	writeExternal(java.io.ObjectOutput out) Marshals the content of this object to the specified output stream.
void	writeFloat(float v) Writes a float value, which is comprised of four bytes, to the output stream.
void	writeInt(int v) Writes an int value, which is comprised of four bytes, to the output stream.
void	writeLong(long v) Writes an long value, which is comprised of four bytes, to the output stream.
void	writeObject(java.lang.Object obj) Write an object to the underlying storage or stream.
void	writeShort(int v) Writes two bytes to the output stream to represent the value of the argument.
void	writeUTF(java.lang.String str) Writes two bytes of length information to the output stream, followed by the Java modified UTF representation of every character in the string s.

Methods inherited from class java.io.OutputStream

close, flush

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.io.ObjectOutput

close, flush

Constructor Detail

OutMessage

public OutMessage(int payload)

Construct a message with header and trailer of length zero. In this way, OutMessage may be used as a more efficient version of ByteArrayOutputStream.

OutMessage

public OutMessage(InMessage msg)

Construct a OutMessage starting from an InMessage. In this way, it possible to forward messages received from other servers without copying them.

OutMessage

public OutMessage(int payload,
                  int header,
                  int trailer)

This constructor builds a message output stream subdivided in fragments of length header + payload + trailer. Used for messages whose size is initially unknown.

Throws:

java.lang.IndexOutOfBoundsException - Raised if payload is negative or equal to zero; header is negative; trailer is negative.

OutMessage

public OutMessage(int payload,
                  int header,
                  int trailer,
                  int maxsize)

This constructor builds a message output stream subdivided in fragments. Used for messages whose size is known a priori. If maxsize is less than payload, the payload of the message is set to maxsize. The total length of each fragments is header + payload + trailer.

Throws:

java.lang.IndexOutOfBoundsException - Raised if payload is negative or equal to zero; header is negative; trailer is negative; maxsize is negative or equal to zero.

OutMessage

public OutMessage()

Default constructor for externalization.

Method Detail

clear

public void clear(int newmaxsize)

Clear and reset the OutMessage to the given new maxsize. This occurs by reusing the already allocated memory for the fragments of this OutMessage.

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException

Restores the content of this object from the marshalled data contained in the specified input stream.

Specified by:

readExternal in interface java.io.Externalizable

Parameters:

in - the stream to be read

Throws:

java.io.IOException

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

Marshals the content of this object to the specified output stream.

Specified by:

writeExternal in interface java.io.Externalizable

Parameters:

out - the stream to be written

Throws:

java.io.IOException

write

public void write(int b)

Writes the specified byte to this byte array output stream.

If the total number of bytes written in the message exceeds the maximum length, a ArrayIndexOutOfBoundsException is thrown.

Specified by:

write in interface java.io.DataOutput

Specified by:

write in interface java.io.ObjectOutput

Specified by:

write in class java.io.OutputStream

Parameters:

b - the byte to be written.

write

public void write(byte[] b,
                  int off,
                  int len)

Writes len bytes from the specified byte array starting at offset off to this msg output stream.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

If the total number of bytes written in the message exceeds the maximum length, a ArrayIndexOutOfBoundsException is thrown.

Specified by:

write in interface java.io.DataOutput

Specified by:

write in interface java.io.ObjectOutput

Overrides:

write in class java.io.OutputStream

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

write

public void write(byte[] b)

Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).

If the total number of bytes written in the message exceeds the maximum length, a ArrayIndexOutOfBoundsException is thrown.

Specified by:

write in interface java.io.DataOutput

Specified by:

write in interface java.io.ObjectOutput

Overrides:

write in class java.io.OutputStream

Parameters:

b - the data.

writeBoolean

public void writeBoolean(boolean v)
                  throws java.io.IOException

Writes a boolean value to this output stream. If the argument v is true, the value (byte)1 is written; if v is false, the value (byte)0 is written. The byte written by this method may be read by the readBoolean method of interface DataInput, which will then return a boolean equal to v.

Specified by:

writeBoolean in interface java.io.DataOutput

Parameters:

v - the boolean to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeByte

public void writeByte(int v)
               throws java.io.IOException

Writes to the output stream the eight low- order bits of the argument v. The 24 high-order bits of v are ignored. (This means that writeByte does exactly the same thing as write for an integer argument.) The byte written by this method may be read by the readByte method of interface DataInput, which will then return a byte equal to (byte)v.

Specified by:

writeByte in interface java.io.DataOutput

Parameters:

v - the byte value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeShort

public void writeShort(int v)
                throws java.io.IOException

Writes two bytes to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are:

 (byte)(0xff & (v >> 8))
 (byte)(0xff & v)
  

The bytes written by this method may be read by the readShort method of interface DataInput , which will then return a short equal to (short)v.

Specified by:

writeShort in interface java.io.DataOutput

Parameters:

v - the short value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeChar

public void writeChar(int v)
               throws java.io.IOException

Writes a char value, wich is comprised of two bytes, to the output stream. The byte values to be written, in the order shown, are:

 (byte)(0xff & (v >> 8))
 (byte)(0xff & v)
 

The bytes written by this method may be read by the readChar method of interface DataInput , which will then return a char equal to (char)v.

Specified by:

writeChar in interface java.io.DataOutput

Parameters:

v - the char value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeInt

public void writeInt(int v)
              throws java.io.IOException

Writes an int value, which is comprised of four bytes, to the output stream. The byte values to be written, in the order shown, are:

 (byte)(0xff & (v >> 24))
 (byte)(0xff & (v >> 16))
 (byte)(0xff & (v >>    8))
 (byte)(0xff & v)
 

The bytes written by this method may be read by the readInt method of interface DataInput , which will then return an int equal to v.

Specified by:

writeInt in interface java.io.DataOutput

Parameters:

v - the int value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeLong

public void writeLong(long v)
               throws java.io.IOException

Writes an long value, which is comprised of four bytes, to the output stream. The byte values to be written, in the order shown, are:

 (byte)(0xff & (v >> 48))
 (byte)(0xff & (v >> 40))
 (byte)(0xff & (v >> 32))
 (byte)(0xff & (v >> 24))
 (byte)(0xff & (v >> 16))
 (byte)(0xff & (v >>  8))
 (byte)(0xff & v)
 

The bytes written by this method may be read by the readLong method of interface DataInput , which will then return a long equal to v.

Specified by:

writeLong in interface java.io.DataOutput

Parameters:

v - the long value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeFloat

public void writeFloat(float v)
                throws java.io.IOException

Writes a float value, which is comprised of four bytes, to the output stream. It does this as if it first converts this float value to an int in exactly the manner of the Float.floatToIntBits method and then writes the int value in exactly the manner of the writeInt method. The bytes written by this method may be read by the readFloat method of interface DataInput, which will then return a float equal to v.

Specified by:

writeFloat in interface java.io.DataOutput

Parameters:

v - the float value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeDouble

public void writeDouble(double v)
                 throws java.io.IOException

Writes a double value, which is comprised of eight bytes, to the output stream. It does this as if it first converts this double value to a long in exactly the manner of the Double.doubleToLongBits method and then writes the long value in exactly the manner of the writeLong method. The bytes written by this method may be read by the readDouble method of interface DataInput, which will then return a double equal to v.

Specified by:

writeDouble in interface java.io.DataOutput

Parameters:

v - the double value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeBytes

public void writeBytes(java.lang.String s)
                throws java.io.IOException

Writes a string to the output stream. For every character in the string s, taken in order, one byte is written to the output stream. If s is null, a NullPointerException is thrown.

If s.length is zero, then no bytes are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, one byte is written, the low-order byte, in exactly the manner of the writeByte method . The high-order eight bits of each character in the string are ignored.

Specified by:

writeBytes in interface java.io.DataOutput

Parameters:

s - the string of bytes to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeChars

public void writeChars(java.lang.String s)
                throws java.io.IOException

Writes every character in the string s, to the output stream, in order, two bytes per character. If s is null, a NullPointerException is thrown. If s.length is zero, then no characters are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, two bytes are actually written, high-order byte first, in exactly the manner of the writeChar method.

Specified by:

writeChars in interface java.io.DataOutput

Parameters:

s - the string value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

writeUTF

public void writeUTF(java.lang.String str)
              throws java.io.IOException

Writes two bytes of length information to the output stream, followed by the Java modified UTF representation of every character in the string s. If s is null, a NullPointerException is thrown. Each character in the string s is converted to a group of one, two, or three bytes, depending on the value of the character.

If a character c is in the range \u0001 through \u007f, it is represented by one byte:

(byte)c 

If a character c is \u0000 or is in the range \u0080 through \u07ff, then it is represented by two bytes, to be written in the order shown:

 (byte)(0xc0 | (0x1f & (c >> 6)))
 (byte)(0x80 | (0x3f & c))
  

If a character c is in the range \u0800 through uffff, then it is represented by three bytes, to be written in the order shown:

 (byte)(0xc0 | (0x0f & (c >> 12)))
 (byte)(0x80 | (0x3f & (c >>  6)))
 (byte)(0x80 | (0x3f & c))
  

First, the total number of bytes needed to represent all the characters of s is calculated. If this number is larger than 65535, then a UTFDataFormatError is thrown. Otherwise, this length is written to the output stream in exactly the manner of the writeShort method; after this, the one-, two-, or three-byte representation of each character in the string s is written.

The bytes written by this method may be read by the readUTF method of interface DataInput , which will then return a String equal to s.

Specified by:

writeUTF in interface java.io.DataOutput

Parameters:

str - the string value to be written.

Throws:

java.io.IOException - if an I/O error occurs.

size

public final int size()

Returns the current value of the counter written, the number of bytes written to this data output stream so far. Note: in this version, the counter may overflow.

Returns:

the value of the written field.

See Also:

DataOutputStream.written

writeObject

public void writeObject(java.lang.Object obj)
                 throws java.io.IOException

Write an object to the underlying storage or stream. The class that implements this interface defines how the object is written.

Specified by:

writeObject in interface java.io.ObjectOutput

Throws:

java.io.IOException - Any of the usual Input/Output related exceptions.

seek

public void seek(int position)

Move the current position in the stream to the specified position.

Throws:

java.lang.IndexOutOfBoundsException - Raised if the new position in the message exceeds the maximum length.

write2

public void write2(int v)

Write a short integer value v into the stream at the current position.

Throws:

java.lang.ArrayIndexOutOfBoundsException - Raised if the total number of bytes written in the message exceeds the maximum length.

write4

public void write4(int v)

Write an integer value v into the stream at the current position.

Throws:

java.lang.ArrayIndexOutOfBoundsException - Raised if the total number of bytes written in the message exceeds the maximum length.

write8

public void write8(long v)

Write a long value v into the stream at the current position.

Throws:

java.lang.ArrayIndexOutOfBoundsException - Raised if the total number of bytes written in the message exceeds the maximum length.

write

public void write(OutMessage msg)

Write the content of another OutMessage into the current message.

Throws:

java.lang.ArrayIndexOutOfBoundsException - Raised if the total number of bytes written in the message exceeds the maximum length.

reset

public void reset()

Reset the byte array

computeChecksum

public int computeChecksum()

Compute the checksum of the bytes stored in the message

Returns:

the computed checksum.

getPosition

public int getPosition()

Return the current position in this message.

getPayload

public int getPayload()

Return the length of the payload for this message.

getHeader

public int getHeader()

Return the length of the header for this message.

getTrailer

public int getTrailer()

Return the length of the trailer for this message.

getByteCount

public int getByteCount()

Returns the total number of bytes stored in this message.

getFragmentCount

public int getFragmentCount()

Returns the number of fragments composing the message.

getLastPayload

public int getLastPayload()

Returns the length of the payload of the last fragment composing the message.

getFragments

public byte[][] getFragments()

Returns an array of byte arrays which contains the fragments composing the message. The length of fragment array may be greater than the number of fragments actually allocated; the actual number of fragments is obtained by invoking method getFragmentCount.

toByteArray

public byte[] toByteArray()

Converts the whole OutMessage into a byte array.

toString

public java.lang.String toString(boolean all)

Returns a string representation of this object (used only for debugging)

toString

public java.lang.String toString()

Returns a string representation of this object

Overrides:

toString in class java.lang.Object