The whole proposal looks very good to me! You should consider the lack of comments as support from the silent majority ;-)
On 2012-01-17, at 10:42, Nigel Deakin wrote:
> 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
>
>
>