On 13/03/2013 16:38, Nigel Deakin wrote:
> With the JMS 2.0 final release imminent, I have been trying to minimise the changes that we make to the API. The only
> changes I think we should make at this stage are corrections to new features.
>
> There is one new feature that unfortunately I think we need to change. This is the new Java EE connection factory and
> destination definition annotations and the corresponding deployment descriptor elements.
>
> As I've explained before I see this as essentially a Java EE feature since they are defined in the Java EE platform spec
> (section EE.5.19 "Resource Definition and Configuration" rather than in the JMS spec. However since the annotations are
> defined as part of the JMS API this expert group is involved. (I think this unclear responsibility is why we're only
> spotting bugs in the spec at this late stage),
>
> Here's a brief summary:
>
> Following recent feedback from the JCA spec lead and others I have discovered that we need to change the
> JMSConnectionFactoryDefinition and JMSDestinationDefinition annotations to allow the interface name to be specified as
> well as the implementation class name. Instead of defining an additional attribute interfaceName which can be set to
> javax.jms.Queue, javax.jms.QueueConnectionFactory etc I propose we replace these two annotations with five new
> annotations, one for each interface.
I had no comments from the community, but several comments from colleagues which have led me to revise (and simplify)
this change.
Here's a reminder of the issue: the JMSConnectionFactoryDefinition and JMSDestinationDefinition annotations currently
have a mandatory element className which needs to be set to the required JMS interface. However there are two problems
with this: (1) className is not an appropriate name given that it is actually the interface name that must always be
specified, not the implementation class name. (2) Sometimes specifying the interface name is not enough information and
the implementation class name is required as well.
The obvious fix is to add a new element interfaceName which must be set to the JMS interface required. In my email
yesterday I proposed replacing the existing two annotations with five annotations, one for each JMS resource interface.
This would remove the need to explicitly specify instanceName.
However I have realised that this change would have required changes to the "composite" annotations
JMSConnectionFactoryDefinitions and JMSDestinationDefinitions, which are needed to wrap multiple occurrences of the same
class-level annotation. We would have needed to introduce five composite annotations, one for each of the new
annotations, or else have multiple array elements under the existing composite annotations. In either case the
additional complexity would probably outweigh the simplification offered by not having to specify interfaceName. This
also makes this change bigger than I think is prudent at this late stage.
I am therefore abandoning yesterday's proposal and instead I propose we simply add interfaceName to the existing
annotations and amend the description of className and resourceAdapter as follows.
In the case of JMSConnectionFactoryDefinition I propose that interfaceName simply defaults to
javax.jms.JMSConnectionFactory, so in most cases it can be omitted. However with JMSDestinationDefinition instanceName
must always be specified.
Here is a summary of the proposed changes:
javax.jms.JMSConnectionFactoryDefinition
----------------------------------------
resourceAdapter
Resource adapter name.
If not specified then the application server will define the default behaviour,
which may or may not involve the use of a resource adapter.
interfaceName
(This is a new "optional" element)
Fully qualified name of the connection factory object’s interface.
Permitted values are javax.jms.ConnectionFactory or javax.jms.QueueConnectionFactory or
javax.jms.TopicConnectionFactory.
If not specified then javax.jms.ConnectionFactory will be used.
className
(This existing element ceases to be "required" and becomes "optional")
Fully qualified name of the connection factory implementation class.
Ignored if a resource adapter is used.
javax.jms.JMSDestinationDefinition
----------------------------------
resourceAdapter
Resource adapter name.
If not specified then the application server will define the default behaviour,
which may or may not involve the use of a resource adapter.
interfaceName
(This is a new "required" element)
Fully qualified name of the destination object’s interface.
Permitted values are javax.jms.Queue or javax.jms.Topic.
className
(This existing element ceases to be "required" and becomes "optional")
Fully qualified name of the connection factory implementation class.
Ignored if a resource adapter is used unless the resource adapter defines more than one connection factory
class for the specified interface.
You can inspect the changes online in the usual place
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/index.html
though at the time of writing this part of java.net appears to be down.
I'm working with the Java EE spec leads to make corresponding changes to the Java EE schema. This will add new
sub-elements <interface-name> to the <jms-connection-factory> and <jms-destination> elements.
As usual, questions and comments are invited.
Nigel