jakartaee / jakartaee/messaging
Ambiguous javadocs for Connection.createConnectionConsumer and createDurableConnectionConsumer
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 49
- Forks
- 34
- PR merge metrics
- No merged PRs in 30d
Description
The JMS 1.1 javadocs for Connection.createConnectionConsumer lists the following possible exceptions:
JMSException - if the Connection object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.
InvalidDestinationException - if an invalid destination is specified.
InvalidSelectorException - if the message selector is invalid.
The JMS 1.1 javadocs for Connection.createDurableConnectionConsumer lists the following possible exceptions:
JMSException - if the Connection object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.
InvalidDestinationException - if an invalid destination is specified.
InvalidSelectorException - if the message selector is invalid.
So what exception is thrown if a invalid message selector is supplied? An InvalidSelectorException (since the message selector is invalid) or a JMSException (invalid argument for messageSelector).
Since a InvalidSelectorException is a subtype of JMSException then it would be safe to return a InvalidSelectorException, but the javadocs as they stand are contradictory.
Affected Versions
[1.1]
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the JMS 1.1 javadocs for Connection.createConnectionConsumer and createDurableConnectionConsumer, then compare the listed JMSException, InvalidDestinationException, and InvalidSelectorException conditions. Confirm the intended exception behavior with the relevant API contract before editing. Done means both method descriptions state the invalid-selector behavior unambiguously.
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
- Mostly clear
- Newbie friendliness
- 35/100