FioranoMQ provides a standardized method to connect and integrate with a J2EE container using the FioranoMQ Resource Adapter. This Adapter enhances the plug-in ability and integration of FioranoMQ with J2EE Servers.
The FioranoMQ Resource Adapter implements the complete semantics of JCA 1.5 allowing:
- J2EE applications (MDBs and EJBs) to send messages to JMS Topics and Queues using a unified JMS model with JCA Outbound Contracts (including Transaction Contracts).
- Message endpoints (MDBs) to asynchronously receive messages from Topics/Queues using JCA 1.5 Message Inflow Contracts.
- The resource adapter to propagate Transactions initiated by the FioranoMQ Server to the application server, using Transaction Inflow contracts.
29.5.1 How Resource Adapter Works
The working of the Resource adapter is illustrated in the figure below:
29.5.2 Deployment of FioranoMQ Resource Adapter
The FioranoMQ Resource Adapter has been packaged in a rar file that can be used to deploy the Resource Adapter:
- %FMQ_HOME%\fmq\lib\jca\fmq-connector-ra.rar can be used to deploy the FioranoMQ Resource Adapter in J2EE 1.3 compliant Application Servers.
- %FMQ_HOME%\fmq\lib\jca\fmq-connector-ra.rar can be used to deploy The FioranoMQ Resource Adapter in J2EE 1.4 compliant Application Servers.
In the FioranoMQ Resource Adapter's deployment descriptor (ra.xml), the properties, below, can be configured/overwritten during deployment:
S.No | Type | Description | Property |
|---|---|---|---|
1 | ProviderURL | String | Provider URL (where JMS admin objects are stored). |
2 | BackupProviderURLs | String | Backup provider URLs, if any. |
3 | Initial Context-Factory | String | Name of the class providing the implementation of Initial Context Factory. |
4 | JndiUserName | String | Username to be used for lookup. |
5 | JndiPassword | String | Password to be used for lookup. |
6 | ConnectionFactory | String | Name of the connection factory to be used for creating a physical connection with the FioranoMQ Server. |
7 | ClientID | String | ID to identify the JMS client (message consumer). |
8 | JmsUserName | String | Username to be used for creating a connection to the FioranoMQ Server. |
9 | JmsPassword | String | Password to be used for creating a connection to the FioranoMQ Server. |
10 | XAEnabled | Boolean | Whether or not to enable XA for receiving messages. |
11 | DebugEnabled | Boolean | Whether or not to print debug statements. To log debug statements RA tries to create an instance of java.util.logging.Logger. If unable to create Logger then RA writes all debug statements using System.out |
The above properties are used by the FioranoMQ Resource adapter for implementing Message-Inflow support. Some of these properties can be overridden by Activation Configuration, as described in the section below.
29.5.3 Configuring the Resource Adapter
<Inbound-resourceadapter> configuration
Inbound Communication allows the Resource Adapter (FioranoMQ RA) to handle messages flowing in from the EIS (JMS Server) to the application (MDB) residing in an application server. The FioranoMQ Resource Adapter (RA) uses the Generic Message Inflow Contract and asynchronously delivers messages to message driven beans via the onMessage () method using the javax.jms.MessageListener interface.
The MDB, when deployed, is registered as a message endpoint for receiving the messages from the Resource Adapter (RA). On deployment of the MDB, the Deployer provides Activation-Configuration information to the RA so that it can deliver messages to the MDB.
29.5.3.1 Sample Activation Configuration
Sample Configurations to be specified in ra.xml
Definition for inbound and outbound resource adapters are given in ra.xml
Configurations for inbound flow are specified in deployment descriptor 'ejb-jar.xml' located in MDB's META-INF folder in case of EJB2 and specified using annotations in case of EJB3.
Sample Activation configuration using EJB2.
Sample Activation configuration using EJB3 annotations
Configurations for outbound flow are specified in deployment descriptor 'jms-ds.xml' located in <JBOSS-HOME> /server/default/deploy/jms folder.
Deploying managed connection factory->jms-ds.xml
While deploying the Managed Connection Factory in the J2EE Server, the properties, below, can be specified for the ManagedConnectionFactory:
Type | Description | Property |
|---|---|---|
ProviderURL | String | Provider URL (where JMS admin objects are stored). |
BackupProviderURLs | String | Backup provider URLs, if any. |
Initial Context-Factory | String | Name of the class providing the implementation of Initial Context Factory |
JndiUserName | String | Username to be used for lookup. |
JndiPassword | String | Password to be used for lookup |
ConnectionFactory | String | Name of the connection factory to be used for creating a physical connection with the FioranoMQ Server. |
ClientID | String | ID to identify the JMS client (message consumer). |
JmsUserName | String | Username to be used for creating a connection to the FioranoMQ Server. |
JmsPassword | String | Password to be used for creating a connection to the FioranoMQ Server. |
XAEnabled | Boolean | Whether or not to enable XA for receiving messages. |
Is Transacted | Boolean | Whether or not the session is Transacted. This is used to create a JMS session, if the value of the property XAEnabled is false. |
Once the connection Factory has been deployed, all the end User needs to do in order to send the message to the FioranoMQ Server is implement standard JMS programming, as shown below:
29.5.4 Configuring FioranoMQ Resource Adapter in JBoss 4.2.2
29.5.4.1 Changes Required for Inbound Communications (Message Inflow Contracts)
The following steps will deploy Fiorano RA and enable Inbound Communication onto JBOSS AS.
- Shutdown any instance of the JBoss Application Server.
- Edit ra.xml located at $FIORANO_HOME\fmq\lib\jca\resources\1.4\META-INF and modify the property ProviderURL to point to the appropriate instance of FioranoMQ.
- Run the buildJcaJars.bat / buildJcaJars.sh script available at FIORANO_HOME\fmq\lib\jca to generate the required .rar files. Two new folders, j2ee1_4 and j2ee1_3 are created. These folders store the generated .rar files.
- Copy fmq-connector-ra.rar from $FIORANO_HOME\fmq\lib\jca \j2ee1_4 to deploy the directory of the desired JBoss Server configuration profile (all, default, minimal and so on). For example, use $JBOSS_HOME/server/default/deploy.
29.5.4.2 Changes required for Outbound Communication
For EJBs in JBoss to be able to send messages to the FioranoMQ Server, the end User should create Connection Factories. These Connection Factories can be used to create the FioranoMQ connection as per JCA Connection Management contracts.
Connection factories can be created by modifying jms-ds.xml located in $JBOSS_HOME/server/$PROFILE/deploy/jms. The listing below shows the deployment of Sample ConnectionFactories supporting XA and Non-XA connections.
Connection factories can be lookedup by J2EE applications for sending and receiving messages from FioranoMQ Topics and Queues.
Restart the JBoss application server.
Sample
FioranoMQ contains samples that demonstrate the usage of FioranoMQ RA. These samples are available in the %FMQ_HOME%\fmq\samples\ApplicationServer\fmqmdb\dist\jboss_4 directory. Refer to readme_JBoss4.txt available in the samples\ApplicationServer\ fmqmdb directory for step-by-step instructions on deploying and running the sample.
29.5.5 Configuring FioranoMQ RA in JBoss 4.2.2-XA
To deploy the FioranoMQ Resource Adapter in JBoss 4.2.2, perform the steps below:
- Stop the instance of JBoss running on the Server. Change the value of the property ProviderURL in ra.xml to point to the appropriate instance of FioranoMQ. This .xml file is file located in $FIORANO_HOME\fmq\lib\jca\resources\1.3\META-INF.
- Run the buildJcaJars.bat/buildJcaJars.sh script available at $FIORANO_HOME\fmq\lib\jca. This will generate the rar files.
- Copy fmq-connector-ra.rar from $FIORANO_HOME\fmq\lib\jca\j2ee1_3 to deploy the directory of the desired JBoss Server configuration profile (all, default, minimal, and so on). For example, use $JBOSS_HOME/server/default/deploy
In jms-ds.xml, replace codes appear in bold:
<!-- The JMS provider loader -->
<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
name="jboss.mq:service=JMSProviderLoader,name=JMSProvider">
<attribute name="ProviderName">DefaultJMSProvider</attribute>
<attribute name="ProviderAdapterClass">
org.jboss.jms.jndi.JNDIProviderAdapter
</attribute>
<!-- The queue connection factory -->
<attribute name="QueueFactoryRef">java:/XAConnectionFactory</attribute>
<!-- The topic factory -->
<attribute name="TopicFactoryRef">java:/XAConnectionFactory</attribute>
<!-- Uncomment to use HAJNDI to access JMS
<attribute name="Properties">
java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
java.naming.provider.url=localhost:1100
</attribute>
-->
</mbean>
With
<!-- The JMS provider loader -->
<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
name="jboss.mq:service=JMSProviderLoader,name=HAJNDIJMSProvider">
<attribute name="ProviderName">DefaultJMSProvider</attribute>
<attribute name="ProviderAdapterClass">
org.jboss.jms.jndi.JNDIProviderAdapter
</attribute>
<!-- The queue connection factory -->
<attribute name="QueueFactoryRef">primaryXAQCF</attribute>
<!-- The topic factory -->
<attribute name="TopicFactoryRef">primaryXATCF</attribute>
<!-- Access JMS via HAJNDI -->
<attribute name="Properties">
java.naming.factory.initial=fiorano.jms.runtime.naming.FioranoInitialContextFactory
java.naming.provider.url=http://localhost:1856
</attribute>
</mbean>
Start JBoss Server.
Sample
A sample MDB can be run that demonstrates how FioranoMQ RA works with JBoss 4.2.2 (located in the %FMQ_HOME%\JCA\Samples\ directory). Before running this sample, please refer to the readme_JBoss4.2.2.txt available in the samples directory for step-by-step instructions on deploying and running this sample.
29.5.6 Configuring MDBs for XA or NONXA
Following configurations should be made in ejb-jar.xml in case of EJB2 or should be specified as annotations in case of EJB3.
Non-XA:
'TransactionType' for MDB should be specified as 'BEAN'
or
'TransactionType' for MDB should be specified as 'CONTAINER' & 'TransactionAttribute' as 'NOT_SUPPORTED'
XA:
'TransactionType' for MDB should be specified as 'CONTAINER'. By default the 'TransactionAttribute' will be 'REQUIRED'.