I know I promised that I had finished adding new issues to the JMS 2.0 errata, whilst I was drafting the new text for
JMS_SPEC-158 I came across what looks like a clear error in the javadocs for Connection#stop and JMSContext#stop.
I've logged this as JMS_SPEC-165: Error in javadoc for Connection#stop and JMSContext#stop
https://java.net/jira/browse/JMS_SPEC-165
Although nobody has reported this before, I think we should fix this now because we need to reword these javadocs for
JMS_SPEC-158. Although the two issues are unrelated, it's difficult to rewording it for the first issue without feeling
obligated to fix it for the other. I also think we can fix this simply by deleting one sentence from the javadocs.
Here's the issue and the proposed corrections. Do you agree?
The issue
---------
The JMS 1.1 javadocs for Connection#stop contains the following text:
This call blocks until receives and/or message listeners
in progress have completed.
Exactly the same text is found in the JMS 2.0 javadocs for Connection#stop and for JMSContext#stop.
This text is incorrect because it suggests that the call to stop is required to block until all calls to receive have
returned. There is no mention of this requirement in the specification itself and it is contradicted by the text that
follows it in the javadocs for Connection#stop:
A call to stop must not return until delivery of messages has paused.
This means that a client can rely on the fact that none of its message
listeners will be called and that all threads of control waiting for
receive calls to return will not return with a message until the
connection is restarted. The receive timers for a stopped connection
continue to advance, so receives may time out while the connection is stopped.
I think this means that:
* a call to stop does not force all pending receives to return prematurely.
* a call to stop is not required to block until all pending receives reach their timeout period (especially as that
might be infinite)
* after the call to stop has returned, pending receives will continue to block until they either (1) reach their timeout
and return null or (2) the connection is restarted and a message becomes available, whichever occurs first.
It is suggested that, to keep things simple, we don't try to completely rewrite this but simply delete the incorrect
sentence. Note that the requirement to block until message listeners have returned is already covered by the sentence:
If message listeners are running when stop is invoked, the stop call must
wait until all of them have returned before it may return. While these
message listeners are completing, they must have the full services of the
connection available to them.
Proposed changes
----------------
Proposed change to Javadocs for Connection#stop
Existing text:
This call blocks until receives and/or message listeners
in progress have completed.
Proposed text:
[Delete this text]
Proposed change to Javadocs for JMSContext#stop
Existing text:
This call blocks until receives and/or message listeners
in progress have completed.
Proposed text:
[Delete this text]