John,
On 15/03/2013 23:32, John D. Ament wrote:
> Nigel,
>
> I can't think of any scenario where the className should or could be specified. These are typically very convoluted
> names like com.myjms.physical.storage.destinations.jms.TopicDestinationImpl that no developer should ever know. I'm
> assuming that we put className in there originally thinking it would be the interface name, right?
These interfaces came from the Java EE spec leads (where these annotations, and the corresponding XML, are described) so
I'm not sure what the thinking was. I suspect they were simply copied from javax.annotation.sql.DataSourceDefinition,
where className is set to the implementation class name. (I think DataSourceDefinition is the inspiration for this whole
feature).
However I have always expected that for JMS this would be set to the interface name. As you say, we really don't want
users to be hardcoding implementation class names in their code, even though that seems normal practice for DataSource.
>
> Can it just come out?
That would be my preference.
However I've been told there is a use case where both className and instanceName may need to be specified, even if a
resource adapter is being used. This is in the case of destination objects, when the resource adapter's ra.xml defines
more than one <admin-object> entry with the same interface but different implementation classes. This is obscure, but
allowed by the JCA spec.
JMSDestinationDefinition is a special case of javax.resource.AdministeredObjectDefinition. That more general anotation
defines both className and instanceName for this very reason. In fact for that annotation, specifying className is
mandatory, whereas interfaceName is not, which I think is the wrong way round (and have said so).
http://javaee-spec.java.net/nonav/javadocs/javax/resource/AdministeredObjectDefinition.html
The other reason for having a className attribute for both destination and connection factory is for the case of
application servers which don't use a resource adapter and the user wants to use a implementation class name different
from the application server's default. I'm not sure how common that use case will be in practice, though.
Nigel
>
> John
>
>
> On Fri, Mar 15, 2013 at 8:31 AM, Nigel Deakin <nigel.deakin_at_oracle.com <mailto:nigel.deakin_at_oracle.com>> wrote:
>
> 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
> JMSConnectionFactoryDefinition__s 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 <http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/index.html>
> though at the time of writing this part of java.net <http://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
>
>