/*
     * Read a 32-bit integer from the stream message
     *
     * @return a 32-bit integer value from the stream message, interpreted
     * as an <code>int</code>
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if end of message stream
     * @throws MessageFormatException if this type conversion is invalid
     * @throws MessageNotReadableException if message is in write-only mode
     * @throws NumberFormatException if numeric conversion is invalid
     */
    public final int readInt() throws JMSException {
        int result = 0;
        prepare();
        try {
            result = FormatConverter.getInt(readNext());
        } catch (MessageFormatException exception) {
            revert(exception);
        } catch (NumberFormatException exception) {
            revert(exception);
        }
        return result;
    }

    /*
     * Read a 64-bit integer from the stream message
     *
     * @return a 64-bit integer value from the stream message, interpreted as
     * a <code>long</code>
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if end of message stream
     * @throws MessageFormatException if this type conversion is invalid
     * @throws MessageNotReadableException if message is in write-only mode
     * @throws NumberFormatException if numeric conversion is invalid
     */
    public final long readLong() throws JMSException {
        long result = 0;
        prepare();
        try {
            result = FormatConverter.getLong(readNext());
        } catch (MessageFormatException exception) {
            revert(exception);
        } catch (NumberFormatException exception) {
            revert(exception);
        }
        return result;
    }

    /**
     * Read a <code>float</code> from the stream message
     *
     * @return a <code>float</code> value from the stream message
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if end of message stream
     * @throws MessageFormatException if this type conversion is invalid
     * @throws MessageNotReadableException if message is in write-only mode
     * @throws NullPointerException if the value is null
     * @throws NumberFormatException if numeric conversion is invalid
     */
    public final float readFloat() throws JMSException {
        float result = 0;
        prepare();
        try {
            result = FormatConverter.getFloat(readNext());
        } catch (MessageFormatException exception) {
            revert(exception);
        } catch (NullPointerException exception) {
            revert(exception);
        } catch (NumberFormatException exception) {
            revert(exception);
        }
        return result;
    }

    /**
     * Read a <code>double</code> from the stream message
     *
     * @return a <code>double</code> value from the stream message
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if end of message stream
     * @throws MessageFormatException if this type conversion is invalid
     * @throws MessageNotReadableException if message is in write-only mode
     * @throws NullPointerException if the value is null
     * @throws NumberFormatException if numeric conversion is invalid
     */
    public final double readDouble() throws JMSException {
        double result = 0;
        prepare();
        try {
            result = FormatConverter.getDouble(readNext());
        } catch (MessageFormatException exception) {
            revert(exception);
        } catch (NullPointerException exception) {
            revert(exception);
        } catch (NumberFormatException exception) {
            revert(exception);
        }
        return result;
    }

    /**
     * Read in a string from the stream message
     *
     * @return a Unicode string from the stream message
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if end of message stream
     * @throws MessageFormatException if this type conversion is invalid
     * @throws MessageNotReadableException if message is in write-only mode
     */
    public final String readString() throws JMSException {
        String result = null;
        prepare();
        try {
            result = FormatConverter.getString(readNext());
        } catch (MessageFormatException exception) {
            revert(exception);
        }
        return result;
    }

    /**
     * Read a byte array field from the stream message into the
     * specified byte[] object (the read buffer).
     * <p>
     * To read the field value, readBytes should be successively called
     * until it returns a value less than the length of the read buffer.
     * The value of the bytes in the buffer following the last byte
     * read are undefined.
     * <p>
     * If readBytes returns a value equal to the length of the buffer, a
     * subsequent readBytes call must be made. If there are no more bytes
     * to be read this call will return -1.
     * <p>
     * If the bytes array field value is null, readBytes returns -1.
     * <p>
     * If the bytes array field value is empty, readBytes returns 0.
     * <p>
     * Once the first readBytes call on a byte[] field value has been done,
     * the full value of the field must be read before it is valid to read
     * the next field. An attempt to read the next field before that has
     * been done will throw a MessageFormatException.
     * <p>
     * To read the byte field value into a new byte[] object, use the
     * {@link #readObject} method.
     *
     * @param value the buffer into which the data is read.
     * @return the total number of bytes read into the buffer, or -1 if
     * there is no more data because the end of the byte field has been
     * reached.
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if an end of message stream
     * @throws MessageFormatException if this type conversion is invalid
     * @throws MessageNotReadableException if message is in write-only mode
     */
    public final int readBytes(byte[] value) throws JMSException {
        checkRead();
        getInputStream();
        int read = 0; // the number of bytes read
        if (_readBytes == 0) {
            // read the next byte array field
            try {
                _in.mark(_bytes.length - _in.available());
                byte type = (byte) (_in.readByte() & 0x0F);
                if (type == NULL) {
                    return -1;
                } else if (type != BYTE_ARRAY) {
                    _in.reset();
                    if (type < TYPE_NAMES.length) {
                        throw new MessageFormatException(
                            "Expected type=" + TYPE_NAMES[BYTE_ARRAY]
                            + ", but got type=" + TYPE_NAMES[type]);
                    } else {
                        throw new MessageFormatException(
                            "StreamMessage corrupted");
                    }
                }
            } catch (IOException exception) {
                raise(exception);
            }
            try {
                _byteArrayLength = _in.readInt();
            } catch (IOException exception) {
                raise(exception);
            }
        }

        if (_byteArrayLength == 0) {
            // No bytes to read. Return -1 if this is an incremental read
            // or 0 if the byte array was empty
            if (_readBytes != 0) {
                // completing an incremental read
                read = -1;
            }
            _readBytes = 0;   // indicates finished reading the byte array
        } else if (value.length <= _byteArrayLength) {
            // bytes to read >= size of target
            read = value.length;
            try {
                _in.readFully(value);
            } catch (IOException exception) {
                raise(exception);
            }
            _byteArrayLength -= value.length;
            ++_readBytes;
        } else {
            // bytes to read < size of target
            read = _byteArrayLength;
            try {
                _in.readFully(value, 0, _byteArrayLength);
            } catch (IOException exception) {
                raise(exception);
            }
            _readBytes = 0;
        }
        return read;
    }

    /**
     * Read a Java object from the stream message
     * <p>
     * Note that this method can be used to return in objectified format,
     * an object that had been written to the stream with the equivalent
     * <code>writeObject</code> method call, or it's equivalent primitive
     * write<type> method.
     * <p>
     * Note that byte values are returned as byte[], not Byte[].
     *
     * @return a Java object from the stream message, in objectified
     * format (eg. if it set as an int, then a Integer is returned).
     * @throws JMSException if JMS fails to read message due to some internal
     * JMS error
     * @throws MessageEOFException if end of message stream
     * @throws MessageNotReadableException if message is in write-only mode
     */
    public final Object readObject() throws JMSException {
        Object result = null;
        prepare();
        try {
            result = readNext();
        } catch (MessageFormatException exception) {
            revert(exception);
        }
        return result;
    }

    /**
     * Write a <code>boolean</code> to the stream message.
     * The value <code>true</code> is written out as the value
     * <code>(byte)1</code>; the value <code>false</code> is written out as
     * the value <code>(byte)0</code>.
     *
     * @param value the <code>boolean</code> value to be written.
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeBoolean(boolean value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            // encode the boolean value in the type byte
            _out.writeByte(BOOLEAN | ((value) ? 1 << 4 : 0));
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write out a <code>byte</code> to the stream message
     *
     * @param value the <code>byte</code> value to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeByte(byte value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            _out.writeByte(BYTE);
            _out.writeByte(value);
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write a <code>short</code> to the stream message
     *
     * @param value the <code>short</code> to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeShort(short value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            _out.writeByte(SHORT);
            _out.writeShort(value);
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write a <code>char</code> to the stream message
     *
     * @param value the <code>char</code> value to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeChar(char value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            _out.writeByte(CHAR);
            _out.writeChar(value);
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write an <code>int</code> to the stream message
     *
     * @param value the <code>int</code> to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeInt(int value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            _out.writeByte(INT);
            _out.writeInt(value);
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write a <code>long</code> to the stream message
     *
     * @param value the <code>long</code> to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeLong(long value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            _out.writeByte(LONG);
            _out.writeLong(value);
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write a <code>float</code> to the stream message
     *
     * @param value the <code>float</code> value to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeFloat(float value) throws JMSException {
        checkWrite();
        try {
            getOutputStream();
            _out.writeByte(FLOAT);
            _out.writeFloat(value);
        } catch (IOException exception) {
            raise(exception);
        }
    }

    /**
     * Write a <code>double</code> to the stream message
     *
     * @param value the <code>double</code> value to be written
     * @throws JMSException if JMS fails to write message due to
     * some internal JMS error
     * @throws MessageNotWriteableException if message in read-only mode
     */
    public final void writeDouble(double value) throws JMSException {
        checkWrite();
        try {