jakartaee / jakartaee/messaging

Ambiguous javadocs for Connection.createConnectionConsumer and createDurableConnectionConsumer

Open
#75 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

jms21doc-minor Priority: Major Type: Improvement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.