Lately I had to work a bit on integrating some of SoftwareAG's messaging brokers (
SoftwareAG webMethods Broker and
Universal Messaging) with common application servers (JBOSS AS 7, WebSphere 8) through standard
JCA resource adaptor construct.
So this post, the first of 3, is to summarize (before I forget myself :) ) some of the steps involved with that setup using SoftwareAG webMethods JMS Broker + JBOSS combination...Hoping that it might be useful to somebody in the meantime.
Please note this post is the 1st out of the following 3 related posts:
- Integrating SoftwareAG webMethods messaging Broker with JBOSS AS 7 through standard JCA
- SSL Encryption / Authentication between JBOSS JCA + SoftwareAG webMethods Broker
- JBOSS Vault to encrypt JMS password for secure JCA configuration
Note 1*: all the resources/code I mention in this post are accessible on github at
jbossjca-sample-mdbs
Note 2**: If you like a more formal documentation with "pretty" screenshots, I posted such doc (PDF) on the SoftwareAG "techcommunity" resource wiki, accessible publicly at
techcommunity.softwareag.com. Please check it out as well...
First words
First, many posts out there talk about the JCA Resource Adapter construct and why it is useful...(eg.
http://planet.jboss.org/post/jboss_as7_and_jca). Yes it is useful as it decouples your code from the JMS low level implementation, and make directly available to you all the enterprise production-ready features that you really don’t want to re-develop yourself (unless you have a lot of extra time on your hand and don’t know what to do with it) such as connection pooling, transactional support, connection validation, connection failure strategies, reconnection strategies, etc…
Secondly, if you’re reading this, you’re likely a knowledgeable webMethods users already, and as such, I won’t go into the details of setting up the SoftwareAG webMethods JMS Broker etc... But for you to reproduce quickly some of the steps identified by this post, I’ve added the admin script that allows you to create all the webMethods Broker objects in 1 liner executable command (using the jmsadmin tool), as follow:
$WM_BROKER_HOME/bin/jmsadmin -properties
jndi.properties -f
jmsadmin.script
At this point, you should have a SoftwareAG webMethods Broker working and accessible with the following objects:
- InboundQueueConnectionFactory
- This is the factory we’ll use to consume messages from our MDBs
- OutboundQueueConnectionFactory
- This is the factory we’ll use to send messages from our sample servlet
- simplequeue
- This is the queue we’ll use
Let’s now get started on the JBOSS side.
1 - Deploy the SoftwareAG webMethods Broker RAR
- The RAR package is at $WM_BROKER_HOME/lib/webm-jmsra.rar
- Deploy RAR package onto JBOSS using either way:
- Copy to the JBOSS deployment folder (<JBOSS-EAP-HOME>/standalone/deployments) and the RAR should be deployed automatically
- A file “webm-jmsra.rar.deployed” should be created.
- If nothing is created, or a file “webm-jmsra.rar.failed” is created, an error occurred during deployment.
- Use the JBOSS admin console to deploy the package just like you would do it for any other deployable resource (EAR, WAR, etc…)
- Success or failure should be displayed in the console
2 - Configure the Resource Adapter
Then, we just need to configure the resource adapter for both inbound (used by message consumers) and outbound (used by message producers). This can all be done thorough the JBOSS admin console at “profile > subsystems > Connector > Resource Adapters”.
For brevity, I’ll pass on the multi-screen setup (it's really well explained on the red-hat website at
Red-Hat Doc: Configure_a_Deployed_Resource_Adapter), and show here the end result that will be written in jboss configuration (standalone.xml or domain.xml) within the subsystem resource-adapters:
webm-jmsra.rar
NoTransaction
java.naming.factory.initial=com.webmethods.jms.naming.WmJmsNamingCtxFactory,java.naming.provider.url=wmjmsnaming://mybroker@wmvm:6849
false
java.naming.factory.initial=com.webmethods.jms.naming.WmJmsNamingCtxFactory,java.naming.provider.url=wmjmsnaming://mybroker@wmvm:6849
true
OutboundQueueConnectionFactory
10
50
true
true
IdleConnections
true
Couple of quick notes on this:
- The resource adapter id / name should be same as the RAR you just uploaded
- "JndiProperties" setting is self-explanatory: it's the usual connection settings to the JMS broker JNDI. For SoftwareAG webMethods broker, the factory class is "com.webmethods.jms.naming.WmJmsNamingCtxFactory"...make sure to use that. And then, customize the url based on your setup.
- The connection-definition section is for outbound pooled connections (sending messages), hence that's why we used the "OutboundQueueConnectionFactory" broker object for the "ConnectionFactoryJndiName" setting
- In the connection-definition section, you notice also that it's registered in JBOSS JNDI with the name specified in jndi-name="java:/jms/broker". This is important as we'll need to refer to that in our code to send messages to the queue (see further down)
- In that same connection-definition section, you can also see that the "class-name" attribute is "com.sun.genericra.outbound.ManagedJMSConnectionFactory"...do not change that, as it's the resource adapter connection factory that will take advantage of application server connection pooling amongst others
- "pool" section: customize it to meet you needs
For a complete reference of all the properties available in the resource adapter, please check out the RA implementation page at
genericjmsra.java.net: user guide (this is the core RA implementation used in the SoftwareAG webMethods Broker RAR package)
When you restart JBOSS, you now should see some JCA activity in the console output. If something is not quite right, and you'd like to see more of what's going on under the hood, an easy way I found was to enable deeper logging within JBOSS for the resource-adapter components:
3 - Tune SoftwareAG webMethods Broker behavior by setting the right system.properties
To tweak the webMethods broker client library, all you need to do is add the right system property in JBOSS...This can be done through the admin console at “profile > General Configuration > System Properties”, or simply be written directly in the jboss configuration (standalone.xml or domain.xml), right under the "extensions" section...
Here is a sample block containing some useful webMethods Broker properties:
4 - Create your MDBs with the right Activation Properties
Here is a sample of an MDB that just prints the received messages in the logs...(full code and working maven-enabled project is on github at
SimpleQueueConsumerBean.java)
As you noticed, I specified - on purpose - a lot of the activation config available in the resource adapter implementation. Interestingly though, you don't see the "JndiProperties" activation spec here...and that's good and expected, since we specified it in the resource adapter "JndiProperties" property...That way I don't have to specify the connection definition in all my MDBs...which is great.
For a complete reference of all the activation parameters available, refer to
genericjmsra.java.net: user guide and go to the "Activation Spec Properties" section.
//imports
...
@MessageDriven(name = "SimpleQueueConsumerBean", activationConfig = {
@ActivationConfigProperty(propertyName = "connectionFactoryJndiName", propertyValue = "InboundQueueConnectionFactory"),
@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
@ActivationConfigProperty(propertyName = "destinationJndiName", propertyValue = "simplequeue"),
@ActivationConfigProperty(propertyName = "maxPoolSize", propertyValue = "50"),
@ActivationConfigProperty(propertyName = "maxWaitTime", propertyValue = "10"),
@ActivationConfigProperty(propertyName = "redeliveryAttempts", propertyValue = "10"),
@ActivationConfigProperty(propertyName = "redeliveryInterval", propertyValue = "1"),
@ActivationConfigProperty(propertyName = "reconnectAttempts", propertyValue = "10"),
@ActivationConfigProperty(propertyName = "reconnectInterval", propertyValue = "5")
})
@TransactionManagement(value=TransactionManagementType.BEAN)
@TransactionAttribute(value=TransactionAttributeType.NOT_SUPPORTED)
@Pool(value="mdb-strict-max-pool")
@ResourceAdapter("webm-jmsra.rar")
public class SimpleQueueConsumerBean implements MessageListener, MessageDrivenBean {
...
public void onMessage(Message rcvMessage) {
TextMessage msg = null;
try {
if(null != rcvMessage){
if (rcvMessage instanceof TextMessage) {
msg = (TextMessage) rcvMessage;
log.info("SimpleQueueConsumerBean: Received Message from queue: " + msg.getText());
} else {
log.error("SimpleQueueConsumerBean: Message of wrong type: " + rcvMessage.getClass().getName());
}
} else {
log.info("SimpleQueueConsumerBean: Received Message from queue: null");
}
} catch (JMSException e) {
throw new RuntimeException(e);
}
}
}
Another thing you might have noticed is the 2 JBOSS-specific annotations @ResourceAdaper (org.jboss.ejb3.annotation.ResourceAdapter) and @Pool (org.jboss.ejb3.annotation.Pool). This is 1 of the ways to specify which resource adapter and MDB pool your MDB should use.
Depending on your setup (eg. all your MDBs should be using the same resource adapter + parameters), it might just be easier/better to make the webMethods Broker resource adapter the default one, and assign it a default pool...This is done in the EJB3 subsystem, as follow:
Tune the "mdb-strict-max-pool" to meet your performance needs...One rule of thumb though: whatever "max-pool-size" you chose for the MDB pool, make sure that it's the same number also for the maxPoolSize activation property. For example, I used 50 for both.
@ActivationConfigProperty(propertyName = "maxPoolSize", propertyValue = "50"),
5 - Create message producer that uses the Resource Adapter outbound pooled connection
Ok, so now we need to send messages to that webMethods Broker queue and see if our MDB setup works ok. Sending messages to a queue is nothing new in Java JMS and we've written that type of code thousands of time. BUT the interesting part here is to send messages using the outbound connection defined in the resource adapter and identified by the JBOSS JNDI name "java:/jms/broker". By doing so, we automatically get access to app server goodness such as connection pooling for best performance...
All your code needs to do "different" (from a non-managed implementation) is to bind the connection factory to that jndi entry "java:/jms/broker", which is easily achieved using the standard @resource annotation. See the extract below for details (full class at
JcaRequestMessageProducer.java)
@WebServlet("/JcaMessageProducer")
public class JcaMessageProducer extends HttpServlet {
...
//this uses the resource-adapter to make sure it's a managed connection etc...
@Resource(mappedName = "java:/jms/broker")
private ConnectionFactory connectionFactory;
...
private void sendMessage(String textToSend, String destinationName, boolean isQueue) throws JMSException {
Connection connection = null;
try {
if (null == connectionFactory)
throw new JMSException("connection factory is null...can't do anything.");
connection = connectionFactory.createConnection();
Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
//here we avoid a JNDI lookup...
Destination destination;
if (isQueue)
destination = session.createQueue(destinationName);
else
destination = session.createTopic(destinationName);
MessageProducer messageProducer = session.createProducer(destination);
TextMessage message = session.createTextMessage();
log.info(String.format("Sending new message to %s %s : %s ", (isQueue) ? "queue" : "topic", destinationName, textToSend));
message.setText(textToSend);
messageProducer.send(message); // Send Message
log.info(String.format("Messages Sent"));
} catch (Exception e) {
log.error("error while sending message", e);
throw new JMSException("Couldn't send to queue");
} finally {
if (null != connection)
connection.close();
}
}
6 - Deploy and test!
To deploy the sample code directly onto your local JBOSS, a simple maven command (thanks maven and jboss plugin!):
"mvn clean package jboss-as:deploy"
Once successfully deployed, you should be able to access the URL "http://localhost:8080/jbossjca-sample-mdbs/JcaMessageProducer", providing the right parameter for queue name and number of message to send...
For example, I have a queue called "simplequeue" and want to send 20 message...hence url would be: "http://localhost:8080/jbossjca-sample-mdbs/JcaMessageProducer?queue=simplequeue&count=20"
Upon execution of that url, you should see in the JBOSS standard output the messages being submitted as well as consumed by our sample MDB...
Final Words
I think that's it for now...You can easily recreate all this on your local laptop (as long as you have access to JBOSS EAP 6 / JBOSS AS 7 and webMethods Broker that is) as I put everything I wrote about (and more) on github at
j2ee-jms-examples.
To build and deploy the project:
- First, You'll need to put the webMethods Broker client libraries in the jbossjca-sample-mdbs/libs folder (not required to compile, but required to be added to the WAR package). Another way would be to put these jars in a Jboss global module...
- Then simple maven command: mvn clean package jboss-as:deploy -P jboss-ga-repository
In some follow up posts, I'll go over the steps involved in setting up JBOSS for SSL encryption and authentication to SoftwareAG webMethods Broker...as well as specifics around JBOSS vault usage in order to encrypt the password for SSL certs...
Hope that was helpful...
