Rapid Integration with UltraStudio: Adding Custom Resources to project.xpml

project.xpml is the entrypoint of an Ultra Project, the integration building-block of the new and improved AdroitLogic UltraESB-X. Let’s see how to effectively use project.xpml when developing an integration flow using UltraStudio, the brand new IDE for UltraESB-X.

When you create an empty Ultra Project using UltraStudio, It will automatically create a project.xpml file as shown in the following image.

When you double click the project.xpml file, it will open as an XML document. As shown in following image, an empty project contains a few XML content in its project.xpml.

It contains the overall project details like project ID, project name, version and description. Also it has two XML tags, flows and resources. flows tag should contain the integration flows that are contained in the project. resources tag should contain resources that have to be added to the project.

This project.xpml file has two views, Design view and Text view. You can go to the Design view by selecting Design tab at the bottom of the page. In this view UltraStudio shows us a nice Graphical User Interface for the XML file.

As I mentioned before, the project.xpml file is used to add resources to the project. For example,

• when we want to use JMS ingress or egress connectors which use ActiveMQ, we have to add ActiveMQ Configuration beans to this file.
• when we want to use a database processor or connector in the integration flow, we have to add data source configurations to this file.

In this post, let’s see how to add a JMS ingress connector which uses ActiveMQ, to an integration flow. We will start with a simple flow that accepts a JSON message via an ActiveMQ queue, converts it to XML, and sends it to another ActiveMQ queue. We shall also make our flow transactional to ensure that the original message will be rolled back to the queue if we encounter an error during the conversion, or when sending the final message to the destination queue, with a Transaction Scope.

First of all, you should have an ActiveMQ server in your network. If you don’t, simply download and install ActiveMQ on your local machine. (This article assume that ActiveMQ is running on your local machine; if yours is not, then use the corresponding hostname (instead of localhost) for the subsequent activities; depending on your server you may need to change the port numbers as well.)

We also have to add the ActiveMQ client library to our project. This can be done by adding the activemq-all dependency in the pom.xml file.

Now we can start to develop our integration flow with UltraStudio.

Create a new integration flow by right-clicking on the conf folder.

Ensure that the necessary connector and processor dependencies are added to the project, via Tools → Ultra Studio → Component Registry. For this exercise we need the Spring JMS connectors and Message Transformation processors, so select (tick) them on the corresponding tabs if they are not already selected.

Add the connectors Spring JMS Listener and Spring JMS Sender, along with a JSON to XML Transformer, to the integration flow. Use a Transaction Scope (under Processors → Scope on the left pane) to connect the JSON to XML Transformer and Spring JMS Sender, and connect the Spring JMS Listener to the Transaction Scope Start Element (since the flow ends with the JMS sender you can simply delete the Transaction Scope End Element that gets added automatically). After connecting, the integration flow will look like this.

Now, we have to configure these elements.

For the Spring JMS Sender,

• Source queue: provide the name of an ActiveMQ queue from which the input message will be picked up (we can create the actual queue later on).
• Connection Factory: we need a JMS connection factory resource in order to establish connections with the source queue; however, since we have not defined any such resources yet, the drop-down list is empty at the moment.

The Transaction Scope does not need any additional configurations.

For the JSON to XML Transformer, you just have to add a name for the root tag of the output XML document.

For the Spring JMS Sender,

• JMS Destination: provide the name of the ActiveMQ queue to which you wish to send the transformed message. (ActiveMQ will create a new queue at runtime, if there is no existing queue for the given name.)
• JMS Template: we need to select a JMS template resource here; but similar to the Connection Factory configuration in the listener, we do not yet have a candidate for this drop-down list as well.

There are 4 ways to add the JMS template configurations to project.xpml, each of which we will discuss here. However, if you are in a hurry, skip down to the 4th way which is the easiest. (Each of these approaches are completely independent, so if you try a new approach, ensure that the changes done in the previous approach are completely reverted.)

(Before adding this resource, you should know about how to configure a JMS client with Spring. In effect, what we need is this configuration.)There are 4 ways to add the JMS template configurations to project.xpml, each of which we will discuss here. However, if you are in a hurry, skip down to the 4th way which is the easiest. (Each of these approaches are completely independent, so if you try a new approach, ensure that the changes done in the previous approach are completely reverted.)

(Before adding this resource, you should know about how to configure a JMS client with Spring. In effect, what we need is this configuration.)

1st way — Through the XML (Text) view, adding resources manually

Open project.xpml in Text view and type the resource beans as follows:

Save the file, and it’s done. Let’s check the second way.

2nd way — Through the Design view

Open project.xpml in Design view and click the [+]Bean Button.

Type “ActiveMQConnectionFactory” in the input box. When you do so, UltraStudio will suggest you the classes with names containing “ActiveMQConnectionFactory”. Select org.apache.activemq.ActiveMQConnectionFactory, and click Load to load setters and constructors for that class.

Provide a unique resource ID and fill properties that we want to define. In this case we only want to provide the brokerURL property. Fill it with tcp://localhost:61616 and click Save.

In the same way, load the org.springframework.jms.core.JmsTemplate class, select myConnectionFactory from the drop down menu for the connectionFactory property, and save it.

Now the Design view will look like this.

3rd way — Through a Custom Template

Without adding the interrelated resources one by one, we can define a single, reusable template to do it. Create a new Java class as follows:

Important: before the next step, compile this class, and close and reopen project.xpml if it is already open.

On project.xpml, now you will able choose your newly created template. You only need to provide the brokerURL in the template, and both resource beans will created (according to the template class) for you.

4th way — Through the built-in ActiveMQ JMS Template

UltraStudio already has a built-in ActiveMQ JMS template. So, instead of creating a template manually we can simply choose this template and provide the brokerURL as described before.

Using one of the above methods, add the JMS template resources to project.xpml.

Now we will be able to add myJmsTemplate (resource ID of the JMS template) to the Spring JMS Sender configuration. Also provide the name of the queue to which you want to send the message and save the configuration.

Similarly, select myJmsTemplate as the Connection Factory of the Spring JMS Listener, along with a source queue name.

If you followed one of the above 4 approaches, our configuration is almost complete. However, if you want the UltraESB-X platform to take care of transactionality, you need to make some more minor reconfigurations:

Ensure that you are using the built-in JMS template provided by UltraStudio (approach 4 above).

In the JMS Ingress Connector:

• ensure that you have selected myJmsTemplate-activeMQ-springCachingConnectionFactory as the Connection Factory (as opposed to myJmsTemplate-activeMQ-ConnectionFactory).
• on the Transaction tab, select myJmsTemplate-activeMQ-ultraTxnManager as the transaction manager (instead of myJmsTemplate-activeMQ-jmxTxnManager).

Now the hard part is over!

Build the project by running mvn clean install in the terminal.

Then launch the project with an UltraESB Server configuration.

Open the Ultra Studio Toolbox at the bottom, and open and configure a new JMS Client using the [+] button on the left pane:

1. Input the source queue (which you specified for the JMS listener) as the Destination Name.
2. Fill the Payload input with a sample JSON message (or select a JSON input file using the Import button).
3. Click the Settings (wrench) button.
4. Select the ActiveMQ option under JMS Configuration.
5. Fill in the Hostname (localhost) and Port (61616) configurations.

Now click the green arrow (Run) button, log in to the ActiveMQ Admin Panel and check the respective queue. You will observe that it contains a message containing the corresponding XML for the provided JSON input.

Congratulations, you now have a fully working JMS integration flow with JSON-to-XML payload transformation!

If you made the transactional reconfigurations described above, you can also check out what happens if the message flow fails. Send an invalid JSON payload (e.g. one missing the trailing curly brace) via the JMS Client toolbox and check the ESB run log in the IDE. The ESB will fetch the message several times (default: 7) but will fail to process it, and will rollback the message back to the source queue after each failure. Finally, the input message will be moved to the ActiveMQ dead letter queue, without the content being lost.

Stay tuned for more adventures with UltraStudio!