Overview of the ServiceMix Basic Example

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:

The source code for the Basic example is located in the ServiceMix installation directory under the examples\basic 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


Handy Hint

Note: if you are running version 3.0-M2 and experience an error like
  bla, bla, bla 'Bean class org.quartz.SimpleTrigger' not found bla, bla, bla
you probably need to run "ant setup" in \examples\basic directory to download additional packages (as Quartz, Common Pools and Common Collection)

Then type:

[servicemix_install_dir]\bin\servicemix servicemix.xml

where servicemix_install_dir is the directory in which ServiceMix was installed.

Handy Hint

Add $SERVICEMIX_HOME\bin directory to $PATH variable to simplify execution of the example.

Stopping the Basic Example

To terminate the Basic example type "CTRL-C" in the command shell in which it is running and answer "y" to the "Terminate batch job (y/n)?" question.

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: org.servicemix.jbi.messaging.InOnlyImpl@4fdf11 received IN message:
org.servicemix.jbi.messaging.NormalizedMessageImpl@1be0369{properties: {org.servicemix.jms.message=ACTIVEMQ_TEXT_MESSAGE:
id = 0 ActiveMQMessage{ , jmsMessageID = null, bodyAsBytes = org.activemq.io.util.ByteArray@1d1fc02,
readOnlyMessage = true, jmsClientID = 'ID:Lisas-2828-1126207917359-23:0' ,
 jmsCorrelationID = 'null' , jmsDestination = demo.org.servicemix.result, jmsReplyTo = null, jmsDeliveryMode = 2,
 jmsRedelivered = false, jmsType = 'null' , jmsExpiration = 0, jmsPriority = 4, jmsTime
stamp = 1126207938593, properties = {}, readOnlyProperties = true, entryBrokerName = 'ID:Lisas-2828-1126207917359-0:0' ,
entryClusterName = 'default' , consumerNos = [0], transactionId = 'null' , xaTransacted = false,
consumerIdentifer = 'ID:Lisas-2828-1126207917359-14:0' , messageConsumed = false, transientConsumed = true,
sequenceNumber = 7, deliveryCount = 1, dispatchedFromDLQ = false, messageAcknowledge = org.activemq.ActiveMQSession@1de7497,
jmsMessageIdentity = null, producerKey = ID:Lisas-2828-1126207917359-29: }, text = <?xml version="1.0" encoding="UTF-8"?>
<timer><name>My Example Job</name><group>ServiceMix</group><fullname>ServiceMix.My Example Job</fullname><description/><fireTime>
Thu Sep 08 12:32:18 PDT 2005</fireTime></timer>}}

Details

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

Component or Bean ID

Description

jbi

jbi is the "id" of the JBI container and provides the basic infrastructure services for the following components: timer, inputSender, inputReceiver, outputSender, jmsTrace, and trace. During initialization, several singletons are instantiated: transactionManager, broker, jencks, jmsFactory, and jbi. After initialization, the components in the jbi container are activated, starting with the timer component.

timer

The timer component shows the use of the QuartzComponent class. Every 5 seconds, until the program is terminated, the timer component kicks off an instance of a SimpleTrigger, which is associated with an instance of JobDetail. The job has a property called "name" with a value of "My Example Job" and another property called "group" with a value of "ServiceMix." The resulting message is converted to a normalized message and routed through the NMR.

inputSender

This is a component inside the JBI container. It receives the normalized message (the message from the trigger), converts it to a JMS message, and publishes it to the topic called demo.org.servicemix.source. It uses the jmsTemplate(1) bean to handle the publish.

inputReceiver

This component uses jencks , the JCA container, to listen on port 61616 for a JMS message on the topic called "demo.org.servicemix.source." inputReceiver subscribes to the demo.org.servicemix.source topic. It takes the message, normalizes it, and routes it to outputSender via the NMR. This component combined with outputSender and supporting beans creates a JMS bridge between two topics.

outputSender

This component receives a normalized message from the NMR, marshals it into a JMS message using jmsTemplate, then publishes it on the ActiveMQ (JMS) topic called "demo.org.servicemix.result."

jmsTrace

This component uses jencks to subscribe to the "demo.org.servicemix.result" topic and get messages. It then marshals the message into a normalized message and routes it via the NMR to the trace component.

trace

Receives normalized messages from jmsTrace via the NMR. It transforms the normalized message into a string and logs it to the console.

jencks

The jencks bean defines a JCA container. The JCA container allows you to configure thread pool size, configure a transaction manager, and configure a resource adapter. In this example, the resource adapter is an ActiveMQ adapter, however, another JMS listener could be configured instead. This adapter listens on port 61616 for JMS messages.

broker

The broker bean uses the activemq.xml file to configure the message broker, which handles the JMS messages for the components that require JMS messaging services.

transactionManager

This bean is configured to be the default transaction manager for the jbi container. jencksis configured to use the default transaction manager. This transaction manager provides transactional services between the resource adapter (in this case the ActiveMQ resource adapter provided by the jencks JCA container) and components the jbi container.

jmsFactory

This bean listens on port 61616 and provides a pooled ActiveMQ connection.

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.

Issues

The ServiceMix 2.0.2 distribution has a known logging bug, so output is not logged to the console. This can be corrected in the sourcedistribution of ServiceMix 2.0.2, by replacing the jencks-all-1.1.1.jar with the jencks-all-1.1.2.jar file. Upgrading to 2.0.3 will also resolve the problem. 2.0.3 release is a developer's release at this time. Please see Download for the latest developer's release.

This procedure explains the work around for 2.0.2.

  1. Download the jencks-all-1.2.jar here.
  2. Copy the jar file to [servicemix_src_install_dir]\assembly\target\servicemix-2.0.2\bin\servicemix-2.0.2\lib, where [servicemix_src_install_dir] is the directory in which the ServiceMix distribution is located.
  3. Delete jencks-all-1.1.1.jar from that directory.
  4. Place a copy of the jar file in the ServiceMix web directory at [servicemix_src_install_dir]\servicemix-2.0.2\tooling\servicemix-web\target\servicemix-web\WEB-INF as well.
  5. To run the example in the source distribution: 
    cd [servicemix_src_install_dir]\assembly\target\servicemix-2.0.2\bin\servicemix-2.0.2\bin

..\..\bin\servicemix servicemix.xml
  6. test

Note: It is not necessary to build the source distribution if you have previously done so. If ServiceMix has not been built, execute the above steps before building. The procedure on how to build the source distribution can be found here.

Related Documentation

For more information on the following topics please see:

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

  • No labels

1 Comment

  1. Joseph Dennis O. Gapuz

    - please update the Servicemix version from the heading - Overview of the ServiceMix 1.x Basic Example.