Red Hat JBoss Fuse 7.0-TP Apache Camel Development Guide

585 Pages·2017·4.41 MB·English

Red Hat JBoss Fuse 7.0-TP
Apache Camel Development Guide
Develop applications with Apache Camel
Last Updated: 2018-03-29

Red Hat JBoss Fuse 7.0-TP Apache Camel Development Guide
Develop applications with Apache Camel
Legal Notice
Copyright © 2018 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. .6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.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. .7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1. IMPLEMENTING A ROUTEBUILDER CLASS 27
Overview 27
RouteBuilder classes 27
Implementing a RouteBuilder 27
1.2. BASIC JAVA DSL SYNTAX 28
What is a DSL? 28
Router rule syntax 28
Consumers and producers 29
Exchanges 29
Message exchange patterns 30
Grouped exchanges 31
Processors 31
Expressions and predicates 31
1.3. ROUTER SCHEMA IN A SPRING XML FILE 31
Namespace 31
Specifying the schema location 31
Runtime schema location 32
Using an XML editor 32
1.4. ENDPOINTS 33
Overview 33
Endpoint URIs 33
Working with Long Endpoint URIs 33
Specifying time periods in a URI 34
Specifying raw values in URI options 35
Case-insensitive enum options 35
Specifying URI Resources 35
Apache Camel components 36
Consumer endpoints 37
Producer endpoints 37
1.5. PROCESSORS 38
Overview 38
Some sample processors 45
Choice 45
Filter 46
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 JBoss Fuse 7.0-TP 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 56
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 63
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 71
How to propagate stack trace information 71
2.4. BEAN INTEGRATION 72
Overview 72
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 75
Method signature for processing message bodies 75
Method signature for processing exchanges 75
Accessing a Spring bean from Spring XML 76
Accessing a Spring bean from Java 76
Bean shutdown order in Spring XML 77
Parameter binding annotations 77
Basic annotations 78
Expression language annotations 78
2
Table of Contents
Inherited annotations 81
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 85
Builder class 86
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 94
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 106
Java thread pool API 106
Apache Camel thread pool API 106
3
Red Hat JBoss Fuse 7.0-TP 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 110
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 119
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 119
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.12. ONCOMPLETION 129
Overview 129
Route Only Scope for onCompletion 129
Global Scope for onCompletion 130
Using onWhen 130
Using onCompletion with or without a thread pool 131
Run onCompletion before Consumer Sends Response 131
2.13. METRICS 132
Overview 132
Metrics Route Policy 132
Metrics Route Policy Factory 133
Options 133
2.14. JMX NAMING 134
Overview 134
Default naming strategy 134
Customizing the JMX naming strategy 135
Specifying a name pattern in Java 135
Specifying a name pattern in XML 135
Name pattern tokens 135
Examples 135
Ambiguous names 136
2.15. PERFORMANCE AND OPTIMIZATION 136
Message copying 136
.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. .7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1. OVERVIEW OF THE PATTERNS 137
Enterprise Integration Patterns book 137
Messaging systems 137
Messaging channels 138
Message construction 139
Message routing 139
Message transformation 141
Messaging endpoints 142
System management 143
.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. .4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1. OVERVIEW OF REST IN CAMEL 144
Overview 144
What is REST? 144
A sample REST invocation 144
REST wrapper layers 144
REST implementations 145
JAX-RS REST implementation 146
4.2. DEFINING SERVICES WITH REST DSL 147
REST DSL is a facade 147
Advantages of the REST DSL 147
Components that integrate with REST DSL 147
Configuring REST DSL to use a REST implementation 147
Syntax 148
REST DSL with Java 148
REST DSL with XML 149
5
Red Hat JBoss Fuse 7.0-TP Apache Camel Development Guide
Specifying a base path 149
Using Dynamic To 150
URI templates 150
Embedded route syntax 151
REST DSL and HTTP transport component 152
Specifying the content type of requests and responses 152
Additional HTTP methods 153
Defining custom HTTP error messages 153
Parameter Default Values 154
Wrapping a JsonParserException in a custom HTTP error message 154
REST DSL options 155
4.3. MARSHALLING TO AND FROM JAVA OBJECTS 157
Marshalling Java objects for transmission over HTTP 157
Integration of JSON and JAXB with the REST DSL 158
Supported data format components 158
How to enable object marshalling 158
Configuring the binding mode 159
Example 161
Configure the Servlet component as the REST implementation 161
Required dependencies 162
Java type for responses 163
Sample REST DSL route with JSON binding 164
REST operations 165
URLs to invoke the REST service 165
4.4. CONFIGURING THE REST DSL 166
Configuring with Java 166
Configuring with XML 166
Configuration options 166
Default CORS headers 169
Enabling or disabling Jackson JSON features 170
4.5. SWAGGER INTEGRATION 171
Overview 171
Configuring a CamelContext to enable Swagger 171
Swagger module configuration options 172
Using the CORS filter to enable CORS support 174
Obtaining JSON or YAML output 175
Examples 175
Enhancing documentation generated by Swagger 175
.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 .7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1. MESSAGE 177
Overview 177
Types of message 177
Message structure 177
Correlating messages 178
Exchange objects 178
Accessing messages 178
5.2. MESSAGE CHANNEL 178
Overview 178
Message-oriented components 179
ActiveMQ 179
JMS 179
AMQP 180
6