jakartaee / jakartaee/messaging

Fix JavaDocs to reflect missing IllegalStateException from API methods

Open
#2 6 comments 0 reactions 1 assignee Claimed by @nigeldeakin View on GitHub
bug jms21doc-minor Priority: Major Type: Bug
Dominant language
Java
Stars
49
Forks
34
PR merge metrics
No merged PRs in 30d

Description

**IllegalStateException tests**

The JavaDocs for the following methods below need to be updated to reflect that IllegalStateException can be thrown. In particular IllegalStateException is being thrown in the case of these methods being called on closed connection objects. There could be more methods than those listed below.

```
javax.jms.QueueSession.commit}}
javax.jms.QueueSession.getTransacted
javax.jms.QueueSession.rollback
javax.jms.QueueSession.recover
javax.jms.QueueConnection.getClientID
javax.jms.QueueConnection.getMetaDataTest
javax.jms.QueueConnection.createQueueSession
javax.jms.QueueConnection.start
javax.jms.QueueSession.createBrowser(*)
javax.jms.QueueSession.createQueue
javax.jms.QueueSession.createSender()
javax.jms.QueueSession.createTemporaryQueue()
javax.jms.QueueSession.createMessage()
javax.jms.QueueSession.createBytesMessage()
javax.jms.QueueSession.createMapMessage()
javax.jms.QueueSession.createObjectMessage(*)
javax.jms.QueueSession.createStreamMessage()
javax.jms.QueueSession.createTextMessage(*)
javax.jms.QueueSession.createStreamMessage()
javax.jms.QueueReceiver.getMessageSelector()
javax.jms.QueueReceiver.receive(*)
javax.jms.QueueReceiver.receiveTimeout()
javax.jms.QueueReceiver.receiveNoWait()
javax.jms.QueueReceiver.getQueue()
javax.jms.QueueSender.getDeliveryMode()
javax.jms.QueueSender.getDisabledMessageID()
javax.jms.QueueSender.getDisabledMessageTimeStamp()
javax.jms.QueueSender.getPriority()
javax.jms.QueueSender.getTimeToLive()
javax.jms.QueueSender.setDeliveryMode()
javax.jms.QueueSender.setDisabledMessageID()
javax.jms.QueueSender.setDisabledMessageTimeStamp()
javax.jms.QueueSender.setPriority()
javax.jms.QueueSender.setTimeToLive()
javax.jms.QueueSender.getQueue()
javax.jms.QueueSender.send(*)
javax.jms.TopicSession.commit
javax.jms.TopicSession.rollback
javax.jms.TopicSession.recover
javax.jms.TopicSession.createTopic
javax.jms.TopicSession.createSubscriber(*)
javax.jms.TopicSession.createDurableSubscriber(*)
javax.jms.TopicSession.createPublisher()
javax.jms.TopicSession.createTemporaryTopic()
javax.jms.TopicSession.unsubscribe()
javax.jms.TopicSession.createMessage
javax.jms.TopicSession.createBytesMessage
javax.jms.TopicSession.createMapMessage
javax.jms.TopicSession.createObjectMessage
javax.jms.TopicSession.createStreamMessage
javax.jms.TopicSession.createTextMessage
javax.jms.TopicSession.getTransacted
javax.jms.TopicSubscriber.getMessageSelector
javax.jms.TopicSubscriber.receive(*)
javax.jms.TopicSubscriber.receiveNoWait()
javax.jms.TopicSubscriber.getNoLocal()
javax.jms.TopicSubscriber.getTopic()
javax.jms.TopicConnection.getClientID
javax.jms.TopicConnection.getMetaDataTest
javax.jms.TopicConnection.start
javax.jms.TopicConnection.createTopicSession
javax.jms.TopicPublisher.getDeliveryMode()
javax.jms.TopicPublisher.getDisabledMessageID()
javax.jms.TopicPublisher.getDisabledMessageTimeStamp()
javax.jms.TopicPublisher.getPriority()
javax.jms.TopicPublisher.getTimeToLive()
javax.jms.TopicPublisher.setDeliveryMode()
javax.jms.TopicPublisher.setDisabledMessageID()
javax.jms.TopicPublisher.setDisabledMessageTimeStamp()
javax.jms.TopicPublisher.setPriority()
javax.jms.TopicPublisher.setTimeToLive()
javax.jms.TopicPublisher.getTopic()
javax.jms.TopicPublisher.publish(*)
```

**Tests for IllegalStateException**

The JavaDocs should be updated for all of the above method calls to specify that an IllegalStateException can be thrown on closed connection objects. Currently it doesn't. Only the JMS spec specifies that IllegalStateException must be thrown. The JavaDoc should be in sync with the spec and should mention it as well.

The JMS spec references for this is in the following sections:

* 4.3.5 Closing a Connection
* 4.4.1 Closing a Session
* 4.11 Method Inheritance across Messaging Domains
* Table 4-1 Methods That Must Throw an IllegalStateException
* 7.3 Standard Exceptions
* 11.2.21 JMS Source Java API documentation Clarifications
* Table 11-2 Domain Dependent Interfaces

The CTS JMS test directories which are testing for IllegalStateException to be thrown on closed QueueConnection, closed QueueReciever, closed QueueSender, etc. objects are listed below:

```
jms/ee/all/closedQueueConnection
jms/ee/all/closedQueueReceiver
jms/ee/all/closedQueueSender
jms/ee/all/closedQueueSession
jms/ee/all/closedTopicConnection
jms/ee/all/closedpublisher
jms/ee/all/closedsubscriber
jms/ee/all/closedtopicsessiontests
```
#### Environment
N/A
#### Affected Versions
[1.1]

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.