[JMS_SPEC-61] Selector on JMS body Created: 17/Nov/11  Updated: 08/Jan/13  Resolved: 10/Apr/12

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

Type: New Feature Priority: Major
Reporter: koen.serneels Assignee: Unassigned
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

It would be a very nice feature to apply selectors on the message body.
Possibly using regexp, or XPath in case of TextMessages.
The same for key/value pairs of MapMessage.



 Comments   
Comment by rdohna [ 21/Nov/11 ]

There may be use-cases, but I doubt that this is a good path to follow. It would add a lot of complexity to the spec, and the performance will probably be terrible, as providers can create something similar to an index on all properties, but not on the payload. And the message would have to be unpacked by every filter around, while it's not so easy to see if there could be messages that slip through all of your selectors... or be matched by more than one!

Take it from a different perspective: You suggest regex and/or XPath. What if the content is JSON, or POJOs, or Byte-Arrays, or streamed messages, or ... You'd open up a can of worms where every use-case would require a change to the spec. So you'd have to find a generic form - some kind of filter SAM type seems a good option here. I put such filters exclusively into a content based router, i.e. it does not invoke the business code directly, but forwards the messages to several more specific destinations. This keeps the routing logic in one place where it's easier to make sure that there is no gap or overlap in your logic; and every message would have to be unpacked exactly two times, not up to n times with n selectors.

Comment by Nigel Deakin [ 09/Dec/11 ]

As the previous comment said, we need to be wary of introducing features which are impossible for the JMS provider to implement efficiently. Message properties were invented to allow the provider to handle selectors on a limited amount of information without the need to unmarshall/uncompress/index the entire message payload.

I'll raise it with the expert group after the early draft to see what views there are, especially from the representatives of JMS vendors. If you have any particular priorities please state them (and give as much justification as you can).

Nigel

Comment by Nigel Deakin [ 10/Apr/12 ]

Following a discussion with the JSR 343 expert group, I am rejecting this proposal as it would be contrary to the way in which JMS is designed. Currently message selectors can be used to filter messages on the basis of application-defined message properties. JMS supports message properties expressly to avoid the need for the message selector mechanism to examine the message body, which might be inefficient.

Closing this issue with a resolution of "Won't fix"

Comment by axel_podehl [ 08/Jan/13 ]

I agree with closing this issue.

The implementation of regexp or XPath filtering should be implemented by JMS providers, but can't be defined by the JMS standard. There are too many ways to define these filters and each regex or Xpath package used would have slight differences in syntax.

Also, there's nothing preventing JMS providers to extend the notion of a JMS selector.
In addition to supporting the standard JMS selector, a JMS provider can extend the notion of this selector.

For example to apply the JMS selectors also on the properties of a MapMessages, there's an open source package: http://jamsel.sourceforge.net/

In another product, you can use these types of JMS selector strings:

::regex::.trader=peter.
::xpath::/trade[trader='peter']
::request::fromTime=2002-12-31T14:15:16.123456





[JMS_SPEC-56] Enhance the EJB specification to support the delivery of messages in batches to MDBs Created: 08/Nov/11  Updated: 01/May/12  Resolved: 01/May/12

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

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

Issue Links:
Dependency
depends on JMS_SPEC-36 Allow messages to be delivered asynch... Open
depends on EJB_SPEC-44 Enhance the EJB specification to supp... Resolved
Tags: eg, jms20-jsr345

 Description   

This is a request for changes to the EJB specification to support the asynchronous delivery of messages to a message-driven bean in batches.

This new feature is described in JMS_SPEC-36. To support this there will be a new listener interface javax.jms.BatchMessageListener, which provides the method onMessages(Message[] messages).

Where batch delivery is not required, the existing javax.jms.MessageListener interface and its method onMessage(Message message) will continue to be used as before.

The following changes to the EJB specification are suggested (references are to the EJB 3.1 specification)

Section 5.4.2 "The Required Message Listener Interface"


Change: "The message-driven bean class's implementation of the javax.jms.MessageListenerinterface distinguishes the message-driven bean as a JMS message-driven bean."

To: "The message-driven bean class's implementation of the javax.jms.MessageListener or javax.jms.BatchMessageListener interface distinguishes the message-driven bean as a JMS message-driven bean."

An additional node should be added to state that a JMS message-driven bean may implement either of these interfaces or both.

5.6.2 "Message-Driven Bean Class"


Change: "In the case of JMS, this is the javax.jms.MessageListener interface."

To: "In the case of JMS, this is either the javax.jms.MessageListener or javax.jms.BatchMessageListener interface."

13.6.3.2 "REQUIRED£


In all four places change: "onMessage method"

to: "onMessage or onMessages method"

21.3.5 "JMS 1.1 Requirements"


Change name of section to: "JMS 2.0 Requirements"

Change: "An implementation requiring the full EJB 3.1 API must include the JMS 1.1 extension"

To: "An implementation requiring the full EJB 3.2 API must include JMS 2.0"

In the fourth paragraph,

Change: "Enterprise beans must not call the javax.jms.MessageConsumer.setMessageListener or javax.jms.MessageConsumer.getMessageListener method."

To: "Enterprise beans must not call the javax.jms.MessageConsumer.setMessageListener, javax.jms.MessageConsumer.setBatchMessageListener, javax.jms.MessageConsumer.getMessageListener or javax.jms.MessageConsumer.getBatchMessageListener methods."

5.4.14 "Activation Configuration Properties"


This section introduces a list of activation configuration properties for JMS message-driven beans. An additional section should be inserted which describes the additional properties needed for batch delivery:

Insert new section: 5.4.<n> "Batch delivery" as follows:

If the JMS Message-driven bean implements the javax.jms.BatchMessageListener interface then the following activation configuration properties may be used to configure batch delivery:

  • batchSize: If set to greater than zero, messages will be delivered by calling the onMessages(Message[] messages) method. The bean class must implement javax.jms.BatchMessageListener. Messages will be delivered in batches of up to batchSize messages. The actual batch size used may be any value between one and the specified batchSize. It is invalid to specify a value greater than zero if the bean class does not implement javax.jms.BatchMessageListener.
  • batchTimeout: If batch delivery is used, this specifies the maximum number of milliseconds that the JMS provider may defer message delivery for in order to assemble a batch of messages that is as large as possible but no larger than the batch size.


 Comments   
Comment by Nigel Deakin [ 23/Nov/11 ]

This issue has now been forwarded to the EJB 3.2 expert group as EJB_SPEC-44. Please make further comments there, not here.

Comment by Nigel Deakin [ 01/May/12 ]

Following the decision to defer JMS_SPEC-36 (Allow messages to be delivered asynchronously in batches) I am going to close this issue. If changes are needed to the MDB specification in the future a new issue will be logged.

Comment by Nigel Deakin [ 01/May/12 ]

Closing as "Won'tFix" because that's the nearest resolution I can see to "withdrawn".





[JMS_SPEC-38] Allow JMS clients to specify whether a message is compressed in transit Created: 05/Aug/11  Updated: 06/Jan/12  Resolved: 06/Jan/12

Status: Closed
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: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

This issue was raised by a member of the JSR 343 Expert Group and is logged here to allow the issue to be discussed and tracked.

This is a request to allow JMS clients to define whether a message is compressed in transit, perhaps on a per-message basis or more globally.

JMS providers are currently free to decide for themselves whether to compress a message, and many do, so the question here is whether it is desirable to allow clients to control this via the API rather than via provider configuration features.



 Comments   
Comment by colincrist [ 12/Sep/11 ]

I'd say this is an administrative configuration in the provider and out of the scope of the API. Allowing each endpoint to choose makes administering a large install a headache as you need a code change to enable compression.

Better for the provider to be configured centrally to make a client compress based on username/clientID/queue/topic/wildcard

Comment by Nigel Deakin [ 06/Jan/12 ]

I don't think there's a need for this. Many providers already offer message compression. The JMS spec deliberately doesn't define the wire format of a message and so providers are free to compress messages in transit if they wish to.

In my view, message compression is best configured using global settings in the provider rather than on a per-message basis. This is because whether message compression is needed for a given message depends on the performance characteristics of the provider itself: there is a trade-off between the extra time needed to compress and decompress a large message and the time saved in sending a smaller message down the wire. This trade-off will vary from provider to provider, and so allowing the application code to directly configure whether a message is compressed would reduce its portability.

A further reason for keeping message compression as a provider-specific configuration option rather than as part of the JMS API is that it allows providers to decide for themselves what configuration options they want to provider. Some providers may not support message compression at all. Others may offer a global switch to allow message compression to be switched on or off. Others may allow message compression to be defined on a per-destination basis. Other may allow the administrator to define a size threshold above which messages will be compressed. Finally, some providers may allow the administrator to configure what compression algorithm is used. I feel this is an area where it is beneficial to allow providers to differ and offer whatever features that they believe provide best performance.

Comment by Nigel Deakin [ 06/Jan/12 ]

We've discussed this on the JSR 343 expert group and the original proposer and decided not to proceed with this proposal. I'm therefore closing this issue with a resolution of "won't fix"





[JMS_SPEC-35] Remove the use of unchecked exceptions from the JMS API as far as possible Created: 29/Jul/11  Updated: 06/Jan/12  Resolved: 06/Jan/12

Status: Closed
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: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

In JMS 1.1, almost every method in the JMS API throws a javax.jms.JMSException, which is a checked exception and so needs to be caught and handled by the application.

In practice the developer rarely knows what to do in such circumstances, and provides some generic exception handling that is not specific to JMSException. The result is to clutter the application code with boilerplate exception handling which adds little value.

In addition, the fact that so many API methods throw this checked exception makes it more difficult to construct frameworks on top of the JMS API.

It is therefore proposed that the JSR 343 Expert Group consider whether they should change the JMS API to throw unchecked rather than checked exceptions as much as possible. One simple way of achieving this would be to change javax.jms.JMSException to extend java.lang.RuntimeException instead of java.lang.Exception.

Existing applications which explicitly catch JMSException would not need to be changed.



 Comments   
Comment by rdohna [ 30/Aug/11 ]

fixed typos

Comment by Nigel Deakin [ 20/Oct/11 ]

The Java Tutorial contains the following useful discussion of when an exception should be checked or unchecked.
http://download.oracle.com/javase/tutorial/essential/exceptions/runtime.html

This includes the advice:

If a client can reasonably be expected to recover from an exception, make it a checked exception. If a client cannot do anything to recover from the exception, make it an unchecked exception.

Given that in most cases a client cannot recover from a JMSException (which is why they tend to log the exception and rethrow it), making it an unchecked exception seems appropriate in this case.

Comment by Nigel Deakin [ 20/Oct/11 ]

I've received this comment:

try {
   a{};
} catch (RuntimeException rte){
   b{};
} catch (MyException e) {
   c();
}

In JMS 1.1, if a JMSException in throw in a(), then c() will be called. However if JMSException is changed as proposed above, b() will be called. Also, the above code will not compile because c() is unreachable.

This means that we cannot guarantee that this change will never require code changes.

Comment by Nigel Deakin [ 06/Jan/12 ]

Unfortunately, as noted in the previous comment, to simply make JMSException a subtype of RuntimeException would be an incompatible change as defined in the Java EE compatibility requirements:
http://java.net/projects/javaee-spec/pages/CompatibilityRequirements
This means that this change is not allowed.

There is no reason why new exception classes cannot be defined which are subtypes of RuntimeException and which are thrown by any new methods that are added to JMS. This has been done in the proposed simplified JMS API: http://java.net/jira/browse/JMS_SPEC-64

Comment by Nigel Deakin [ 06/Jan/12 ]

Since this proposal cannot be implemented (for existing methods) without breaking Java EE compatibility requirements, it will be closed with a resolution of "won't fix".





[JMS_SPEC-46] Define standard API to create and configure a ConnectionFactory Created: 11/Aug/11  Updated: 27/Mar/12  Resolved: 27/Mar/12

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

Type: Improvement Priority: Major
Reporter: Nigel Deakin Assignee: Unassigned
Resolution: Won't Fix Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

This is a proposal to extend the JMS specification to define a standard way of instantiating and configuring connection factory objects.

Background

A connection factory is an example of an administered object. The JMS 1.1 specification establishes the convention whereby administered objects (connection factories and destinations) are not created in application code. Instead they are created by an administrator using tools specific to the JMS provider and stored in JNDI. The application code then looks up the connection factory or destination from JNDI and uses them in accordance with the JMS API.

The purpose of this is clearly stated in the specification: it is to allow everything that is non-standard and specific to a particular JMS provider to be kept out of the code itself. (See Relevant sections of the JMS 1.1 Specification below).

In the case of connection factories, this means that the application doesn't have to contain any information about how to connect to the JMS provider. For example, if the JMS provider is running on some remote server, the application doesn't contain any information about the location of the server or the protocol used to connect to it. All this information is defined when the connection factory is created by an administrator, separate from the application itself.

However the JMS specification says nothing about how the connection factory itself is created or configured, other than saying that it is done by "provider-specific facilities". All it says is that:

  • it must implement javax.jms.ConnectionFactory,
  • it must implement javax.naming.Referenceable and java.io.Serializable, so it can be stored in all JNDI naming contexts (section 4.2)
  • it is recommended that implementations "follow the JavaBeans design patterns"
  • it allows client identifier to be set (section 4.3.2)

However the specification does not define:

  • how a connection factory is instantiated
  • how the location of the server is defined
  • how client identifier is set
  • how other properties are set

Now although this omission from the JMS 1.1 specification is no doubt deliberate, it does cause some difficulties:

  • it is not possible to develop standard tools for creating connection factories (and binding them in JNDI) which work with multiple JMS providers
  • in a Java EE environment, there is no standard way of configuring the JMS requirements of a particular application
  • it is inconsistent with way in which a JDBC DataSource objects is defined, both in a Java SE and a Java EE environment. This is discussed more in How JDBC DataSource objects are configured.

Proposals

It is proposed that the way that a ConnectionFactory is created and configured be partially standardised in a manner similar to JDBC DataSource objects, as follows:

  • A ConnectionFactory implementation is a JavaBean, and may be instantiated by executing the no-arg constructor of its implementation class. For example:
ConnectionFactory cf = Class.forName("com.sun.messaging.ConnectionFactory") 
  • The JMS specification will define a set of properties which may be used to identify and describe a ConnectionFactory implementation.
Property name Type Description
description String description of this connection factory
user String user name (may be overridden when createConnection is called)
password String password corresponding to user name may be overridden when createConnection is called)
networkProtocol String network protocol used to communicate with the JMS provider
serverName String server name of the JMS provider
portNumber String port number of the JMS provider
networkProtocols String[] array of network protocols used to communicate with the JMS provider
serverNames String[] array of server names of the JMS provider
portNumbers String[] array of port numbers of the JMS provider
url String Opaque string which defines how to connect to the JMS provider
clientId String JMS client identifier
  • ConnectionFactory properties follow the convention specified for properties of JavaBeans components in the JavaBeans 1.01 Specification. ConnectionFactory implementations may augment this set with implementation-specific properties. If new properties are added, they must be given names that do not conflict with the
    standard property names.
  • ConnectionFactory implementations must provide "getter" and "setter" methods for each property they support. These properties typically are intended to be initialized before the object is bound in JNDI for subsequent use by an application.
  • ConnectionFactory properties are not intended to be directly accessible by JMS clients. This design is reinforced by defining the access methods on the implementation class rather than on the public DataSource interface used by applications. Furthermore, the object that the client manipulates can be a wrapper that only
    implements the ConnectionFactory interface. The setter and getter methods for the properties need not be exposed to the client.
  • Management tools that need to manipulate the properties of a ConnectionFactory implementation can access those properties using introspection.

Note that this gives three alternative ways to define how the connection factory should communicate with the server:

  • an opaque URL string
  • a tuple of (networkProtocol, serverName, portNumber), where networkProtocol may be omitted
  • an array of such tuples, represented here as three separate arrays

A JMS provider may support all, some or none of these alternatives.

  • If both URL and one of the other forms are supported and both are supplied, the URL is used.
  • If the single tuple (networkProtocol, serverName, portNumber) is supported, then a single-element array of tuples will also be supported

(Much of the wording above is based on section 9.4.1 DataSource properties of the JDBC 4.0 specification.)

Please also see the following additional information which has been added as separate notes below:

  • How JDBC DataSource objects are configured
  • Relevant sections of the JMS 1.1 Specification


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

How JDBC DataSource objects are configured

This section describes how, although JDBC DataSource objects are similar in concept to JMS ConnectionFactory objects, the JDBC and Java EE specifications define in much more detail how DataSource objects are created and configured than the JMS specification defines for ConnectionFactory objects.

A JMS ConnectionFactory is a factory for creating connections to a JMS provider, using the createConnection method. In JDBC, a javax.jdbc.DataSource fulfils a similar role as a factory for creating connections to a JDBC database, using the getConnection method.

Section 9.4.2 recommends that javax.jdbc.DataSource objects are stored in JNDI to allow database-specific configuration to be kept separate from the application. This much is similar to JMS.

However the JNDI specification differs from JMS in providing a lot of guidance on how to create a DataSource. Section 9.4.1 contains a whole list of standard data source properties which may be supported:

  • databaseName
  • dataSourceName
  • description
  • networkProtocol
  • password
  • portNumber
  • roleName
  • serverName
  • user

Although the specification suggests that not all DataSource implementations support all properties, it does define names for these most common properties, and specifies that when supported, they must be configurable using standard JavaBeans "setters and getters".

In addition, a DataSource may be instantiated by invoking its no-arg constructor. This isn't stated explicitly in the spec (if the DataSource were a JavaBean then a no-arg constructor would be mandatory, but the spec only states that its properties follow the conventions specified for properties of JavaBeans, not that a DataSource is itself a JavaBean) but in practice the convention that it can is well-established.

This means that a DataSource may be instantiated, given the name of the implementation class as a String, using code of the following form:

DataSource ds = Class.forName("oracle.jdbc.pool.OracleDataSource") 

Meanwhile, the Java EE 6 specification defines a DataSourceDefinition annotation and a corresponding <data-source> element which defines the following properties of a DataSource:

  • className (required)
  • name (required)
  • databaseName
  • description
  • initialPoolSize
  • isolationLevel
  • loginTimeout
  • maxIdleTime
  • maxPoolSize
  • maxStatements
  • minPoolSize
  • password
  • portNumber
  • properties
  • serverName
  • transactional
  • url
  • user

This is a longer list than is defined in JDBC, partly because the JDBC spec is older, but also because it also includes pooling properties. Perhaps of the most interest is the url property, which may be provided as an alternative to serverName and port.

Comment by Nigel Deakin [ 11/Aug/11 ]

Relevant sections of the JMS 1.1 Specification

The relevant sections of the JMS specification are given below:

Section 2.3 Administration

It is expected that JMS providers will differ significantly in their underlying messaging technology. It is also expected there will be major differences in how a provider’s system is installed and administered.

If JMS clients are to be portable, they must be isolated from these proprietary aspects of a provider. This is done by defining JMS administered objects that are created and customized by a provider's administrator and later used by clients. The client uses them through JMS interfaces that are portable. The administrator creates them using provider-specific facilities.

There are two types of JMS administered objects:

• ConnectionFactory - This is the object a client uses to create a connection with a provider.
• Destination - This is the object a client uses to specify the destination of messages it is sending and the source of messages it receives.

Administered objects are placed in a JNDI namespace by an administrator. A JMS client typically notes in its documentation the JMS administered objects it requires and how the JNDI names of these objects should be provided to it.

Section 4.2 Administered Objects

JMS administered objects are objects containing JMS configuration information that are created by a JMS administrator and later used by JMS clients. They make it practical to administer JMS applications in the enterprise.

Although the interfaces for administered objects do not explicitly depend on JNDI, JMS establishes the convention that JMS clients find them by looking them up in a namespace using JNDI.

An administrator can place an administered object anywhere in a namespace. JMS does not define a naming policy.

This strategy of partitioning JMS and administration provides several benefits:

• It hides provider-specific configuration details from JMS clients.
• It abstracts JMS administrative information into Java objects that are easily organized and administered from a common management console.
• Since there will be JNDI providers for all popular naming services, this means JMS providers can deliver one implementation of administered objects that will run everywhere.

An administered object should not hold on to any remote resources. Its lookup should not use remote resources other than those used by JNDI itself.

Clients should think of administered objects as local Java objects. Looking them up should not have any hidden side effects or use surprising amounts of local resources.

JMS defines two administered objects, Destination and ConnectionFactory.

It is expected that JMS providers will provide the tools an administrator needs to create and configure administered objects in a JNDI namespace. JMS provider implementations of administered objects should be both javax.naming.Referenceable and java.io.Serializable so that they can be stored in all JNDI naming contexts. In addition, it is recommended that these implementations follow the JavaBeans design patterns.

Section 1.4.6 Java Naming and Directory InterfaceTM (JNDI) API

JMS clients look up configured JMS objects using the JNDI API. JMS administrators use provider-specific facilities for creating and configuring these objects.

This division of work maximizes the portability of clients by delegating provider-specific work to the administrator. It also leads to more administrable applications because clients do not need to embed administrative values in
their code.

Section 4.3.2 Client Identifier

The preferred way to assign a client’s client identifier is for it to be configured in a client-specific ConnectionFactory and transparently assigned to the connection it creates.

Comment by Nigel Deakin [ 27/Mar/12 ]

I am withdrawing this proposal in favour of a simpler alternative. To avoid confusion I have logged this as a separate issue, JMS_SPEC-89





[JMS_SPEC-99] Define annotations for Java EE 7 resource configuration Created: 22/Aug/12  Updated: 10/Sep/12  Resolved: 10/Sep/12

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

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


 Description   

In the Java EE 7 specification:

Section EE.5.17.4 "JMS Connection Factory Resource Definition" states that "A JMS ConnectionFactory resource may also be defined using the JMSConnectionFactoryDefinition annotation

Section EE.5.17.5 "JMS Destination Definition" states that "A JMS Destination resource may also be defined using the JMSDestinationDefinition annotation".

These annotations need to be defined in the javax.jms package as part of JMS 2.0.



 Comments   
Comment by Nigel Deakin [ 10/Sep/12 ]

This is a duplicate of JMS_SPEC-96 and JMS_SPEC-97





[JMS_SPEC-23] Allow and specify clustered durable subscribers Created: 04/Jul/11  Updated: 09/Mar/12  Resolved: 09/Mar/12

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

Type: Improvement Priority: Major
Reporter: F.Degenaar Assignee: Unassigned
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
duplicates JMS_SPEC-40 Allow multiple consumers to be create... Resolved

 Description   

The current specification arguably disallows clustering durable subscibers by the following wording: "Only one session at a time can have a TopicSubscriber for a particular durable subscription."

At least one JMS provider (WebSphereMQ) allows multiple TopicSubscribers to the same durable subscription. The subscribers themselves basically act like receivers for a queue.

This feature helps avoiding a single point of failure.



 Comments   
Comment by Nigel Deakin [ 09/Mar/12 ]

Thank you for raising this. This is a good idea which others have proposed as well and is being considered by the expert group for inclusion in the JMS 2.0 early draft. There's a separate (subsequent) JIRA issue which contains the current proposals: JMS_SPEC-40.

I'm going to close this issue as it is a duplicate of that one. Please feel free to comment on that other issue, which will be updated as it is considered in more detail.





[JMS_SPEC-19] Support for Multi-Part Messages Created: 24/May/11  Updated: 10/May/13  Resolved: 10/May/13

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

Type: Improvement Priority: Major
Reporter: fribeiro Assignee: Unassigned
Resolution: Invalid Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: pd20-forreview-vague

 Description   

Has it ever considered by the EG to add support to multi-part messages?



 Comments   
Comment by Nigel Deakin [ 09/Mar/12 ]

Can you please provide more information about what you are suggesting? This is too vague a description to be able to review.

Nigel

Comment by fribeiro [ 10/May/13 ]

You may want to go ahead and close the issue.

Comment by Nigel Deakin [ 10/May/13 ]

Closed as requested by submitter, and because there isn't enough information to review this issue.





[JMS_SPEC-17] Durable subscription iterator Created: 24/May/11  Updated: 09/Mar/12  Resolved: 09/Mar/12

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

Type: New Feature Priority: Major
Reporter: colincrist Assignee: Unassigned
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
duplicates JMS_SPEC-18 Standard set of server JMX MBeans Open
duplicates JMS_SPEC-59 Basic metadata/management via JMS Open

 Description   

As a monitoring client I would like to list all the durable subscriptions the login is permissioned to see., i.e. the clientID, durableName and any selector.



 Comments   
Comment by Nigel Deakin [ 09/Mar/12 ]

I'm merging this proposal with two more general proposals:

JMS_SPEC-59 - which covers general non-JMX metadata queries
JMS_SPEC-18 - which covers general JMX facilities

I'm going to close this issue as a duplicate of those. Feel free to contribute comments to those issues.





[JMS_SPEC-16] Depth of messages for a durable subscription Created: 24/May/11  Updated: 09/Mar/12  Resolved: 09/Mar/12

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

Type: New Feature Priority: Major
Reporter: colincrist Assignee: Unassigned
Resolution: Duplicate Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
duplicates JMS_SPEC-18 Standard set of server JMX MBeans Open
duplicates JMS_SPEC-59 Basic metadata/management via JMS Open

 Description   

As a client I would like to get the current approximate number of pending messages for a durable subscription. All existing providers give this information via a custom API or JMX at present.



 Comments   
Comment by fribeiro [ 24/May/11 ]

My first comment on JMS_SPEC-15 also applies here.

Comment by Nigel Deakin [ 09/Mar/12 ]

I'm merging this proposal with two more general proposals:

JMS_SPEC-59 - which covers general non-JMX metadata queries
JMS_SPEC-18 - which covers general JMX facilities

I'm going to close this issue as a duplicate of those. Feel free to contribute comments to those issues.





[JMS_SPEC-10] Support for Cloud Services Created: 18/May/11  Updated: 10/May/13  Resolved: 02/Mar/12

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

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


 Description   

In addition to the vendors of on-premises software, we should hear from vendors of cloud services (like StormMQ) about any changes to the API that they think would make it easier to implement it.



 Comments   
Comment by abien [ 18/Jun/11 ]

What is the point of your suggestion? Just vendor involvement?

Comment by fribeiro [ 02/Jan/12 ]

Yes, I think it would be hear from them, as well as from the on-premises vendors already on board.

Comment by Nigel Deakin [ 02/Mar/12 ]

The JSR 343 expert group is open to suggestions for new features which will assist could services. Feel free to contact specific organisations and encourage them to get involved.

Since this isn't a specific requirement, I'm going to close this issue. However specific proposals remain welcome. If you'd simply like to discuss an issue, please raise it on the user alias.

Nigel

Comment by fribeiro [ 10/May/13 ]

You may want to go ahead and close the issue.





[JMS_SPEC-8] Add Reference to URI Scheme Created: 17/May/11  Updated: 10/May/13  Resolved: 10/May/13

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

Type: New Feature Priority: Major
Reporter: fribeiro Assignee: Unassigned
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

The IETF has published an "official" URI scheme for JMS that should probably be referred to by the next release of the spec.



 Comments   
Comment by fribeiro [ 17/May/11 ]

http://www.rfc-editor.org/rfc/rfc6167.txt

Comment by Nigel Deakin [ 12/Mar/12 ]

I'm not sure this is needed, or even appropriate given that this is a completely separate specification. However this will be raised with the expert group for possible inclusion in the JMS 2.0 public draft.

Comment by fribeiro [ 10/May/13 ]

You may want to go ahead and close the issue.

Comment by Nigel Deakin [ 10/May/13 ]

Closed at request of submitter.





[JMS_SPEC-6] Add Reference to SOAP Binding Created: 17/May/11  Updated: 10/May/13  Resolved: 10/May/13

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

Type: New Feature Priority: Major
Reporter: fribeiro Assignee: Unassigned
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

The W3C has developed an "official" SOAP binding for JMS that should probably be referred to by the next release of the spec.



 Comments   
Comment by John D. Ament [ 17/May/11 ]

Can you link to this SOAP binding?

Comment by fribeiro [ 17/May/11 ]

http://www.w3.org/TR/soapjms/

Comment by Nigel Deakin [ 02/Mar/12 ]

What would you like to see added to the JMS spec? It's not obvious that any change is needed; the document referred to is dependent on JMS, not the other way round.

I'll raise this with the expert group (which includes representatives of the organisations that proposed that document).

Comment by fribeiro [ 10/May/13 ]

You may want to go ahead and close the issue.

Comment by Nigel Deakin [ 10/May/13 ]

Closed at request of submitter. Marking as "won't fix".





[JMS_SPEC-4] Properties on Messages should follow builder pattern. Created: 11/May/11  Updated: 10/Apr/12  Resolved: 10/Apr/12

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

Type: New Feature Priority: Major
Reporter: John D. Ament Assignee: Unassigned
Resolution: Won't Fix Votes: 2
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Currently, methods such as javax.jms.Message.setBoolean return void. However, in recent years the builder pattern has grown in adoption, allowing developers to chain method calls by having the method return the object that the method was performed upon. If the property methods return these objects, then the code would look much cleaner.



 Comments   
Comment by abien [ 18/Jun/11 ]

I would change the syntax and use a withBoolean, instead of setBoolean in general. setters in Java do imply void return type.
The final call of the method build() could verify the consistency of all set values and message.

Comment by Nigel Deakin [ 28/Feb/12 ]

Are you referring to the methods for setting message properties, such as setBooleanProperty(String name, boolean value)?

I'll raise this with the expert group. Tagging for review prior to the public draft.

This is an issue of API style, but my inclination is to avoid changing this long-established API.

It might be argued that if a method such as setBooleanProperty(String name, boolean value) was to return a value, it should return the previous value of the property, just like the equivalent methods on java.util.Map and java.util.Property.

Nigel

Comment by Nigel Deakin [ 10/Apr/12 ]

Although the builder pattern is an established design pattern, the JMS API was defined a long time ago and adding new methods at this stage would simply be undesirable bloat.

I am therefore closing this issue as "won't fix".





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

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Fixed 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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-158] JMS 2.0 introduced incompatible changes to Connection.stop and close and Session.close Created: 22/Sep/14  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Issue Links:
Dependency
blocks JMS_SPEC-159 Allow stop and close to be called fro... Open
Tags: jms20-errata

 Description   

Background: JMS 1.1

The JMS 1.1 specification stated that the stop method on Connection, and the close methods on Connection, Session and MessageConsumer must not return until any message listeners have returned.

This had the unfortunate consequence of requiring that if these methods were called from a message listener on its own Connection, Session or MessageConsumer then deadlock would occur and these methods would never return.

This error in JMS 1.1 was well-known to developers of JMS 1.1 implementations. Some vendors decided (many years ago) that it was unacceptable to cause customer applications to block for ever and so took the decision to ignore the requirement that these methods block for ever when called from a message listener on its own Connection, Session or MessageConsumer.

Changes in JMS 2.0

The JMS 2.0 specification (JMS_SPEC-48) addressed this error by amending the required behaviour to avoid the possibility of deadlock. It did so in two different ways.

  • In the case of the stop method on Connection, and the close methods on Connection and Session, the requirement to block for ever when these methods were called from a message listener (on its own Connection or Session) was replaced by the requirement to throw a javax.jms.IllegalStateException.
  • However in the case of the close method on MessageConsumer, the requirement to block for ever when this method was called from a message listener (on its own MessageConsumer) was removed by allowing the close method to return normally.

The problem

The change introduced in JMS 2.0 replaces the requirement to block for ever with the requirement to throw an exception. The expert group considered that this was not an incompatible change since the old behaviour was clearly unacceptable and no application would rely on it.

However this change does force an incompatible change on those JMS vendors which, many years ago, took the unilateral decision to ignore the erroneous requirement in JMS 1.1. The new requirements of JMS 2.0 means that existing applications which called stop and close from within a message listener, and which previously worked just fine, will now encounter an exception and fail.

Although, strictly speaking, JMS vendors that ignored the original JMS 1.1 requirement were violating the specification, this was not an unreasonable thing to do given that JMS 1.1 was clearly erroneous and that no further versions of JMS were developed until JMS 2.0 over a decade later.

This means that, even though the change in JMS 2.0 was technically valid, in practice it has introduced an incompatible change for some JMS vendors which would force them to break existing applications.

The solution

It is proposed an errata be added to JMS 2.0 to state that the requirement to throw an exception is optional. JMS vendors would be allowed to decide whether these methods should throw an exception or return normally. This would allow vendors which have long allowed these methods to return normally to continue to do so, and avoid breaking existing applications.

Existing JMS 2.0 implementations would not need to change.

Since this would mean that some vendors would throw an exception and some would not, applications which relied on these methods being called from a message listener would not be portable, and the specification would need to warn of this.

(In the longer term, this lack of portability could be resolved by removing the option to throw an exception. That is the subject of a separate issue JMS_SPEC-159).



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

(These proposals are now superseded by these updated proposals)

Proposed changes

Changes to A.1.19 Clarification: use of stop or close from a message listener (JMS_SPEC-48)

Existing text

If a MessageListener’s onMessage method calls stop or close on its own
Connection, close on its own Session, or stop or close on its own JMSContext,
then the the JMS provider must throw a javax.jms.IllegalStateException.

Replacement text

In the simplified API, if a MessageListener’s onMessage method calls stop or
close on its own JMSContext, then the the JMS provider must throw a
javax.jms.IllegalStateException.

In the classic and domain-specific APIs, if a MessageListener’s onMessage
method calls stop or close on its own Connection or close on its own Session,
then the stop or close method will either fail and throw a
javax.jms.IllegalStateException, or it will succeed and close the connection.

Changes to Section 6.1.5 “Pausing delivery of incoming messages”

Existing text

A message listener must not attempt to stop its own connection as this would
lead to deadlock. The JMS provider must detect this and throw a
javax.jms.IllegalStateException.

Replacement text

In the simplified API, if the stop method is called from a message listener
on its own JMSContext then it must throw a javax.jms.IllegalStateException.

In the classic and domain-specific APIs, if the stop method is called from a
message listener on its own Connection then it will either fail and throw a
javax.jms.IllegalStateException or it will succeed and stop the connection,
blocking until all other message listeners that may have been running have
returned.

Since two alternative behaviors are permitted in this case, applications
using the classic and domain-specific APIs should avoid calling stop from
a message listener on its own Connection because this is not portable.

Changed to Section 6.1.8 “Closing a connection”

Existing text

A message listener must not attempt to close its own connection as this would
lead to deadlock. The JMS provider must detect this and throw a
javax.jms.IllegalStateException.

Replacement text

In the simplified API, if the close method is called from a message listener
on its own JMSContext then it must throw a javax.jms.IllegalStateException.

In the classic and domain-specific APIs, if the close method is called from a
message listener on its own Connection then it will either fail and throw a
javax.jms.IllegalStateException or it will succeed and close the connection,
blocking until all other message listeners that may have been running have
returned, and all pending receive calls have completed. If close succeeds and
the acknowledge mode of the session is set to AUTO_ACKNOWLEDGE, the current
message will still be acknowledged automatically when the onMessage() call
completes.

Since two alternative behaviors are permitted in this case, applications
using the classic and domain-specific APIs should avoid calling close from
a message listener on its own Connection because this is not portable.

Changes to Section 6.2.15 “Closing a session”

Existing text

A message listener must not attempt to close its own session as this would
lead to deadlock. The JMS provider must detect this and throw a
javax.jms.IllegalStateException

Replacement text

In the simplified API, if the close method is called from a message listener
on its own JMSContext then it must throw a javax.jms.IllegalStateException.

In the classic and domain-specific APIs, if the close method is called from a
message listener on its own Session then it will either fail and throw a
javax.jms.IllegalStateException or it will succeed and close the Session,
blocking until any pending receive call in progress has completed. If close
succeeds and the acknowledge mode of the session is set to AUTO_ACKNOWLEDGE,
the current message will still be acknowledged automatically when the
onMessage() call completes.

Since two alternative behaviors are permitted in this case, applications
using the classic and domain-specific APIs should avoid calling close from
a message listener on its own Session because this is not portable.

Changes to the javadocs for javax/jms/Connection.html#close():

Existing text:

When this method is invoked, it should not return until message
processing has been shut down in an orderly fashion. This means that all
message listeners that may have been running have returned, and that all
pending receives have returned.

Replacement text:

When this method is invoked, it should not return until message
processing has been shut down in an orderly fashion. This means that all
message listeners that may have been running have returned, and that all
pending receives have returned.

However if the close method is called from a message listener on its own
connection, then it will either fail and throw a
javax.jms.IllegalStateException, or it will succeed and close the connection,
blocking until all other message listeners that may have been running have
returned, and all pending receive calls have completed. If close succeeds and
the acknowledge mode of the session is set to AUTO_ACKNOWLEDGE, the current
message will still be acknowledged automatically when the onMessage() call
completes.

Since two alternative behaviors are permitted in this case, applications
should avoid calling close from a message listener on its own
connection because this is not portable.

Existing text:

A message listener must not attempt to close its own connection as this
would lead to deadlock. The JMS provider must detect this and throw a
IllegalStateException.

Replacement text:

[Delete this text]

Changes to the javadocs for javax/jms/Connection.html#stop():

Existing text:

This call blocks until receives and/or message listeners in progress have
completed.

Replacement text:

[Delete this text]

Existing text:

A call to stop must not return until delivery of messages
has paused. This means that a client can rely on the fact that none of
its message listeners will be called and that all threads of control
waiting for receive calls to return will not return with a
message until the connection is restarted. The receive timers for a
stopped connection continue to advance, so receives may time out while
the connection is stopped.

If message listeners are running when stop is invoked, the
stop call must wait until all of them have returned before
it may return. While these message listeners are completing, they must
have the full services of the connection available to them.

A message listener must not attempt to stop its own connection as this
would lead to deadlock. The JMS provider must detect this and throw a
IllegalStateException.

Replacement text:

This call blocks until receives and/or message listeners in progress have
completed. A call to stop must not return until delivery of messages
has paused. This means that a client can rely on the fact that none of
its message listeners will be called and that all threads of control
waiting for code calls to return will not return with a
message until the connection is restarted. The receive timers for a
stopped connection continue to advance, so receives may time out while
the connection is stopped.

However if the stop method is called from a message listener on its own
connection, then it will either fail and throw a
javax.jms.IllegalStateException, or it will succeed and stop the connection,
blocking until all other message listeners that may have been running have
returned.

Since two alternative behaviors are permitted in this case, applications
should avoid calling stop from a message listener on its own
Connection because this is not portable.

Changes to the javadocs for javax/jms/Session.html#close()

Existing text:

This call will block until a receive call or message listener in
progress has completed.

Replacement text:

This call will block until a receive call or message listener in
progress has completed.

However if the close method is called from a message listener on its own
Session, then it will either fail and throw a javax.jms.IllegalStateException,
or it will succeed and close the session, blocking until any pending receive
call in progress has completed. If close succeeds and the acknowledge mode
of the session is set to AUTO_ACKNOWLEDGE, the current message will still
be acknowledged automatically when the onMessage call completes.

Since two alternative behaviors are permitted in this case, applications
should avoid calling close from a message listener on its own
Session because this is not portable.

Existing text:

A MessageListener must not attempt to close its own
Session> as this would lead to deadlock. The JMS provider must
detect this and throw a IllegalStateException.

Replacement text:

[Delete this text]

Comment by Nigel Deakin [ 19/Dec/14 ]

Views are also invited on whether the same changes should be made to the new JMS 2.0 methods JMSContext#stop and JMSContext#close. The current proposal is to leave these methods unchanged since there is no need to change them, and it is better to stick with the current, unambiguous, definition.

However there is one reason why we might want to keep the simplified API consistent with the classic API, and allow stop and close to be called in the simplified API as well as in the classic API. This is if we decided that it is actually better to allow stop and close to be called than throw an exception (i.e. requiring an exception was a mistake).

If we decided that, then in JMS 2.1 we could remove the option to throw an exception (which we could reasonably argue wasn't an incompatible change to applications).

I'm attracted by this, as I've received complaints that requiring an exception to be thrown has made it harder to write applications, but unless there is clear support for this we should stick to the more limited proposals above.

Comment by chris.barrow [ 06/Jan/15 ]

I am strongly in favor of this suggestion (keep the simplified API consistent with the classic API, and allow stop and close to be called in the simplified API as well as in the classic API), for several reasons:

  1. consistency is always better
  2. the ability to call stop and close from within a message listener is a useful feature for flow control purposes (as Matthew pointed out in an e-mail discussion), or to allow remote control of an application.
  3. as a general principle we should avoid imposing unnecessary restrictions on API usage, to improve usability. I do not see any compelling reason to forbid calling Connection.stop or start from within a MessageListener, since by definition JMS implementations are in control of listener execution, so can avoid deadlocks.

Then for 2.1 we can remove the option to throw an exception.

Comment by Nigel Deakin [ 06/Jan/15 ]

Further to my comment here, and in response to feedback here, on the community mailing list, and directly to me, I'm now proposing to allow stop and close to be called in the simplified API as well as in the classic API. Here are the updated changes:

Proposed changes

Changes to A.1.19 Clarification: use of stop or close from a message listener (JMS_SPEC-48)

Existing text

If a MessageListener’s onMessage method calls stop or close on its own
Connection, close on its own Session, or stop or close on its own JMSContext,
then the JMS provider must throw a javax.jms.IllegalStateException.

Replacement text

If a MessageListener’s onMessage method calls stop or close on its own
Connection, close on its own Session, stop or close on its own JMSContext,
or stop on a JMSContext which uses the same connection,
then the stop or close method will either fail and throw a
javax.jms.IllegalStateException (for methods on Session and Connection)
or javax.jms.IllegalStateRuntimeException (for methods on JMSContext),
or it will succeed and stop or close the Connection, Session or
JMSContext as appropriate.

Changes to Section 6.1.5 "Pausing delivery of incoming messages"

Existing text

If any message listeners are running when stop is invoked, stop must wait
until all of them have returned before it may return. While these message
listeners are completing, they must have the full services of the connection
available to them.

A message listener must not attempt to stop its own connection as this would
lead to deadlock. The JMS provider must detect this and throw a
javax.jms.IllegalStateException.

Replacement text

If any message listeners are running when stop is invoked, stop must wait
until all of them have returned before it may return. While these message
listeners are completing, they must have the full services of the connection
available to them.

If the stop method is called from a message listener on its own Connection or
JMSContext, or on a JMSContext that uses the same connection, then it will
either fail and throw a javax.jms.IllegalStateException (in the case of
Connection) or javax.jms.IllegalStateRuntimeException (in the case of JMSContext),
or it will succeed and stop the connection, blocking until all other message
listeners that may have been running have returned.

Since two alternative behaviors are permitted in this case, applications
should avoid calling stop from a message listener on its own Connection or
JMSContext, or on a JMSContext that uses the same connection, because this is
not portable.

Changes to Section 6.1.8 "Closing a connection"

Existing text

A message listener must not attempt to close its own connection as this would
lead to deadlock. The JMS provider must detect this and throw a
javax.jms.IllegalStateException.

Closing a Connection, QueueConnection or TopicConnection closes its
constituent sessions, producers, consumers or queue browsers. The connection
close is sufficient to signal the JMS provider that all resources for the
connection should be released.

Closing a JMSContext closes the underlying session and any underlying producers
and consumers. If there are no other active (not closed) JMSContext objects
using the underlying connection then this method also closes the underlying
connection.

Replacement text (the first two paragraphs below are unchanged):

Closing a Connection, QueueConnection or TopicConnection closes its
constituent sessions, producers, consumers or queue browsers. The connection
close is sufficient to signal the JMS provider that all resources for the
connection should be released.

Closing a JMSContext closes the underlying session and any underlying producers
and consumers. If there are no other active (not closed) JMSContext objects
using the underlying connection then this method also closes the underlying
connection.

If a message listener attempts to close its own connection (either by calling
close on a Connection object or by calling close on a JMSContext object
which has no other active JMSContext objects using the underlying connection)
then it will either fail and throw a javax.jms.IllegalStateException (in the
case of Connection) or javax.jms.IllegalStateRuntimeException (in the case of
JMSContext), or it will succeed and close the connection, blocking until
all other message listeners that may have been running have returned, and all
pending receive calls have completed. If close succeeds and the acknowledge
mode of the session is set to AUTO_ACKNOWLEDGE, the current message will still
be acknowledged automatically when the onMessage call completes.

Since two alternative behaviors are permitted in this case, applications
should avoid calling close from a message listener on its own Connection
or JMSContext because this is not portable.

Changes to Section 6.2.15 "Closing a session"

Existing text

A message listener must not attempt to close its own session as this would
lead to deadlock. The JMS provider must detect this and throw a
javax.jms.IllegalStateException

Replacement text

If a message listener attempts to close its own session (either by calling
close on a Session object or by calling close on a JMSContext object)
then it will either fail and throw a javax.jms.IllegalStateException (in the
case of Session) or javax.jms.IllegalStateRuntimeException (in the case of
JMSContext), or it will succeed and close the session, blocking until
any pending receive call in progress has completed. If close succeeds and
the acknowledge mode of the session is set to AUTO_ACKNOWLEDGE, the current
message will still be acknowledged automatically when the onMessage call
completes.

Since two alternative behaviors are permitted in this case, applications
should avoid calling close from a message listener on its own Session
or JMSContext because this is not
portable.

Changes to the javadocs for javax/jms/Connection.html#close():

Existing text:

When this method is invoked, it should not return until message
processing has been shut down in an orderly fashion. This means that all
message listeners that may have been running have returned, and that all
pending receives have returned.

Replacement text:

When this method is invoked, it should not return until message
processing has been shut down in an orderly fashion. This means that all
message listeners that may have been running have returned, and that all
pending receives have returned.

However if the close method is called from a message listener on its own
connection, then it will either fail and throw a
javax.jms.IllegalStateException, or it will succeed and close the connection,
blocking until all other message listeners that may have been running have
returned, and all pending receive calls have completed. If close succeeds and
the acknowledge mode of the session is set to AUTO_ACKNOWLEDGE, the current
message will still be acknowledged automatically when the onMessage() call
completes.

Since two alternative behaviors are permitted in this case, applications
should avoid calling close from a message listener on its own
connection because this is not portable.

Existing text:

A message listener must not attempt to close its own connection as this
would lead to deadlock. The JMS provider must detect this and throw a
IllegalStateException.

Replacement text:

[Delete this text]

Changes to the javadocs for javax/jms/Connection.html#stop():

Existing text:

If message listeners are running when stop is invoked, the
stop call must wait until all of them have returned before
it may return. While these message listeners are completing, they must
have the full services of the connection available to them.

A message listener must not attempt to stop its own connection as this
would lead to deadlock. The JMS provider must detect this and throw a
IllegalStateException.

Replacement text: (the first paragraph below is unchanged)

If message listeners are running when stop is invoked, the
stop call must wait until all of them have returned before
it may return. While these message listeners are completing, they must
have the full services of the connection available to them.

However if the stop method is called from a message listener on its own
connection, then it will either fail and throw a
javax.jms.IllegalStateException, or it will succeed and stop the connection,
blocking until all other message listeners that may have been running have
returned.

Since two alternative behaviors are permitted in this case, applications
should avoid calling stop from a message listener on its own
Connection because this is not portable.

Changes to the javadocs for javax/jms/Session.html#close()

Existing text:

This call will block until a receive call or message listener in progress has completed. A blocked message consumer receive call returns null when this session is closed.

Replacement text: (the first paragraph below is unchanged)

This call will block until a receive call or message listener in progress has completed. A blocked message consumer receive call returns null when this session is closed.

However if the close method is called from a message listener on its own Session, then it will either fail and throw a javax.jms.IllegalStateException, or it will succeed and close the session, blocking until any pending receive call in progress has completed. If close succeeds and the acknowledge mode of the session is set to AUTO_ACKNOWLEDGE, the current message will still be acknowledged automatically when the onMessage call completes.

Since two alternative behaviors are permitted in this case, applications should avoid calling close from a message listener on its own Session because this is not portable.

Existing text:

A MessageListener must not attempt to close its own
Session as this would lead to deadlock. The JMS provider must
detect this and throw a IllegalStateException.

Replacement text:

[Delete this text]

Changes to the javadocs for javax/jms/JMSContext.html#stop():

Existing text:

If message listeners are running when stop is invoked, the stop call must wait
until all of them have returned before it may return. While these message
listeners are completing, they must have the full services of the connection
available to them.

A message listener must not attempt to stop its own JMSContext as this would
lead to deadlock. The JMS provider must detect this and throw a
IllegalStateRuntimeException

Replacement text: (the first paragraph below is unchanged)

If message listeners are running when stop is invoked, the stop call must wait
until all of them have returned before it may return. While these message
listeners are completing, they must have the full services of the connection
available to them.

However if the stop method is called from a message listener on its own
JMSContext, or any other JMSContext that uses the same connection,
then it will either fail and throw a javax.jms.IllegalStateRuntimeException,
or it will succeed and stop the connection, blocking until all other message
listeners that may have been running have returned.

Since two alternative behaviors are permitted in this case, applications
should avoid calling stop from a message listener on its own JMSContext, or
any other JMSContext that uses the same connection, because this is not
portable.

Changes to the javadocs for javax/jms/JMSContext.html#close()

Existing text:

When this method is invoked, it should not return until message processing has
been shut down in an orderly fashion. This means that all message listeners
that may have been running have returned, and that all pending receives have
returned. A close terminates all pending message receives on the connection's
sessions' consumers. The receives may return with a message or with null,
depending on whether there was a message available at the time of the close.
If one or more of the connection's sessions' message listeners is processing
a message at the time when connection close is invoked, all the facilities of
the connection and its sessions must remain available to those listeners until
they return control to the JMS provider.

Replacement text: (the first paragraph below is unchanged)

When this method is invoked, it should not return until message processing has
been shut down in an orderly fashion. This means that any message listener
that may have been running has returned, and that any pending receive call has
returned. A close terminates any pending receive call on the JMSContext's
consumers. The receive call may return with a message or with null, depending
on whether there was a message available at the time of the close. If one of
the JMSContext's message listeners is processing a message at the time when
close is invoked from another thread, all the facilities of the JMSContext
must remain available to it until it returns control to the JMS provider.

However if the close method is called from a message listener on its own
JMSContext, then it will either fail and throw a
javax.jms.IllegalStateRuntimeException, or it will succeed and close the
JMSContext. If close succeeds and the session mode of the JMSContext is set to
AUTO_ACKNOWLEDGE, the current message will still be acknowledged automatically
when the onMessage call completes.

Since two alternative behaviors are permitted in this case, applications
should avoid calling close from a message listener on its own
JMSContext because this is not portable.

Existing text:

A MessageListener must not attempt to close its own JMSContext as this would
lead to deadlock. The JMS provider must detect this and throw a
IllegalStateRuntimeException.

Replacement text:

[Delete this text]

Comment by chris.barrow [ 06/Jan/15 ]

This looks fine. Just one thing, in a few places in the replacement texts there is mention of javax.jms.IllegalStateRException. I presume that is intended to read javax.jms.IllegalStateRuntimeException.

Comment by Nigel Deakin [ 07/Jan/15 ]

Thanks for reporting this typo. I've corrected the proposed changes to say javax.jms.IllegalStateRuntimeException

Comment by Nigel Deakin [ 08/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=312.
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=312
Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/Connection.java?rev1=311&rev2=312

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

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

Comment by chris.barrow [ 08/Jan/15 ]

I have reviewed the draft spec (PDF) and the changes look fine to me.

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-157] JMS 2.0 introduced an incompatible restriction on creating two sessions per connection in Java EE Created: 02/Sep/14  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Fixed 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, 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 or which would require changes to existing applications.

However it appears that JMS 2.0 has inadvertently introduced an incompatible change related to the use of the Connection method createSession in a Java EE web or EJB application when a session already exists for that connection.

The problem

In the Java EE 6 specification, section EE 6.7 "Java Message Service (JMS) 1.1 Requirements" states that

Application components in the web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. An attempt to use the Connection object’s createSession method when an active Session object exists for that connection should be prohibited by the container. The container may throw a JMSException if the application component violates this restriction. Application client containers must support the creation of multiple sessions for each connection.

This wording states that applications "must" not attempt to create more than one session per connection in the Java EE web or EJB containers. However it only says that the container "should" prohibit this, and that it "may" throw an exception. In accordance with the generally-accepted interpretations of the words "should" and "may", this means that it is optional whether or not the createSession method throws an exception.

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

Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection.

If an application attempts to use the Connection object’s createSession method when an active Session object exists for that connection then a JMSException should be thrown.

If an application attempts to use the JMSContext object’s createContext method then a JMSRuntimeException should be thrown, since the first JMSContext already contains a connection and session and this method would create a second session on the same connection.

This wording continues to use the word "should" which keeps it optional whether or not the createSession method (or createContext method) throws an exception.

In addition to this change, the javadoc for these methods was also updated. Unfortunately the wording used was inconsistent with that in section 12.2.

The javadoc for createSession states that:

Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException will be thrown.

The words "will be thrown" make it obligatory for the createSession method to throw an exception. This introduces an additional restriction which was not in Java EE 6 (and is not in JMS 2.0 section 12.2) and inadvertently introduces an incompatible change which may cause existing applications to fail.

The corresponding javadoc for createContext contains a similar wording:

This method must not be used by applications running in the Java EE web or EJB containers because doing so would violate the restriction that such an application must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container then a JMSRuntimeException will be thrown.

This method is new in JMS 2.0 so there is no compatibility issue. Nevertheless the words "will be thrown" make it obligatory for the createContext method to throw an exception, which is inconsistent with the wording in JMS 2.0 section 12.2 which implies that throwing an exception is optional.



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

Proposed changes (superseded by updated proposals below)

JMS specification section 12.2 "Restrictions on the use of JMS API in the Java EE web or EJB container": No changes are proposed.

JMS specification section 12.3 "Behaviour of JMS sessions in the Java EE web or EJB container". Existing text:

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.

Replacement text:

The JMS API defines the following method to create a JMSContext from an
existing JMSContext. Applications must not call this method in a Java EE
web or EJB container. See section 12.2 "Restrictions on the use of JMS API
in the Java EE web or EJB container".

JMS specification section 2.8.2. "Key features of the simplified API": Existing text

Applications running in the Java EE web and EJB containers are not permitted
to create more than one active session on a connection...

Modified text: (changed words thus)

Applications running in the Java EE web and EJB containers must not
create more than one active session on a connection...

It is proposed that the javadoc for the Connection object’s three createSession methods be changed to make it consistent with the Java EE 6 specification and with JMS 2.0 section 12.2.

Javadoc for Connection.html#createSession(): Existing text

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If this
method is called in a Java EE web or EJB container when an active Session object
already exists for this connection then a JMSException will be thrown.

Replacement text: (changed word thus)

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If this
method is called in a Java EE web or EJB container when an active Session object
already exists for this connection then a JMSException may be thrown.

Javadoc for Connection.html#createSession(int): Existing text

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If this
method is called in a Java EE web or EJB container when an active Session object
already exists for this connection then a JMSException will be thrown.

Replacement text: (changed word thus)

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If this
method is called in a Java EE web or EJB container when an active Session object
already exists for this connection then a JMSException may be thrown.

Javadoc for Connection.html#createSession(boolean, int): Existing text

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If this
method is called in a Java EE web or EJB container when an active Session object
already exists for this connection then a JMSException will be thrown.

Replacement text: (changed word thus)

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If this
method is called in a Java EE web or EJB container when an active Session object
already exists for this connection then a JMSException may be thrown.

It is also proposed to make the same change to the JMSContext object’s createContext method to to make it consistent with JMS 2.0 section 12.2.

Javadoc for JMSContext.html: Existing text

Applications running in the Java EE web and EJB containers are not permitted to
create more than one active session on a connection so combining them in a single
object takes advantage of this restriction to offer a simpler API.

However applications running in a Java SE environment or in the Java EE application
client container are permitted to create multiple active sessions on the same connection.

Replacement text: (changed words thus)

Applications running in the Java EE web and EJB containers must not
create more than one active session on a connection so combining them in a single
object takes advantage of this restriction to offer a simpler API.

However applications running in a Java SE environment or in the Java EE application
client container may create multiple active sessions on the same connection.

Javadoc for JMSContext.html#createContext(int): Existing text

This method must not be used by applications running in the Java EE web or EJB containers
because doing so would violate the restriction that such an application must not attempt
to create more than one active (not closed) Session object per connection. If this method
is called in a Java EE web or EJB container then a JMSRuntimeException will be thrown.

Replacement text: (changed word thus)

This method must not be used by applications running in the Java EE web or EJB containers
because doing so would violate the restriction that such an application must not attempt
to create more than one active (not closed) Session object per connection. If this method
is called in a Java EE web or EJB container then a JMSRuntimeException may be thrown.

Comment by Nigel Deakin [ 18/Dec/14 ]

Here is an updated proposal for this issue. As with the previous proposal, this would relax from must to should the requirement for the three createSession methods to throw an exception if the application tries to create two sessions for the same connection in a Java EE web or EJB application. This change is necessary to maintain the less strict wording in the Java EE 6 specification and avoid introducing an incompatible change to createSession(boolean, int).

However this proposal leaves unchanged the requirement for the simplified API to throw an exception in the same circumstances. This requirement is already in the javadocs (and enforced by CTS). However the text in section 12.2 of the specification is inconsistent so I am proposing to change it to match the javadocs.

In both cases, the spec will continue to say that the application must not do these things, since this is the wording used in Java EE 6. Note that this is an obligation on the application, and not on the JMS implementation.

JMS specification section 12.2 "Restrictions on the use of JMS API in the Java EE web or EJB container"

Existing text:

Applications running in the Java EE web and EJB containers must not attempt
to create more than one active (not closed) Session object per connection.

  • If an application attempts to use the Connection object’s createSession
    method when an active Session object exists for that connection then a
    JMSException should be thrown.
  • If an application attempts to use the JMSContext object’s createContext
    method then a JMSRuntimeException should be thrown, since the first
    JMSContext already contains a connection and session and this method would
    create a second session on the same connection.

Replacement text (changed words thus)

Applications running in the Java EE web and EJB containers must not attempt
to create more than one active (not closed) Session object per connection.

  • If an application attempts to use the Connection object’s createSession
    method when an active Session object exists for that connection then a
    JMSException should be thrown.
  • If an application attempts to use the JMSContext object’s createContext
    method then a JMSRuntimeException must be thrown, since the first
    JMSContext already contains a connection and session and this method would
    create a second session on the same connection.

JMS specification section 2.8.2. "Key features of the simplified API"

Existing text

Applications running in the Java EE web and EJB containers are not permitted
to create more than one active session on a connection...

Modified text: (changed words thus)

Applications running in the Java EE web and EJB containers must not
create more than one active session on a connection...

Javadoc for Connection.html#createSession()

Existing text

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException will be thrown.

Replacement text:

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException may be thrown.

Javadoc for Connection.html#createSession(int)

Existing text

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException will be thrown.

Replacement text:

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException may be thrown.

Javadoc for Connection.html#createSession(boolean, int)

Existing text

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException will be thrown.

Replacement text:

Applications running in the Java EE web and EJB containers must not attempt to
create more than one active (not closed) Session object per connection. If
this method is called in a Java EE web or EJB container when an active Session
object already exists for this connection then a JMSException may be thrown.

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=313.
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=313
Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/Connection.java?rev1=312&rev2=313

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-162] Typos in section 7.3 "Asynchronous send" Created: 01/Dec/14  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

There are two minor typos in the JMS 2.0 specification, section 7.2 "Asynchronous send".

In the third bullet point, change "synchronously" to "asynchronously using"

In the fourth bullet point, change "synchronously" to "asynchronously".



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

Changes to section 7.3. Asynchronous send

Existing text:

  • In the domain-specific API for point-to-point messaging a QueueSender may be used to send a message synchronously any of the methods inherited from MessageProducer and listed above.
  • In the domain-specific API for pub/sub messaging a TopicPublisher may be used to send a message synchronously using any of the methods inherited from MessageProducer and listed above.

Replacement text:

  • In the domain-specific API for point-to-point messaging a QueueSender may be used to send a message asynchronously using any of the methods inherited from MessageProducer and listed above.
  • In the domain-specific API for pub/sub messaging a TopicPublisher may be used to send a message asynchronously using any of the methods inherited from MessageProducer and listed above.
Comment by Nigel Deakin [ 07/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=311.
Latest PDF at https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/specification/word/JMS20.pdf

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-163] Javadoc for JMSContext#setClientID contains obsolete MessageContext reference Created: 01/Dec/14  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

The javadoc for JMSContext#setClientID contains an obsolete mention of MessageContext. This should be changed to JMSContext



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

Changes to javadoc for JMSContext#setClientID

Existing text:

Alternatively, a client can set the client identifier for the MessageContext's connection
using a provider-specific value.

Replacement text:

Alternatively, a client can set the client identifier for the JMSContext's connection
using a provider-specific value.

Comment by Nigel Deakin [ 07/Jan/15 ]

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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-161] serialVersionUID of JMSException has changed from JMS 1.1 to JMS 2.0 Created: 19/Nov/14  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Issue Links:
Related
is related to MQ-359 serialVersionUID of JMSException has ... Open
Tags: jms20-errata

 Description   

The serialVersionUID of javax.jms.JMSException has changed from JMS 1.1 to JMS 2.0, which means that if an instance of this exception is serialized using JMS 1.1 it cannot be deserialized using JMS 2.0 or vice versa.



 Comments   
Comment by Nigel Deakin [ 19/Nov/14 ]

Although these classes are defined in the JMS specification, their implementation is, strictly speaking, part of the RI. Fixing this issue will not require a revision to the spec.

Comment by Nigel Deakin [ 25/Nov/14 ]

Now fixed in the reference implementation. See MQ-359 for fix details.

This issue will be updated when the new API jar is released.

Comment by Nigel Deakin [ 09/Dec/14 ]

A new JMS 2.0 API jar containing this fix has been released to Maven Central at
http://search.maven.org/#artifactdetails%7Cjavax.jms%7Cjavax.jms-api%7C2.0.1-b01%7Cjar
This is a release candidate (hence the b01 suffix), for the purposes of testing.

The final release of this jar will occur at the same time as the JMS 2.0 errata release.

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the release of the JMS 2.0.1 API jar that accompanied the JMS 2.0 rev A maintenance release





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

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Fixed 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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-165] Error in javadoc for Connection#stop and JMSContext#stop Created: 08/Jan/15  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 1.1, 2.0
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

The JMS 1.1 javadocs for Connection#stop contains the following text:

This call blocks until receives and/or message listeners in progress have completed.

The same text is found in the JMS 2.0 javadocs for Connection#stop and for JMSContext#stop.

This text is incorrect because it suggests that the call to stop is required to block until all calls to receive have returned. There is no mention of this requirement in the specification itself and it is contradicted by the text that follows it in the javadocs for Connection#stop:

A call to stop must not return until delivery of messages has paused. This means that a client can rely on the fact that none of its message listeners will be called and that all threads of control waiting for receive calls to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance, so receives may time out while the connection is stopped.

This means that:

  • a call to stop does not force all pending receives to return prematurely.
  • a call to stop is not required to block until all pending receives reach their timeout period (especially as that might be infinite)
  • after the call to stop has returned, pending receives will continue to block until they either (1) reach their timeout and return null or (2) the connection is restarted and a message becomes available, whichever occurs first.

It is suggested that, to keep things simple, we don't try to completely rewrite this but simply delete the incorrect sentence. Note that the requirement to block until message listeners have returned is already covered by the sentence:

If message listeners are running when stop is invoked, the stop call must wait until all of them have returned before it may return. While these message listeners are completing, they must have the full services of the connection available to them.



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

Proposed change to Javadocs for Connection#stop

Existing text:

This call blocks until receives and/or message listeners in progress have completed.

Proposed text:

[Delete this text]

Proposed change to Javadocs for JMSContext#stop

Existing text:

This call blocks until receives and/or message listeners in progress have completed.

Proposed text:

[Delete this text]

Comment by Nigel Deakin [ 09/Jan/15 ]

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=314
Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/Connection.java?rev1=313&rev2=314

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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-164] Typos in section 7.3.5 and 12.2: Change Session to MessageProducer Created: 02/Jan/15  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

JMS 2.0 section 7.3.5. "Restrictions on usage in Java EE" and section 12.2 "Restrictions on the use of JMS API in the Java EE web or EJB container" contain references to various send methods. The spec states that these are on javax.jms.Session when they are actually on javax.jms.MessageProducer.

Changes to 7.3.5. "Restrictions on usage in Java EE"

Existing text

  • javax.jms.Session method send(Message message, CompletionListener completionListener)
  • javax.jms.Session method send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)
  • javax.jms.Session method send(Destination destination, Message message, CompletionListener completionListener)
  • javax.jms.Session method send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)

Replacement text

  • javax.jms.MessageProducer method send(Message message, CompletionListener completionListener)
  • javax.jms.MessageProducer method send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)
  • javax.jms.MessageProducer method send(Destination destination, Message message, CompletionListener completionListener)
  • javax.jms.MessageProducer method send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)

Changes to 12.2 "Restrictions on the use of JMS API in the Java EE web or EJB container"

Existing text

  • javax.jms.Session method send(Message message, CompletionListener completionListener)
  • javax.jms.Session method send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)
  • javax.jms.Session method send(Destination destination, Message message, CompletionListener completionListener)
  • javax.jms.Session method send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)

Replacement text

  • javax.jms.MessageProducer method send(Message message, CompletionListener completionListener)
  • javax.jms.MessageProducer method send(Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)
  • javax.jms.MessageProducer method send(Destination destination, Message message, CompletionListener completionListener)
  • javax.jms.MessageProducer method send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive, CompletionListener completionListener)


 Comments   
Comment by Nigel Deakin [ 07/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=309.
Latest PDF at https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/specification/word/JMS20.pdf

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-140] Assumptions over Destination name within TCK Created: 05/Nov/13  Updated: 05/Nov/13  Resolved: 05/Nov/13

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

Type: Improvement Priority: Major
Reporter: mbwhite Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

When running the tck



 Description   

The Session object for example has createQueue() and createTopic() methods - both taking a string 'name' that provider-specific. The Queue and Topic objects both have methods that can get this name.

The TCK includes a check that gets this and confirms that what is passed in on create is the same as what is got. Not unreasonable; however the TCK has made an assumption of the format of the string used to set. This might not be valid.



 Comments   
Comment by Nigel Deakin [ 05/Nov/13 ]

Sounds a fair comment, particularly if this is a new test in JMS 2.0.

Sorry to be bureaucratic, but if you think the TCK is incorrect can you please take this up directly with the organisation which supplied you with the TCK? You should have the necessary contact details at Java partner Engineering (part of Oracle). You don't need to log these in JIRA first. Email me directly if you need help finding the right contact. nigel.deakin@oracle.com

Comment by mbwhite [ 05/Nov/13 ]

Thanks for the comment - wanted to raise that to see if it sounded reasonable. In this case the TCK supplies something like "QueueNameOne" - and a provider may just say sorry that isn't valid for various reasons.. It could then have to treat it as 'shorthand' or abbreviation. Therefore the string returned could be different but in valid 'providerSyntax'...

No you're right to be bureaucratic - this should be a TCK issue.

Comment by mbwhite [ 05/Nov/13 ]

As commented by Nigel this should raised as TCK issue.





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

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: None
Fix Version/s: JMS 2.0 rev A

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Fixed 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.

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-119] Remove reference to password alias Created: 26/Apr/13  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

The JMS 2.0 specification, section 12.4.3 "Injection syntax" includes an example of the use of password aliases in Java EE. Although password aliases were discussed for Java EE they were not included in the final release, so the example should be removed.



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

Proposed change

In the JMS 2.0 specification, section 12.4.3 "Injection syntax", delete the following text:

Since it is undesirable to hardcode clear text passwords in an application, the password may be specified as an alias:

@Inject
@JMSPasswordCredential(
   username="admin",
   password="${ALIAS=myAdminPassword}")
private JMSContext context;

The use of a password alias allows the password to be defined in a secure manner separately from the application. See the Java EE 7 platform specification for more information on password aliases.

Comment by Nigel Deakin [ 02/Dec/14 ]

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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-122] Typos in javadocs for ConnectionFactory.createContext Created: 08/May/13  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: None
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

1. There's a typo in the javadocs for ConnectionFactory.createContext(int sessionMode)

In the paragraph "In a Java EE web or EJB container, when there is an active JTA transaction in progress: ", change:

Since the argument is ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

to:

Since the argument is ignored, developers are recommended to use createContext(), which has no arguments, instead of this method.

2. There's a typo in the javadocs for ConectionFactory.createContext(String userName, String password, int sessionMode):

In the paragraph "In a Java EE web or EJB container, when there is an active JTA transaction in progress: ", change:

Since the argument is ignored, developers are recommended to use createSession(), which has no sessionMode parameter, instead of this method.

to:

Since the argument is ignored, developers are recommended to use createContext(String userName, String password), which has no sessionMode parameter, instead of this method.



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

Proposed changes to ConnectionFactory#createContext(int sessionMode):

Existing text

Since the argument is ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

Replacement text

Since the argument is ignored, developers are recommended to use createContext() instead of this method.

Proposed changes to ConnectionFactory#createContext(String userName, String password, int sessionMode):

Existing text

Since the argument is ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

Replacement text

Since the argument is ignored, developers are recommended to use createContext(String userName, String password) instead of this method.

Comment by Nigel Deakin [ 12/Jan/15 ]

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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-125] Define whether a JMS provider should call reset after sending a BytesMessage asynchronously Created: 17/May/13  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Issue Links:
Related
is related to JMS_SPEC-166 Define that the JMS provider should c... Open
Tags: jms20-errata

 Description   

This issue concerns the behaviour of the JMS provider when it sends a BytesMessage.

The spec is not clear on what state the body of a BytesMessage is left in after it has been sent. We're talking about the message object in the sending program, not in the receiving program.

A JMS 2.0 vendor has asked for the behaviour to be clarified for async send. However this issue will discuss the behaviour for both async and sync send.

There are three possibilities:

1. The JMS provider leaves the body in write-only mode with the stream positioned at the end. That would allow the application to send a message, append additional data to the message body, and send it a second time. An application which wanted to read the message body would have to call reset.

2. The JMS provider leaves the BytesMessage in read-only with the stream positioned at the start. To achieve this the send method would need to call reset before returning.

3. Leave the behaviour undefined.

This issue applies to both synchronous and asynchronous send. In the sync case the issue is what state the message is left in after the call to send returns. In the async case the issue is what state the message is in when the CompletionListener callback is performed. Let's consider these separately.

Asynchronous send

Option 1 (leave the body in write-only mode with the stream positioned at the end):

  • It is not practically possible for a JMS provider to implement this correctly. This is because of the need to support the case where the JMS provider is used to send a message whose implementation is not its own (as required by JMS 2.0 section 3.12). In that case the JMS provider must use the public API to read the data from the "foreign" message. After it has done so the message would be in read-only mode, with the stream positioned at the end. The only way to change the message to write-only mode would be to call reset, but that would position the stream back at the start.

Option 2 (leave the body in read-only mode with the stream positioned at the start).

  • This is the current de facto spec requirement for async send. This is because there is a JMS 2.0 TCK test which sends a BytesMessage asynchronously and which attempts to read the body of the message object passed to the CompletionListener. without calling reset. All existing JMS 2.0 providers will have passed this test.
  • There is also a clear use case for this option, since It is expected that a CompletionListener callback method may want to read the message in order to identify the message that was successfully sent.

Option 3 (leave the behaviour undefined).

  • This is undesirable because the only things a portable application application could do would be to call reset and read the message, or call clearBody to clear it and re-write it from scratch. If a JMS provider left the body in write-only mode with the stream positioned at the end, and the application took advantage of this to append to the body, then the application would not be portable.

Proposal: It is therefore proposed to update the JMS 2.0 specification to require the behaviour described in option 2: when a BytesMessage is sent asynchronously, the message object that was sent must be set to be read-only with the stream positioned at the start prior to calling the CompletionListener. To achieve this the send method would need to call reset before returning.

Synchronous send

JMS 1.1 was not specific about this and different vendors already adopt different behaviour. There are no TCK tests which rely on a specific behaviour. It is therefore probably too late to define more specific behaviour, especially as this has not been reported as an issue by users or vendors.

In practice I would suggest that for a synchronous send there is little reason for a sending application to want to read a the body of a BytesMessage after it has been sent.

Nevertheless, for consistency, we should perhaps change the spec to recommend that when a message is sent synchronously, the provider should call reset before the send() returns. But this will need to remain a recommendation since existing JMS 1.1 providers may have interpreted this differently, making it too late to standardise this.

Proposal It is proposed to update the JMS 2.0 specification to recommend, but not require, that the provider should call reset before the send() returns, and to add a warning that portable applications must not make assumptions about what state the message is in.



 Comments   
Comment by John D. Ament [ 21/May/13 ]

What is the use case for trying to read data from a BytesMessage that you just sent?

Comment by Nigel Deakin [ 22/May/13 ]

The reason the Message is passed to the CompletionListener is to allow it to determine which message has been sent (e.g. there may be more than one incomplete send). To do that it might need to read the message.

This is a somewhat obscure use case (though it came up in a TCK test) but we have the opportunity to define the required behaviour here and so should take it.

Comment by Nigel Deakin [ 09/Dec/14 ]

Proposed changes (supersed by updated proposal below)

javadoc for BytesMessage: Existing text:

When the message is first created, and when clearBody is called, the body of
the message is in write-only mode. After the first call to reset has been
made, the message body is in read-only mode.

After a message has been sent, the client that sent it can retain and modify
it without affecting the message that has been sent. The same message object
can be sent multiple times.

When a message has been received, the provider has called reset so that the
message body is in read-only mode for the client.

Replacement text: (new words marked *thus)

When the message is first created, and when clearBody is called, the body of
the message is in write-only mode. After the first call to reset has been
made, the message body is in read-only mode.

After a message has been sent synchronously, it is recommended that the
provider has called reset so that the message body is in read-only mode.

After a message has been sent asynchronously, the provider must call reset
prior to invoking the CompletionListener so that the message body is in
read-only mode. This means that the message passed to the
CompletionListener may be read without the application needing to call
reset.

In both cases, after a message has been sent (a synchronous send has returned
or an asynchronous send has completed and the CompletionListener has been
invoked), the client that sent it can retain and modify it without affecting
the message that has been sent. The same message object can be sent multiple
times.

When a message has been received, the provider has called reset so that the
message body is in read-only mode for the client.

Comment by mbwhite [ 09/Dec/14 ]

A side issue this raises is if the message object reference by the completion listener is the same object as referenced by the thread that sending the message.

Another option would be suggest that the message that is passed to the completion listener be a clone in read-only mode. This would let the main thread retain the message in write-only.

The implication as well is that behavior with 'foreign' messages is identical to 'own' messages. Reasonable - but would be worth adding in the messaging section.

Comment by Nigel Deakin [ 19/Dec/14 ]

Updated proposal

Here's an updated proposal, drawn more narrowly. It mentions only async send, and uses wording which would not prevent the message passed to the completion listener being a clone, without explicitly saying that it can be.

In the javadoc for BytesMessage, 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 BytesMessage is sent asynchronously, the provider must call reset
on the BytesMessage passed to the CompletionListener. This means that the
CompletionListener can read the message body without needing to call
reset.

Comment by Nigel Deakin [ 09/Jan/15 ]

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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-133] Update javadoc comments for QueueConnection#createQueueSession and TopicConnection#createTopicSession Created: 19/Aug/13  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

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

Tags: jms20-errata

 Description   

The javadoc comments for QueueConnection#createQueueSession and TopicConnection#createTopicSession should be updated to match those for Connection#createSession (mutatis mutandis), by describing the required behaviour in the various Java EE containers etc.



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

Here are the proposed changes.

javadoc for QueueConnection#createQueueSession

It is proposed the existing javadoc for this method is replaced by a copy of the javadoc for Connection#createSession (after applying the changes for JMS_SPEC-155 and JMS_SPEC-157), with the following modifications

  • The first paragraph "This method has been superseded by...instead of this one" is omitted.
  • "Creates a Session object" is changed to "Creates a QueueSession object"
  • "Returns: a newly created queue session" is changed to "Returns: a newly created QueueSession"
  • "if the Connection object fails to create a session" is changed to "if the QueueConnection object fails to create a QueueSession"
  • In the section "See Also:", the references to createSession(int), createSession() are omitted.

Existing text:

Creates a QueueSession object.

Parameters:

transacted - indicates whether the session is transacted

acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.

Returns:

a newly created queue session

Throws:

JMSException - if the QueueConnection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

Replacement text:

Creates a QueueSession object, specifying transacted and acknowledgeMode.

The effect of setting the transacted and acknowledgeMode arguments depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and acknowledgeMode arguments also depends on whether or not there is an active JTA transaction in progress.

In a Java SE environment or in the Java EE application client container:

  • If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored.
  • If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below.

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

  • Both arguments transacted and acknowledgeMode are ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the session's commit or rollback methods. Since both arguments are ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

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 Session.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 Session.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.

Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException may be thrown.

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.

Returns:

a newly created QueueSession

Throws:

JMSException - if the QueueConnection object fails to create a QueueSession due to some internal error, lack of support for the specific transaction and acknowledgement mode, or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection.

Since:

JMS 1.1

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

javadoc for TopicConnection#createTopicSession

It is proposed the existing javadoc for this method is replaced by a copy of the javadoc for Connection#createSession (after applying the changes for JMS_SPEC-155 and JMS_SPEC-157), with the following modifications

  • The first paragraph "This method has been superseded by...instead of this one" is omitted.
  • "Creates a Session object" is changed to "Creates a TopicSession object"
  • "Returns: a newly created topic session" is changed to "Returns: a newly created TopicSession "
  • "if the Connection object fails to create a session" is changed to "if the TopicConnection object fails to create a TopicSession"
  • In the section "See Also:", the references to createSession(int), createSession() are omitted.

Existing text:

Creates a TopicSession object.

Parameters:

transacted - indicates whether the session is transacted

acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.

Returns:

a newly created topic session

Throws:

JMSException - if the TopicConnection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

Replacement text:

Creates a TopicSession object, specifying transacted and acknowledgeMode.

The effect of setting the transacted and acknowledgeMode arguments depends on whether this method is called in a Java SE environment, in the Java EE application client container, or in the Java EE web or EJB container. If this method is called in the Java EE web or EJB container then the effect of setting the transacted} and acknowledgeMode arguments also depends on whether or not there is an active JTA transaction in progress.

In a Java SE environment or in the Java EE application client container:

  • If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored.
  • If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below.

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

  • Both arguments transacted and acknowledgeMode are ignored. The session will participate in the JTA transaction and will be committed or rolled back when that transaction is committed or rolled back, not by calling the session's commit or rollback methods. Since both arguments are ignored, developers are recommended to use createSession(), which has no arguments, instead of this method.

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 Session.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 Session.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.

Applications running in the Java EE web and EJB containers must not attempt to create more than one active (not closed) Session object per connection. If this method is called in a Java EE web or EJB container when an active Session object already exists for this connection then a JMSException may be thrown.

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.

Returns:

a newly created TopicSession

Throws:

JMSException - if the TopicConnection object fails to create a TopicSession due to some internal error, lack of support for the specific transaction and acknowledgement mode, or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection.

Since:

JMS 1.1

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

Comment by Nigel Deakin [ 09/Jan/15 ]

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

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

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-128] Typo in section 4.1.4 "Queue" Created: 06/Jun/13  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

Type: Bug Priority: Major
Reporter: Nigel Deakin Assignee: Nigel Deakin
Resolution: Fixed 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...

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





[JMS_SPEC-103] A JMS 2.0 resource adapter needs to be able to include cluster name in a generated subscription name Created: 29/Oct/12  Updated: 14/Nov/12  Resolved: 14/Nov/12

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

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

Issue Links:
Dependency
depends on JMS_SPEC-73 Define how messages from a topic are ... Open
blocks MQ-230 Enhance JMSRA to include cluster name... Closed
Tags: pd20-forreview-minor

 Description   

The draft JMS 2.0 specification, chapter 12.1. "ActivationSpec properties" states that:

If a durable subscription is specified but subscriptionName is not specified then the resource adapter will set the name of the durable subscription to be a name which is unique to the deployed MDB.

The intention of this feature is to allow the resource adapter to automatically generate a subscription name automatically which will be different for each deployed MDB but the same for each instance in the cluster. This instances of the same deployed MDB across the whole cluster to share the work of processing messages from the same subscription.

However if the same JMS provider is being used by two different application server clusters, and the two clusters are using the same MDB name, then this would cause the two clusters to share the same subscription which is undesirable.

To avoid this, the subscription name generated by the resource adapter should be composed of (1) a name which uniquely identifies the deployed MDB within thin the cluster as well as (2) a name which uniquely identifies the application server cluster.

The JMS specification needs to be extended to cover (2)



 Comments   
Comment by Nigel Deakin [ 29/Oct/12 ]

This will also require a change to the EJB 3.2 specification which contains a similar definition of what the container does it the subscriptionName property is not set.

Implementing this will require a change to the Java EE specification to make the name of the cluster available.

Comment by Nigel Deakin [ 29/Oct/12 ]

This is an extension of issue JMS_SPEC-73

Comment by Nigel Deakin [ 14/Nov/12 ]

I'm closing this issue as a duplicate of JMS_SPEC-73 because that issue is still open and it is best to keep this as a single open issue.





[JMS_SPEC-102] Make JMSConsumer.receivePayload methods consistent with Message.getBody Created: 26/Oct/12  Updated: 20/Mar/13  Resolved: 20/Mar/13

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0PD
Fix Version/s: 2.0PD, 2.0

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

Issue Links:
Dependency
depends on JMS_SPEC-101 New methods Message.getBody(Class<T> ... Resolved
blocks MQ-228 Implement new name and behaviour for ... Closed
Tags: pd20-added

 Description   

JMS_SPEC_64 introduced a new interface JMSConsumer for JMS 2.0. This has methods receivePayload(Class<T> c), receivePayload(Class<T> c, long timeout) and receivePayloadNoWait(Class<T> c).

JMS_SPEC-101 will introduce a new method getBody(Class<T> c).

If JMS_SPEC-101 is agreed then the definition of receivePayload(Class<T> c), receivePayload(Class<T> c, long timeout) and receivePayloadNoWait(Class<T> c) should be amended to make it consistent with the definition of getBody(Class<T> c). Specifically, these methods should allow the specified class to be any type to which the message payload can be assigned. In addition, these methods should throw a MessageFormatException rather than a ClassCastException if the message payload cannot be assigned.

In addition, the name of these method should be changed to receiveBody(Class<T> c), receiveBody(Class<T> c, long timeout) and receiveBodyNoWait(Class<T> c) since the word "payload" is inconsistent with the term "body" which is used in JMS 1.1.



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

In addition, all references to "payload" which were introduced in the JMS 2.0 spec should be changed to "body". (The JMS 1.1 spec does not use the word "payload", but uses the word "body" consistently, including in the names of methods such as clearBody().

Comment by Nigel Deakin [ 30/Oct/12 ]

Please also consider whether to simply change the names of these methods to just "receive", since there would be no clash with the existing receive methods.

Comment by nwright [ 12/Nov/12 ]

I like JMSConsumer.receiveBodyX(Class<T> c).

RE changing these methods to just "receive": I do not think we should move to JMSConsumer.receiveX(Class<T> c) as this is potentially confusing - it looks to me as if the whole message including headers would be delivered with this method. Better to keep the 'Body' in the method name.

Comment by Nigel Deakin [ 16/Nov/12 ]

The API and specification have now been updated with these changes. The new method names are receiveBody(Class<T> c), receiveBody(Class<T> c, long timeout) and receiveBodyNoWait(Class<T> c). Please see the JMS 2.0 API docs for details.





[JMS_SPEC-60] Obscurity setting special JMSHeaders Created: 17/Nov/11  Updated: 22/Nov/11  Resolved: 22/Nov/11

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

Type: Improvement Priority: Minor
Reporter: koen.serneels Assignee: Unassigned
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
is duplicated by JMS_SPEC-34 Calling setJMSDeliveryMode or setJMSP... Resolved

 Description   

Currently it is specced that some headers can only set by "send or publish" method.
This is very confusing. For example someone not knowing about this might be tempted to set JMSPriority on a message.
This will not trigger any exception, but in the end be completely ignored if send by he regular send method (.send(message)) instead of the overloaded send(message, deliveryMode, priority, timeToLive).
The question is; why are these headers mutable on the javax.jms.Message in the first place?



 Comments   
Comment by rdohna [ 21/Nov/11 ]

We assume that the setters are there for cross-provider posting, i.e. a client consumes a message from a destination bound to one JMS provider (say Glassfish MQ) and resends it to a destination bound to another JMS provider (say Active MQ). The outgoing provider may want to set the priority of that message object, while it doesn't know which implementation it is.

But you are right: It's very confusing.

Comment by Nigel Deakin [ 22/Nov/11 ]

Changing Issue Type to "Improvement"
Changing priority to "Low priority"

Comment by Nigel Deakin [ 22/Nov/11 ]

This issue is a duplicate of JMS_SPEC-34

I've added some additional information to JMS_SPEC-34 which explains why these methods are needed and confirms that the javadoc will be clarified.

I'll close this issue as a duplicate. Feel free to continue any discussion on JMS_SPEC-34

Comment by Nigel Deakin [ 22/Nov/11 ]

Corrected "Affects version" to 1.1.





[JMS_SPEC-167] JMS 2.0: Session javadoc should mention consumer.close is allowed outside thread of control Created: 22/Jan/15  Updated: 14/May/15  Resolved: 14/May/15

Status: Closed
Project: jms-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: JMS 2.0 rev A

Type: Bug Priority: Minor
Reporter: chris.barrow Assignee: Nigel Deakin
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: jms20-errata

 Description   

The class level javadoc for Session contains the following paragraph (my bolding):

Once a connection has been started, any session with one or more registered message listeners is dedicated to the thread of control that delivers messages to it. It is erroneous for client code to use this session or any of its constituent objects from another thread of control. The only exception to this rule is the use of the session or connection close method.

The last sentence should be augmented to include message consumer close since from JMS 2.0 that method is now explicitly allowed to be called from another thread (see JMS_SPEC-48 and MessageConsumer.close javadoc). Moreover, it should not really mention connection close because that is irrelevant (the connection is not a constituent object of the Session). Suggested rewording for the last sentence:

The only exceptions to this rule are the use of the session and message consumer close methods

.



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

I don't think the spec says that you are allowed to call MessageConsumer#close from outside the thread of control, though perhaps it should.

JMS_SPEC-48 and MessageConsumer.close javadoc say you can call this method from a message listener on its own consumer, but in that case it would still be called from the thread of control.

I suppose the connection close method is mentioned because it implicitly closes the session(s), and so could be considered to be "using this session".

Comment by Nigel Deakin [ 22/Jan/15 ]

Added to the list for JMS 2.1

Comment by chris.barrow [ 27/Jan/15 ]

My remark about being allowed to call MessageConsumer#close from any thread is based on the following:

  • from the javadoc:

    This method is the only {@code MessageConsumer} method that can be called concurrently.

  • from a comment in MS_SPEC-48 saying

    The JMS EG has agreed to revise the behaviour of consumer close to:...Allowing a consumer to be closed from any thread, even if it isn't the thread of control

Did I misunderstand?

Comment by Nigel Deakin [ 27/Jan/15 ]

Updated: Thanks for the follow-up. Looks like it was me who misunderstood. I agree with your proposal for the following reasons:

1. JMS 2.0 section 8.8 "closing a consumer" already says

close is the only method on a consumer that may be invoked from a thread of control separate from the one which is currently controlling the session.

So this change simply updates the javadocs for Session to say the same thing.

2. MessageConsumer.close contains the words words "This method is the only MessageConsumer method that can be called concurrently" in, which were added in JMS 2.0.

That sentence isn't very clear, but Session.close, has had identical wording since JMS 1.1, and I believe it is intended to mean that the method doesn't have to be called from the "thread of control".

3. Closing a session implicitly closes all consumers, so if session close can be called from outside the "thread of control" then it is reasonable to expect the same for consumer close.

So I agree with your proposal to amend the Session javadoc.

I'll see if we can fit it into the JMS 2.0 errata.

Comment by chris.barrow [ 27/Jan/15 ]

OK thanks.

Comment by Nigel Deakin [ 12/Feb/15 ]

Proposed changes to the class javadoc for Session

Existing text:

Once a connection has been started, any session with one or more registered message listeners is dedicated to the thread of control that delivers messages to it. It is erroneous for client code to use this session or any of its constituent objects from another thread of control. The only exception to this rule is the use of the session or connection close method.

Replacement text:

Once a connection has been started, any session with one or more registered message listeners is dedicated to the thread of control that delivers messages to it. It is erroneous for client code to use this session or any of its constituent objects from another thread of control. The only exception to this rule is the use of the session or message consumer close method.

Comment by Nigel Deakin [ 12/Feb/15 ]

Updated source

The draft JMS 2.0 javadocs can be viewed at
https://jms-spec.java.net/2.0RevA-SNAPSHOT/apidocs/index.html

Updated source for javax.jms.Session can be viewed at, and downloaded from,
https://java.net/projects/jms-spec/sources/repository/content/jms2.0a/src/main/java/javax/jms/Session.java?rev=328

Diffs can be viewed at
https://java.net/projects/jms-spec/sources/repository/diff/jms2.0a/src/main/java/javax/jms/Session.java?rev1=327&rev2=328

Comment by chris.barrow [ 12/Feb/15 ]

Thanks, looks good.

Comment by Nigel Deakin [ 14/May/15 ]

Fixed in the JMS 2.0 rev A maintenance release





Generated at Tue May 31 11:22:43 UTC 2016 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.