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.

How Resource Adapter Works

The working of the Resource adapter is illustrated in the figure below:

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.

Icon

This is where %FMQ_HOME% represents the installation directory of FioranoMQ.

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.

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.

Icon

For complete details on semantics with which the Message-Driven Bean asynchronously receives messages using FioranoMQ RA, please refer to Section 12.7.1 of JCA 1.5 specifications.
FioranoMQ RA specifies the following Activation-Configurations in the FioranoMQ-RA deployment descriptor:

More details on the Activation-Configuration for Message Inflow to JMS endpoints can be found in Appendix B of JCA 1.5 specification document.
FioranoMQ RA uses JMS Application Server Facilities for concurrent processing of subscription messages and message delivery to the MDB endpoints.

For details on JMS Application Server Facilities, refer to Chapter 8 of JMS 1.1 specifications.

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:

Configuring FioranoMQ Resource Adapter in JBoss 4.2.2

Icon

JBoss AS 4.2.2 requires JDK1.6 or later versions to function properly.

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.

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.

Icon

For a quick start, edit the jms-ds.xml to include the above xml.

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.

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:

<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>

<attribute name="QueueFactoryRef">java:/XAConnectionFactory</attribute>

<attribute name="TopicFactoryRef">java:/XAConnectionFactory</attribute>

</mbean>
With

<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>

<attribute name="QueueFactoryRef">primaryXAQCF</attribute>

<attribute name="TopicFactoryRef">primaryXATCF</attribute>

<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.

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'.

Integrating FioranoMQ with J2EE Servers

How Resource Adapter Works

Deployment of FioranoMQ Resource Adapter

Configuring the Resource Adapter

Sample Activation Configuration

Configuring FioranoMQ Resource Adapter in JBoss 4.2.2

Changes Required for Inbound Communications (Message Inflow Contracts)

Changes required for Outbound Communication

Configuring FioranoMQ RA in JBoss 4.2.2-XA

Configuring MDBs for XA or NONXA