[JMS_SPEC-62] Define standard way to create JMS Destination objects from within a Java EE application Created: 23/Nov/11  Updated: 24/Feb/12  Resolved: 24/Feb/12

Status: Resolved
Project: jms-spec
Component/s: None
Affects Version/s: 1.1
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: arjan tijms Assignee: Unassigned
Resolution: Invalid Votes: 2
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: destination, javaee

 Description   

The JMS 1.1 spec states in section 2.3 that JMS Destinations (Queue and Topic) are administered objects for the following reason:

It is also expected there will be major differences in how a provider's system is installed and administered. If JMS clients are to be portable, they must be isolated from these proprietary aspects of a provider.

In practice however, there is often only very little information needed to create a basic Destination that is suitable for a lot of use-cases and there aren't really any major differences there. Especially if such Destinations are completely used internally in the application, they don't necessarily need to be administered objects. Many Java EE servers do make it possible to define Destinations from within the application, but every implementation has a different way to do this. This hurts portability.

For instance;

JBoss AS 6.x

*-hornetq-jms.xml
<configuration xmlns="urn:hornetq"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:hornetq /schema/hornetq-jms.xsd"
>    
    <queue name="myQueue">
        <entry name="/queue/myQueue" />
    </queue>
</configuration>

Glassfish 3.1.x

META-INF/glassfish-resources.xml
<!DOCTYPE resources PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Resource Definitions//EN" 
    "http://glassfish.org/dtds/glassfish-resources_1_5.dtd">
<resources>
    <admin-object-resource res-adapter="jmsra" res-type="javax.jms.Queue" jndi-name="java:app/myQueue" >        
        <property name="Name" value="myQueue"/>
    </admin-object-resource>
</resources>

As can be seen in these two examples, all that the user needs to declare is a name and whether a queue or topic is required.

I would like to propose to define a standard way to define Destinations from within a Java EE application, analogous to how JDBC datasources can be defined via a DataSourceDefinition annotation and a corresponding <data-source> element in application.xml.



 Comments   
Comment by arjan tijms [ 04/Dec/11 ]

Slide 29 of http://java.net/downloads/jms-spec/JMS2.0Devoxx2011.pdf mentions exactly this:

JSR 342 (Java EE 7) will define new annotations:

@JMSConnectionFactoryDefinition( 
    name="java:app/MyJMSFactory", 
    resourceType="javax.jms.QueueConnectionFactory", 
    clientId="foo",
    resourceAdapter="jmsra", 
    initialPoolSize=5, 
    maxPoolSize=15
)
@JMSDestinationDefinition( 
    name="java:app/orderQueue", 
    resourceType="javax.jms.Queue", 
    resourceAdapter="jmsra", 
    destinationName="orderQueue"
)
Comment by Nigel Deakin [ 08/Dec/11 ]

As mentioned in those Devoxx slides, the Java EE 7 platform expert group is planning to include a feature similar to this. Please contact the Java EE 7 expert group for more information. http://javaee-spec.java.net

This is a platform issue and won't be addressed in the JMS spec.

Comment by Nigel Deakin [ 24/Feb/12 ]

Please see section EE.5.17.5 "JMS Destination Definition" of the proposed Java EE 7 specification (available via http://javaee-spec.java.net). This states

An application may define a JMS Destination resource. A JMS Destination resource is a JMS Queue or Topic.

The JMS {{Destination}}resource may be defined in any of the JNDI namespaces described in Section EE.5.2.2, “Application Component Environment Namespaces”.

A JMS Destination resource may be defined in a web module, EJB module, application client module, or application deployment descriptor using the jms-destination element.

For example:

<jms-destination>
    <description>Sample JMS Destination definition</description>
    <name>java:app/MyJMSDestination</name>
    <class-name>javax.jms.Queue</class-name>
    <resource-adapter-name>myJMSRA</resource-adapter-name>
    <resource-name>myQueue1</resource-name>
    <property>
      <name>Property1</name>
      <value>10</value>
    </property>
    <property>
      <name>Property2</name>
      <value>20</value>
    </property>
    </jms-destination>

A JMS Destination resource may also be defined using the JMSDestinationDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

@JMSDestinationDefinition(
    name="java:app/MyJMSQueue",
    className="javax.jms.Queue",
    resourceName="myQueue1")

The JMSDestinationDefinition annotation can be overridden by a deployment descriptor when the application is deployed.)

Once defined, a JMS Destination resource may be referenced by a component using the resource-ref deployment descriptor element or the Resource annotation. For example, the above Destination could be referenced as follows:

@Stateless
public class MySessionBean {
    @Resource(lookup = "java:app/MyJMSQueue")
    Queue myQueue;
    ...
}

The following JMSDestinationDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to specify an address for a JMS Destination resource: resourceAdapterName, resourceName.

Comment by Nigel Deakin [ 24/Feb/12 ]

I've marked this as resolved, with a resolution of "invalid". This doesn't mean the suggestion was invalid, of course, but that the request applied to a different specification. Comments and feedback remain welcome.

Generated at Sun Aug 30 12:29:20 UTC 2015 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.