4. Examples

Bridge

Basic Example

Overview

This document describes how to run the Basic example and provides details about what it does. For information on the business use case, please refer to: Use Case for Basic.

The Basic example illustrates the following:

• use of declarative programming
• how to use an ActiveMQ message broker
• how to use a Quartz timer
• how to use the Jencks JCA container
• how to use the Geronimo Transaction Manager via the Jencks factory bean
• how to use tracing

The source code for the Basic example is located in the ServiceMix installation directory under the examples\basic\src\main\resources directory in the servicemix.xml file. It is recommended that you refer to the source code while reading this document.

There are several components in the servicemix.xmlfile. One component sets off a trigger to send messages to a source destination. Then those messages are consumed by another component and sent to a different output destination. A trace component displays the messages as they arrive.

Running the Basic Example

From a command shell, go to the Basic example directory:

cd [servicemix_install_dir]\examples\basic

Then type:

mvn jbi:embeddedServicemix

Handy Hint This example starts an ActiveMQ JMS Broker, so be sure to stop any ServiceMix server already running.

Stopping the Basic Example

To terminate the Basic example type "CTRL-C" in the command shell in which it is running.

How it Works

The diagram below illustrates the flow of messages through the Basic components.

Basic Example Message Flow Diagram

 

Messages flow through the components as follows:

1. The timer component sends a message to inputSender through the Normalized Message Router (NMR).
2. inputSender converts the message (marshals it) into a JMS message, then uses the jmsTemplate bean to publish the message.
3. jmsTemplate uses the jmsFactorybean to get a connection to the port associated with the JMS topic called "demo.org.servicemix.source." The message is published on the "demo.org.servicemix.source" topic.
4. jencks (the JCA resource adapter) listens on port 61616 for messages.
5. inputReceiver subscribes to the "demo.org.servicemix.source" topic via jencks and receives the JMS message.
6. inputReceiver normalizes the JMS message and sends it to outputSender via the NMR.
7. outputSender marshals the normalized message to a JMS message and uses jmsTemplate to publish the message on the "demo.org.servicemix.result" topic.
8. jmsTemplate publishes it on the "demo.org.servicemix.result" topic using jmsFactory to get a connection to the result topic.
9. jencks listens on port 61616 for messages.
10. jmsTrace subscribes to the "demo.org.servicemix.result" topic and receives the JMS message via jencks.
11. jmsTrace converts the JMS message into a normalized message and sends it to trace via the NMR.
12. trace transforms the normalized message into a string and logs it to the console.
    

Every 5 seconds logging information is written to the console, followed by information from the trace component. Note, that the triggers' property values of "name", "My Example Job", "group", and "ServiceMix" are displayed along with a timestamp. Typical output looks like the following:

INFO  TraceComponent - Exchange: InOnly[
  id: ID:guillaumes-1927-1157464363171-19:11
  status: Active
  role: provider
  service: {http://servicemix.apache.org/demo/}trace
  endpoint: trace
  in: <?xml version="1.0" encoding="UTF-8"?>
      <timer>
        <name>My Example Job</name>
        <group>ServiceMix</group>
        <fullname>ServiceMix.My Example Job</fullname>
        <description/>
        <fireTime>Tue Sep 05 15:53:39 CEST 2006</fireTime>
      </timer>

Details

The following table provides more details about the function of each component and bean in the servicemix.xml file.

1. jmsTemplate: JmsTemplate is a Spring component which hides the low level details when sending JMS messages. For additional information see: JmsTemplate. jmsTemplate is not a component in the jbi container. It is used by inputSender and outputSender.

Use case

ServiceMix is an Enterprise Service Bus (ESB) that is based on the Java Business Integration (JBI) standard JSR 208. The JBI-based design specifies a standards-based pluggable architecture with a JVM-based runtime component called the Normalized Message Router (NMR). The Basic example demonstrates how applications communicate via the ServiceMix ESB, and the role that the NMR can play in that communication. Similar techniques could be used to plug any external ¹ application or service into ServiceMix (e.g. SAP, Peoplesoft, spreadsheets, POJOs, Webservices and EJBs) and allow it to communicate with other external applications or components using ServiceMix itself.

A hypothetical business scenario, which extends the Basic Example, is that of a department store distributor. This distributor sells products from multiple wholesalers (suppliers) to various retailers (customers). The distributor presents a common interface for product ordering to each of its department store customers. However, the distributor must work with a different ordering interface for each wholesale suppliers for the products they are buying.

Using an ESB, the distributor has developed a number of components to receive department store orders and then dynamically route and transform these orders to the appropriate wholesaler. The order processing flow is described as follows:

1. Using the distributor's web interface, a department store customer submits an order for multiple products. An HTTP request is sent to the OrderReceiver, an HTTP binding component (BC). ³
2. The OrderReceiver sends the message to an OrderRouter service engine (SE) ⁴ component. This SE is responsible for parsing the order and deciding, based on the message content, which OrderTransformer should receive which part of the message (i.e., an order for a product).
3. The OrderRouter publishes the orders to the appropriate message topics based on the message content. Specifically, the OrderRouter publishes the messages based on which wholesaler sells the item.
4. The OrderTransformer is a service engine component, which modifies the message and puts it in a format which is readable by the wholesaler interface that will fulfill the order.
5. Each OrderTransformer sends the modified message to the OrderProcessor.
6. The OrderProcessor is a binding component that has two functions:
   a. It places an order to the appropriate wholesaler through the wholesaler's Webservice or proprietary interface.
   b. It also publishes a message about the order on a topic.
7. The message on the topic is subsequently picked up by the BusinessMonitor component via the jmsTrace component.
8. The BusinessMonitor component monitors the orders for quality assurance and business analytics, such as data mining.

The following diagram illustrates this:

Department Store Distributor's Order Processing System

1. External means the application is outside of the ESB.
2. Resource Adapter: a resource adapter provides connectivity between a specific external application and the ESB. In the Basic example the jencks container provides a JMS resource adapter.
3. Binding Component (BC): a BC provides connectivity to applications that are external to the ESB.
4. Service Engine (SE): a service engine provides business logic and transformation services to other components within the enterprise service bus.

Related Documentation

For more information on the following topics please see:

• ActiveMQ related components, jmsFactory, jmsTemplate, broker

• JCA Container, jencks

• Quartz timer

For a brief explanation of the XML tags in the servicemix.xml file, please see:

• XSD

4. Examples

Bridge