Red Hat Fuse 7.1 Apache Camel Development Guide

595 Pages·2017·4.36 MB·English

Red Hat Fuse 7.1
Apache Camel Development Guide
Develop applications with Apache Camel
Last Updated: 2019-01-08

Red Hat Fuse 7.1 Apache Camel Development Guide
Develop applications with Apache Camel
Legal Notice
Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity
logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other
countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related to
or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other countries
and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
This guide describes how to develop JBoss Fuse applications with Apache Camel. It covers the
basic building blocks, enterprise integration patterns, basic syntax for routing expression and
predicate languages, creating web services with the Apache CXF component, using the Apache
Camel API, and how to create a Camel component that wraps any Java API.
Table of Contents
Table of Contents
.P .A . R. T. .I .. I.M . P. .L .E .M . E. .N .T . I.N .G . .E .N . T. E. .R .P . R. I.S . E. .I N. .T .E .G . R. .A .T . I.O .N . .P .A . T. T. E. .R .N . S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 .7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.C .H . A. P. .T .E .R . .1 .. .B . U. I.L .D . I.N . G. .B . L. O. .C . K. S. . F. O. .R . R. .O . U. T. .E . D. .E .F .I N. .I T. I.O . N. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 .8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1. IMPLEMENTING A ROUTEBUILDER CLASS 28
Overview 28
RouteBuilder classes 28
Implementing a RouteBuilder 28
1.2. BASIC JAVA DSL SYNTAX 29
What is a DSL? 29
Router rule syntax 29
Consumers and producers 30
Exchanges 30
Message exchange patterns 31
Grouped exchanges 32
Processors 32
Expressions and predicates 32
1.3. ROUTER SCHEMA IN A SPRING XML FILE 32
Namespace 32
Specifying the schema location 32
Runtime schema location 33
Using an XML editor 33
1.4. ENDPOINTS 33
Overview 34
Endpoint URIs 34
Working with Long Endpoint URIs 34
Specifying time periods in a URI 35
Specifying raw values in URI options 36
Case-insensitive enum options 36
Specifying URI Resources 36
Apache Camel components 36
Consumer endpoints 38
Producer endpoints 38
1.5. PROCESSORS 39
Overview 39
Some sample processors 45
Choice 45
Filter 47
Throttler 47
Custom processor 47
.C .H . A. P. .T .E .R . .2 .. .B . A. S. .I C. .P . R. I.N . C. I.P . L. E. S. . O. .F . R. .O .U . T. E. . B. U. .I L. D. .I N. G. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 .9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1. PIPELINE PROCESSING 49
Overview 49
Processor nodes 49
Pipeline for InOnly exchanges 50
Pipeline for InOut exchanges 51
Pipeline for InOptionalOut exchanges 51
2.2. MULTIPLE INPUTS 52
Overview 52
Multiple independent inputs 52
Segmented routes 52
Direct endpoints 53
1
Red Hat Fuse 7.1 Apache Camel Development Guide
SEDA endpoints 53
VM endpoints 54
Content enricher pattern 54
2.3. EXCEPTION HANDLING 55
2.3.1. onException Clause 55
Overview 55
Trapping exceptions using onException 56
Java DSL example 56
XML DSL example 56
Trapping multiple exceptions 57
Deadletter channel 58
Use original message 58
Redelivery policy 59
Conditional trapping 60
Handling exceptions 61
Suppressing exception rethrow 62
Continuing processing 62
Sending a response 62
Exception thrown while handling an exception 64
Scopes 64
Route scope 64
2.3.2. Error Handler 65
Overview 65
Java DSL example 65
XML DSL example 65
Types of error handler 66
2.3.3. doTry, doCatch, and doFinally 67
Overview 67
Similarities between doCatch and Java catch 67
Special features of doCatch 67
Example 67
Rethrowing exceptions in doCatch 68
Conditional exception catching using onWhen 69
Nested Conditions in doTry 70
2.3.4. Propagating SOAP Exceptions 70
Overview 70
How to propagate stack trace information 70
2.4. BEAN INTEGRATION 71
Overview 71
Bean registry 72
Registry plug-in strategy 72
Accessing a bean created in Java 73
Accessing overloaded bean methods 73
Specify parameters explicitly 74
Basic method signatures 74
Method signature for processing message bodies 75
Method signature for processing exchanges 75
Accessing a Spring bean from Spring XML 75
Accessing a Spring bean from Java 76
Bean shutdown order in Spring XML 77
Parameter binding annotations 77
Basic annotations 77
Expression language annotations 78
2
Table of Contents
Inherited annotations 80
Interface implementations 81
Invoking static methods 82
Invoking an OSGi service 82
2.5. CREATING EXCHANGE INSTANCES 83
Overview 83
ExchangeBuilder class 83
Example 83
ExchangeBuilder methods 83
2.6. TRANSFORMING MESSAGE CONTENT 84
2.6.1. Simple Message Transformations 84
Overview 84
API for simple transformations 84
ProcessorDefinition class 84
Builder class 85
ValueBuilder class 87
2.6.2. Marshalling and Unmarshalling 89
Java DSL commands 89
Data formats 89
Java serialization 89
JAXB 90
XMLBeans 90
XStream 91
2.6.3. Endpoint Bindings 91
What is a binding? 91
DataFormatBinding 91
Associating a binding with an endpoint 92
Binding URI 92
BindingComponent 92
BindingComponent constructors 93
Implementing a custom binding 94
Binding interface 94
When to use bindings 95
2.7. PROPERTY PLACEHOLDERS 95
Overview 95
Property files 96
Resolving properties 96
Specifying locations using system properties and environment variables 97
Configuring the properties component 97
Placeholder syntax 98
Substitution in endpoint URIs 98
Substitution in Spring XML files 99
Substitution of XML DSL attribute values 99
Substitution of Java DSL EIP options 100
Substitution in Simple language expressions 100
Using Property Placeholders in the XML DSL 101
Integration with OSGi blueprint property placeholders 102
Implicit blueprint integration 102
Explicit blueprint integration 103
Integration with Spring property placeholders 104
2.8. THREADING MODEL 105
Java thread pool API 105
Apache Camel thread pool API 106
3
Red Hat Fuse 7.1 Apache Camel Development Guide
Component threading model 106
Processor threading model 106
threads DSL options 107
Creating a default thread pool 108
Default thread pool profile settings 108
Changing the default thread pool profile 109
Customizing a processor’s thread pool 109
Creating a custom thread pool 110
Creating a custom thread pool profile 112
Sharing a thread pool between components 113
Customizing thread names 113
2.9. CONTROLLING START-UP AND SHUTDOWN OF ROUTES 114
Overview 114
Setting the route ID 114
Disabling automatic start-up of routes 115
Manually starting and stopping routes 115
Startup order of routes 116
Shutdown sequence 117
Shutdown order of routes 117
Shutting down running tasks in a route 117
Shutdown timeout 118
Integration with custom components 118
2.9.1. RouteIdFactory 118
2.10. SCHEDULED ROUTE POLICY 119
2.10.1. Overview of Scheduled Route Policies 119
Overview 119
Scheduling tasks 119
Quartz component 119
2.10.2. Simple Scheduled Route Policy 119
Overview 120
Dependency 120
Java DSL example 120
XML DSL example 120
Defining dates and times 121
Graceful shutdown 122
Logging Inflight Exchanges on Timeout 122
Scheduling tasks 122
Starting a route 122
Stopping a route 123
Suspending a route 123
Resuming a route 124
2.10.3. Cron Scheduled Route Policy 124
Overview 124
Dependency 125
Java DSL example 125
XML DSL example 125
Defining cron expressions 126
Scheduling tasks 126
Starting a route 127
Stopping a route 127
Suspending a route 127
Resuming a route 127
2.10.4. Route Policy Factory 128
4
Table of Contents
Using Route Policy Factory 128
2.11. RELOADING CAMEL ROUTES 128
2.11.1. Enabling Live Reload 129
2.12. RUNNING APACHE CAMEL STANDALONE 129
2.13. ONCOMPLETION 130
Overview 130
Route Only Scope for onCompletion 131
Global Scope for onCompletion 132
Using onWhen 132
Using onCompletion with or without a thread pool 132
Run onCompletion before Consumer Sends Response 133
2.14. METRICS 133
Overview 133
Metrics Route Policy 134
Metrics Route Policy Factory 134
Options 135
2.15. JMX NAMING 136
Overview 136
Default naming strategy 136
Customizing the JMX naming strategy 136
Specifying a name pattern in Java 137
Specifying a name pattern in XML 137
Name pattern tokens 137
Examples 137
Ambiguous names 138
2.16. PERFORMANCE AND OPTIMIZATION 138
Message copying 138
.C .H . A. P. .T .E .R . .3 .. .I N. .T .R .O . D. .U .C . I.N . G. .E . N. T. .E .R . P. R. .I S. E. . I.N .T .E . G. .R .A . T. I.O . N. .P . A. T. .T .E .R . N. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 .3 .9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1. OVERVIEW OF THE PATTERNS 139
Enterprise Integration Patterns book 139
Messaging systems 139
Messaging channels 140
Message construction 141
Message routing 141
Message transformation 143
Messaging endpoints 144
System management 145
.C .H . A. P. .T .E .R . .4 .. .D . E. F. I.N . I.N .G . .R . E. S. .T . S. E. .R .V . I.C .E . S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 .4 .6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1. OVERVIEW OF REST IN CAMEL 146
Overview 146
What is REST? 146
A sample REST invocation 146
REST wrapper layers 146
REST implementations 147
JAX-RS REST implementation 148
4.2. DEFINING SERVICES WITH REST DSL 149
REST DSL is a facade 149
Advantages of the REST DSL 149
Components that integrate with REST DSL 149
Configuring REST DSL to use a REST implementation 149
Syntax 150
5
Red Hat Fuse 7.1 Apache Camel Development Guide
REST DSL with Java 150
REST DSL with XML 151
Specifying a base path 151
Using Dynamic To 152
URI templates 152
Embedded route syntax 153
REST DSL and HTTP transport component 154
Specifying the content type of requests and responses 154
Additional HTTP methods 155
Defining custom HTTP error messages 155
Parameter Default Values 156
Wrapping a JsonParserException in a custom HTTP error message 156
REST DSL options 157
4.3. MARSHALLING TO AND FROM JAVA OBJECTS 159
Marshalling Java objects for transmission over HTTP 159
Integration of JSON and JAXB with the REST DSL 160
Supported data format components 160
How to enable object marshalling 160
Configuring the binding mode 161
Example 163
Configure the Servlet component as the REST implementation 163
Required dependencies 164
Java type for responses 165
Sample REST DSL route with JSON binding 166
REST operations 167
URLs to invoke the REST service 167
4.4. CONFIGURING THE REST DSL 168
Configuring with Java 168
Configuring with XML 168
Configuration options 168
Default CORS headers 171
Enabling or disabling Jackson JSON features 172
4.5. SWAGGER INTEGRATION 173
Overview 173
Configuring a CamelContext to enable Swagger 173
Swagger module configuration options 174
Using the CORS filter to enable CORS support 176
Obtaining JSON or YAML output 177
Examples 177
Enhancing documentation generated by Swagger 177
.C .H . A. P. .T .E .R . .5 .. .M . E. S. .S .A . G. .I N. G. . S. Y. .S .T .E . M. .S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 .7 .9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1. MESSAGE 179
Overview 179
Types of message 179
Message structure 179
Correlating messages 180
Exchange objects 180
Accessing messages 180
5.2. MESSAGE CHANNEL 180
Overview 180
Message-oriented components 181
ActiveMQ 181
6