I've made a number of small modifications to the proposed simplified API in response to the comments that I forwarded
earlier.
On 12/12/2011 15:46, Nigel Deakin wrote:
> On 08/12/2011 14:51, Nigel Deakin wrote:
>>
>> As you know we've had quite a few discussions on this already, and as promised I've written up a proposal. This is
>> described in a pdf document at:
>> http://java.net/downloads/jms-spec/Simplified%20API/JMS20SimplifiedAPIv1.pdf
>> with a corresponding set of javadocs at:
>> java.net/projects/jms-spec/downloads/download/Simplified%20API/jms-2.0-javadoc.jar
>>
>> Please take a look and make comments.
>>
>> Comments are welcome on anything I've written, but I should say from the outset that some aspects of the proposals are
>> further advanced than others. In particular I haven't suggested how we might exploit the new API using CDI. I hope that
>> the proposed API makes this easier to achieve but I hope to have a discussion about what we might do.
>>
>> The proposals also suggest a simple API for sending and receiving message payloads directly but I think this needs some
>> more work.
>
> A colleague sent me some comments I've paraphrased as follows, and added my own responses afterwards:
>
> 1. Comment: If a client uses the SyncMessageConsumer.receivePayload() methods to consume a message payload directly,
> they can't perform client acknowledgement because they don't have a Message object on which to call acknowledge().
> How about adding a new method MessagingContext.acknowledge() to allow this? Since calling Message.acknowledge()
> actually acknowledges all messages delivered by the Session this makes more sense anyway.
>
> Nigel responds: Very good point, and I agree with the suggestion.
I've now made this change to the proposed simplified API (the interfaces and the javadocs).
There's now a new method MessagingContext.acknowledge()
> We could also add Session.acknowledge() as well.
> ideally we should remove Message.acknowledge() but we can't because we need to maintain backwards compatibility.
I've logged this as
http://java.net/jira/browse/JMS_SPEC-68, since we might want to do that anyway.
> 2. Comment: If you're going to start automatically the connection used by a MessagingContext as soon as
> setMessageListener is called (as stated on p4) then calling setMessageListener a second time, perhaps for a second
> destination, will break the threading restrictions on a Session. The client will need to call MessagingContext.stop(),
> call MessagingContext.setMessageListener and then call MessagingContext.start().
>
> Nigel responds: Good point. I suggest we expressly state that this is allowed. The implementation may either temporarily
> stop the connection or it could implement it in a safe way. We should look out for other cases like this.
Yes, the JMS 1.1 spec, section 4.4.6 "Conventions for using a session" explicitly mentions this issue. It says
"...a connection must be in stopped mode to set up a session with more than one message listener. The reason is that
when a connection is actively delivering messages, once the first message listener for a session has been registered,
the session is now controlled by the thread of control that delivers messages to it. At this point a client thread of
control cannot be used to further configure the session."
This suggests that we have three options:
1. Abandon the idea of starting a connection automatically
2. Start a connection automatically by default but allow the application to disable this feature
3. Explicitly waive the threading restrictions when certain methods on MessagingContext such as setMessageListener are
called, and leave it to the JMS provider to decide how to implement it.
My preference is for (3), and I have amended the proposals document to state this (I haven't modified the spec document
yet).
>
> 3. Comment: For Java SE applications which need to create two MessagingContext objects on the same underlying
> Connection, instead of providing methods like Connection.createMessagingContext(), how about providing a new method
> MessagingContext.createMessagingContext(sessionMode) which creates a second MessagingContext using the same Connection
> as the first MessagingContext? This would remove the need for such applications to use Connection objects at all.
>
> Nigel responds: I think this is an excellent idea.
I've now made this change to the proposed simplified API (the interfaces, the javadocs and the proposals document, The
change is simple: I've removed Connection.createMessagingContext(sessionMode) and added a new method
MessagingContext.createMessagingContext(sessionMode).
I think the result is similar to a suggestion that Clebert made some time ago.
I've also updated the example "Receiving a message in multiple threads (Java SE)" in the proposals document which now
looks even simpler as a result of this change.
>
> 4. Comment: On P23 you observed that "If you simply want to create a durable subscriber, but not actually consume
> messages from it, you now need to call createSyncDurableSubscriber, even if you intend to use async consumption in the
> future (previously you just called createDurableSubscription). This works but the method name is confusing when used for
> this purpose rather than to start sync consumption. Perhaps we need a void createDurableSubscription(…) method?"
>
> How about calling it simply subscribe(...), for consistency with unsubscribe(...)?
I've now added a new method subscribe() to MessagingContext which creates a durable subscription but does not create a
consumer on it.
For all these changes, I've updated the javadocs and the proposals document. I still haven't attempted to say anything
about the simplified API in the spec itself.
The updated javadocs are in the usual place:
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/target/jms-2.0-javadoc.jar
I have also produced a new version of the spmplified API proposals document. This is version 2:
http://java.net/downloads/jms-spec/Simplified%20API/JMS20SimplifiedAPIv2.pdf
There are change bars and a change log at the bottom.
This is all the changes to the simplified API we have at the moment. The next step is to propose how applications can
make use of CDI to inject MessagingContext objects.
Nigel