I've now updated the draft spec and API docs with the changes proposed in my previous email on this thread. Here are
the updated sections (all part of section 4.6.2. "Asynchronous send"):
4.6.2.1. Quality of service
After the send operation has completed successfully, which means that the message has been successfully sent with the
same degree of confidence as if a normal synchronous send had been performed, the JMS provider must invoke the
CompletionListener's onCompletion method.The CompletionListener must not be invoked earlier than this.
4.6.2.2. Exceptions
If an exception is encountered during the call to the send method then an appropriate exception should be thrown in the
thread that is calling the send method. In this case the JMS provider must not invoke the CompletionListener's
onCompletion or onException method.
If an exception is encountered which cannot be thrown in the thread that is calling the send method then the JMS
provider must call the CompletionListener's onException method.
In both cases if an exception occurs it is undefined whether or not the message was successfully sent.
4.6.2.4. Close, commit or rollback
If the close method is called on the MessageProducer, Session, Connection or JMSContext object then the JMS provider
must block until any incomplete send operations have been completed and all CompletionListener callbacks have returned
before closing the object and returning.
If the session is transacted (uses a local transaction) then when the commit or rollback method is called the JMS
provider must block until any incomplete send operations have been completed and all CompletionListener callbacks have
returned before performing the commit or rollback.
Incomplete sends should be allowed to complete normally unless an error occurs.
A CompletionListener callback method must not call close on its own JMSContext, Connection, Session or MessageProducer
or call commit or rollback on its own JMSContext or Session. Doing so will cause the close, commit or rollback to throw
an IllegalStateException or IllegalStateRuntimeException (depending on the method signature).
4.6.2.8. Use of the CompletionListener by the JMS provider
A session will only invoke one CompletionListener callback method at a time. For a given MessageProducer or JMSContext,
callbacks (both onCompletion and onException) will be performed in the same order as the corresponding calls to the
asynchronous send method.
A JMS provider must not invoke the CompletionListener from the thread that is calling the asynchronous send method.
I've also updated the API docs for
* JMSProducer.setAsync
* the four Session.send methods which perform an async send
* Connection.close
* Session.close
* MessageProducer.close
* JMSContext.close
I hope async send is now complete for now!
Links to the latest draft specification and API docs can be found here:
http://java.net/projects/jms-spec/pages/Home#Latest_draft_specification_and_javadocs
Nigel