{"id":1263,"date":"2012-05-15T01:00:00","date_gmt":"2012-05-15T01:00:00","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/2012\/10\/apache-camel-tutorial-introduction-to-eip-routes-components-testing-and-other-concepts.html"},"modified":"2012-10-22T05:12:22","modified_gmt":"2012-10-22T05:12:22","slug":"apache-camel-tutorial-introduction-to","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2012\/05\/apache-camel-tutorial-introduction-to.html","title":{"rendered":"Apache Camel Tutorial – Introduction to EIP, Routes, Components, Testing and other Concepts"},"content":{"rendered":"
Data exchanges between companies increase a lot. The number of applications, which must be integrated increases, too. The interfaces use different technologies, protocols and data formats. Nevertheless, the integration of these applications shall be modeled in a standardized way, realized efficiently and supported by automatic tests. Such a standard exists with the Enterprise Integration Patterns (EIP) [1], which have become the industry standard for describing, documenting and implementing integration problems. Apache Camel [2] implements the EIPs and offers a standardized, internal domain-specific language (DSL) [3] to integrate applications. This article gives an introduction to Apache Camel including several code examples. <\/p>\n

Enterprise Integration Patterns<\/strong> <\/p>\n

EIPs can be used to split integration problems into smaller pieces and model them using standardized graphics. Everybody can understand these models easily. Besides, there is no need to reinvent the wheel every time for each integration problem. <\/p>\n

Using EIPs, Apache Camel closes a gap between modeling and implementation. There is almost a one-to-one relation between EIP models and the DSL of Apache Camel. This article explains the relation of EIPs and Apache Camel using an online shop example. <\/p>\n

Use Case: Handling Orders in an Online Shop<\/strong> <\/p>\n

The main concepts of Apache Camel are introduced by implementing a small use case. Starting your own project should be really easy after reading this article. The easiest way to get started is using a Maven archetype [4]. This way, you can rebuild the following example within minutes. Of course, you can also download the whole example at once[5]. <\/p>\n

Figure 1 shows the example from EIP perspective. The task is to process orders of an online shop. Orders arrive in csv format. At first, the orders have to be transformed to the internal format. Order items of each order must be split because the shop only sells dvds and cds. Other order items are forwarded to a partner.
\n  <\/p>\n

<\/a><\/div>\n

Figure <\/strong>1<\/strong>: EIP Perspective of the Integration Problem<\/strong> <\/p>\n

This example shows the advantages of EIPs: The integration problem is split into several small, perseverative subproblems. These subproblems are easy to understand and solved the same way each time. After describing the use case, we will now look at the basic concepts of Apache Camel. <\/p>\n

Basic Concepts<\/strong> <\/p>\n

Apache Camel runs on the Java Virtual Machine (JVM). Most components are realized in Java. Though, this is no requirement for new components. For instance, the camel-scala component is written in Scala. The Spring framework is used in some parts, e.g. for transaction support. However, Spring dependencies were reduced to a minimum in release 2.9 [6]. The core of Apache Camel is very small and just contains commonly used components (i.e. connectors to several technologies and APIs) such as Log, File, Mock or Timer. <\/p>\n

Further components can be added easily due to the modular structure of Apache Camel., Maven is recommended for dependency management, because most technologies require additional libraries. Though, libraries can also be downloaded manually and added to the classpath, of course. <\/p>\n

The core functionality of Apache Camel is its routing engine. It allocates messages based on the related routes. A route contains flow and integration logic. It is implemented using EIPs and a specific DSL. Each message contains a body, several headers and optional attachments. The messages are sent from a provider to a consumer. In between, the messages may be processed, e.g. filtered or transformed. Figure 1 shows how the messages can change within a route. <\/p>\n

Messages between a provider and a consumer are managed by a message exchange container, which contains an unique message id, exception information, incoming and outgoing messages (i.e. request and response), and the used message exchange pattern (MEP). \u201eIn Only\u201c MEP is used for one-way messages such as JMS whereas \u201eIn Out\u201c MEP executes request-response communication such as a client side HTTP based request and its response from the server side. <\/p>\n

After shortly explaining the basic concepts of Apache Camel, the following sections will give more details and code examples. Let\u2019s begin with the architecture of Apache Camel. <\/p>\n

Architecture<\/strong> <\/p>\n

Figure 2 shows the architecture of Apache Camel. A CamelContext provides the runtime system. Inside, processors handle things in between endpoints like routing or transformation. Endpoints connect several technologies to be integrated. Apache Camel offers different DSLs to realize the integration problems. <\/p>\n

<\/a><\/div>\n

Figure <\/strong>2<\/strong>: Architecture of Apache Camel<\/strong> <\/p>\n

CamelContext<\/strong> <\/p>\n

The CamelContext is the runtime system of Apache Camel and connects its different concepts such as routes, components or endpoints. The following code snipped shows a Java main method, which starts the CamelContext and stops it after 30 seconds. Usually, the CamelContext is started when loading the application and stopped at shutdown. <\/p>\n

public class CamelStarter {\r\n\r\npublic static void main(String[] args) throws Exception {\r\n \r\n   CamelContext context = new DefaultCamelContext();\r\n\r\n   context.addRoutes(new IntegrationRoute());\r\n \r\n   context.start();\r\n\r\n   Thread.sleep(30000);\r\n\r\n   context.stop();\r\n\r\n   }\r\n\r\n}\r\n \r\n<\/pre>\n
The runtime system can be included anywhere in the JVM environment, including web container (e.g. Tomcat), JEE application server (e.g. IBM WebSphere AS), OSGi container, or even in the cloud.   <\/p>\n
Domain Specific Languages<\/strong>  <\/p>\n
DSLs facilitate the realization of complex projects by using a higher abstraction level. Apache Camel offers several different DSLs. Java, Groovy and Scala use object-oriented concepts and offer a specific method for most EIPs. On the other side, Spring XML DSL is based on the Spring framework and uses XML configuration. Besides, OSGi blueprint XML is available for OSGi integration.   <\/p>\n
Java DSL has best IDE support. Groovy and Scala DSL are similar to Java DSL, in addition they offer typical features of modern JVM languages such as concise code or closures. Contrary to these programming languages, Spring XML DSL requires a lot of XML. Besides, it offers very powerful Spring-based dependency injection mechanism and nice abstractions to simplify configurations (such as JDBC or JMS connections). The choice is purely a matter of taste in most use cases. Even a combination is possible. Many developer use Spring XML for configuration whilst routes are realized in Java, Groovy or Scala.   Routes<\/strong>  <\/p>\n
Routes are a crucial part of Apache Camel. The flow and logic of an integration is specified here. The following example shows a route using Java DSL:   
 
<\/div> <\/div><\/p>\n
public class IntegrationRoute extends RouteBuilder {\r\n\r\n@Override\r\n \r\n\r\npublic void configure() throws Exception {\r\n \r\n\r\nfrom(\u201cfile:target\/inbox\u201d)\r\n \r\n\r\n                      .process(new LoggingProcessor())\r\n \r\n\r\n\r\n                      .bean(new TransformationBean(), \r\n\r\n\r\n                                  \u201cmakeUpperCase\u201d)                                             \r\n \r\n\r\n\r\n.to(\u201cfile:target\/outbox\/dvd\u201d);\r\n \r\n}\r\n\r\n}\r\n \r\n<\/pre>\n
The DSL is easy to use. Everybody should be able to understand the above example without even knowing Apache Camel. The route realizes a part of the described use case. Orders are put in a file directory from an external source. The orders are processed and finally moved to the target directory.   <\/p>\n
Routes have to extend the \u201eRouteBuilder\u201c class and override the \u201econfigure\u201c method. The route itself begins with a \u201efrom\u201c endpoint and finishes at one or more \u201eto\u201c endpoints. In between, all necessary process logic is implemented. Any number of routes can be implemented within one \u201econfigure\u201c method.   <\/p>\n
The following snippet shows the same route realized via Spring XML DSL:  <\/p>\n
<beans \u2026 >\r\n \r\n<bean class=\u201dmwea.TransformationBean\u201d id=\u201dtransformationBean\u201d\/>\r\n \r\n<bean class=\u201dmwea.LoggingProcessor\u201d id=\u201dloggingProcessor\u201d\/>\r\n \r\n\r\n<camelContext xmlns=\u201dhttp:\/\/camel.apache.org\/schema\/spring\u201d>\r\n \r\n<package>mwea<\/package>\r\n \r\n<route>\r\n \r\n        <from uri=\u201dfile:target\/inbox\u201d\/>\r\n \r\n\r\n\r\n                    <process ref=\u201dloggingProcessor\u201d\/> \r\n\r\n\r\n                    <bean ref=\u201dtransformationBean\u201d\/>\r\n \r\n\r\n\r\n        <to uri=\u201dfile:target\/outbox\u201d\/>\r\n \r\n   <\/route>\r\n \r\n<\/camelContext>\r\n \r\n<\/beans>\r\n <\/pre>\n
Besides routes, another important concept of Apache Camel is its components. They offer integration points for almost every technology.   <\/p>\n
Components<\/strong>  <\/p>\n
In the meantime, over 100 components are available. Besides widespread technologies such as HTTP, FTP, JMS or JDBC, many more technologies are supported, including cloud services from Amazon, Google, GoGrid, and others. New components are added in each release. Often, also the community builds new custom components because it is very easy.   <\/p>\n
The most amazing feature of Apache Camel is its uniformity. All components use the same syntax and concepts. Every integration and even its automatic unit tests look the same. Thus, complexity is reduced a lot. Consider changing the above example: If orders should be sent to a JMS queue instead of a file directory, just change the \u201eto\u201c endpoint from \u201efile:target\/outbox\u201c to \u201ejms:queue:orders\u201c. That\u2019s it! (JMS must be configured once within the application before, of course)   <\/p>\n
While components offer the interface to technologies, Processors and Beans can be used to add custom integration logic to a route.   <\/p>\n
Processors and Beans<\/strong>  <\/p>\n
Besides using EIPs, you have to add individual integration logic, often. This is very easy and again uses the same concepts always: Processors or Beans. Both were used in the route example above.   <\/p>\n
Processor is a simple Java interface with one single method: \u201eprocess\u201c. Inside this method, you can do whatever you need to solve your integration problem, e.g. transform the incoming message, call other services, and so on.  <\/p>\n
public class LoggingProcessor implements Processor {\r\n \r\n@Override\r\n \r\npublic void process(Exchange exchange) throws Exception {\r\n \r\nSystem.out<\/em>.println(\u201cReceived Order: \u201d +\r\n \r\nexchange.getIn().getBody(String.class));\r\n \r\n}\r\n \r\n}\r\n <\/pre>\n
The \u201eexchange\u201c parameter contains the Messsage Exchange with the incoming message, the outgoing message, and other information. Due to implementing the Processor interface, you have got a dependency to the Camel API. This might be a problem sometimes. Maybe you already have got existing integration code which cannot be changed (i.e. you cannot implement the Processor interface)? In this case, you can use Beans, also called POJOs (Plain Old Java Object). You get the incoming message (which is the parameter of the method) and return an outgoing message, as shown in the following snipped:   <\/p>\n
public class TransformationBean {\r\n \r\n\r\npublic String makeUpperCase(String body) {\r\n \r\n\r\nString transformedBody = body.toUpperCase();\r\n\r\nreturn transformedBody;\r\n}\r\n \r\n}\r\n \r\n<\/pre>\n
The above bean receives a String, transforms it, and finally sends it to the next endpoint. Look at the route above again. The incoming message is a File. You may wonder why this works? Apache Camel offers another powerful feature: More than 150 automatic type converters are included from scratch, e.g. FileToString, CollectionToObject[] or URLtoInputStream. By the way: Further type converters can be created and added to the CamelContext easily [7].   <\/p>\n
If a Bean only contains one single method, it even can be omitted in the route. The above call therefore could also be .bean(new TransformationBean()) instead of .bean(new TransformationBean(), \u201cmakeUpperCase\u201d).   <\/p>\n
Adding some more Enterprise Integration Patterns<\/strong>  <\/p>\n
The above route transforms incoming orders using the Translator EIP before processing them. Besides this transformation, some more work is required to realize the whole use case. Therefore, some more EIPs are used in the following example:  <\/p>\n
public class IntegrationRoute extends RouteBuilder {\r\n \r\n@Override\r\n \r\npublic void configure() throws Exception {\r\n \r\nfrom(\u201cfile:target\/inbox\u201d)\r\n\r\n.process(new LoggingProcessor())\r\n \r\n.bean(new TransformationBean())\r\n\r\n.unmarshal().csv()\r\n \r\n.split(body().tokenize(\u201c,\u201d))\r\n \r\n.choice()\r\n \r\n.when(body().contains(\u201cDVD\u201d))\r\n \r\n.to(\u201cfile:target\/outbox\/dvd\u201d)\r\n \r\n.when(body().contains(\u201cCD\u201d))\r\n \r\n.to(\u201cactivemq:CD_Orders\u201d)\r\n \r\n.otherwise()\r\n\r\n.to(\u201cmock:others\u201d);\r\n \r\n\r\n}\r\n\r\n}\r\n<\/pre>\n
Each csv file illustrates one single order containing one or more order items. The camel-csv component is used to convert the csv message. Afterwards, the Splitter EIP separates each order item of the message body. In this case, the default separator (a comma) is used. Though, complex regular expressions or scripting languages such as XPath, XQuery or SQL can also be used as splitter.   <\/p>\n
Each order item has to be sent to a specific processing unit (remember: there are dvd orders, cd orders, and other orders which are sent to a partner). The content-based router EIP solves this problem without any individual coding efforts. Dvd orders are processed via a file directory whilst cd orders are sent to a JMS queue.   <\/p>\n
ActiveMQ is used as JMS implementation in this example. To add ActiveMQ support to a Camel application, you only have to add the related maven dependency for the camel-activemq component or add the JARs to the classpath manually. That\u2019s it. Some other components need a little bit more configuration, once. For instance, if you want to use WebSphere MQ or another JMS implementation instead of ActiveMQ, you have to configure the JMS provider.   <\/p>\n
All other order items besides dvds and cds are sent to a partner. Unfortunately, this interface is not available, yet. The Mock component is used instead to simulate this interface momentarily.   <\/p>\n
The above example shows impressively how different interfaces (in this case File, JMS, and Mock) can be used within one route. You always apply the same syntax and concepts despite very different technologies.   <\/p>\n
Automatic Unit and Integration Tests<\/strong>  <\/p>\n
Automatic tests are crucial. Nevertheless, it usually is neglected in integration projects. The reason is too much efforts and very high complexity due to several different technologies.   <\/p>\n
Apache Camel solves this problem: It offers test support via JUnit extensions. The test class must extend CamelTestSupport to use Camel\u2019s powerful testing capabilities. Besides additional assertions, mocks are supported implicitly. No other mock framework such as EasyMock or Mockito is required. You can even simulate sending messages to a route or receiving messages from it via a producer respectively consumer template. All routes can be tested automatically using this test kit. It is noteworthy to mention that the syntax and concepts are the same for every technology, again.   <\/p>\n
The following code snipped shows a unit test for our example route:   <\/p>\n
public class IntegrationTest extends CamelTestSupport {\r\n \r\n\r\n@Before\r\n \r\n\r\npublic void setup() throws Exception {\r\n \r\n\r\nsuper.setUp();\r\n \r\ncontext.addRoutes(new IntegrationRoute());\r\n \r\n\r\n}\r\n \r\n\r\n@Test\r\n \r\n\r\npublic void testIntegrationRoute() throws Exception {\r\n \r\n\/\/ Body of test message containing several order items\r\n \r\n\r\nString bodyOfMessage = \u201cHarry Potter \/ dvd, Metallica \/ cd, Claus Ibsen \u2013\r\n \r\n\r\nCamel in Action \/ book \u201c;\r\n\r\n\/\/ Initialize the mock and set expected results\r\n \r\nMockEndpoint mock = context.getEndpoint(\u201cmock:others\u201d,\r\n \r\nMockEndpoint.class);\r\n \r\nmock.expectedMessageCount(1);\r\n\r\nmock.setResultWaitTime(1000);\r\n\r\n\/\/ Only the book order item is sent to the mock\r\n\r\n\/\/ (because it is not a cd or dvd)\r\n \r\n\r\nString bookBody = \u201cClaus Ibsen \u2013 Camel in Action \/ book\u201d.toUpperCase();\r\n\r\nmock.expectedBodiesReceived(bookBody);\r\n \r\n\r\n\/\/ ProducerTemplate sends a message (i.e. a File) to the inbox directory\r\n \r\n\r\ntemplate.sendBodyAndHeader(\u201cfile:\/\/target\/inbox\u201d, bodyOfMessage, Exchange.FILE_NAME<\/em>, \u201corder.csv\u201d);\r\n \r\n\r\nThread.sleep(3000);\r\n \r\n\/\/ Was the file moved to the outbox directory?\r\n\r\nFile target = new File(\u201ctarget\/outbox\/dvd\/order.csv\u201d);\r\n\r\nassertTrue(\u201cFile not moved!\u201d, target.exists());\r\n\r\n\/\/ Was the file transformed correctly (i.e. to uppercase)?\r\n \r\n\r\nString content = context.getTypeConverter().convertTo(String.class, target);\r\n\r\nString dvdbody = \u201cHarry Potter \/ dvd\u201d.toUpperCase();\r\n \r\nassertEquals(dvdbody, content);\r\n \r\n\/\/ Was the book order (i.e. \u201eCamel in action\u201c which is not a cd or dvd) sent to the mock?\r\n\r\nmock.assertIsSatisfied();\r\n \r\n}\r\n \r\n\r\n}\r\n<\/pre>\n
The setup method creates an instance of CamelContext (and does some additional stuff). Afterwards, the route is added such that it can be tested. The test itself creates a mock and sets its expectations. Then, the producer template sends a message to the \u201efrom\u201c endpoint of the route. Finally, some assertions validate the results. The test can be run the same way as each other JUnit test: directly within the IDE or inside a build script. Even agile Test-driven Development (TDD) is possible. At first, the Camel test has to be written, before implementing the corresponding route.   <\/p>\n
If you want to learn more about Apache Camel, the first address should be the book \u201eCamel in Action\u201c [8], which describes all basics and many advanced features in detail including working code examples for each chapter. After whetting your appetite, let\u2019s now discuss when to use Apache Camel\u2026   <\/p>\n
Alternatives for Systems Integration<\/strong>  <\/p>\n
Figure 3 shows three alternatives for integrating applications:   <\/p>\n