I received no comments on this proposal. (If you've forgotten what this is all about, there's a summary in the quoted
email below).
Since this is essentially a Java EE platform feature, I think our main interest for JMS is in the the "standard"
connection factory properties that this feature is implicitly introducing. These are url, clientId, connectionTimeout,
user and password. Everything else is effectively imposed by the platform.
It was me who proposed user, password and clientId. These already have a well-defined meaning in JMS - and indeed JMS
1.1 recommends that clientId is set on the connection factory. So I think we can be fairly confident about these.
I also proposed url as an "opaque connection string" with a provider-specific meaning. The Java EE platform spec leads
thought this was too vague and that unless JMS defined exactly how such a string was constructed it was better to leave
this as a provider-specific property defined via the properties element. I am now therefore proposing we drop this element.
The Java EE platform spec leads proposed "connectionTimeout" as a standard property, where this was the socket timeout
passed to Socket.connect(). My view is that selecting this particular property for standardisation (out of the dozens
that any JMS provider supports) is somewhat arbitrary, and also that this particular timeout is not particularly useful
as most JMS providers tend to have some kind of retry behaviour. I have therefore proposed to the Java EE platform spec
leads that we drop this element.
This will leave applications with the ability to specify provider-specific properties via the generic properties element.
Summary
-------
In summary, I have amended the JMSConnectionFactoryDefinition annotation to remove the url and connectionTimeout
properties. You can see the updated javadoc here:
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSConnectionFactoryDefinition.html
I have taken this opportunity to reword the description of this and the JMSDestinationDefinition annotaton using words
copied from the Java EE specification. You can see the updated javadoc for JMSDestinationDefinition here:
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSDestinationDefinition.html
The Java EE 7 schema (which defines the corresponding deployment descriptor elements <jms-connection-factory> and
<jms-destination>) will be updated in due course. If you're interested, the Java EE 7 schema can be seen here:
https://svn.java.net/svn/glassfish~svn/trunk/schemas/javaee7/src/javaee_7.xsds
What this doesn't change
------------------------
Note, incidentally, that this feature does not standardise how to actually create a connection factory or set its
properties. That remains non-standard. I did make some proposals on this (
http://java.net/jira/browse/JMS_SPEC-89), but
we didn't reach a conclusion and that issue remains open (and unlikely to make it into the next draft now).
Nigel
On 14/09/2012 16:41, Nigel Deakin wrote:
> I refer to the following two JIRA issues:
>
> http://java.net/jira/browse/JMS_SPEC-96
> http://java.net/jira/browse/JMS_SPEC-97
>
> Those of you who have been following the development of the Java EE platform spec may have noticed that then the Java EE
> 7 Early Draft was published in April this year it contained a new section EE 5.17 "Resource definition and
> configuration". Much of what follows is taken from that section.
>
> This new section defines how an application can "specify the definition and configuration of resources that it requires
> in its operational environment" either by adding following annotations to their applications: DataSourceDefinition,
> JMSConnectionFactoryDefinition, JMSDestinationDefinition, MailSessionDefinition, and ConnectorResourceDefinition, or by
> adding corresponding elements to the XML deployment descriptor.
>
> From a JMS perspective, this means that a a Java EE application can use annotations or deployment descriptor elements
> to define what JMS destination and connection factory resources it requires. The deployer is able to override this
> definition, or add additional requirements, by modifying the deployment descriptor appropriately.
>
> The underlying reason for adding this new feature is to allow the application server to automatically "provision" the
> required resources. For example it could create the required connection factory or destination objects and bind them to
> JNDI in the location specified. It could also create the physical destination in the JMS provider. The intention is to
> allow PaaS providers to automatically provision resources needed by applications without the need for manual
> intervention. However the Java EE spec makes it clear (EE 5.17.2) that automatic provisioning is not required.
>
> The Java EE 7 specification already defines the deployment descriptor elements and annotations that will be used.
>
> The deployment descriptor elements are defined in the Java EE 7 spec and also in the Java EE 7 schema here:
> https://svn.java.net/svn/glassfish~svn/trunk/schemas/javaee7/src/javaee_7.xsds
> (search for the <jms-connection-factory> and <jms-destination> elements)
>
> The corresponding annotations are also defined in the Java EE 7 spec. However I have been informed that since the Java
> EE platform spec does not itself define an API jar, these annotations need to be in the JMS API jar (and in the
> javax.jms package). To allow us to discuss them (and also to allow work on the RI to continue) I have now added these
> and you can view them at
>
> http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSConnectionFactoryDefinition.html
> http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSConnectionFactoryDefinitions.html
> http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSDestinationDefinition.html
> http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/JMSDestinationDefinitions.html
>
> These elements/descriptor allow various properties of the destination or connection factory to be defined. I have been
> consulted on these but would like to invite the JMS EG to review them. Here's a summary:
>
> <jms-destination> & JMSDestinationDefinition
> --------------------------------------------
>
> Mandatory elements:
>
> className - JMS destination implementation class name which implements: javax.jms.Queue or javax.jms.Topic
> name - JNDI name of the destination resource being defined.
>
> Optional elements:
>
> String description - Description of this JMS Destination.
> String destinationName - Name of the queue or topic.
> String[] properties - JMS destination property.
> String resourceAdapterName - Resource adapter name.
>
> Of these, the only property which has a specific meaning in JMS is destinationName, which corresponds to the queue or
> topic name that you would pass into Session.createQueue or Session.createTopic.
>
> <jms-connection-factory> & JMSConnectionFactoryDefinition
> ---------------------------------------------------------
>
> Mandatory elements:
>
> String className - JMS connection factory implementation class name which implements: javax.jms.ConnectionFactory or
> javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory
> String name - JNDI name of the JMS connection factory being defined.
>
> Optional elements:
>
> String clientId - Client id to use for connection.
> int connectionTimeout - Sets the maximum time in seconds that to wait while attempting to connect to the resource.
> String description - Description of this JMS connection factory.
> int initialPoolSize - Number of connections that should be created when a connection pool is initialized.
> int maxIdleTime - The number of seconds that a physical connection should remain unused in the pool before the
> connection is closed for a connection pool.
> int maxPoolSize - Maximum number of connections that should be concurrently allocated for a connection pool.
> int minPoolSize - Minimum number of connections that should be concurrently allocated for a connection pool.
> String password - Password to use for connection authentication.
> String[] properties - JMS connection factory property.
> String resourceAdapterName - Resource adapter name.
> boolean transactional - Set to false if connections should not participate in transactions.
> String url - Opaque string which defines how to connect to the JMS provider.
> String user - User name to use for connection authentication.
>
> Of these, only the following are really connection factory properties (the remaining are used to define the resource
> adapter, configure the connection pool, or the specify behaviour of the transaction manager):
>
> url
> clientId
> connectionTimeout
> user
> password
>
> If these five properties, three are already defined in JMS: user, password and url (though not as connection factory
> properties).
>
> Two are new:
>
> url
> connectionTimeout
>
> Although it is not mandatory for JMS providers (or application servers) to support these (if this is not stated it
> certainly should be) I hope these five properties are generic enough to be genuinely useful.
>
> Please let me know if you have any comments or questions. If necessary I'll ask the Java EE spec lead to respond.
>
> Thanks,
>
> Nigel
>
> (P.S. In case you spot it, url isn't in the schema yet)
>
>
>
>
>
>
>