jakartaee / jakartaee/messaging
Add guidance on when to use receiveBody and how to handle MessageFormatRuntimeException
- Dominant language
- Java
- Stars
- 49
- Forks
- 34
- PR merge metrics
- No merged PRs in 30d
Description
The JMSConsumer methods receiveBody(Class c), receiveBody(Class c, long timeout) and receiveBodyNoWait(Class c) are intended to be used when the application knows in advance that the type of the next message will be, or if all messages on the queue or topic are of the same type.
If the application calls these methods with an inappropriate class then a MessageFormatRuntimeException will be thrown. The specification defines what must happen next with the message; the required behaviour depends on the session mode but in all cases is designed to give the application a further opportunity to receive the message, either by calling receiveBody with a different class, or by calling the normal receive method.
It may be helpful if the documentation for these methods included some recommendations on when to use them, and how to handle a MessageFormatRuntimeException.
The documentation could state that these methods are intended to be used only when the application knows in advance that the type of the next message will be, or if all messages on the queue or topic are of the same type.
The documentation could also state that if a MessageFormatRuntimeException is thrown then since the application, by definition, does not know what the type of the message is, it is probably best to receive the message a second time using the normal receive method, which does not require the type of the next message to be known.
(Note that prior to calling receive, if the session mode is CLIENT_ACKNOWLEDGE then the application will need to call recover, and if the session mode is transacted then the application will need to rollback the transaction and start a new one. If the session mode is AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE then the application can simply call receive immediately.)
#### Affected Versions
[2.0]
Contributor guide
Research direction
Start by locating the JMSConsumer API documentation for receiveBody(Class), its timeout and no-wait variants, and compare the existing guidance with this issue. Update the documentation to explain when these methods are appropriate, how to respond to MessageFormatRuntimeException, and the required recovery steps for each session mode; done means all three methods describe this behavior consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100