Apache ServiceMix Documentation
Apache Software Foundation Table of Contents
1. User Guide ...... 1
1.1. Introduction ...... 1
1.2. What is (in) ServiceMix? ...... 1
1.2.1. Platform presentation ...... 1
1.2.2. OSGi for Dummies...... 1
1.2.3. Powered by Apache Karaf...... 2
1.2.4. Apache Camel...... 3
1.2.5. Services proposed ...... 3
1.3. Technology selection guide ...... 4
1.3.1. When to use Camel? ...... 4
1.3.2. When to use ActiveMQ?...... 4
1.3.3. When to use CXF? ...... 4
2. Quickstart Guide...... 5
2.1. Introduction ...... 5
2.2. Installation ...... 5
2.2.1. System requirements ...... 5
2.2.2. Downloading Apache ServiceMix ...... 5
2.2.3. Installing Apache ServiceMix...... 5
2.2.4. Starting Apache ServiceMix ...... 6
2.3. Apache ServiceMix console ...... 7
2.3.1. Working with bundles ...... 7
2.3.2. Working with logging...... 8
2.3.3. …and there’s a lot more...... 9
2.4. Using Camel ...... 9
2.4.1. Our simple scenario ...... 10
2.4.2. Creating the route ...... 10
2.4.3. Deploying the route ...... 10
2.4.4. Using the shell to manage the route...... 10
2.5. Adding ActiveMQ to the 'Mix ...... 11
2.5.1. Our scenario...... 11
2.5.2. Moving files and sending event messages ...... 11
2.5.3. Receiving the event messages ...... 12
2.5.4. Using the shell to manage the routes ...... 13
2.6. Optional features ...... 13
2.6.1. List of features...... 13
2.6.2. Example: web console ...... 13
2.7. Wrapping it up…...... 14
3. Camel Guide...... 14 3.1. Introduction...... 14
3.1.1. Camel in ServiceMix...... 14
3.1.2. Goal of this guide ...... 14
3.1.3. Examples...... 14
3.1.4. More information about Camel...... 14
3.2. Deployment Options ...... 15
3.2.1. Benefits and drawbacks ...... 15
3.2.2. Deploy as a plain Spring XML file ...... 15
3.2.3. Deploy as a plain Blueprint XML file ...... 17
3.2.4. Deploy as an OSGi bundle with Spring ...... 19
3.2.5. Deploy as an OSGi bundle with Blueprint ...... 19
3.3. Installing Components...... 23
3.3.1. List available components ...... 23
3.3.2. Install and uninstalling components ...... 23
3.4. Troubleshooting ...... 23
3.4.1. No component with id 'xyz' could be found ...... 23
4. ActiveMQ Guide ...... 24
4.1. Introducing ActiveMQ ...... 24
4.1.1. ActiveMQ Supports...... 24
4.1.2. Using ActiveMQ from ServiceMix ...... 25
4.1.3. When should I use ActiveMQ? ...... 25
4.1.4. Common use cases ...... 25
4.2. Using ActiveMQ with Camel...... 25
4.2.1. Objectives ...... 25
4.2.2. Prerequisites ...... 25
4.2.3. ActiveMQ and ServiceMix Web Consoles ...... 26
4.2.4. Blueprint Example Explained ...... 26
4.2.5. Building, Running, and Modifying the Example ...... 28
5. Activiti Guide...... 28
5.1. Introducing Activiti ...... 28
5.1.1. Activiti Engine ...... 28
5.2. Goal of this guide ...... 29
5.3. Examples...... 29
5.4. More information about Activiti...... 29
5.5. Using Activiti with Camel ...... 29
5.5.1. Blueprint configuration...... 30
5.5.2. Route Definition ...... 31
5.5.3. Process definition ...... 32
5.5.4. Building and running the example...... 34
6. Karaf User Guide ...... 34
7. Karaf Developer Guide ...... 34 8. Resources ...... 34
8.1. Books ...... 34
8.2. Websites ...... 37 1. User Guide
1.1. Introduction
Apache ServiceMix is a flexible, open-source integration container that unifies the features and functionality of Apache ActiveMQ, Camel, CXF and Karaf into a powerful runtime platform for building integrations solutions.
The goal of this document is to introduce you to the different components that are part of Apache ServiceMix and explain how and when they can be used together.
1.2. What is (in) ServiceMix?
Apache ServiceMix is an open source ESB (Enterprise Service Bus) that combines the functionality of a Service Oriented Architecture (SOA) and the modularity. The adoption of a Service Bus allows to decouple the applicatons together and reduce dependencies. Messages are used to wire together applications (=services) and/or connectors to exchange information using different protocols or communication modes like FTP, HTTP, and web services.
Apache ServiceMix is designed on top of the OSGI specification. Using OSGI framework brings a new important feature to SOA development: modularity. That means that we can handle classloading and application lifecycle differently between the components.
ServiceMix is lightweight and easily embeddable, has integrated Spring support and can be run at the edge of the network (inside a client or server), as a standalone ESB provider or as a service within another ESB. You can use ServiceMix in Java SE or Java EE application server.
1.2.1. Platform presentation
Apache ServiceMix is a distributed ESB built from the ground up and released under the Apache license.
ServiceMix uses ActiveMQ to provide remoting, clustering, reliability and distributed failover.
ServiceMix can also be embedded into a JEE application server such as JBoss WildFly, Oracle Weblogic or IBM Websphere.
1.2.2. OSGi for Dummies
OSGi technology is the dynamic module system for Java. The OSGi Service Platform provides functionality to Java that makes Java the premier environment for software integration and thus for development. Java provides the portability that is required to support products on many different platforms. The OSGi technology provides the standardized primitives that allow applications to be constructed from small, reusable and collaborative components. These components can be composed into an application and deployed.
The OSGi Service Platform provides the functions to change the composition dynamically on the device of a variety of networks, without requiring restarts. To minimize the coupling, as well as
1 make these couplings managed, the OSGi technology provides a service-oriented architecture that enables these components to dynamically discover each other for collaboration. The OSGi Alliance has developed many standard component interfaces for common functions like HTTP servers, configuration, logging, security, user administration, XML and many more. Plug-compatible implementations of these components can be obtained from different vendors with different optimizations and costs. However, service interfaces can also be developed on a proprietary basis.
OSGi technology adopters benefit from improved time-to-market and reduced development costs because OSGi technology provides for the integration of pre-built and pre-tested component subsystems. The technology also reduces maintenance costs and enables unique new aftermarket opportunities because components can be dynamically delivered to devices in the field.
For more information, check out the OSGi Alliance website.
1.2.3. Powered by Apache Karaf
Apache ServiceMix is based on Apache Karaf. Apache Karaf is a small OSGi-based runtime which provides a lightweight container onto which various components and applications can be deployed.
Here is a short list of features supported by the Karaf:
Hot deployment: Karaf supports hot deployment of OSGi bundles by monitoring jar files inside the $home/deploy directory. Each time a jar is copied in this folder, it will be installed inside the runtime. You can then update or delete it and changes will be handled automatically. In addition, the Karaf also supports exploded bundles and custom deployers (Blueprint and Spring ones are included by default).
Dynamic configuration: Services are usually configured through the ConfigurationAdmin OSGi service. Such configuration can be defined in Karaf using property files inside the $home/etc directory. These configurations are monitored and changes on the properties files will be propagated to the services.
Logging System: using a centralized logging back end supported by Log4J, Karaf supports a number of different APIs (JDK 1.4, JCL, SLF4J, Avalon, Tomcat, OSGi)
Provisioning: Provisioning of libraries or applications can be done through a number of different ways, by which they will be downloaded locally, installed and started.
Native OS integration: Karaf can be integrated into your own Operating System as a service so that the lifecycle will be bound to your Operating System.
Extensible Shell console: Karaf features a nice text console where you can manage the services, install new applications or libraries and manage their state. This shell is easily extensible by deploying new commands dynamically along with new features or applications.
Remote access: use any SSH client to connect to Karaf and issue commands in the console .
Security framework based on JAAS.
Managing instances: Karaf provides simple commands for managing multiple instances. You can easily create, delete, start and stop instances of Karaf through the console.
2 For more information, check out the Apache Karaf project page.
1.2.4. Apache Camel
Apache Camel is a powerful open source integration framework based on known Enterprise Integration Patterns with powerful Bean Integration.
Apache Camel lets you create the Enterprise Integration Patterns to implement routing and mediation rules in either a Java based Domain Specific Language (or Fluent API), via Spring based Xml Configuration files or via the Scala DSL.
For more information, check out the Using Apache Camel in ServiceMix User Guide.
1.2.5. Services proposed
TODO: write this bit
Message Broker : Apache ActiveMQ
Apache ServiceMix ships with an embedded instance of Apache ActiveMQ out-of-the-box.
It is a fully functional Apache ActiveMQ message broker instance listening for TCP connections on port 61616 and STOMP connections on port 61613.
The default configuration for the Apache ActiveMQ message broker resides in the ServiceMix installation directory under the etc sub-directory. The ActiveMQ configuration file is named activemq.xml. It’s configured with reasonable default information like Persistence (KahaDB) and Producer Flow Control (essentially to make sure the broker does not run out of memory).
The configuration file also makes use of a reusable connection pool available to all OSGi bundles exposing a javax.jms.ConnectionFactory as a service for consumption. You can re-use this connection pool via tools such as spring-dm or blueprint.
The ActiveMQ message broker allows several components such as servicemix-cluster, camel-jms, camel-activemq, cxf-jms transport to be utilized without any additional configuration.
Transaction : Geronimo Transaction Manager
TODO: write this bit
Routing and Mediation : Apache Camel
TODO: write this bit
Web Services : Apache CXF
TODO: write this bit
Web Container
TODO: write this bit
3 SOA platform
TODO: write this bit
Spring DM container
TODO: write this bit
Blueprint OSGI container
TODO: write this bit
EJB Container
TODO: write this bit
1.3. Technology selection guide
ServiceMix offers a set of different messaging and integration technologies:
• ActiveMQ
• Camel
• CXF
Depending on the solution you’re building, you want to select one or more of these technologies. Below are some guidelines to help you pick the right mix for your problem.
1.3.1. When to use Camel?
For any integration scenario, we recommend to start as simple as possible. Camel allows you to build routes for integration scenario’s quickly and efficiently. You can deploy these routes directly on ServiceMix by deploying the plain Spring XML route or by packaging the route in an OSGi bundle.
As you need more (advanced) features, start combining Camel with ActiveMQ and CXF.
1.3.2. When to use ActiveMQ?
ActiveMQ is a JMS message broker, featuring support for clustering, pluggable persistence mechanism, master-slave configuration for failover, and more.
ServiceMix includes an instance of the ActiveMQ broker, which can be combined with Camel to provide easy-to-use message persistence and reliable messaging.
After setting up multiple instances of ActiveMQ (or ServiceMix) on the network, you can configure ActiveMQ clustering or master-slave mode to allow for a more reliable and scalable set-up.
1.3.3. When to use CXF?
CXF is an open-source services framework that you can use to suit your REST and WS-* standards
4 integration needs. It allows you to use common programming APIs like JAX-RS or JAX-WS for building your own services and to expose them to the outside world.
You can use CXF from within your Camel routes with the Camel CXF component.
2. Quickstart Guide
2.1. Introduction
First of all, welcome to the Apache ServiceMix project!
The goal of this Quickstart guide is to give you a 20-minute overview of what ServiceMix is and what you can do with it. In that time, we’ll install ServiceMix on your machine, deploy some basic integration routes and extend the container with an additional feature.
2.2. Installation
Before we can start working with Apache ServiceMix, we have to get it installed and running on our local machine first.
2.2.1. System requirements
For running Apache ServiceMix itself, you’ll need
• Java Runtime Environment (JRE) 1.7.x (Java 7) or Java Runtime Environment (JRE) 1.8.x (Java 8)
• About 100 MB of free disk space for the default assembly
If you’re developing your own integration applications and OSGi bundles, you’ll also need
• Java Developer Kit (JDK) 1.7.x (Java 7) or Java Developer Kit (JDK) 1.8.x (Java 8)
• Apache Maven 3.0.4 or higher
2.2.2. Downloading Apache ServiceMix
Apache ServiceMix 7.0.1-SNAPSHOT is available under the Apache License v2 and can be downloaded from http://servicemix.apache.org/downloads.html.
Depending on your operation system, you should download either the tar.gz or the zip file:
• tar.gz for Linux/Unix/MacOS X
• zip for Windows
2.2.3. Installing Apache ServiceMix
Installing Apache ServiceMix is as simple as uncompressing the downloaded archive on your hard disk. For the rest of this guide, we’ll refer to the this location as
5 2.2.4. Starting Apache ServiceMix
Depending on your platform, start Apache ServiceMix by following the instructions below. After starting the container, you will have access to the console from which you can manage the container.
On Windows
In a command prompt window, navigate to the directory where you extracted ServiceMix and run the bin\servicemix.bat file.
Example: if ServiceMix in installed in the c:\tools\apache-servicemix-7.0.1-SNAPSHOT directory
> cd c:\tools\apache-servicemix-7.0.1-SNAPSHOT > .\bin\servicemix
On Linux/Unix/MacOS X
On a command shell, navigate to the directory where you extracted ServiceMix and the bin/servicemix shell script
Example: if ServiceMix is installed in the ~/bin/apache-servicemix-7.0.1-SNAPSHOT directory.
$ cd ~/bin/apache-servicemix-7.0.1-SNAPSHOT $ ./bin/servicemix
6 2.3. Apache ServiceMix console
Now that we successfully installed and started Apache ServiceMix, we’ll take a closer look at the console. This is where you manage your ServiceMix instance, add and remove bundles, install optional features, and more.
2.3.1. Working with bundles
When ServiceMix is first started, a whole set of bundles providing the core features for the product are being installed. Let’s use the command console to find out more about them.
The bundle:list command can be used to get a list of all bundles currently installed. Enter this
karaf@root> bundle:list
This is what the output looks like if you run this on your ServiceMix instance.
For every bundle, you see:
7 • the bundle id
• the bundle state
• the bundle start level
• the bundle version and name
If you’re looking for something specific in the list, you can use unix-like pipes and utilities to help you. An example: to look for all Camel related bundles:
karaf@root> bundle:list | grep camel
2.3.2. Working with logging
Many of the applications you write will have some form of log output. To look at the message in the log file, you can us the log:diplay command.
karaf@root> log:display
If you’re only interested in the latest exception in the log file, you can use log:exception-display instead.
karaf@root> log:exception-display
8 You can also change the log level at runtime by using the log:set command. You can try these commands on your instance now by first setting the log level to DEBUG and then using grep to make sure that you can actually see the extra logging.
karaf@root> log:set DEBUG karaf@root> log:display | grep DEBUG
Afterwards, revert the log level to its original INFO value again with log:set.
karaf@root> log:set INFO
2.3.3. …and there’s a lot more
These are obviously just a few examples of what the command shell is all about. There are a lot more commands in the shell to help you deploy, monitor, manage and troubleshoot the applications you’re building with ServiceMix.
2.4. Using Camel
Now that we know how to operate Apache ServiceMix through the shell console, it’s time to start
9 using it for what it is built for. Let’s build our very first integration solution with a Camel route and deploy it on ServiceMix.
2.4.1. Our simple scenario
In this simple scenario, we’re going to move files from an input directory called camel/input to an output directory called camel/output. To ensure we can keep track of which files get moved, we’ll also write a message to the log file whenever we move a file.
2.4.2. Creating the route
One of the most simple ways to deploy a new route on ServiceMix, is by defining the route in a Blueprint XML file.
2.4.3. Deploying the route
In order to deploy and start the route, just copy the XML file you created into ServiceMix' deploy directory. The file will get picked up and deployed by ServiceMix. You will see a camel/input folder appear in your ServiceMix installation directory and any files you copy into that directory will get moved into the camel/output directory.
If you do a log:display in the shell, you will also see the log output for every file that’s been moved.
2.4.4. Using the shell to manage the route
Using bundle:list, you’ll notice that your XML file has been transformed into a bundle and that the
10 Blueprint container has been created to start your Camel route.
From this output, you also learn that the bundle id for your XML file is 250. This allow you to start and stop the route whenever necessary. Let’s give this a go now:
First, stop the route with
karaf@root> bundle:stop 250
The route is no longer active, so any files you copy into the orders/input folder will remain there for now. As soon as you restart the route, the pending files will get moving again.
karaf@root> bundle:start 250
2.5. Adding ActiveMQ to the 'Mix
Out-of-the-box, every Apache ServiceMix instance comes with an embedded ActiveMQ JMS broker. This makes it easy to communicate between Camel routes using persistent messages on the same machine, but it will also enable you to distribute your routes over multiple instances afterwards for clustering or load-balancing.
2.5.1. Our scenario
In this scenario, we also want to move files between directories. Instead of logging the move directly, we are going to send an event JMS message onto a queue. Afterwards, we will create a second Camel route to receive the events and log them.
2.5.2. Moving files and sending event messages
The first Blueprint XML file we’ll create contains a Camel route that moves the files from activemq/input to the activemq/output directory. Afterwards, it will generate an event message and send that to an ActiveMQ queue called events.
11
Save this file in ServiceMix' deploy folder and use bundle:list to check on the bundle status as you did with the simple Camel example. You should now be able to put files in the activemq/input directory and see them being moved to activemq/output.
2.5.3. Receiving the event messages
After deploying the first XML file, you’re obviously not seeing any events being logged yet. The event messages are sent to an ActiveMQ queue, but there’s nobody to receive the events yet. Let’s change that now by creating a second Blueprint XML file.
12 As soon as this second file has been deployed, you’ll start seeing the event messages in your log:display output.
2.5.4. Using the shell to manage the routes
You can now start and stop both routes from the command shell. The important thing to note here is that you can stop the event handler route while files are being processed. As soon as you restart that bundle afterwards, you’ll receive the events from all files that have been moved while the route was not running.
2.6. Optional features
Everything discussed in the quickstart guide so far is installed out-of-the-box in Apache ServiceMix, but we also have a lot of optional features that can be installed in the container when necessary.
2.6.1. List of features
The list of features is available with the feature:list command. The overview shows you whether or not the feature is currently installed, the version and the name of the feature.
The full list contains a lot of different features: optional Camel components, features for adding OBR or wrapper support to ServiceMix, a web console, and many more. Again, you can use things like | and grep to find the things in the list that you’re interested in.
karaf@root> feature:list | grep camel
2.6.2. Example: web console
To get the web console installed in ServiceMix, install the feature from your console
karaf@root> feature:install webconsole
Afterwards, you can verify that the feature is installed and started in the overview.
karaf@root> feature:list | grep -i webconsole
13 You will now be able to point your browser to http://localhost:8181/system/console and login with user smx and password smx to access the web console. From the webconsole, Karaf can be managed, including starting and stopping bundles, installing and uninstalling features, and managing the configuration.
2.7. Wrapping it up…
This is where our introductory journey through the world of Apache ServiceMix ends. We’ve obviously just scratched the surface of what is possible, but we hope you have an idea of what you can expect from Apache ServiceMix and how you can use it in your environment.
For more in-depth information, have a look at our set of user guides. Also, if you have any questions, we welcome you on our user mailing list!
3. Camel Guide
3.1. Introduction
Apache Camel is a powerful open source integration framework based on known Enterprise Integration Patterns with powerful Bean Integration.
3.1.1. Camel in ServiceMix
In ServiceMix, Apache Camel is like our swiss army knife for creating integration solutions. It allows using XML or a Java/Scala-based DSL to express your routes, comes with almost 200 optional components, has powerful and versatile Java bean integration, error handling, and tons of other features.
Apache Camel is installed by default if you first start the container. We also have out-of-the-box hot- deployment support for both Spring and Blueprint to make it easy to deploy your own Camel routes, as well as optionally installable features for all the available Camel components.
3.1.2. Goal of this guide
The goal of this guide is to look into the details for using Camel inside ServiceMix:
• deployment options
• installing additional components
3.1.3. Examples
The Apache ServiceMix distribution also contain a set of Camel examples. You can find these examples in the examples/camel directory.
3.1.4. More information about Camel
More information about Camel itself can be found on http://camel.apache.org.
14 There’s also a great book available about Camel. Its second edition is planned to be published in July 2017:
• Ibsen, Claus, and Anstey, Jonathan. (July 2017). Camel in Action, Second Edition. Manning Publications. ISBN: 9781617292934.
3.2. Deployment Options
There are a few different ways to deploy Camel routes on ServiceMix:
• deploy routes in a plain Blueprint XML file
• deploy routes in a plain Spring XML file
• deploy a bundle containing a Blueprint XML file
• deploy a bundle containing a Spring XML file
3.2.1. Benefits and drawbacks
Plain XML or OSGi bundles
Choose a plain XML file:
• if you want to get routes deployed as quickly as possible. All you need for developing routes is a simple text editor, no compilation and building is required.
• if you prefer the XML syntax over the Java of Scala DSL.
Choose an OSGi bundle:
• if you want to package helper classes together with your route definitions.
• if you prefer developing routes in the Java or Scala DSL. The RouteBuilder implementations can be packaged inside the bundle.
Blueprint or Spring
Choose Blueprint if you want the best possible integration with the OSGi Framework and Service Registy. The Blueprint specification has been developed specifically for the OSGi Framework by the OSGi Alliance.
Choose Spring if you already invested in Spring for creating and running Camel routes.
3.2.2. Deploy as a plain Spring XML file
ServiceMix supports the deployment of plain Spring XML files, automatically creating and starting the Spring ApplicationContext from the XML file.
In order to leverage this feature to create and start Camel routes, drop a file with this syntax in the $SERVICEMIX_HOME/deploy folder:
15
Example
Create a new XML file, plain-spring.xml, in the deployment folder with the code below to start a route to copy files from one directory to another.
16
Verify in the Karaf console that it has been started:
karaf@root> bundle:list | grep plain-spring 223 | Active | 80 | 0.0.0 | plain-spring.xml karaf@root>
Copy a file into the folder $SERVICEMIX_HOME/input, and verify that it is copied to the folder $SERVICEMIX_HOME/output. Note that the original file has been moved to the folder $SERVICEMIX_HOME/input/.camel.
3.2.3. Deploy as a plain Blueprint XML file
ServiceMix supports the deployment of plain Blueprint XML files, automatically creating and starting the Blueprint container from the XML file.
In order to leverage this feature to create and start Camel routes, drop a file with this syntax in the $SERVICEMIX_HOME/deploy folder:
17
Example
Create a new XML file, plain-blueprint.xml, in the deployment folder with the code below to start a route to copy files from one directory to another.
Verify in the Karaf console that it has been started:
karaf@root> bundle:list | grep plain-blueprint 223 | Active | 80 | 0.0.0 | plain-blueprint.xml karaf@root>
Copy a file into the folder $SERVICEMIX_HOME/input, and verify that it is copied to the folder $SERVICEMIX_HOME/output. Note that the original file has been moved to the folder $SERVICEMIX_HOME/input/.camel.
18 3.2.4. Deploy as an OSGi bundle with Spring
Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes.
In this case, you’re using Spring to start your Camel routes, so you include your Spring XML file (e.g. camel-context.xml) in the META-INF/spring folder inside your bundle.
+
After the bundle has been activated, the Spring DM extender will find, create and start your Spring ApplicationContexts.
Example: Referring to Java or Scala RouteBuilder classes
If your RouteBuilder classes have been defined in the org.apache.servicemix.manual.camel package, the file would look like this:
Example in the distribution
Another example for using this deployment option can be found in the camel-osgi example that is shipped with Apache ServiceMix.
3.2.5. Deploy as an OSGi bundle with Blueprint
Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes.
19 In this case, we will use a Blueprint XML file to start your Camel routs. To do so, the Blueprint XML files have to be included in the bundle inside the OSGI-INF/blueprint directory.
+
As soon as the bundle becomes Active, the Blueprint extender will create the Blueprint container starting your Routes.
Example: Referring to Java or Scala RouteBuilder classes
If your RouteBuilder classes have been defined in the org.apache.servicemix.examples.camel package, the file would look like this:
Example in the distribution
Another example for using this deployment option can be found in the camel-blueprint example that is shipped with Apache ServiceMix.
In order to add a Java DSL route to that example, the following changes have to be implemented.
First, add the camel-core library as a dependency to the pom-file:
20 Then, add the following class to the org.apache.servicemix.examples.camel-package, alongside the existing MyTransform-class:
package org.apache.servicemix.examples.camel;
import org.apache.camel.builder.RouteBuilder;
public class MyRouteBuilder extends RouteBuilder {
public void configure() { // set up the transform bean MyTransform transform = new MyTransform(); transform.setPrefix("JavaDSL");
from("timer://javaTimer?fixedRate=true&period=2000") .bean(transform, "transform") .to("log:ExampleRouter"); } }
Finally, add the package-element to the Blueprint-file. The complete Blueprint file looks like this:
21
②
① The package-element causes the route defined by the Java DSL to be installed and started.
② The route defined by XML tags and the one defined by the Java DSL are functionally equivalent, and run independently.
③ The default value of the prefix-parameter is displayed in the output in the Karaf console, unless it is changed in the example configuration file.
Once you have built the example, with mvn clean install, and installed it in Karaf using feature:install examples-camel-blueprint output from both routes will be displayed in the Karaf console:
>>>> Blueprint-Example set body: Sun May 07 13:38:47 CEST 2017 >>>> JavaDSL set body: Sun May 07 13:38:47 CEST 2017
22 3.3. Installing Components
Camel comes with almost 200 components, so you can imagine that we don’t install all of them by default. This section shows you how to find available components and how to install them at runtime.
3.3.1. List available components
Camel components are available as installable features. You can look at the full list of available features using the feature:list command, using grep to limit things down to features related to Camel:
karaf@root> feature:list | grep camel camel-xmlsecurity | 2.16.5 | | Uninstalled | camel-2.16.5 | camel-xmpp | 2.16.5 | | Uninstalled | camel-2.16.5 | camel-xstream | 2.16.5 | x | Started | camel-2.16.5 | camel-yammer | 2.16.5 | | Uninstalled | camel-2.16.5 | camel-zipfile | 2.16.5 | | Uninstalled | camel-2.16.5 |
3.3.2. Install and uninstalling components
You can use feature:install to install any component on the list.
An example: to install the camel-cache component
karaf@root> feature:install camel-cache
Similarly, you can also uninstall components that you’re no longer using with feature:uninstall
karaf@root> feature:uninstall camel-cache
3.4. Troubleshooting
In this section, you’ll find solutions for some frequently asked questions when using Camel on ServicMix.
3.4.1. No component with id 'xyz' could be found
This usually means that your route is trying to use a component that hasn’t been installed yet.
Solution:
1. install the additional component
2. restart the bundle using the bundle:restart
23 Refer to Installing additional components
4. ActiveMQ Guide
4.1. Introducing ActiveMQ
Apache ActiveMQ is the most popular and powerful open source messaging and Integration Patterns provider. Apache ActiveMQ is fast, supports many Cross Language Clients and Protocols and many advanced features while fully supporting JMS 1.1 and J2EE 1.4. Apache ActiveMQ is released under the Apache 2.0 License.
4.1.1. ActiveMQ Supports
Easy communication via Cross Language Clients
• ActiveMQ C++ Clients
• Ajax
• C Integration
• CMS
• Delphi and FreePascal
• dot Net
• Perl
• PHP
• Pike
• Python
• Ruby
• WebSockets
• JMS to JMS Bridge
Several Protocols
• AMQP
• OpenWire
• REST
• RSS and Atom
• Stomp
• WSIF
• WS Notification
• XMPP
24 4.1.2. Using ActiveMQ from ServiceMix
To start using ActiveMQ from your code, simply get hold of the connection pool declared in the activemq.xml file. You can also utilize ActiveMQ from Camel via the camel-jms component.
4.1.3. When should I use ActiveMQ?
Whenever you have a unit of work or payload that you could process asynchronously, you would like to have multiple recipients, concurrent competing recipients to scale or leverage multiple processing units. If you want to spread load across multiple system boundaries. You want to cluster or provide fail over and messaging security, you have long running flows.
In any of these instances it would be strongly suggested you evaluate what a scalable and secure messaging solution can bring to the table.
4.1.4. Common use cases
Integration with other systems, since you can pass messages in and out of ActiveMQ from pretty much any programming language it is very simple to start integrating heterogeneous environments.
Providing an event driven architecture. You can develop your solutions based on actions as opposed to looking for data or relying on completely synchronous behaviour.
Providing infrastructure for messaging across large distances, leverage the network connectors and broker networks to integrate for example geographically different data centres.
4.2. Using ActiveMQ with Camel
This sections is based on the activemq-camel-blueprint example in the ServiceMix distribution.
4.2.1. Objectives
The objectives of this sections are to explain how to
• define Camel routes as an OSGi bundle using Blueprint,
• publish messages to an ActiveMQ queue,
• consume messages from an ActiveMQ queue,
• build and install the OSGi bundle,
• write messages to the log.
4.2.2. Prerequisites
For this example, it is assumed that ServiceMix, Java and Maven are installed locally on your machine. Further, it is assumed that ServiceMix is up and running.
25 4.2.3. ActiveMQ and ServiceMix Web Consoles
The ActiveMQ web console can be used to inspect and manage ActiveMQ configuration, queues and topics. If ServiceMix is running locally, the console can be accessed at http://localhost:8181/ activemqweb/.
If the ActiveMQ web console has not been installed previously, install the feature from the Karaf console:
karaf@root> feature:install activemq-web-console
Note that the ServiceMix console is accessible at http://localhost:8181/system/console/, with default username smx, and password smx. This feature can be installed from the Karaf console using
karaf@root>feature:install webconsole
Inspect the ActiveMQ web console before running the example. Note that initially, there are no queues defined.
4.2.4. Blueprint Example Explained
The following Blueprint XML-file is based on the example included in the ServiceMix distribution. Configuration related to the custom transformation bean and handling of persistent properties have been removed for simplicity.
26
① A Camel timer endpoint generates a heartbeat event every 2000ms, generating a new message.
② The timer message is transformed by the transform method of the bean referenced by myTransform.
③ The message is sent to the LOG.ME queue on the ActiveMQ broker. This queue is created automatically.
④ The message is consumed from the LOG.ME queue on the ActiveMQ broker.
⑤ A Camel log endpoint sends the message to the Jakarta commons logger. By default, the log is written to _c:\bin\apache-servicemix-7.0.0\data\log\servicemix.log.
⑥ The persistent property prefix has a default value of ActiveMQ-Blueprint-Example and can be configured in the file org.apache.servicemix.examples.cfg if desired.
⑦ The bean myTransform references the class org.apache.servicemix.examples.activemq.MyTransform. This class has one configurable property, prefix. The expression ${prefix} links it to the corresponding persistent cm:property.
The class org.apache.servicemix.examples.activemq.MyTransform transforms the message, using the
27 prefix, some text and the current date. It writes to both a logger and System.out.
4.2.5. Building, Running, and Modifying the Example
Open a command window and navigate to the example directory, e.g. c:\bin\apache-servicemix- 7.0.0\examples\activemq\activemq-camel-blueprint\.
If you are using ServiceMix 7.0.0 download the pom.xml-file from https://issues.apache.org/jira/browse/SM-3225 and replace the pom.xml-file in the examples folder of the distribution with this.
Build the bundle by executing mvn clean install. After a successfull build, install the bundle from the Karaf console using
karaf@root> feature:install examples-activemq-camel-blueprint
Almost immediately, log messages begin to appear in the Karaf console.
Open the ActiveMQ web console at http://localhost:8181/activemqweb/ and inspect the Queues: the queue LOG.ME has automatically been created.
Edit the class MyTransform and set verbose=false; to suppress the messages written to the Karaf console. Rebuild the bundle, and reinstall it. Note that the bundle needs to be uninstalled before it can be re-installed:
karaf@root> feature:uninstall examples-activemq-camel-blueprint karaf@root> feature:install examples-activemq-camel-blueprint
The relation between the feature name, examples-activemq-camel-blueprint, and the Maven artifact coordinates is defined in the file servicemix-examples-7.0.1- SNAPSHOT-features.xml in the ServiceMix distribution.
5. Activiti Guide
5.1. Introducing Activiti
Activiti is a BPMN 2.0 process-engine framework that implements the BPMN 2.0 specification. It’s able to perform BPMN 2.0 functions including deploy process definitions, start new process instances, and execute user tasks. Its core is a super-fast and rock-solid BPMN 2 process engine for Java.
5.1.1. Activiti Engine
This is the heart of the Activiti project. It’s a Java process engine that runs BPMN 2 processes natively. It will have the following key properties:
28 • Allows user updates to be combined with process updates in a single transaction
• Runs on any Java environment like Spring, JTA, standalone with any form of transaction demarcation
• Easy to get up and running with the setup utility
• Built to support the cloud scalability from the ground up
• Very simple to add new custom activity types and complete dedicated process languages
• Transactional timers
• Asynchronous continuations
• Hidden event listeners for decoupling software technical details from business level diagram
• Ability to test process executions in isolation in a plain unit test
5.2. Goal of this guide
The goal of this guide is to look into the details for using Activiti inside ServiceMix:
• create a project
• write and debug a simple process
5.3. Examples
The Apache ServiceMix distributions also contains an Activiti example. You can find this example in the examples/activiti directory.
5.4. More information about Activiti
More information about Activiti itself, can be found on http://activiti.org/.
There’s also book available about Activiti
• Tijs Rademakers. (July 2012). Activiti in Action. Greenwich, Manning. ISBN: 9781617290121.
5.5. Using Activiti with Camel
In this example we show an example how Activiti can be used with Camel in ServiceMix through
29 Blueprint Container.
Before being able to run Activiti with Camel, you have to install some additional features into the container first to add support for the Activiti.
karaf@root>feature:install activiti
By default in ServiceMix, the Activiti Engine uses an embedded (local) H2 database. It the can be found under
${karaf.data}/activiti/database.
The Activiti engine is the entry point for starting new process instances, deploying new processes, querying for user tasks, and more. Process data is stored in the H2 database.
5.5.1. Blueprint configuration
Let’s see how you can set up the Camel context in a Blueprint configuration. As you can see, the Camel integration is specified with the Activiti Engine in the same Blueprint configuration:
① This Camel context contains the routes that interact with our BPMN process.
② Here we instruct the Camel context to scan the classpath in org.apache.servicemix.examples.activiti.
③ Obtain a reference to Activiti’s RuntimeService - this reference will automatically be picked up
30 by the subsequent Activiti Camel component definition.
④ Register a context provider to link the Camel context to the OrderProcess definition. Doing this will allow your BPMN process to communicate with the Camel routes using the ${camel} expression.
5.5.2. Route Definition
public class ActivitiRouteBuilder extends RouteBuilder {
private final Helper helper = new Helper();
@Override public void configure() throws Exception { /* * This route will start a new OrderProcess instance. Using the * PROCESS_KEY_PROPERTY, we are assigning a business key to our process * to allow for easier correlation in later processing steps. We are * also sending a Map containing additional variables to add to the * process instance. */ from("file:var/activiti-camel/order") .setBody(bean(helper)) .setProperty(PROCESS_KEY_PROPERTY, simple("file:name")) .to("activiti:OrderProcess") .log("Process to handle incoming order file has been started (process instance id ${body})");
/* * This route will notify a running OrderProcess of an order delivery * event. Here too, we are setting the PROCESS_KEY_PROPERTY to * correlate the delivery message with right order process instance. */ from("file:var/activiti-camel/delivery") .log("Notifying process about delivery for order ${file:name}") .setBody(bean(helper)) .setProperty(PROCESS_KEY_PROPERTY, simple("file:name")) .to("activiti:OrderProcess:receiveDelivery");
/* * The BPMN process can also trigger Camel routes as part of the * process. In these routes, the variables that you added to the * process are available as Exchange properties. The next two routes * will be triggered while processing the order and the order delivery. */ from("activiti:OrderProcess:processOrder?copyVariablesToProperties=true") .log("Processing order ${property.orderid} created on ${property.timestamp}") .log(" original message: ${property.message}");
from("activiti:OrderProcess:processDelivery?copyVariablesToProperties=true")
31 .log("Processing delivery for order ${property.orderid} created on ${property.timestamp}") .log(" original message: ${property.message}"); }
/* * A few helper methods used for routing */ public static final class Helper {
/* * This method will extract information from the Exchange (using Camel * annotations) and put them in a Map that will be used for setting up * the process' variables. */ @Handler public Map getProcessVariables(@Body String body, @Header(Exchange.FILE_NAME) String filename, @Simple("${date:now:yyyy-MM-dd kk:mm:ss}") String timestamp) { Map
5.5.3. Process definition
32
The process presented here above define a simple order process. It processes the incoming orders and subsequently waits for its delivery. Once the delivery notification has been received, another bit of processing occurs before the business process ends.
This process defines the BPMN definition and is automatically deployed as soon as bundle is started:
start --> processOrder --> waitForDelivery --> processDelivery --> end
When the service task is executed by the Activiti Engine, the execution is delegated to the CamelBehaviour class, which will send a message containing all process variables to an Activiti endpoint defined in the Camel context. This behavior is obtained through the use the
33 delegateExpression in the Java service task
5.5.4. Building and running the example
1. Open a command prompt, and navigate to the directory containing the example, examples/activiti/activiti-camel.
2. Build the bundle using mvn clean install.
3. In the Karaf console, install the bundle using bundle:install mvn:org.apache.servicemix.examples/activiti-camel/7.0.1-SNAPSHOT. Note the bundle id that is returned.
4. In the Karaf console, start the bundle using bundle:start
5. Create a possibly empty file representing a new order in the newly created directory var/activiti-camel/order under your ServiceMix installation directory. The file name corresponds to the order id.
6. In the log, you will find a message similar to Process to handle incoming order file has been started (process instance id {orderid=1234, message=, timestamp=2017-05-09 20:35:33})
7. At that point, you have a running process instance for order 1234 that is waiting for delivery.
8. To notify the process about the delivery, you have to create a file with the same name in the var/activiti-camel/delivery directory.
9. As soon as the Camel route picks up the file, you will find messages similar to Notifying process about delivery for order 1234 and Processing delivery for order 1234 created on 2017-05-09 20:43:09 in the log.
6. Karaf User Guide
Apache ServiceMix uses Apache Karaf as the underlying OSGi server runtime. The Karaf User Guide explains about the features and functionality provided by Karaf.
7. Karaf Developer Guide
The Apache Karaf Developer Guide gives you some information about developing with and for the OSGi server runtime.
8. Resources
8.1. Books
34 Enterprise Integration Patterns : Designing, Building, and Deploying Messaging Solutions Gregor Hohpe and Bobby Woolf October 2003
Service Oriented Java Business Integration - Enterprise Service Bus Integration Solutions for Java Developers Binildas A. Christudas March 2008
SOA Design Patterns Thomas Erl January 2009
Understanding Enterprise SOA Eric Pulier and Hugh Taylor November 2005
Service-Oriented Architecture: A Field Guide to Integrating XML and Web Services Thomas Erl April 2006
35 Service-Oriented Architecture (SOA): Concepts, Technology, and Design Thomas Erl August 2005
Enterprise SOA: Service-Oriented Architecture Best Practices Dirk Krafzig, Karl Banke, and Dirk Slama November 2004
Understanding SOA with Web Services Eric Newcomer and Greg Lomow December 2004
Web Services, Service-Oriented Architectures, and Cloud Computing, Second Edition: The Savvy Manager’s Guide Douglas K. Barry January 2013
36 Web Services Platform Architecture : SOAP, WSDL, WS-Policy, WS-Addressing, WS-BPEL, WS-Reliable Messaging, and More Sanjiva Weerawarana, Francisco Curbera, Frank Leymann, Tony Storey, and Donald F. Ferguson April 2005
Loosely Coupled: The Missing Pieces of Web Services Doug Kaye August 2003
8.2. Websites
• Enterprise Integration Patterns
• The Prentice Hall Service Technology Series from Thomas Erl
37