Looks good to me.
On Wed, Feb 20, 2013 at 7:54 AM, Nigel Deakin <nigel.deakin_at_oracle.com>wrote:
> On 20/02/2013 12:13, Nigel Deakin wrote:
>
>>
>> I think what is needed is a new overview of queue and topic semantics
>> towards the beginning of the spec. I'll work on
>> some text and circulate it for comments.
>>
>
> I've now drafted this, adding new sections 4.1.2. Queue semantics and
> 4.2.2. Topic semantics. These are the first sections in the spec that
> describe how queues and topics behave. I've pasted the new sections below,
> but you may find it easier to read the pdf version from the usual place:
> http://java.net/projects/jms-**spec/sources/repository/**
> content/jms2.0/specification/**word/JMS20.pdf<http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf>
>
> (Note that I plan to include this new text in the "proposed final draft"
> that I will be submitting shortly, since leaving it out would make things
> more complicated to review. However despite the name this isn't the final
> version, so please comment in the usual way)
>
> Here are the changes I have made:
>
> QUEUES: I've added a new section 4.1.2. "Queue semantics" as follows. This
> is intended to be an introductory section which describes the basic
> semantics, and replaces both of the sections I mentioned in my previous
> email (in JMS 1.1 these were 4.4.9 "Multiple sessions" and section 5.8
> "QueueReceiver").
>
> ------------------------------**------------------------------**
> ------------------------------**---------------
> 4.1.2. Queue semantics
>
> When point-to-point messaging is being used, an application sends messages
> to a queue.
>
> An application may consume messages from the queue by creating a consumer
> (a MessageConsumer, JMSConsumer or QueueReceiver object) on that queue. A
> consumer may be used to consume messages either synchronously or
> asynchronously.
>
> A queue may have more than one consumer. Each message in the queue is
> delivered to only one consumer.
>
> A consumer may be configured to use a message selector. In this case only
> messages whose properties match the message selector will be delivered to
> the consumer. Messages which are not selected remain on the queue or are
> delivered to another consumer.
>
> The order in which an individual consumer receives messages is described
> in section 6.2.9 “Message order” below.
>
> By definition, if a consumer uses a message selector, or there are other
> consumers on the same queue, then a consumer may not receive all the
> messages on the queue. However those messages that are delivered to the
> consumer will be delivered in the order defined in section 6.2.9.
>
> Apart from the requirements of any message selectors, JMS does not define
> how messages are distributed between multiple consumers on the same queue.
> ------------------------------**------------------------------**
> ------------------------------**---------------
>
> TOPICS: As for topics, I had already spent time rewriting section 4.2.2
> "Topic subscriptions" to cover the basic semantics of topics, covering
> shared/unshared and durable/non-durable subscriptions. I have renamed this
> to 4.2.2. "Topic semantics" and added some new text to the start to match
> that added above for queues:
>
> ------------------------------**------------------------------**
> ------------------------------**---------------
>
> 4.2.2. Topic semantics
>
> When pub/sub messaging is being used, an application sends messages to a
> topic.
>
> An application consumes messages from a topic by creating a subscription
> on that topic, and creating a consumer (a MessageConsumer, JMSConsumer or
> TopicSubscriber object) on that subscription.
>
> A subscription may be thought of as an entity within the JMS provider
> itself whereas a consumer is a JMS object within the application.
>
> A subscription will receive a copy of every message that is sent to the
> topic after the subscription is created, except if a message selector is
> specified. If a message selector is specified then only those messages
> whose properties match the message selector will be added to the
> subscription.
>
> Each copy of the message is treated as a completely separate message. Work
> done on one copy has no effect on any other; acknowledging one does not
> acknowledge any other; one message may be delivered immediately, while
> another waits for its consumer to process messages ahead of it.
>
> Some subscriptions are restricted to a single consumer. In this case all
> the messages in the subscription are delivered to that consumer. Some
> subscriptions allow multiple consumers. In this case each message in the
> subscription is delivered to only one consumer. JMS does not define how
> messages are distributed between multiple consumers on the same subscription
>
> The order in which messages are delivered to a consumer is described in
> section 6.2.10 “Message order” below. By definition, if a subscription uses
> a message selector, or there are other consumers on the same
> subscription,then a consumer may not receive all the messages sent to the
> topic. However those messages that are delivered to the consumer will be
> delivered in the order defined in section 6.2.10.
>
> (the remainder of this section introduces shared/unshared and
> durable/non-durable subscriptions, and is unchanged)
>
> Nigel
>