[JMS_SPEC-26] Decide on the future of the optional Chapter 8 API "JMS Application Server Facilities" Created: 06/Jul/11  Updated: 24/Feb/12

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Critical
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: eg, pd20-underreview

 Description   

Chapter 8 of the JMS 1.1 specification, "JMS Application Server Facilities", defines an API for use by application servers. It has two parts:

  • API to allow concurrent processing of a subscription's messages: the interfaces ServerSession, ServerSessionPool, ConnectionConsumer and the methods Session.setMessageListener(), Session.getMessageListener() and Session.run().
  • API to support distributed (XA) transactions: XAConnectionFactory, XAConnection and XASession.

This API is optional and has no compliance tests.

Should this API be made mandatory, like the rest of the JMS spec, or should it be formally pruned from the spec?

This will partly depend on the outcome of http://java.net/jira/browse/JMS_SPEC-25 (Standardise the interface between a JMS provider and a Java EE application server). If it is decided that the interface between a JMS provider and a Java EE application server should use these interfaces (rather than the Java EE Connector API) then clearly they should become mandatory.

However, irrespective of the outcome of http://java.net/jira/browse/JMS_SPEC-25 it may be beneficial to keep this API and make it mandatory since that would

1. allow the creation of a generic JMS resource adapter that can work with any JMS 2.0 implementation, and
2. allow the creation of non-Java EE frameworks that provide services such as XA transactions and async delivery to multiple consumers, but which don't support the Java EE Connector Architecture

However these potential benefits need to be offset against the additional burden this may place on JMS vendors.

Note that if it is decided that these interfaces are not needed, they would not be deleted from the spec but remain in their current optional state, in accordance with chapter EE.6.1.3 "Pruned Java Technologies" of the Java EE 6 specification, perhaps with an explicit statement of why they are not needed.

If it is decided that these interfaces are still required then there some improvements may be required to clarify, say, the integration with the transaction manager.



 Comments   
Comment by Nigel Deakin [ 26/Jan/12 ]

It would be worth updating the Javadoc for the optional Chapter 8 API to explain that these classes and methods are primarily intended for use by application servers. This is obvious to anyone reading the spec, but for some reason isn't spelled out in the javadoc for methods like Session.setMessageListener().

Comment by Nigel Deakin [ 16/Feb/12 ]

I asked a colleague for their comments on the Chapter 8 API, and they replied as follows:

The getXAResource call has proved relatively robust for directly integrating foreign providers like Tibco, Sonic, and IBM MQ.

I think the main issue I have with it is the multi-RM problem: correctly fronting a logical RM that's actually backed by an independent set of RMs. In particular the problem is that we must currently somehow return the entire set of in-doubt transactions for all RMs in an entire cluster when "XAResource recover()" is called, even for component RMs that may not be running. We've all already discussed this at length. Currently, each provider must come up with some sort of internal solution on its own - but this isn't easy. Advancing one or all of the JTA, JCA, or JMS specs would help...

Another relatively smaller problem is that it would help to know when a vendor has thread-affinity requirements for a transaction life-cycle on the XAResource (IBM MQ). Or, alternatively, to harden the spec so that it's illegal to require thread affinity by default. It's a bit painful for a container to enforce such a requirement.

A secondary issue is the ConnectionConsumer API. It is complex and it's not entirely clear how it's supposed integrate with a foreign TM, and we've found no strong need to make use of it when integrating foreign providers.





[JMS_SPEC-25] Standardise the interface between a JMS provider and a Java EE application server Created: 06/Jul/11  Updated: 07/Feb/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: None

Type: Improvement Priority: Critical
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: jms21-forreview-major

 Description   

We need to standardise the interface between a JMS provider and a Java EE application server, to allow portability of JMS providers between application servers.

The frontrunner here is to mandate the provision of a JCA resource adapter, though an alternative may be to extend and make mandatory the existing Chapter 8 API.



 Comments   
Comment by John D. Ament [ 06/Jul/11 ]

If we setup CDI integration, +1 maybe to standardize on the CDI extension approach?

Comment by Nigel Deakin [ 21/Jul/11 ]

Following discussions in the expert group mailing list the expert group has agreed in principle to make it mandatory for a JMS vendor to provide a JCA resource adapter to allow their JMS client to be used from any Java EE application server.

Comment by Nigel Deakin [ 07/Feb/13 ]

Following a further discussion , the JSR 343 expert group has changed its view and decided that it should not be mandatory for a JMS vendor to provide a JCA resource adapter.

Comment by Nigel Deakin [ 07/Feb/13 ]

Given that the EG has rejected making it mandatory to provide a resource adapter, should it be mandatory to implement some other API for application server integration, such the optional chapter "JMS application server facilities" in the JMS 2.0 spec? Or is it OK for vendors to continue to develop JMS implementations that can't used in a Java EE application?

Tagging for further review in JMS 2.1.





[JMS_SPEC-2] Fix JavaDocs to reflect missing IllegalStateException from API methods Created: 11/Apr/11  Updated: 20/Mar/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: None

Type: Bug Priority: Major
Reporter: alanf760 Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

N/A


Tags: jms21doc-minor

 Description   

IllegalStateException tests

The JavaDocs for the following methods below need to be updated to reflect that IllegalStateException can be thrown. In particular IllegalStateException is being thrown in the case of these methods being called on closed connection objects. There could be more methods than those listed below.

    javax.jms.QueueSession.commit}}  
    javax.jms.QueueSession.getTransacted  
    javax.jms.QueueSession.rollback 
    javax.jms.QueueSession.recover
    javax.jms.QueueConnection.getClientID
    javax.jms.QueueConnection.getMetaDataTest
    javax.jms.QueueConnection.createQueueSession
    javax.jms.QueueConnection.start
    javax.jms.QueueSession.createBrowser(*)
    javax.jms.QueueSession.createQueue
    javax.jms.QueueSession.createSender()
    javax.jms.QueueSession.createTemporaryQueue()
    javax.jms.QueueSession.createMessage()
    javax.jms.QueueSession.createBytesMessage()
    javax.jms.QueueSession.createMapMessage()
    javax.jms.QueueSession.createObjectMessage(*)
    javax.jms.QueueSession.createStreamMessage()
    javax.jms.QueueSession.createTextMessage(*)
    javax.jms.QueueSession.createStreamMessage()
    javax.jms.QueueReceiver.getMessageSelector()
    javax.jms.QueueReceiver.receive(*)
    javax.jms.QueueReceiver.receiveTimeout()
    javax.jms.QueueReceiver.receiveNoWait()
    javax.jms.QueueReceiver.getQueue()
    javax.jms.QueueSender.getDeliveryMode()
    javax.jms.QueueSender.getDisabledMessageID()
    javax.jms.QueueSender.getDisabledMessageTimeStamp()
    javax.jms.QueueSender.getPriority()
    javax.jms.QueueSender.getTimeToLive()
    javax.jms.QueueSender.setDeliveryMode()
    javax.jms.QueueSender.setDisabledMessageID()
    javax.jms.QueueSender.setDisabledMessageTimeStamp()
    javax.jms.QueueSender.setPriority()
    javax.jms.QueueSender.setTimeToLive()
    javax.jms.QueueSender.getQueue()
    javax.jms.QueueSender.send(*)
    javax.jms.TopicSession.commit  
    javax.jms.TopicSession.rollback 
    javax.jms.TopicSession.recover
    javax.jms.TopicSession.createTopic
    javax.jms.TopicSession.createSubscriber(*)
    javax.jms.TopicSession.createDurableSubscriber(*)
    javax.jms.TopicSession.createPublisher()
    javax.jms.TopicSession.createTemporaryTopic()
    javax.jms.TopicSession.unsubscribe()
    javax.jms.TopicSession.createMessage
    javax.jms.TopicSession.createBytesMessage
    javax.jms.TopicSession.createMapMessage
    javax.jms.TopicSession.createObjectMessage
    javax.jms.TopicSession.createStreamMessage
    javax.jms.TopicSession.createTextMessage
    javax.jms.TopicSession.getTransacted
    javax.jms.TopicSubscriber.getMessageSelector
    javax.jms.TopicSubscriber.receive(*)
    javax.jms.TopicSubscriber.receiveNoWait()
    javax.jms.TopicSubscriber.getNoLocal()
    javax.jms.TopicSubscriber.getTopic()
    javax.jms.TopicConnection.getClientID
    javax.jms.TopicConnection.getMetaDataTest
    javax.jms.TopicConnection.start
    javax.jms.TopicConnection.createTopicSession
    javax.jms.TopicPublisher.getDeliveryMode()
    javax.jms.TopicPublisher.getDisabledMessageID()
    javax.jms.TopicPublisher.getDisabledMessageTimeStamp()
    javax.jms.TopicPublisher.getPriority()
    javax.jms.TopicPublisher.getTimeToLive()
    javax.jms.TopicPublisher.setDeliveryMode()
    javax.jms.TopicPublisher.setDisabledMessageID()
    javax.jms.TopicPublisher.setDisabledMessageTimeStamp()
    javax.jms.TopicPublisher.setPriority()
    javax.jms.TopicPublisher.setTimeToLive()
    javax.jms.TopicPublisher.getTopic()
    javax.jms.TopicPublisher.publish(*)

Tests for IllegalStateException

The JavaDocs should be updated for all of the above method calls to specify that an IllegalStateException can be thrown on closed connection objects. Currently it doesn't. Only the JMS spec specifies that IllegalStateException must be thrown. The JavaDoc should be in sync with the spec and should mention it as well.

The JMS spec references for this is in the following sections:

  • 4.3.5 Closing a Connection
  • 4.4.1 Closing a Session
  • 4.11 Method Inheritance across Messaging Domains
  • Table 4-1 Methods That Must Throw an IllegalStateException
  • 7.3 Standard Exceptions
  • 11.2.21 JMS Source Java API documentation Clarifications
  • Table 11-2 Domain Dependent Interfaces

The CTS JMS test directories which are testing for IllegalStateException to be thrown on closed QueueConnection, closed QueueReciever, closed QueueSender, etc. objects are listed below:

    jms/ee/all/closedQueueConnection
    jms/ee/all/closedQueueReceiver
    jms/ee/all/closedQueueSender
    jms/ee/all/closedQueueSession
    jms/ee/all/closedTopicConnection
    jms/ee/all/closedpublisher
    jms/ee/all/closedsubscriber
    jms/ee/all/closedtopicsessiontests


 Comments   
Comment by Nigel Deakin [ 15/Apr/11 ]

Added formatting to description.

Comment by Nigel Deakin [ 28/Feb/12 ]

In the JMS 1.1 spec, section 4.3.5 "Closing a Connection" states that

Once a connection has been closed, an attempt to use it or its sessions or their message consumers and producers must throw an IllegalStateException (calls to the close method of these objects must be ignored).

In addition, JMS 1.1 section 4.4.1 "Closing a Session" states that

Once a session has been closed, an attempt to use it or its message consumers
and producers must throw an IllegalStateException (calls to the close method of
these objects must be ignored). It is valid to continue to use message objects
created or received via the session, with the exception of a received message’s
acknowledge method.

(The corresponding sections in the JMS 2.0 spec are 6.1.8. "Closing a connection" and 6.2.16. "Closing a session")

Furthermore, JMS 1.1 section 11.2.21 "JMS Source Java API documentation Clarifications" states:

The IllegalStateException has been noted as a required exception for several
more error conditions. they are acknowledging a message received from a
closed session; attempting to call the recover method of a transacted session;
attempting to call any method of a closed connection, session, consumer or
producer (with the exception of the close method itself);

The text about "attempting to call any method on a closed consumer or producer" causing an IllegalStateException doesn't seem to have made it into the body of the JMS 1.1 spec, and so at the time of writing there is no mention in the JMS 2.0 spec. This needs to be corrected.

In addition, the javadoc for all methods except close on a connection, session, producer or consumer should be updated to mention that an IllegalStateException may be thrown if the connection, session, consumer or producer is closed.

Comment by Nigel Deakin [ 20/Mar/13 ]

This didn't make it into JMS 2.0 and so is carried forward to JMS 2.1.





[JMS_SPEC-3] Fix JavaDocs to reflect missing NumberFormatException from API methods Created: 11/Apr/11  Updated: 20/Mar/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: None

Type: Bug Priority: Major
Reporter: alanf760 Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

N/A


Tags: jms21doc-minor

 Description   

---------------------------
NumberFormatException tests
---------------------------

For javax.jms.MapMessage and javax.jms.StreamMessage the JavaDoc's need to be updated for the string to numeric conversions. The String to numeric conversions must throw a
java.lang.NumberFormatException if the numerics valueOf() method does not accept the the String value as a valid representation.

Tests for (NumberFormatException) which is not listed in JavaDoc for the getXXX() methods. Test in question is: MapMessageConversionQTestsInvFormatString. The
(NumberFormatException) is mentioned in spec but missing in JavaDoc.

The JavaDoc's for the following methods below of class javax.jms.MapMessage and class javax.jms.StreamMessage need to be modified to add the NumberFormatException.

getBoolean, getByte, getShort, getInt, getLong, getFloat, getDouble, etc



 Comments   
Comment by Nigel Deakin [ 11/Apr/11 ]

A big thank you to Alan for logging our first issue!

Comment by Nigel Deakin [ 28/Feb/12 ]

The JMS 1.1 spec, section 3.11.3 "Conversions provided by StreamMessage and MapMessage" states:

Both StreamMessage and MapMessage support the following conversion table. The marked cases must be supported. The unmarked cases must throw a JMS MessageFormatException. The String to numeric conversions must throw a java.lang.NumberFormatException if the numeric’s valueOf() method does not accept the String value as a valid representation.

This means that the methods this return a numeric: getShort, getLong, getDouble, getInt must throw a java.lang.NumberFormatException in the case described. This seems clear.

However I'm not sure about the methods which don't return a numeric, such as getBoolean. getByte and getBytes. Where does it say that these must throw a java.lang.NumberFormatException?

Tagging for review for the Public Draft.

Comment by Nigel Deakin [ 20/Mar/13 ]

This didn't make it into JMS 2.0 and so is carried forward to JMS 2.1.





[JMS_SPEC-132] FR javadocs are out of sync Created: 25/Jun/13  Updated: 25/Jun/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: John D. Ament Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

When I visit

http://download.oracle.com/otndocs/jcp/jms-2_0-fr-eval-spec/index.html

the javadocs available here are out of sync. For example, they are missing JMSContext#createContext(int sessionMode).

Not sure if other content is missing.



 Comments   
Comment by Nigel Deakin [ 25/Jun/13 ]

(I tried to download this and got a permissions error. I reported this and it seems to have gone away).

If I now download the javadocs from the location specified they look OK and include a javadoc comment for
javax/jms/JMSContext.html#createContext(int). Can you download it again and check?





[JMS_SPEC-117] Specifying redelivery behaviour when a JMS MDB performs rollback Created: 21/Mar/13  Updated: 02/Apr/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 1.1, 2.0
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
is duplicated by MQ-220 Improvements in handling consecutive ... Closed
Tags: jms21-forreview-major

 Description   

It may be helpful if the spec defined what should happen if a JMS MDB receives a message and then rolls back the transaction, typically because setRollbackOnly has been called. If the rollback is caused by a system error (such as a database failure) then the same message might be redelivered and rolled back repeatedly.

Possible behaviour that might be required is:

  • A delay before the message is redelivered - perhaps increasing as the number of redelivery attempts increases
  • A maximum number of consecutive rollbacks after which the message will be delivered to a dead-message queue

No doubt there are other possibilities.

It would of course be necessary to allow this behaviour to be configured, perhaps using activation properties.



 Comments   
Comment by Nigel Deakin [ 02/Apr/13 ]

Comment from colleague TB:

I thought there were already some JIRAs in this area. As time permits, can you comment on whether the following related functionality is covered?

  • An equivalent to "setRollbackOnly" for non-TX MDB would be nice. E.g., a way to force redelivery without throwing
  • An equivalent to this JIRA issue for the MDB non-TX case (or extend the current JIRA).
  • An equivalent to this JIRA issue for pure JMS clients (or extend the current JIRA).

As for the latter, there are trade-offs between implementing rollback/recover side-effects at the JMS layer or the MDB layer. It looks like it would be helpful to consider both layers at the same time when spec'ing out this area.

JMS layer poison-messaging-handling can preserve the message-id and time-stamp, can treat both expired and redelivered messages using the same mechanism, can move the problem message to a new destination with optimal efficiency, and can move the message "exactly-once" to the error destination without requiring the client to be transactional. The MDB layer, on the other hand, can forward the message with a helpful "rollback reason" attached as a property, and can forward the failed message to any destination - not just destinations known to the original provider.





[JMS_SPEC-73] Define how messages from a topic are delivered to clustered application server instances Created: 15/Feb/12  Updated: 22/Mar/13

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Dependency
blocks JMS_SPEC-103 A JMS 2.0 resource adapter needs to b... Closed
Tags: jms21-forreview-major

 Description   

This issue was raised on the JMS forum:
https://forums.oracle.com/forums/thread.jspa?threadID=2124417
and is being logged here on behalf of that contributor

How many times are topic messages delivered ?

This may seem to be a trivial question, but when clustering is involved, it's not.

JEE has strong support for clustering, but many JEE specifications do not define what is actually supported, and leaves room for application server specific features. This is the case for JMS in the various specifications involved (JMS, JEE, EJB, JCA).

The question is how many times are messages delivered and treated (e.g. once per cluster or once per application server)?

Note that to simplify the problem I will not address selectors, delivery modes or acknowledgement considerations. I will also only address business application clustering, not JMS implementation clustering.

When Queues are used the situation is quite clear, the message is delivered once whether you use clustering or not. But when Topics are used, there is no simple answer.

When a message is sent to a Topic, each currently active non-durable subscriber should receive the message once. If the receiving application is clustered, the message should be received one time per application server instance in the cluster. That's what we get with JBoss 4.2.3.

This is actually not always the case. One example with WebSphere 6.1:

  • A business application is deployed to a cluster of two application servers
  • The JMS message engine is also deployed to a cluster of two application servers
  • The application uses a MDB with a non-durable subscription to a Topic
  • A message is sent to that Topic
    If the two clusters are different, then the message is received by one MDB on each application instance, so the message is treated twice. But if the two clusters are actually the same, then the message is only received by one MDB instance on the application server where the message engine instance runs, so the message is treated once instead of twice. Painful.

For reliability considerations, enterprise applications often use durable subscriptions to Topics. This makes the situation even more complicated.

Durable subscriptions are identified by a subscription name. This defines the number of deliveries, meaning that the message should be delivered once per distinct subscription name.

JMS offers three ways to receive messages: Message Driven Beans (MDB), synchronous receptions using MessageConsumer:receive and explicit message listeners using MessageConsummer:setMessageListener. We won't address message listeners as they are forbidden on the server side by the JEE specifications.

When doing synchronous receptions or message listeners, the durable subscription name is managed by the developper using Session:createDurableSubscriber. This way it is possible (it is actually required by the JMS specification) to give a different name per application instance in the cluster to choose the number of times the messages are received.

With MDB we cannot officially manage the subscription name, so there is not portable control of the number of messages delivery. Note that we cannot manage the client ID either. In more details, both client ID and subscription name are valid parameters as per the JCA specification, but they are not according to the EJB specification.

We need precise, portable and cluster compliant semantics about the number of time JMS messages get delivered.



 Comments   
Comment by Nigel Deakin [ 07/Feb/13 ]

The JMS 2.0 public draft (Jan 2013) specified a new feature called "subscription scope" to address this issue. This was configured using a new MDB activation property subscriptionScope. The activation properties clientId and subscriptionName were also amended to support this new feature. Here's the text that the public draft contained:

MDB Activation properties

Activation property Description
clientId This property may be used to specify the client identifier that will be used when connecting to the JMS provider from which the endpoint (message-driven bean) is to receive messages.

Setting this property is always optional. If subscriptionScope is set (to Instance or Cluster) then this property must not be set.
subscriptionName This property only applies to endpoints (message-driven beans) that receive messages published to a topic. It may be used to specify the name of the durable or non-durable subscription.

If subscriptionScope is not set and the subscriptionDurability property is set to NonDurable then the subscriptionName property may be left unset.

If subscriptionScope is set (to Instance or Cluster) then the subscriptionName property may be left unset. A suitable subscription name will be generated automatically if needed.

If subscriptionScope is set to Instance and the subscriptionName property has been specified then the value of the subscriptionName property will be used as part of the subscription name.

If subscriptionScope is set to {[Cluster}

] and the subscriptionName property has been specified then the value of the subscriptionName property will be used as the subscription name.

subscriptionScope The subscriptionScope property only applies to message-driven beans that receive messages published to a topic. It applies to both durable and non-durable subscriptions, as specified using the subscriptionDurability property.

Setting the subscriptionScope property is optional. If this property is set then it must be set to either Instance or Cluster.

For both durable and non-durable subscriptions, setting this property allows the deployer to specify the scope of the subscription that will be used.

instance scope

If the scope is Instance then the resource adapter will create a separate topic subscription for each application server instance into which the message-driven bean is deployed.

cluster scope

If the scope is Cluster, and the message-driven bean is deployed into a clustered application server, then the resource adapter will create a single shared topic subscription for the entire cluster.
If the scope is Cluster, and the application server is not clustered, then the resource adapter will create a separate topic subscription for each application server instance into which the message-driven bean is deployed.

Generation of subscription name

The resource adapter will generate a suitable subscription name in the cases where a shared subscription is used.

If the scope is Instance, the subscriptionDurability is Durable and the subscriptionName property has been specified then the resource adapter will use the subscriptionName property as part of the subscription name.

If the scope is {[Cluster}}, the {{subscriptionDurability}] is Durable and the subscriptionName property has been specified then the the resource adapter will use the subscriptionName property as the subscription name. In this case the deployer is responsible to ensuring that the specified subscriptionName is unique to this cluster.

Client identifier

If the subscriptionScope property is specified then clientId must not be specified. Otherwise a deployment error will occur.

Implementation of topic subscriptions

This section contains some additional recommendations as to how the specified ActivationSpec properties should be used in a resource adapter implementation.

When subscriptionScope is not specified

This section applies if the subscriptionScope property is not specified.

It is not defined whether a subscriptionDurability of NonDurable should be implemented using a shared or unshared non-durable subscription. If an unshared durable subscription is used then any subscriptionName specified will be ignored.

It is also not not defined whether a subscriptionDurability of NonDurable should be implemented using a shared or unshared durable subscription.

When subscriptionScope is set to Cluster

This section applies if the subscriptionScope property is set to Cluster.

It is recommended that a subscriptionDurability of NonDurable be implemented using a shared non-durable subscription.

It is recommended that a subscriptionDurability of Durable be implemented using a shared durable subscription.

If the message-driven bean is deployed into a clustered application server, then the subscription name that is generated should be the same for the same endpoint in each application server instance within the cluster but otherwise unique.

When subscriptionScope is set to Instance

This section applies if the subscriptionScope property is set to Instance.

It is not defined whether a non-durable subscription should be implemented using a shared or unshared non-durable subscription, or whether a durable subscription should be implemented using a shared or unshared durable subscription.

If the subscriptionScope property is set to instance, and the message-driven bean is deployed into a clustered application server, then the subscription name that is generated must be different for every endpoint and for every application server instance.

When subscriptionScope is set to Instance or Cluster

This section applies if the subscriptionScope property is set to either Instance or Cluster.

It is recommended that the subscription name that is generated includes a unique identifier to ensure that it is unique across other clusters or across other application server instances that are not part of the cluster.

If the application server instance into which the message-driven bean is deployed is not part of a cluster, then that the subscription name that is generated must be must be different for every endpoint and for every application server instance.

In this case it is recommended that the subscription name that is generated includes a unique identifier to ensure that it is as unique as possible across all application server instances.

Requirements for generated subscription names

The subscription name generated by the resource adapter must be a valid JMS subscription name. This means that it must be no longer than 128 characters and must consist only of Java letters or digits (as defined in the Java Language Specification) or the underscore (_), dot (.) or minus characters.

Since a durable subscription can be used to store messages indefinitely it is recommended that its name remains unchanged even if the application server is restarted or reconfigured, or if the application is redeployed.

Since a subscription name may be visible to the user or administrator it is recommended that the subscription name is at least partly human-readable.

Implementation in a resource adapter

The Java EE Connector Architecture (JCA) specification defines a method getInstanceName on javax.resource.spi.BootstrapContext and a method getActivationUniqueName on MessageEndpointFactory. If a scope of Cluster is specified then a suitable subscription name may be obtained by calling the getActivationUniqueName method. If a scope of Instance is specified then a suitable subscription name may be obtained by calling the getInstanceName and getActivationUniqueName methods and concatenating the results.

However if the subscriptionName property and the subscription is durable then the value of this property should be used instead of the value returned by getActivationUniqueName.

The term "application server instance" as used in this section refers to a single application server JVM. The exact meaning of the term "application server cluster" as used in this section is left to the application server to define but is intended to refer to a group of co-operating application server JVMs to which an identical Java EE application may be deployed.

Comment by Nigel Deakin [ 07/Feb/13 ]

For the reasons described here and here this feature has been dropped from JMS 2.0 and deferred until a later version of JMS.

Comment by Nigel Deakin [ 07/Feb/13 ]

Tagged for review for JMS 2.1

Comment by Nigel Deakin [ 22/Mar/13 ]

Removing "fix version=2.0" as this issue was removed from the spec





[JMS_SPEC-120] Typo: in example, change .class() to .class Created: 26/Apr/13  Updated: 02/Dec/14

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: jms20-errata

 Description   

The JMS spec contains the following code in an example:

StockObject stockObject = message.getBody(StockObject.class());

This is incorrect. It should be changed to

StockObject stockObject = message.getBody(StockObject.class);

i.e. class should not be followed by ().



 Comments   
Comment by Nigel Deakin [ 02/Dec/14 ]

JMS specification section 14.4.10 "Unpacking an ObjectMessage": Existing text:

StockObject stockObject = message.getBody(StockObject.class());

Replacement text

StockObject stockObject = message.getBody(StockObject.class);
Comment by Nigel Deakin [ 02/Dec/14 ]

I have updated the specification in the source code repository. PDF may be downloaded here.





[JMS_SPEC-160] JMS API source contains self-closing HTML tags Created: 17/Nov/14  Updated: 07/Jan/15

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: jms20-errata

 Description   

The JMS API source contains self-closing HTML tags in its javadoc comments. For example, the source of javax.jms.Message contains the tag <br/>.

To reproduce the issue, simply run the javadoc command on the API source using the Java 8 version of javadoc.

Self-closing tags are not valid HTML and they cause the Java 8 version of javadoc to fail (unless a flag has been set to suppress this).

It looks as if this incorrect HTML was added in JMS 2.0.



 Comments   
Comment by Nigel Deakin [ 01/Dec/14 ]

Changes to javadoc for Message

Change <br/> to <br> in 12 places.

Changes to javadoc for JMSConsumer

Change <br/> to <br> in 15 places.

Comment by Nigel Deakin [ 07/Jan/15 ]

Source code now updated.

Updated source for javax.jms.Message can be viewed at, and downloaded from,
https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/src/main/java/javax/jms/Message.java?rev=303
Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/Message.java?rev1=302&rev2=303

Updated source for javax.jms.JMSConsumer can be viewed at, and downloaded from,
https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/src/main/java/javax/jms/JMSConsumer.java?rev=303
Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/JMSConsumer.java?rev1=302&rev2=303





[JMS_SPEC-155] JMS 2.0 introduced incompatible changes to createSession(bool,int) Created: 16/Jul/14  Updated: 09/Jan/15

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: jms20-errata

 Description   

The background

Prior to JMS 2.0, a number of requirements for the behaviour of the JMS API in Java EE applications were defined in the Java EE 6 platform specification and in the EJB 3.1 specification, but were not mentioned in the JMS specification or javadocs. This was confusing for users. To remedy this, JMS 2.0 was extended to incorporate these requirements.

Those extensions to JMS 2.0 were intended to be a rearrangement and clarification of existing requirements and were not intended to introduce changes which were incompatible with Java EE 6 and EJB 3.1 or which would require changes to existing applications.

However it appears that JMS 2.0 may have introduced a number incompatible changes related to the behaviour of the ConnectionFactory method createSession(boolean transacted, int acknowledgeMode) in a Java EE web or EJB application in the case where there is no active JTA transaction in progress and the application has specified the parameter values (true, SESSION_TRANSACTED) or (false,CLIENT_ACKNOWLEDGE).

In the EJB 3.1 specification, section 13.3.5 states

"The Bean Provider should not use the JMS acknowledge method either within a transaction or within an unspecified transaction context. Message acknowledgment in an unspecified transaction context is handled by the container."

The term "unspecified transaction context" is explained in EJB 3.1 section 13.6.5. Although it does not say so explicitly, it is understood to mean those cases where there is there is no active container-managed transaction in progress or where bean-managed transactions are specified but there is no active UserTransaction in progress.

When this requirement was incorporated into the JMS specification, it became the following text in JMS 2.0 section 12.3:

"When an application creates a Session or JMSContext in a Java EE web or EJB container, and there is no active JTA transaction in progress, then the session that is created will be non-transacted and will be automatically-acknowledged. The use of local transactions or client acknowledgement is still not permitted. Parameters may be specified when creating the Session or JMSContext to specify whether the acknowledgement mode should be AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE. If any other session parameter values are specified they will be ignored and an acknowledgement mode of AUTO_ACKNOWLEDGE used."

The problem

Although the JMS 2.0 specification clearly conveys the intent of the EJB 3.1 specification, the requirement given in the EJB specification was loosely worded:

  • EJB 3.1 uses the phrase "should not use the JMS acknowledge method" rather than "must not use the JMS acknowledge method"
  • EJB 3.1 uses the phrase "Message acknowledgment...is handled by the container" without explicitly stating what would happen if the application tries to use client-acknowledgement or local transactions.

It therefore appears (with hindsight) that JMS 2.0 has introduced some additional requirements which are additional to EJB 3.1. In particular it has introduced the requirement that if the application specifies the session parameters as (true, SESSION_TRANSACTED) or (false, CLIENT_ACKNOWLEDGE) then they will be ignored and an acknowledgement mode of AUTO_ACKNOWLEDGE used.

The "Backwards compatibility requirements for Java EE specifications" can be found at
https://java.net/projects/javaee-spec/pages/CompatibilityRequirements

It could be argued that this change does not violate these compatibility requirements. The compatibility requirements state that "Where behavior was undefined or optional in the previous version of the specification then it is permissible to define more explicit behavior in a later version.", which would appear to allow this change (treating EJB 3.1 as the "previous version").

The compatibility requirements also require that "applications that change to using the new version of the specification do not see changes to behaviour that were mandated by the previous version of the specification.". Again, it could be argued that JMS 2.0 did not change behaviour that was mandated by the previous version of the specification" (again (treating EJB 3.1 as the "previous version").

However it has been discovered that at least one JMS vendor has interpreted the EJB 3.1 specification as allowing both client-acknowledgement and local transactions to be used in a Java EE web or EJB application in the case where there is no active JTA transaction.

Given that the EJB 3.1 specification is loosely worded, and that there were no CTS tests to require otherwise, it would appear that this was valid. Therefore, introducing the requirements added in JMS 2.0 would change the behaviour of existing applications, which is contrary to the intent of the backwards compatibility requirements for Java EE specifications.

The proposal

To avoid forcing JMS vendors to change the the behaviour of existing applications, it is proposed to revise section 12.3 of the JMS 2.0 specification, and the corresponding javadocs, as follows:

  • to recommend (rather than require) that applications do not call createSession with the parameters (true, SESSION_TRANSACTED) or (false,CLIENT_ACKNOWLEDGE) when in a Java EE EJB or web application and there is no active JTA transaction, and warn that applications which specify these parameter values may not be portable,
  • to allow JMS providers to choose the behaviour they provide if the application specifies the parameters (true, SESSION_TRANSACTED) when in a Java EE EJB or web application and there is no active JTA transaction from the following options:
    • the JMS provider is recommended but not required to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session.

    • the JMS provider may alternatively provide a local transacted session.
  • to allow JMS providers to choose the behaviour they provide if the application specifies the parameters (false,CLIENT_ACKNOWLEDGE) when in a Java EE EJB or web application and there is no active JTA transaction from the following options:
    • the JMS provider is recommended but not required to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session.

    • the JMS provider may alternatively provide a non-transacted session with client acknowledgement.

Change related new methods to stay consistent

Although the issue of backwards compatibility applies only to the following existing methods:

  • Connection method createSession(boolean transacted, int acknowledgeMode)
  • QueueConnection method createQueueSession(boolean transacted, int acknowledgeMode)
  • TopicConnection method createTopicSession(boolean transacted, int acknowledgeMode)

it is proposed that for consistency the same changes are also made to the following methods added in JMS 2.0:

  • Connection method createSession(int sessionMode)
  • ConnectionFactory method createContext(int sessionMode).


 Comments   
Comment by Nigel Deakin [ 03/Dec/14 ]

(Superseded by updated proposals below)

Proposed changes to JMS specification section 12.3 "Behaviour of JMS sessions in the Java EE web or EJB container"

Existing text:

When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is no active JTA transaction in progress,
then the session that is created will be non-transacted and will be
automatically-acknowledged. The use of local transactions or client
acknowledgement is still not permitted. Parameters may be specified
when creating the Session or JMSContext to specify whether the
acknowledgement mode should be AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE. If any other session parameter values are
specified they will be ignored and an acknowledgement mode of
AUTO_ACKNOWLEDGE used.

The use of local transactions or client acknowledgement is not
permitted in a Java EE web or EJB container even if there is no active
JTA transaction because this would require applications to be written
differently depending on whether there was a JTA transaction or not.

The JMS API provides the following methods to create a session which
allow the session to be defined using either the two parameters
transacted and acknowledgeMode or by the single parameter
sessionMode. If these methods are called in a Java EE web or EJB
container then these parameters will be overridden as described above.

[4 methods]

It is recommended that applications that run in the Java EE web or EJB
container create a session using the following method which does not
specify a parameter:

[1 method]

The JMS API provides the following methods to create a JMSContext
which allow the session to be defined using the single parameter
sessionMode. If these methods are called in a Java EE web or EJB
container then this parameter will be overridden as described above.

[2 methods]

The following method to create a JMSContext from an existing
JMSContext is not permitted in a Java EE web or EJB container because
it would create a second session on an existing connection, which is
not permitted in a java EE web or EJB container.]

[1 method]

It is recommended that applications that run in the Java EE web or EJB
container creates a JMSContext using one of the following methods
which do not specify a sessionMode:

[2 methods]

Replacement text:

When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is no active JTA transaction in progress,
then:

  • If the session parameters specify that the session should be
    non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
    DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages
    will be acknowledged according to the specified acknowledgement mode.
  • If the session parameters specify that the session should be
    non-transacted with an acknowledgement mode of CLIENT_ACKNOWLEDGE then the
    JMS provider is recommended to ignore the specified parameters and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a non-transacted session with client
    acknowledgement.
  • If the session parameters specify that the session should be transacted,
    then the JMS provider is recommended to ignore the specified parameters and
    instead provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a local transacted session.
  • Applications running in a Java EE web or EJB container are recommended to
    specify no session parameters or to specify that the session be
    non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
    DUPS_OK_ACKNOWLEDGE.
  • It is not recommended that applications specify client acknowledgement
    or a local transaction since applications may not be portable. Furthermore
    if the JMS provider does support the use of client acknowledgement
    and local transactions when there is no JTA transaction, the application
    would need to be written differently dependent on whether there was a JTA
    transaction or not.
Comment by Nigel Deakin [ 03/Dec/14 ]

Proposed changes to Javadocs for Connection.html#createSession(boolean, int):

Existing text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • The argument transacted is ignored. The session will always be
    non-transacted, using one of the two acknowledgement modes
    AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE.
  • The argument acknowledgeMode is used to specify how messages
    received by this session will be acknowledged. The only permitted
    values in this case are Session.AUTO_ACKNOWLEDGE and
    Session.DUPS_OK_ACKNOWLEDGE. The value Session.CLIENT_ACKNOWLEDGE
    may not be used. For a definition of the meaning of these
    acknowledgement modes see the links below.

Replacement text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • If transacted is set to false and acknowledgeMode is set to
    JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE then the
    session will be non-transacted and messages will be acknowledged according
    to the value of acknowledgeMode.
  • If transacted is set to false and acknowledgeMode is set to
    JMSContext.CLIENT_ACKNOWLEDGE then the JMS provider is recommended to
    ignore the specified parameters and instead provide a non-transacted,
    auto-acknowledged session. However the JMS provider may alternatively
    provide a non-transacted session with client acknowledgement.
  • If transacted is set to true, then the JMS provider is recommended to
    ignore the specified parameters and instead provide a non-transacted,
    auto-acknowledged session. However the JMS provider may alternatively
    provide a local transacted session.
  • Applications are recommended to set transacted to false and
    acknowledgeMode to JMSContext.AUTO_ACKNOWLEDGE or
    JMSContext.DUPS_OK_ACKNOWLEDGE since since applications which set
    transacted to false and set acknowledgeMode to
    JMSContext.CLIENT_ACKNOWLEDGE, or which set transacted to true, may not be
    portable.

Existing text:

Parameters:

transacted - indicates whether the session will use a local transaction.
If this method is called in the Java EE web or EJB container then this
argument is ignored.

acknowledgeMode - indicates how messages received by the session will be
acknowledged.

  • If this method is called in a Java SE environment or in the Java EE
    application client container, the permitted values are
    Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and
    Session.DUPS_OK_ACKNOWLEDGE.
  • If this method is called in the Java EE web or EJB container when
    there is an active JTA transaction in progress then this argument is
    ignored.
  • If this method is called in the Java EE web or EJB container when
    there is no active JTA transaction in progress, the permitted values
    are Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. In this
    case Session.CLIENT_ACKNOWLEDGE is not permitted.

Replacement text:

Parameters:

transacted - indicates whether the session will use a local transaction,
except in the cases described above when this value is ignored.

acknowledgeMode - when transacted is false, indicates how messages received
by the session will be acknowledged, except in the cases described above
when this value is ignored.

Comment by Nigel Deakin [ 03/Dec/14 ]

Proposed changes to Javadocs for Connection.html#createSession(int):

Existing text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • The argument acknowledgeMode must be set to either of
    Session.AUTO_ACKNOWLEDGE or Session.DUPS_OK_ACKNOWLEDGE. The session will
    be non-transacted and messages received by this session will be
    acknowledged automatically according to the value of acknowledgeMode. For
    a definition of the meaning of these acknowledgement modes see the links
    below. The values Session.SESSION_TRANSACTED and Session.CLIENT_ACKNOWLEDGE
    may not be used.

Replacement text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • If sessionMode is set to Session.AUTO_ACKNOWLEDGE or
    Session.DUPS_OK_ACKNOWLEDGE then the session will be
    non-transacted and messages will be acknowledged according to the value
    of sessionMode.
  • If sessionMode is set to Session.CLIENT_ACKNOWLEDGE then the JMS
    provider is recommended to ignore the specified parameter and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a non-transacted session with
    client acknowledgement.
  • If sessionMode is set to Session.SESSION_TRANSACTED, then the JMS
    provider is recommended to ignore the specified parameter and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a local transacted session.
  • Applications are recommended to use only the values
    Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE
    since applications which use Session.CLIENT_ACKNOWLEDGE or
    Session.SESSION_TRANSACTED may not be portable.

Existing text:

Parameters:

sessionMode - indicates which of four possible session modes will be used.

  • If this method is called in a Java SE environment or in the Java EE
    application client container, the permitted values are
    Session.SESSION_TRANSACTED, Session.CLIENT_ACKNOWLEDGE,
    Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE.
  • If this method is called in the Java EE web or EJB container when there
    is an active JTA transaction in progress then this argument is ignored.
  • If this method is called in the Java EE web or EJB container when there
    is no active JTA transaction in progress, the permitted values are
    Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. In this case
    the values Session.TRANSACTED and Session.CLIENT_ACKNOWLEDGE are not permitted.

Replacement text:

Parameters:

sessionMode - specifies the session mode that will be used, except in the
cases described above when this value is ignored. Legal values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.

Comment by Nigel Deakin [ 03/Dec/14 ]

(This proposal has now been dropped. See updated proposals below)

Proposed changes to Javadocs for ConnectionFactory.html.createContext(int):

Existing text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • The argument acknowledgeMode must be set to either of
    JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE. The
    session will be non-transacted and messages received by this session
    will be acknowledged automatically according to the value of
    acknowledgeMode. For a definition of the meaning of these
    acknowledgement modes see the links below. The values
    JMSContext.SESSION_TRANSACTED and JMSContext.CLIENT_ACKNOWLEDGE may
    not be used.

Replacement text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • If sessionMode is set to JMSContext.AUTO_ACKNOWLEDGE or
    JMSContext.DUPS_OK_ACKNOWLEDGE then the session will be
    non-transacted and messages will be acknowledged according to the value
    of sessionMode.
  • If sessionMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS
    provider is recommended to ignore the specified parameter and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a non-transacted session with
    client acknowledgement.
  • If sessionMode is set to JMSContext.SESSION_TRANSACTED, then the JMS
    provider is recommended to ignore the specified parameter and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a local transacted session.
  • Applications are recommended to use only the values
    JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE
    since applications which use JMSContext.CLIENT_ACKNOWLEDGE or
    JMSContext.SESSION_TRANSACTED may not be portable.

Existing text:

Parameters:

sessionMode - indicates which of four possible session modes will be used.

  • If this method is called in a Java SE environment or in the Java EE
    application client container, the permitted values are
    JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
    JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
  • If this method is called in the Java EE web or EJB container when there
    is an active JTA transaction in progress then this argument is ignored.
  • If this method is called in the Java EE web or EJB container when there
    is no active JTA transaction in progress, the permitted values are
    JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE. In this case
    the values JMSContext.TRANSACTED and JMSContext.CLIENT_ACKNOWLEDGE are not
    permitted.

Replacement text:

Parameters:

sessionMode - specifies the session mode that will be used, except in the
cases described above when this value is ignored. Legal values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.

Comment by Nigel Deakin [ 03/Dec/14 ]

(This proposal has now been dropped. See updated proposals below)

Proposed changes to Javadocs for ConnectionFactory.html.createContext(String, String, int):

Existing text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • The argument acknowledgeMode must be set to either of
    JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE. The session
    will be non-transacted and messages received by this session will be
    acknowledged automatically according to the value of acknowledgeMode.
    For a definition of the meaning of these acknowledgement modes see the
    links below. The values JMSContext.SESSION_TRANSACTED and
    JMSContext.CLIENT_ACKNOWLEDGE may not be used.

Replacement text:

In the Java EE web or EJB container, when there is no active JTA
transaction in progress:

  • If sessionMode is set to JMSContext.AUTO_ACKNOWLEDGE or
    JMSContext.DUPS_OK_ACKNOWLEDGE then the session will be
    non-transacted and messages will be acknowledged according to the value
    of sessionMode.
  • If sessionMode is set to JMSContext.CLIENT_ACKNOWLEDGE then the JMS
    provider is recommended to ignore the specified parameter and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a non-transacted session with
    client acknowledgement.
  • If sessionMode is set to JMSContext.SESSION_TRANSACTED, then the JMS
    provider is recommended to ignore the specified parameter and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a local transacted session.
  • Applications are recommended to use only the values
    JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE
    since applications which use JMSContext.CLIENT_ACKNOWLEDGE or
    JMSContext.SESSION_TRANSACTED may not be portable.

Existing text:

Parameters:

userName - the caller's user name

password - the caller's password

sessionMode - indicates which of four possible session modes will be used.

  • If this method is called in a Java SE environment or in the Java EE
    application client container, the permitted values are
    JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
    JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.
  • If this method is called in the Java EE web or EJB container when there
    is an active JTA transaction in progress then this argument is ignored.
  • If this method is called in the Java EE web or EJB container when there
    is no active JTA transaction in progress, the permitted values are
    JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE. In this
    case the values JMSContext.TRANSACTED and JMSContext.CLIENT_ACKNOWLEDGE
    are not permitted.

Replacement text:

Parameters:

userName - the caller's user name

password - the caller's password

sessionMode - specifies the session mode that will be used, except in the
cases described above when this value is ignored. Legal values are
JMSContext.SESSION_TRANSACTED, JMSContext.CLIENT_ACKNOWLEDGE,
JMSContext.AUTO_ACKNOWLEDGE and JMSContext.DUPS_OK_ACKNOWLEDGE.

Comment by Nigel Deakin [ 17/Dec/14 ]

Updated proposal

Here is an updated proposal which would update the specification and javadocs for the classic API (createSession methods) only but make no changes to the simplified API (createContext methods) on the grounds these new methods do not break backward compatibility and so don't need to be changed.

The following javadoc changes would still be needed:

The changed originally proposed to JMS specification section 12.3 "Behaviour of JMS sessions in the Java EE web or EJB container" would be replaced by the following:

Existing text

12.3 "Behaviour of JMS sessions in the Java EE web or EJB container"

The behaviour of a JMS session in respect of transactions and message
acknowledgement is different for applications which run in a Java EE
web or EJB container than it is for applications which run in a normal
Java SE environment or in the Java EE application client container.

These differences also apply to JMSContext objects, since these
incorporate a JMS session.

When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is an active JTA transaction in progress,
then the session that is created will participate in the JTA
transaction and will be committed or rolled back when the JTA
transaction is committed or rolled back. Any session parameters that
are specified when creating the Session or JMSContext are ignored. The
use of local transactions or client acknowledgement is not permitted.

This applies irrespective of whether the JTA transaction is demarcated
automatically by the container or programmatically using methods on
javax.transaction.UserTransaction.

The term “session parameters” here refers to the arguments that may be
passed into a call to the createSession or createContext methods to
specify whether the session should use a local transaction and, if the
session is non-transacted, what the acknowledgement mode should be.

When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is no active JTA transaction in progress,
then the session that is created will be non-transacted and will be
automatically-acknowledged. The use of local transactions or client
acknowledgement is still not permitted. Parameters may be specified
when creating the Session or JMSContext to specify whether the
acknowledgement mode should be AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE. If any other session parameter values are
specified they will be ignored and an acknowledgement mode of
AUTO_ACKNOWLEDGE used.

The use of local transactions or client acknowledgement is not
permitted in a Java EE web or EJB container even if there is no active
JTA transaction because this would require applications to be written
differently depending on whether there was a JTA transaction or not.

The JMS API provides the following methods to create a session which
allow the session to be defined using either the two parameters
transacted and acknowledgeMode or by the single parameter sessionMode.
If these methods are called in a Java EE web or EJB container then
these parameters will be overridden as described above.

(4 methods)

It is recommended that applications that run in the Java EE web or EJB
container create a session using the following method which does not
specify a parameter:

(1 method)

The JMS API provides the following methods to create a JMSContext
which allow the session to be defined using the single parameter
sessionMode. If these methods are called in a Java EE web or EJB
container then this parameter will be overridden as described above.

(2 methods)

The following method to create a JMSContext from an existing
JMSContext is not permitted in a Java EE web or EJB container because
it would create a second session on an existing connection, which is
not permitted in a java EE web or EJB container.]

(1 method)

It is recommended that applications that run in the Java EE web or EJB
container creates a JMSContext using one of the following methods
which do not specify a sessionMode:

(2 methods)

Replacement text

The behaviour of JMS Session and JMSContext objects in respect of
transactions and message acknowledgement is different for applications
which run in a Java EE web or EJB container than it is for applications
which run in a normal Java SE environment or in the Java EE application
client container.

When an application creates a Session or JMSContext in a Java EE web
or EJB container, and there is an active JTA transaction in progress,
then the session that is created will participate in the JTA
transaction and will be committed or rolled back when the JTA
transaction is committed or rolled back. Any session parameters that
are specified when creating the Session or JMSContext are ignored. The
use of local transactions or client acknowledgement is not permitted.

This applies irrespective of whether the JTA transaction is demarcated
automatically by the container or programmatically using methods on
javax.transaction.UserTransaction.

The term “session parameters” here refers to the arguments that may be
passed into a call to the createSession or createContext methods to
specify whether the session should use a local transaction and, if the
session is non-transacted, what the acknowledgement mode should be.

When an application uses one of the createSession methods to create
a Session, and there is no active JTA transaction in progress,
then:

  • If the session parameters specify that the session should be
    non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
    DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages
    will be acknowledged according to the specified acknowledgement mode.
  • If the session parameters specify that the session should be
    non-transacted with an acknowledgement mode of CLIENT_ACKNOWLEDGE then the
    JMS provider is recommended to ignore the specified parameters and instead
    provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a non-transacted session with client
    acknowledgement.
  • If the session parameters specify that the session should be transacted,
    then the JMS provider is recommended to ignore the specified parameters and
    instead provide a non-transacted, auto-acknowledged session. However the JMS
    provider may alternatively provide a local transacted session.
  • Applications running in a Java EE web or EJB container are recommended to
    specify no session parameters or to specify that the session be
    non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
    DUPS_OK_ACKNOWLEDGE.
  • It is not recommended that applications specify client acknowledgement
    or a local transaction since applications may not be portable. Furthermore
    if the JMS provider does support the use of client acknowledgement
    and local transactions when there is no JTA transaction, the application
    would need to be written differently dependent on whether there was a JTA
    transaction or not.

When an application uses one of the createContext methods to create
a JMSContext, and there is no active JTA transaction in progress,
then:

  • If the specified session mode is AUTO_ACKNOWLEDGE or
    DUPS_OK_ACKNOWLEDGE then the session will be non-transacted and messages
    will be acknowledged according to the specified acknowledgement mode.
  • If the specified session mode is CLIENT_ACKNOWLEDGE or SESSION_TRANSACTED
    then it will be ignored and a session mode of AUTO_ACKNOWLEDGE used.
  • Applications running in a Java EE web or EJB container are recommended to
    specify no session parameters or to specify that the session be
    non-transacted with an acknowledgement mode of AUTO_ACKNOWLEDGE or
    DUPS_OK_ACKNOWLEDGE.
  • The use of local transactions or client acknowledgement is not
    permitted in a Java EE web or EJB container even if there is no active
    JTA transaction because this would require applications to be written
    differently depending on whether there was a JTA transaction or not.
Comment by Nigel Deakin [ 09/Jan/15 ]

Draft spec now updated.
PDF (with change bar) at https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/specification/word/JMS20.pdf?rev=315.
Latest PDF at https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/specification/word/JMS20.pdf

Updated source for javax.jms.Connection can be viewed at, and downloaded from,
https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/src/main/java/javax/jms/Connection.java?rev=315
Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/Connection.java?rev1=314&rev2=315





[JMS_SPEC-166] Define that the JMS provider should call reset on a StreamMessage passed to a CompletionListener Created: 12/Jan/15  Updated: 12/Jan/15

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to JMS_SPEC-125 Define whether a JMS provider should ... Open

 Description   

JMS_SPEC-125 proposes that when a BytesMessage is sent asynchronously, the provider must call reset on the BytesMessage passed to the CompletionListener,

This issue proposes making the same change to StreamMessage, for exactly the same reasons. These reasons are discussed in JMS_SPEC-125.



 Comments   
Comment by Nigel Deakin [ 12/Jan/15 ]

Proposed changes

In the javadoc for StreamMessage, insert the following new text after the sentence ending "After the first call to reset has been made, the message body is in read-only mode.":

Inserted text:

When a StreamMessage is sent asynchronously, the provider must call reset on the StreamMessage passed to the CompletionListener. This means that the CompletionListener can read the message body without needing to call reset.





[JMS_SPEC-128] Typo in section 4.1.4 "Queue" Created: 06/Jun/13  Updated: 16/Jan/15

Status: Open
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: jms20-errata

 Description   

There's a typo in section 4.1.4 "Queue":

The sentence

See Section 0 "<new page>Administered objects" for more information...

contains an incorrect section number and a spurious page throw.



 Comments   
Comment by Nigel Deakin [ 01/Dec/14 ]

Draft spec now updated. PDF (with change bar) at https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/specification/word/JMS20.pdf?rev=305

Comment by Nigel Deakin [ 19/Dec/14 ]

Proposed changes to JMS specification section 4.1.4 "Queue"

Existing text

See Section 0 "<new page>Administered objects" for more information...

(where <new page> means that the subsequent text was on the next page)

Replacement text

See Section 5 "Administered objects" for more information...





Generated at Fri Mar 27 04:09:18 UTC 2015 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.