PAGE UNDER CONSTRUCTION

Introduction

This article describes how to implement Java jobs to communicate over a Message Queue (MQ). This includes one Java job for publishing and one for subscribing and receiving.

The document explains which classes have to be created and for which purpose. This example was developed with the use of Apache MQ.

Goal of the Example

The example covers the specifics to achieve the use case. It neither covers the complete job api nor the complete possibilities of JMS.

For the coverage of the JobScheduler job api refer to the XML part of the API Documentation.

For the coverage of the JMS api refer to the Oracle Java Documentation.

 The Use Case

The use case consists of the following steps:

1. Run a Java Job in the JobScheduler which sends an XML fragment to a message queue (MQ) 
2. Run a Java Job in the JobScheduler which receives an XML fragment from an MQ
3. Execute an XML command in the JobScheduler

The Show Case???(How to name this better)

The steps described in this article are as follows:

• How to implement a Java job using the job api
• How to implement the Producer Job
• How to implement the Consumer Job
• How to execute an XML fragment using the job api
• How to deploy the jobs to the JobScheduler
• How to configure the JobScheduler Jobs with JOE using the developed classes

Prerequisites

To write a Java job for the JobScheduler the following dependency is needed.

• engine-job-api.jar
  • The library is hosted on Maven Central. Please download the jar and add it to the classpath of the Java project. 
  • If the Java project already is a maven project, simply add the following dependency to the project configuration.

<dependency>
    <groupId>com.sos-berlin.jobscheduler.engine</groupId>
    <artifactId>engine-job-api</artifactId>
    <version>1.10.3</version>
</dependency>

• • Make sure to use the correct version suitable for the JobScheduler in use.

For this example the activemq-all-5.13.0.jar library is used.

• Either download the jar file and add it to the classpath
• or in case of a maven project add the following dependency to the project configuration

<dependency>
    <groupId>org.apache.activemq</groupId>
    <artifactId>activemq-all</artifactId>
    <version>5.13.0</version>
</dependency>

The Basic Structure of an API Job Java Class

A Java Job using the JobScheduler API has to extend the Job_impl class.

It has to overwrite the method spooler_process().

public class CLASSNAME extends Job_impl {

    @Override
    public boolean spooler_process() throws Exception {
		// This is the place where the work is done!
        return spooler_job.order_queue() != null;
    }
}

The Return Value of spooler_process()

If the Java job is an order job it has to return true in case no error occurs for the order to be able to continue with the next task.

If the Java job  is a standalone job it has to return false for the JobScheduler to be able to recognize the task has finished.

This can be achieved by using the return value spooler_job.order_queue() != null. It determines if an order is in the queue of the job (true) or not (false).

Logging

Because the Java Jobs run API methods, we can directly use the logging feature of the JobScheduler. As shown in the detailed method examples below, logging is done by using the spooler_log method.

Make sure to throw the catched exception in order to hand it over the spooler_process() method. This is needed for a job running in a job chain to determine that it has to fail in case an error occurs.

Initialization of the MQ Connection

Both Java jobs need some methods to initialize a connection to an MQ Server. This section of the document shows how to implement them. The implementation is based on the JMS implementation used and shipped by activeMQ.

The createConnection() method

This method instantiates a ConnectionFactory object with an ActiveMQConnectionFactory object and creates a Connection object through the factory method createConnection().

The ActiveMQConnectionFactory object has to be instantiated with the URL of the MQ server.

public Connection createConnection(String uri){
    factory = new ActiveMQConnectionFactory(uri);
    Connection jmsConnection = null;
        try {
            jmsConnection = factory.createConnection();
        } catch (JMSException e) {
            spooler_log.error("JMSException occurred while trying to connect: ");
            throw e;
        }
        return jmsConnection;
}

The createSession(Connection connection) method

The method is called with an already instantiated Connection object and instantiates a Session object through the Connection object´s createSession(boolean transacted, int acknowledgeMode) method.

The acknowledgeMode has the following options among others:

• AUTO_ACKNOWLEDGE
• CLIENT_ACKNOWLEDGE

In summary the acknowledge mode AUTO_ACKNOWLEDGE results in the message be dequeued when one consumer has read the message from the MQ server, whereas the CLIENT_ACKNOWLEDGE puts the responsibility on the client.

When the acknowledge mode CLIENT_ACKNOWLEDGE is set, the message will stay present for all consumers to read until a consumer acknowledges the message. Only then the message will be dequeued and is not available for further consumers.

private Session createSession(Connection connection) throws JMSException{
    Session session = null;
    try {
        session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);
    } catch (JMSException e) {
        spooler_log.error("JMSException occurred while trying to create Session: ");
        throw e;
    }
    return session;
}

Implementation of the Producer Job

Implementation of the Consumer Job