This section will detail application design notes that will help you appreciate the design decisions that went into developing this sample application, the architecture diagram that lets you visualize how different components fit together in the overall scheme of the application, and code snippets that help you relate the implementation of concepts in code.
Design Notes
The application consists of a web component (servlet)
and ejb component (mdb). The servlet sends a message to a JMS queue on which
an MDB is listening on. The MDB upon receipt of the message sends a reply
message back to the queue, linking the received and reply messages using
JMSCorrelationID. The servlet waits for the reply and verifies that all
replies are correctly received. The architecture diagram illustrates this
scenario.
WebSphere MQ JMS provider is used for this illustration. The application demonstrates
the following concepts:
- All JCA outbound contracts, including connection pooling.
- All JCA inbound contracts with the exception of Transaction inflow.
- Enlistment and participation of JCA Managed
Connections in global transactions. The
trans-attributefor the mdb's onMessage method is specified asRequired, so the receive of the message (by the JMS provider) and the send of the reply (by the mdb's onMessage in a new JMS connection) are part of the same global transaction.
Architecture Diagram
Configuration Support
A Resource Adapter is a driver that an application server or an application client uses to connect to a specific EIS.
This application provides Resource
Adapter aRchive mqjra.rar (located in the
directory jcajmsmq\dist) which has been configured to connect to WebSphere
MQ. This archive contains:
|
gjra.jar
|
JAR file containing the generic JMS resource adapter classes provided by OC4J | |
| meta-inf\ |
ra.xml
|
The standard J2EE deployment descriptor for Resource Adapter |
| meta-inf\ |
oc4j-ra.xml
|
OC4J specific additional Resource Adapter configuration information |
The following configurations are set in ra.xml
to enable access to the WebSphere MQ Queue and Topic:
<connector...>
...
<resourceadapter>
|
The Resource Provider Name is set as 'MQSeries'. 'MQQ',
'MQT', 'MQQCF', 'MQTCF', 'MQXATCF', 'MQXATCF' are the JNDI bound JMS objects
created using JMSAdmin of WebSphere MQ which can now be looked up by the application.
These can be found in the .bindings file created
while configuring WebSphere MQ JMS Provider. Refer to Step 3 in the Install.html.
The OC4J specific configurations are set in oc4j-ra.xml
as follows:
<oc4j-connector-factories> <connector-factory location="mqjms/MyQCF" connector-name="MQJMS"> |
mqjra.rar can be readily
used by any application which requires to connect to WebSphere MQ configured
with similar JMS objects.
OC4J JCA requires the JMS provider's destination to be
mapped into the JCA JNDI namespace. This is done by configuring the rar
details in oc4j-connectors.xml as follows:
<oc4j-connectors> |
OC4J requires that the path to oc4j-connectors.xml should
be defined in orion-application.xml along with the Resource Provider
specific details:
<orion-application> ... <resource-provider |
The application uses the rar as an embedded resource
adapter meaning that the rar is bundled along with the EAR. The following
entry is added to application.xml in the EAR file:
<application> ... |
Code Support
The previous section explains the configurations required to make the JMS provider WebSphere MQ available to the applications. This section explains the configurations and code required in the application to make use of the configuration details and send/receive messages from JMS Topic/Queue.
Configuring EJBs to connect to the JMS Topic/Queue
To enable EJB's specifically MDBs in this application to connect to the JMS Topic/Queue, the OC4J specific EJB deployment descriptor
orion-ejb-jar.xmlshould be configured as follows:
<message-driven-deployment name="simpleMdb" resource-adapter="mqjms">
<resource-ref-mapping name="jms/XAQCF" location="mqjms/MyXAQCF" />
<resource-env-ref-mapping name="jms/QUEUE1" location="mqjms/MyQ" />
</message-driven-deployment> <message-driven-deployment name="PSsimpleMdb" resource-adapter="mqjms">
<resource-ref-mapping name="jms/XATCF" location="mqjms/MyXATCF" />
<resource-env-ref-mapping name="jms/TOPIC1" location="mqjms/MyT" />
</message-driven-deployment>
</enterprise-beans> ... </orion-ejb-jar>Note that the value of location attributes defined here correspond to the value of location attributes defined in
oc4j-ra.xmlandoc4j-connectors.xml.The reference mapping names specified can now be used in the J2EE standard EJB deployment descriptor
ejb-jar.xmlas follows:
<enterprise-beans>
<message-driven>
<ejb-name>simpleMdb</ejb-name> ... <resource-ref>
...
<res-ref-name>jms/XAQCF</res-ref-name>
<res-type>javax.jms.XAQueueConnectionFactory</res-type>
...
</resource-ref> <resource-env-ref>
...
<resource-env-ref-name>jms/QUEUE1</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
</message-driven> <message-driven>
<ejb-name>PSsimpleMdb</ejb-name> ...
<resource-ref>
... <res-ref-name>jms/XATCF</res-ref-name>
<res-type>javax.jms.XATopicConnectionFactory</res-type>
... </resource-ref> <resource-env-ref>
... <resource-env-ref-name>jms/TOPIC1</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Topic</resource-env-ref-type>
... </resource-env-ref>
</message-driven>
</enterprise-beans> ... </ejb-jar>The resource references set in
ejb-jar.xmlare used in the application to access the JMS Queue/Topic.
The code in the MDB to access the JMS Queue are as follows:
... private XAQueueConnectionFactory m_xaqcf = null;
private Queue m_replyq = null;
Context ctx = new InitialContext(); m_xaqcf = (XAQueueConnectionFactory) ctx.lookup("java:comp/env/jms/XAQCF"); m_replyq = (Queue) ctx.lookup("java:comp/env/jms/QUEUE1"); ...The code in the MDB to access the JMS Topic are as follows:
... private XATopicConnectionFactory m_xatcf = null;
private Topic m_replyt = null;
Context ctx = new InitialContext(); m_xatcf = (XATopicConnectionFactory)ctx.lookup("java:comp/env/jms/XATCF"); m_replyt = (Topic) ctx.lookup("java:comp/env/jms/TOPIC1");
...
Configuring Web Applications to connect to the JMS Topic/Queue
To enable Web Applications specifically servlets in this application to connect to the JMS Topic/Queue, the OC4J specific web deployment descriptor
orion-web.xmlshould be configured as follows:
<resource-ref-mapping name="jms/QCF" location="mqjms/MyQCF" />
<resource-ref-mapping name="jms/XAQCF" location="mqjms/MyXAQCF" />
<resource-env-ref-mapping name="jms/QUEUE1" location="mqjms/MyQ" />
<resource-ref-mapping name="jms/TCF" location="mqjms/MyTCF" />
<resource-ref-mapping name="jms/XATCF" location="mqjms/MyXATCF" />
<resource-env-ref-mapping name="jms/TOPIC1" location="mqjms/MyT" />
</orion-web-app>Note that the value of location attributes defined here correspond to the value of location attributes defined in
oc4j-ra.xmlandoc4j-connectors.xml.The reference mapping names specified can now be used in the J2EE standard web deployment descriptor
web.xmlas follows:
<resource-env-ref-name>jms/QUEUE1</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref> <resource-ref>
<res-ref-name>jms/QCF</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Application</res-auth>
</resource-ref> <resource-ref>
<res-ref-name>jms/XAQCF</res-ref-name>
<res-type>javax.jms.XAQueueConnectionFactory</res-type>
<res-auth>Application</res-auth>
</resource-ref> <resource-env-ref>
<resource-env-ref-name>jms/TOPIC1</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Topic</resource-env-ref-type>
</resource-env-ref> <resource-ref>
<res-ref-name>jms/TCF</res-ref-name>
<res-type>javax.jms.TopicConnectionFactory</res-type>
<res-auth>Application</res-auth>
</resource-ref> <resource-ref>
<res-ref-name>jms/XATCF</res-ref-name>
<res-type>javax.jms.XATopicConnectionFactory</res-type>
<res-auth>Application</res-auth>
</resource-ref>
</web-app>The resource references set in
web.xmlare used in the application to access the JMS Queue/Topic.
The code in the servlet to access the JMS Queue are as follows:
... private String m_factoryName = "java:comp/env/jms/QCF";
private String m_qName = "java:comp/env/jms/QUEUE1";
QueueConnectionFactory qcf = (QueueConnectionFactory)jndiLookup(m_factoryName); Queue ourQ = (Queue)jndiLookup(m_qName);
...The code in the servlet to access the JMS Topic are as follows:
... private String m_factoryName = "java:comp/env/jms/TCF";
private String m_tName = "java:comp/env/jms/TOPIC1";
TopicConnectionFactory tcf = (TopicConnectionFactory)jndiLookup(m_factoryName); Topic ourT = (Topic)jndiLookup(m_tName);
...