This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new dc78f0c CAMEL-13916: website - Add migration guide page
new ce179a5 Merge pull request #3159 from alexkieling/master
dc78f0c is described below
commit dc78f0ca21ba1f3d2d6e92d240d2d3d2864c3b0d
Author: Alexandre Kieling <alex.kiel...@gmail.com>
AuthorDate: Tue Sep 10 18:24:07 2019 -0300
CAMEL-13916: website - Add migration guide page
Convert migration guide do AsciiDoc and move it to
docs/user-manual/modules/ROOT/pages/camel-3-migration-guide.adoc
---
.../ROOT/pages/camel-3-migration-guide.adoc | 202 +++++++++------------
1 file changed, 89 insertions(+), 113 deletions(-)
diff --git a/MIGRATION.md
b/docs/user-manual/modules/ROOT/pages/camel-3-migration-guide.adoc
similarity index 89%
rename from MIGRATION.md
rename to docs/user-manual/modules/ROOT/pages/camel-3-migration-guide.adoc
index bcac998..1b65e58 100644
--- a/MIGRATION.md
+++ b/docs/user-manual/modules/ROOT/pages/camel-3-migration-guide.adoc
@@ -1,16 +1,13 @@
-Apache Camel 3 Migration Guide
-==============================
+= Apache Camel 3 Migration Guide
This document is intended for helping you migrate your Apache Camel
applications
from version 2.x to 3.0.
-Java versions
--------------
+== Java versions
Camel 3 supports Java 11. Support for Java 8 is best effort for the earlier
versions of Camel 3. However at some time in the 3.x lifeline we will drop
support for Java 8.
-Modularization of camel-core
-----------------------------
+== Modularization of camel-core
One of the biggest changes is the modularization of camel-core.
In Camel 2.x camel-core was one JAR file, it has now been split up into many
JARs as follows:
@@ -28,7 +25,7 @@ In Camel 2.x camel-core was one JAR file, it has now been
split up into many JAR
- camel-util
- camel-util-json
-Maven users of Apache Camel can keep using the dependency *camel-core* which
will have transitive dependency on all of its modules, and therefore no
migration is needed.
+Maven users of Apache Camel can keep using the dependency `camel-core` which
will have transitive dependency on all of its modules, and therefore no
migration is needed.
However, users who want to trim the size of the classes on the classpath, can
use fine grained Maven dependency on only the modules needed.
You may find how to do that in the examples.
@@ -60,42 +57,35 @@ We have also modularized many of the core components and
moved them out of `came
- camel-xslt
- camel-zip-deflater
-
-Multiple CamelContexts per application not supported
-----------------------------------------------------
+== Multiple CamelContexts per application not supported
Support for multiple CamelContext's has been removed/deprecated and only 1
CamelContext per deployment is supported.
-The latter was not recommended anyway and was also not 100% implemented (for
example in camel-cdi).
+The latter was not recommended anyway and was also not 100% implemented (for
example in camel-cdi).
For Camel 3 only 1 CamelContext per deployment is recommended and supported.
The `context` attribute on the various Camel annotations such as
`@EndpointInject`, `@Produce`, `@Consume` etc has therefore been removed.
-
-Migrating custom components
----------------------------
+== Migrating custom components
You should depend on `camel-support` and not `camel-core` directly.
The classes from `org.apache.camel.impl` that was intended to support Camel
developers building custom components has been moved out of `camel-core` into
`camel-support` into the `org.apache.camel.support` package. For example
classes such as `DefaultComponent`, `DefaultEndpoint` etc has been moved and
migration is necessary.
-Migrating custom languages
---------------------------
+== Migrating custom languages
The `LanguageAnnotation` annotation class has been moved from package
`org.apache.camel.language` to `org.apache.camel.support.language`.
-Deprecated APIs and Components
-------------------------------
+== Deprecated APIs and Components
All deprecated APIs and components from Camel 2.x has been removed in Camel 3.
-Migrating Camel applications
-----------------------------
+== Migrating Camel applications
-### Main class
+=== Main class
The Camel `Main` class has been moved out of `camel-core` into `camel-main` so
you should add that as dependency if you use Main.
-### Properties component
+=== Properties component
The `properties` component has configuring custom prefix and suffix tokens
removed as if in use, they had potential issues with clashing with simple
languages and elsewhere. The default tokens are now hardcoded and always in use.
@@ -103,7 +93,7 @@ The `properties` component has some advanced options
removed: `propertyPrefix`,
The properties component will now use OS environment variables as preferred
value. This means you can set an OS environment variable which will override
any property values that has been set in property files, JVM system properties
etc. You can configure this with the `environmentVariableMode` option on the
properties component.
-### Removed components
+=== Removed components
We have removed all deprecated components from Camel 2.x, including the old
`camel-http`, `camel-hdfs`, `camel-mina`, `camel-mongodb`, `camel-netty`,
`camel-netty-http`, `camel-quartz` and `camel-rxjava` components.
@@ -117,7 +107,7 @@ The `camel-jetty` component no longer supports producer (eg
to) which has been r
The `twitter-streaming` component has been removed as it relied on the
deprecated Twitter Streaming API and is no longer functional.
-### Renamed components
+=== Renamed components
The `test` component has been renamed to `dataset-test` and moved out of
`camel-core` into `camel-dataset` JAR.
@@ -139,89 +129,90 @@ The `rxjava2` component has been renamed to `rxjava`, and
it's corresponding com
We have also renamed `camel-jetty9` to `camel-jetty`. The supported scheme is
now `jetty`.
-### Using endpoint options with consumer. prefix
+=== Using endpoint options with consumer. prefix
Endpoints with `consumer.` prefix such as `consumer.delay=5000` are no longer
supported (deprecated in latest Camel 2.x) and you should just use the option
without the `consumer.` prefix, eg `delay=5000`.
-### Tracing
+=== Tracing
A new tracer has been implemented and the old tracer has been removed.
The new tracer logs messages at the `org.apache.camel.Tracing` logger name
which is hardcoded. The format of the output is also updated to make it better.
The tracer can be customized.
In JMX the `BacklogTracer` is no longer enabled by default, which you need to
enable by setting `backlogTracing=true` on CamelContext. The backlog tracer and
tracer are not the same. The former is used for capturing a backlog of traced
messages which you can poll via JMX (needed for 3rd party tooling), where as
tracer is writing to the log. Neither of them are enabled by default, and they
must be enabled to be in use.
-### <setHeader> and <setProperty> in XML DSL
+=== <setHeader> and <setProperty> in XML DSL
We have renamed the attribute `headerName` and `propertyName` in the XML DSL
for the `<setHeader>` and `<setProperty`> EIPs, to be just `name`.
So migrate
- <setHeader headerName="foo"><simple>Hello ${body}</simple></setHeader>
+ <setHeader headerName="foo"><simple>Hello ${body}</simple></setHeader>
To
- <setHeader name="foo"><simple>Hello ${body}</simple></setHeader>
+ <setHeader name="foo"><simple>Hello ${body}</simple></setHeader>
And the same for `<setProperty>`.
-### <aggregate> EIP in XML DSL
+=== <aggregate> EIP in XML DSL
The aggregte EIP have renamed the expressions (not the attributes) for setting
correlation size/timeout to avoid a name clash, so migrate:
- <completionSize>
- <header>mySize</header>
- </completionSize>
+ <completionSize>
+ <header>mySize</header>
+ </completionSize>
+
To
- <completionSizeExpression>
- <header>mySize</header>
- </completionSizeExpression>
+ <completionSizeExpression>
+ <header>mySize</header>
+ </completionSizeExpression>
And the same for `<completionTimeout>`.
-#### camel-cdi
+==== camel-cdi
Support for multiple CamelContext's has been removed, and therefore
`@ContextName` has been removed. Instead use standard CDI annotations such as
`@Named` and `@ApplicationScoped`.
-### javax.script
+=== javax.script
The `camel-script` component has been removed and there is no support for
javax.script, which is also deprecated in the JDK and to be removed from Java
11 onwards.
-### Attachments API on Message
+=== Attachments API on Message
The attachments API (javax.activation) has been moved out of
`org.apache.camel.message` into an extension
`org.apache.camel.attachment.AttachmentMessage` from the `camel-attachments`
JAR.
To use this API you can get it via the `getMessage` method on `Exchange`:
- AttachmentMessage am = exchange.getMessage(AttachmentMessage.class);
- am.addAttachment("myAtt", new DataHandler(...));
+ AttachmentMessage am = exchange.getMessage(AttachmentMessage.class);
+ am.addAttachment("myAtt", new DataHandler(...));
-### Fault API on Message
+=== Fault API on Message
The fault API has been removed from `org.apache.camel.Message` as it was only
used for SOAP-WS fault message. The `camel-cxf` and `camel-spring-ws`
components for SOAP-WS has been modified to support fault messages from their
components. The option `handleFault` has also been removed and you now need to
turn this on as endpoint or component option on `camel-cxf` or
`camel-spring-ws`.
-### getOut on Message
+=== getOut on Message
The `hasOut` and `getOut` methods on `Message` has been deprecated in favour
of using `getMessage` instead. (sidenote: The camel-core are still using these
methods in a few places to be backwards compatible and rely on this logic as
Camel was initially designed with the concepts of IN and OUT message inspired
from the JBI and SOAP-WS specifications).
-### OUT message removed from Simple language and Mock component
+=== OUT message removed from Simple language and Mock component
The simple language has removed the OUT message concepts eg `${out.body}`.
Also the mock component has removed OUT message from its assertion API, eg
- mock.message(0).outBody()...
+ mock.message(0).outBody()...
Also the `@OutHeaders` annotation for bean parameter binding has been removed,
instead use `@Headers` instead.
-### Mock component
+=== Mock component
The `mock` component has been moved out of `camel-core` and as part of this
work, we had to remove a number of methods on its _assertion clause builder_
that were seldom in use.
-### ActiveMQ
+=== ActiveMQ
If you are using the `activemq-camel` component, then you should migrate to
use `camel-activemq` component, where the component name has changed from
`org.apache.activemq.camel.component.ActiveMQComponent` to
`org.apache.camel.component.activemq.ActiveMQComponent`.
-### AWS
+=== AWS
The component `camel-aws` has been split into multiple components:
@@ -244,18 +235,17 @@ The component `camel-aws` has been split into multiple
components:
So you'll have to add explicitly the dependencies for these components. From
the OSGi perspective, there is still a `camel-aws` Karaf feature, which
includes all the components features.
-### Telegram
+=== Telegram
The `camel-telegram` component has moved the authorization token from uri-path
to a query parameter instead, eg migrate
- telegram:bots/myTokenHere
+ telegram:bots/myTokenHere
to
telegram:bots?authorizationToken=myTokenHere
-
-### JMX
+=== JMX
If you run Camel standalone with just `camel-core` as a dependency, and you
want JMX enabled out of the box, then you need to add `camel-management-impl`
as a dependency.
@@ -263,73 +253,72 @@ For using `ManagedCamelContext` you now need to get this
an extension from `Came
ManagedCamelContext managed =
camelContext.getExtension(ManagedCamelContext.class);
-### Configuring global options on CamelContext
+=== Configuring global options on CamelContext
In Camel 2.x we have deprecated `getProperties` on `CamelContext` in favour of
`getGlobalOptions`, so you should migrate to:
- context.getGlobalOptions().put("CamelJacksonEnableTypeConverter", "true");
- context.getGlobalOptions().put("CamelJacksonTypeConverterToPojo", "true");
-
-... and in XML:
+ context.getGlobalOptions().put("CamelJacksonEnableTypeConverter", "true");
+ context.getGlobalOptions().put("CamelJacksonTypeConverterToPojo", "true");
- <globalOptions>
- <globalOption key="CamelJacksonEnableTypeConverter" value="true"/>
- <globalOption key="CamelJacksonTypeConverterToPojo" value="true"/>
- </globalOptions>
+and in XML:
+ <globalOptions>
+ <globalOption key="CamelJacksonEnableTypeConverter" value="true"/>
+ <globalOption key="CamelJacksonTypeConverterToPojo" value="true"/>
+ </globalOptions>
-### Extended CamelContext
+=== Extended CamelContext
The APIs on `CamelContext` has been reduced a bit to focus on relevant API for
Camel end users. The advanced use-cases and for SPI and component developers,
then some of the APIs from `CamelContext` has been moved to
`ExtendedCamelContext` which you can access via adapt:
- ExtendedCamelContext ecc = context.adapt(ExtendedCamelContext.class);
+ ExtendedCamelContext ecc = context.adapt(ExtendedCamelContext.class);
-### Main class
+=== Main class
The `Main` class from `camel-core`, `camel-spring` and `camel-cdi` has been
modified to only support a single `CamelContext` which was really its
intention, but there was some old crufty code for multiple Camels. The method
`getCamelContextMap` has been removed, and there is just a `getCamelContext`
method now.
-### POJO annotations
+=== POJO annotations
The `ref` attribute on `@Consume`, `@Produce` and `@EndpointInject` has been
removed. Instead use the ref component in the `uri` attribute, eg `uri =
"ref:myName"`.
The uri attribute has been deprecated, instead use value, which allows a
shorthand style, from using `@Consume(uri = "jms:cheese")` to
`@Consume("jms:cheese")`.
-### Routes with multiple inputs
+=== Routes with multiple inputs
In Camel 2.x you could have 2 or more inputs to Camel routes, however this was
not supported in all use-cases in Camel, and this functionality is seldom in
use. This has
also been deprecated in Camel 2.x. In Camel 3 we have removed the remaining
code for specifying multiple inputs to routes, and its now only possible to
specify exactly only 1 input to a route.
-### JSon DataFormat
+=== JSon DataFormat
The default JSon library with the JSon dataformat has changed from `XStream`
to `Jackson`.
-### Zip and GZip DataFormat
+=== Zip and GZip DataFormat
The zip and gzip dataformat has been renamed to zipdeflater and gzipdeflater
as they are for deflating using the zip/gzip compression; and not for working
with zip/gzip files. Instead use camel-zipfile dataformat. Also these
dataformats has been moved out of `camel-core` into `camel-zip-deflater` JAR.
The XML and Java DSL has also been modified so you should migrate there too to
use their new names. And if you use these data formats you need to add the
`camel-zip-deflater` as dependency [...]
-### Simple language
+=== Simple language
The functionality to change the simple language tokens for start/end functions
has been removed. The default tokens with `${xxx}` and `$simple{xxx}` is now
hardcoded (optimized). The functionality to change these tokens was never
really in use and would only confuse Camel users if a new syntax are in use.
-### Moved APIs
+=== Moved APIs
The following API changes may affect your existing Camel applications, which
needs to be migrated.
-#### CamelContext
+==== CamelContext
The methods on `CamelContext` that are related to catalog has been moved into
a new `CatalogCamelContext` interface, which you can access by adapting:
- CatalogCamelContext ccc = context.adapt(CatalogCamelContext.class);
+ CatalogCamelContext ccc = context.adapt(CatalogCamelContext.class);
The `loadRouteDefinitions` and `loadRestDefinitions` on `ModelCamelContext`
has been changed to `addRouteDefinitions` and `addRestDefinitions` to be
aligned with the other methods. You can find loader methods on the
`ModelHelper` utility class.
-#### Checked vs unchecked exceptions
+==== Checked vs unchecked exceptions
Most of the Camel exception classes has been migrated to be unchecked (eg
extends `RuntimeException`).
Also the lifecycle of the `start`, `stop` and `suspend`, `resume` methods on
`Service` and `SuspendableService` has been changed to not throw checked
exceptions.
-#### Generic Information
+==== Generic Information
The class `SimpleRegistry` is moved from `org.apache.camel.impl` to
`org.apache.camel.support`. Also you should favour using the
`org.apache.camel.support.DefaultRegistry` instead. Also you should use the
`bind` operation instead of `put` to add entries to the `SimpleRegistry` or
`DefaultRegistry`.
@@ -390,62 +379,60 @@ The class `FactoryFinder` has changed its API to use
`Optional` as return types
The option `resolvePropertyPlaceholders` on all the components has been
removed,
as property placeholders is already supported via Camel Main, Camel Spring
Boot and other means.
-#### camel-test
+==== camel-test
If you are using camel-test and override the `createRegistry` method, for
example to register beans from the `JndiRegisty` class, then this is no longer
necessary, and instead
you should just use the `bind` method from the `Registry` API which you can
call directly from `CamelContext`, such as:
- context.getRegistry().bind("myId", myBean);
+ context.getRegistry().bind("myId", myBean);
-
-#### Controlling routes
+==== Controlling routes
The `startRoute`, `stopRoute`, `suspendRoute`, `resumeRoute`,
`getRouteStatus`, and other related methods on `CamelContext` has been moved to
the `RouteController` as shown below:
- context.getRouteController().startRoute("myRoute");
-
+ context.getRouteController().startRoute("myRoute");
-#### JMX events
+==== JMX events
All the events from package `org.apache.camel.management.event` has been moved
to the class `org.apache.camel.spi.CamelEvent` as sub-classes, for example the
event for CamelContext started would be `CamelEvent.CamelContextStartedEvent`.
-#### AdviceWith
+==== AdviceWith
Testing using `adviceWith` currently needs to be changed from:
- context.getRouteDefinition("start").adviceWith(context, new RouteBuilder()
{
- ...
- }
+ context.getRouteDefinition("start").adviceWith(context, new RouteBuilder() {
+ ...
+ }
to using style:
- RouteReifier.adviceWith(context.getRouteDefinition("start"), context, new
RouteBuilder() {
- ...
- }
+ RouteReifier.adviceWith(context.getRouteDefinition("start"), context, new
RouteBuilder() {
+ ...
+ }
We are planning on making this easier in 3.0.0-M2 onwards.
-#### Generic Classes
+==== Generic Classes
The class `JNDIContext` has been moved from
`org.apache.camel.util.jndi.JNDIContext` in the camel-core JAR to
`org.apache.camel.support.jndi.JNDIContext` and moved to the `camel-support`
JAR.
-#### EIPs
+==== EIPs
The `circuitBreaker` load-balancer EIP was deprecated in Camel 2.x, and has
been removed. Instead use Hystrix EIP as the load-balancer.
The class `ThreadPoolRejectedPolicy` has been moved from
`org.apache.camel.ThreadPoolRejectedPolicy` to
`org.apache.camel.util.concurrent.ThreadPoolRejectedPolicy`.
-#### Languages
+==== Languages
The simple language `property` function was deprecated in Camel 2.x and has
been removed. Use `exchangeProperty` as function name.
The terser language has been renamed from terser to hl7terser.
-#### JSSE
+==== JSSE
The classes from `org.apache.camel.util.jsse` has been moved to
`org.apache.camel.support.jsse`.
-#### Helpers and support
+==== Helpers and support
The class `AsyncProcessorHelper` has been moved from
`org.apache.camel.util.AsyncProcessorHelper` in the camel-core JAR to
`org.apache.camel.support.AsyncProcessorHelper` and moved to the
`camel-support` JAR.
@@ -481,44 +468,39 @@ The class `ServiceHelper` has been moved from
`org.apache.camel.util.ServiceHelp
The class `UnitOfWorkHelper` has been moved from
`org.apache.camel.util.UnitOfWorkHelper` in the camel-core JAR to
`org.apache.camel.support.UnitOfWorkHelper` and moved to the `camel-support`
JAR.
-
-#### Idempotent Repositories
+==== Idempotent Repositories
The class `FileIdempotentRepository` has been moved from
`org.apache.camel.processor.idempotent.FileIdempotentRepository` in the
camel-core JAR to
`org.apache.camel.support.processor.idempotent.FileIdempotentRepository` and
moved to the `camel-support` JAR.
The class `MemoryIdempotentRepository` has been moved from
`org.apache.camel.processor.idempotent.MemoryIdempotentRepository` in the
camel-core JAR to
`org.apache.camel.support.processor.idempotent.MemoryIdempotentRepository` and
moved to the `camel-support` JAR.
-
-#### Route Policies
+==== Route Policies
The class `org.apache.camel.impl.RoutePolicySupport` has been moved to
`org.apache.camel.support.RoutePolicySupport`. The return type from
`startConsumer` and `stopConsumer` has been changed from `boolean` to `void` as
they always returned `true` before.
The class `org.apache.camel.impl.ThrottlingInflightRoutePolicy` has been moved
to `org.apache.camel.throttling.ThrottlingInflightRoutePolicy`
-
-#### Aggregation
+==== Aggregation
The class `XsltAggregationStrategy` has been moved from
`org.apache.camel.builder.XsltAggregationStrategy` in the camel-core JAR to
`org.apache.camel.component.xslt.XsltAggregationStrategy` and moved to the
`camel-xslt` JAR.
When using the option `groupedExchange` on the aggregator EIP then the output
of the aggregation is now longer also stored in the exchange property
`Exchange.GROUPED_EXCHANGE`. This behaviour was already deprecated from Camel
2.13 onwards.
-### Fallback type converters
+=== Fallback type converters
The `@FallbackConverter` annotation has been removed, and you should use
`@Converter(fallback = true)` instead. Also you can set
`@Converter(generateLoader = true)` on the converter class to allow Camel to
generate source code for loading type converters in a faster way.
-
-### Removed JMX APIs for explaining EIPs, components, etc.
+=== Removed JMX APIs for explaining EIPs, components, etc.
The APIs that could find, and explain EIPs, components, endpoints etc has been
removed. These APIs have little value for production runtimes, and you can
obtain this kind of information via the `camel-catalog`. Also the related Camel
Karaf commands that used these APIs has been removed.
-
-### Other changes
+=== Other changes
The default for use breadcrumbs has been changed from `true` to `false`.
The `ProducerTemplate` and `ConsumerTemplate` now fails when being used, if
`CamelContext` has not been started first.
-### XML DSL Migration
+=== XML DSL Migration
The XML DSL has been changed slightly.
@@ -528,9 +510,7 @@ The XMLSecurity data format has renamed the attribute
`keyOrTrustStoreParameters
The `<zipFile>` data format has been renamed to `<zipfile>`.
-
-Migrating Camel Maven Plugins
-----------------------------
+== Migrating Camel Maven Plugins
The `camel-maven-plugin` has been split up into two maven plugins:
@@ -541,10 +521,6 @@ The former has the `run` goal, which is intended for
quickly running Camel appli
The `camel-report-maven-plugin` has the `validate` and `route-coverage` goals
which is used for generating reports of your Camel projects such as validating
Camel endpoint URIs and route coverage reports, etc.
-
-Known Issues
-----------------------------
+== Known Issues
There is an issue with MDC logging and correctly transferring the Camel
breadcrumb id's under certain situations with routing over asynchronous
endpoints, due to the internal routing engine refactorings. This change also
affects the `camel-zipkin` component, which may not correctly transfer the span
id's when using MDC logging as well.
-
-
