Nigel,
looks good to me. It does promote mixing application requirements (which e.g. timeout is not) with runtime requirements, but I think that's acceptable, esp. for smaller settings.
Rüdiger
On 19.11.2012, at 20:15, Nigel Deakin <nigel.deakin_at_oracle.com> wrote:
> 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)
>>
>>
>>
>>
>>
>>
>>