Contents

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.

  1. Shutdown any instance of the JBoss Application Server.
  2. 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.
  3. 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.
  4. 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:

  1. 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.
  2. Run the buildJcaJars.bat/buildJcaJars.sh script available at $FIORANO_HOME\fmq\lib\jca. This will generate the rar files.
  3. 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.

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

Adaptavist ThemeBuilder EngineAtlassian Confluence