[JMS_SPEC-2] Fix JavaDocs to reflect missing IllegalStateException from API methods Created: 11/Apr/11  Updated: 20/Mar/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: None

Type: Bug Priority: Major
Reporter: alanf760 Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

N/A


Tags: jms21doc-minor

 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


 Comments   
Comment by Nigel Deakin [ 15/Apr/11 ]

Added formatting to description.

Comment by Nigel Deakin [ 28/Feb/12 ]

In the JMS 1.1 spec, section 4.3.5 "Closing a Connection" states that

Once a connection has been closed, an attempt to use it or its sessions or their message consumers and producers must throw an IllegalStateException (calls to the close method of these objects must be ignored).

In addition, JMS 1.1 section 4.4.1 "Closing a Session" states that

Once a session has been closed, an attempt to use it or its message consumers
and producers must throw an IllegalStateException (calls to the close method of
these objects must be ignored). It is valid to continue to use message objects
created or received via the session, with the exception of a received message’s
acknowledge method.

(The corresponding sections in the JMS 2.0 spec are 6.1.8. "Closing a connection" and 6.2.16. "Closing a session")

Furthermore, JMS 1.1 section 11.2.21 "JMS Source Java API documentation Clarifications" states:

The IllegalStateException has been noted as a required exception for several
more error conditions. they are acknowledging a message received from a
closed session; attempting to call the recover method of a transacted session;
attempting to call any method of a closed connection, session, consumer or
producer (with the exception of the close method itself);

The text about "attempting to call any method on a closed consumer or producer" causing an IllegalStateException doesn't seem to have made it into the body of the JMS 1.1 spec, and so at the time of writing there is no mention in the JMS 2.0 spec. This needs to be corrected.

In addition, the javadoc for all methods except close on a connection, session, producer or consumer should be updated to mention that an IllegalStateException may be thrown if the connection, session, consumer or producer is closed.

Comment by Nigel Deakin [ 20/Mar/13 ]

This didn't make it into JMS 2.0 and so is carried forward to JMS 2.1.

Generated at Sat Feb 13 14:12:49 UTC 2016 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.