O'Reilly - Java Message Service

3.4.7 Read-Only Messages
Java Message Service
When messages are delivered, the body of the message is made read-only. Any attempt to
alter a message body after it has been delivered results in a
javax.jms.MessageNotWriteableException. The only way to change the body of a message
after it has been delivered is to invoke the clearBody( ) method, which is defined in the
Message interface. The clearBody( ) method empties the message's payload so that a new
payload can be added.
Properties are also read-only after a message is delivered. Why are both the body and
properties made read-only after delivery? It allows the JMS provider more flexibility in
implementing the Message object. For example, a JMS provider may choose to stream a
BytesMessage or StreamMessage as it is read, rather than all at once. Another vendor may
choose to keep properties or body data in an internal buffer so that it can be read directly
without the need to make a copy, which is especially useful with multiple consumers on
the same client.
3.4.8 Client-Acknowledged Messages
The acknowledge( ) method, defined in the Message interface, is used when the consumer
has chosen CLIENT_ACKNOWLEDGE as its acknowledgment mode. There are three
acknowledgment modes that may be set by the JMS consumer when its session is created:
AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, and CLIENT_ACKNOWLEDGE. Here is how a pub/sub
consumer sets one of the three acknowledgment modes:
TopicSession topic =
topicConnection.createTopicSession(false, Session.CLIENT_ACKNOWLEDGE);
In CLIENT_ACKNOWLEDGE mode, the JMS client explicitly acknowledges each message as it is
received. The acknowledge( ) method on the Message interface is used for this purpose. For
example:
public void onMessage(Message message){
message.acknowledge( );
...
}
The other acknowledgment modes do not require the use of this method and are covered in
more detail in Chapter 6 and Appendix B.
Any acknowledgment mode specified for a transacted session is
ignored. When a session is transacted, the acknowledgment is part of
the transaction and is executed automatically prior to the commit of
the transaction. If the transaction is rolled back, no acknowledgment
is given. Transactions are covered in more detail in Chapter 6.
51