Using the JMS Notifier with Payara Micro

Payara Server 171 was a huge release with lots of new features and improvements on many others. We've already written about improvements to the Request Tracing service and had a guest blog about using the email notifier.

The email notifier is just one of a whole host of notifiers we now have available. A lot were added in the 171 release and more are on their way in the imminent 172 release!

The current list of notifiers is:

• Log notifier
• Email notifier
• HipChat notifier
• JMS notifier
• Slack notifier
• SNMP notifier (tech preview)
• XMPP notifier
• Datadog notifier (available in the 172 release)
• New Relic notifier (available in the 172 release)

In this blog, I would like to focus on just one of these notifiers: the JMS notifier.

Why focus on the JMS notifier?

Since we are on the cusp of the 172 release of Payara Server and Payara Micro, this blog will take a look at an upcoming feature in Payara Micro - the ability to use Payara Micro as a JMS client!

Being derived from GlassFish, Payara Server inherited several editions, including "Full" and "Web" which, for GlassFish, correspond to the Java EE Full and Web Profiles. The Payara Server Full and Web editions contain the same set of APIs, but with the addition of JCache provided by Hazelcast being the sole change.

When we created Payara Micro, we started with the Payara Web edition and added Concurrency utilities and JBatch on top of the already-added JCache API. With the forthcoming 172 release of Payara Micro, we have added the ability to deploy JCA adapters - meaning you can now deploy a JMS resource adaptor (RAR) and use Payara Micro as a JMS client!

So how can I consume JMS notifications from Payara Micro?

Setting up this demo is relatively straightforward, although there are a few things to gather together first. We will use an example I prepared which listens on a specific queue for JMS messages using the JMS 1.1 API (this is because ActiveMQ does not yet support JMS 2.0)

The key parts of the relevant class - JMS11NotificationConsumer.java -  are shown below:

@MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationLookup", propertyValue = "jms/notifierQueue"),
    @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
    @ActivationConfigProperty(propertyName = "destination", propertyValue = "notifierQueue"),
    @ActivationConfigProperty(propertyName = "resourceAdapter", propertyValue = "activemq-rar-5.14.5")

})
public class JMS11NotificationConsumer implements MessageListener {

    public JMS11NotificationConsumer() { }

    @Override
    public void onMessage(Message message) {
        try {
            if (message instanceof TextMessage) {
                TextMessage txtMsg = (TextMessage) message;
                 System.out.println("Read Message: " + txtMsg.getText());
            }
        } catch (Exception ex) {
            Logger.getLogger(JMS11NotificationConsumer.class.getName()).log(Level.SEVERE, null, ex);
        }
    }
}

1. Download Resources

You will need to make sure you have everything prepared in advance before following along with this blog. Do be aware that you need version 172 of Payara Micro, which may mean you need to download our snapshot build to preview the feature we're looking at. Our snapshot builds are always available from the website and track the master branch from our public GitHub repository:

Below is a checklist of everything you will need to download to follow along with this blog:

1. • Payara Micro 172+; and Payara Server 171+
     
     • Payara Micro can be downloaded from the Payara Website. Your Payara Micro version will need to be 172 or higher and Payara Server will need to be 171 or higher.
   • ActiveMQ Broker
   • ActiveMQ Resource Adaptor (I used 5.14.5)
   • JMS11NotificationConsumer example @ tag 2017.05.18
     
     • This is one of our Payara Examples. If you've never used these before, I'll explain how to build this example in step 2.
     • If you are following along, make sure to check out tag 2017.05.18 to make sure you have the right version for this post.

2. Build the JMS11NotificationConsumer EJB JAR

If you haven't already cloned the Payara Examples repository, then you will need to do that now:

git clone https://github.com/payara/Payara-Examples.git

Next, change to the JMS11NotificationConsumer directory where the module's pom.xml  is located and check out the right tag:

cd Payara-Examples/payara-services/notification-service-examples/JMS11NotificationConsumer

git checkout 2017.05.18

And finally, use Maven to build the JAR and install to your local Maven repository:

mvn clean install

Once that has completed, you should have an EJB JAR file that you can deploy to Payara Micro. It can't be deployed yet, however, because Payara Micro doesn't ship with any JMS RAR file.

3. Create Post-Deploy File

Payara Micro 171 introduced the ability to supply asadmin commands in files. Since you can't interact with Payara Micro on the command line after it has been started, we had to consider timing; certain commands need to be run later than others. For this example, we need to create a post-deploy.asadmin file with the following contents:

1. 1. post-deploy.asadmin:

create-resource-adapter-config --property ServerUrl=tcp\://127.0.0.1\:61616:UserName=\'admin\':Password=\'admin\' activemq-rar-5.14.5
create-connector-connection-pool --raname activemq-rar-5.14.5 --connectiondefinition javax.jms.ConnectionFactory jms/myConnectionPool 
create-connector-resource --poolname jms/myConnectionPool jms/myConnectionFactory 
create-admin-object --raname activemq-rar-5.14.5 --restype javax.jms.Queue --property PhysicalName=notifierQueue jms/notifierQueue 
deploy /home/mike/.m2/repository/fish/payara/examples/JMS11NotificationConsumer/1.0-SNAPSHOT/JMS11NotificationConsumer-1.0-SNAPSHOT.jar

It's important to note that you may need to change the version number of your ActiveMQ RAR if you are using a different version, and you will need to change the deploy command to point to the resulting JAR file that you have built in step 2. Here, I am using the path to the JAR installed in my local Maven repository, so the path will never change in my environment, even if I run this example from a different directory.

4. Deploy to Payara Micro and Start ActiveMQ

By now, you should have downloaded Payara Micro, built the JMS11NotificationConsumer JAR and downloaded ActiveMQ.

Before we can run Payara Micro, we need to start ActiveMQ. It's not problematic to start them the other way round, but you will get periodic errors from Payara Micro as it tries and fails to connect to the local ActiveMQ broker every 30 seconds. If you haven't already extracted ActiveMQ, do that now and then start it with the following command:

java -jar apache-activemq-5.14.5/activemq-all-5.14.5.jar start

Assuming you are in the directory that you downloaded Payara Micro to, you can now start Payara Micro with the following command:

java -jar payara-micro.jar --deploy activemq-rar-5.14.5.rar --postdeploycommandfile post-deploy.asadmin --port 9090


This command will result in Payara Micro:

1. Booting Payara Micro on port 9090 (to avoid later port conflicts)
2. Deploying the ActiveMQ RAR file
3. Creating the resource adapter config, connection pool, connector resource, and queue
4. Deploying our EJB JAR.

You should now see a message similar to the following at the bottom of the Payara Micro output:

2017-05-16 09:17:25,701 [l #1): worker-3] INFO ActiveMQEndpointWorker - Successfully established connection to broker [tcp://127.0.0.1:61616]

5. Configure Payara Server to use the ActiveMQ Resource Adaptor

Now, we can configure Payara Server to push notifications to the ActiveMQ queue where our EJB is listening. First, we need to deploy the same RAR to Payara Server (make sure Payara Server is started first!)

asadmin deploy activemq-rar-5.14.5.rar

Next, rather than create connection resources ourselves, we can simply modify the default connection pool to use the ActiveMQ RAR we have just deployed, either through the admin console, or with the following asadmin command:

asadmin set resources.connector-connection-pool.jms/__defaultConnectionFactory-Connection-Pool.resource-adapter-name=activemq-rar-5.14.5

6. Configure the JMS Notifier

Now we have connection resources which use the ActiveMQ RAR, we can point the JMS notifier to our broker endpoint:

asadmin notification-jms-configure --password=admin --connectionFactoryName=jms/__defaultConnectionFactory --queueName=notifierQueue --contextFactoryClass=com.sun.enterprise.naming.SerialInitContextFactory --dynamic=true --enabled=true --url=localhost:61616 --username=admin --target=server-config


That's all the set up we need! Our next step is to prove that it works so, for that, we will enable the CPU checker in the HealthCheck service since we can reliably get regular notifications from it.

7. Test Notifications With the Healthcheck Service

To configure the HealthCheck service to log CPU activity every 5 seconds, use the following asadmin commands:

asadmin healthcheck-service-configure-checker-with-thresholds --thresholdWarning=50 --unit=MILLISECONDS --thresholdCritical=80 --checkerName=CPUC --dynamic=true --time=5000 --serviceName=healthcheck-cpu --thresholdGood=0 --enabled=true --target=server-config

asadmin healthcheck-configure --historicalTraceEnabled=false --notifierEnabled=true --dynamic=true --enabled=true --historicalTraceStoreSize=20 --target=server-config

You should now find both the Payara Server logs and our Payara Micro instance begin to log the same CPU checker notifications:

Read Message: Health Check notification with severity level: INFO. (host:mike-payara, server:server, domain:domain1,instance:server)
CPUC:Health Check Result:[[status=GOOD, message='CPU%: .57, Time CPU used: 28 milliseconds'']']
 
Read Message: Health Check notification with severity level: INFO. (host:mike-payara, server:server, domain:domain1,instance:server)
CPUC:Health Check Result:[[status=GOOD, message='CPU%: .40, Time CPU used: 19 milliseconds'']']
 
Read Message: Health Check notification with severity level: INFO. (host:mike-payara, server:server, domain:domain1,instance:server)
CPUC:Health Check Result:[[status=GOOD, message='CPU%: .54, Time CPU used: 26 milliseconds'']']
 
Read Message: Health Check notification with severity level: INFO. (host:mike-payara, server:server, domain:domain1,instance:server)
CPUC:Health Check Result:[[status=GOOD, message='CPU%: .47, Time CPU used: 23 milliseconds'']']

[2017-05-10T08:43:33.320+0100] [Payara 4.1] [INFO] [] [fish.payara.nucleus.notification.log.LogNotifierService] [tid: _ThreadID=71 _ThreadName=healthcheck-service-1] [timeMillis: 1494402213320] [levelValue: 800] [[
  Health Check notification with severity level: INFO - CPUC:Health Check Result:[[status=GOOD, message='CPU%: .57, Time CPU used: 28 milliseconds'']']]]
 
[2017-05-10T08:43:38.320+0100] [Payara 4.1] [INFO] [] [fish.payara.nucleus.notification.log.LogNotifierService] [tid: _ThreadID=71 _ThreadName=healthcheck-service-1] [timeMillis: 1494402218320] [levelValue: 800] [[
  Health Check notification with severity level: INFO - CPUC:Health Check Result:[[status=GOOD, message='CPU%: .40, Time CPU used: 19 milliseconds'']']]]
 
[2017-05-10T08:43:43.319+0100] [Payara 4.1] [INFO] [] [fish.payara.nucleus.notification.log.LogNotifierService] [tid: _ThreadID=71 _ThreadName=healthcheck-service-1] [timeMillis: 1494402223319] [levelValue: 800] [[
  Health Check notification with severity level: INFO - CPUC:Health Check Result:[[status=GOOD, message='CPU%: .54, Time CPU used: 26 milliseconds'']']]]
 
[2017-05-10T08:43:48.319+0100] [Payara 4.1] [INFO] [] [fish.payara.nucleus.notification.log.LogNotifierService] [tid: _ThreadID=71 _ThreadName=healthcheck-service-1] [timeMillis: 1494402228319] [levelValue: 800] [[
  Health Check notification with severity level: INFO - CPUC:Health Check Result:[[status=GOOD, message='CPU%: .47, Time CPU used: 23 milliseconds'']']]]

Using Payara Micro as a JMS client, you can now create your own microservice to listen for HealthCheck events and action them based on your own rules. You may notice from the above output that the log notifier from Payara Server will simply show the Healthcheck message, but the JMS notifier also sends out information on the server that is sending the notification. This can help you distinguish between which server is sending events and allow you to take action on a specific server if your conditions are met.