Hi Nigel,
Your proposed changes seem reasonable to me.
Chris
On 1/8/2015 6:31 AM, Nigel Deakin wrote:
> 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]
>
>
>