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)