This is an automated email from the ASF dual-hosted git repository.
davsclaus 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 0f4b12c Improve TypeConverter documentation (#4534)
0f4b12c is described below
commit 0f4b12c6ff9cec2b66eb113981a3427e31f76688
Author: Mike Martino <mikemartin...@gmail.com>
AuthorDate: Thu Oct 29 02:06:47 2020 -0400
Improve TypeConverter documentation (#4534)
* improve MongoDB component documentation
- use headings where applicable
- add use of constant() - current examples do not compile as they are
documented
* change first sentence to not use a passive voice; break it into two
separate sentences.
* add monospaced font for types
* add a callout to clearly highlight where the conversion happens.
- also, collapse the two references to the Message Javadoc; the second one
is sufficient on its own.
* general change in wording for the Default type converter registry section
* simplify wording
- use note icon to highlight important additional information.
- link to Javadoc for getStatistics
* more general formatting improvements
- fix typos
- improve wording of sections
- correct usage of monospaced fonts
* add semi-colon
* 'has' should be 'have'
* change confusing wording on the use of Java Reflection API
* remove words at beginning of sentence
* replace apostrophe with backtick to get monospaced font
---
.../modules/ROOT/pages/type-converter.adoc | 116 +++++++++------------
1 file changed, 52 insertions(+), 64 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/type-converter.adoc
b/docs/user-manual/modules/ROOT/pages/type-converter.adoc
index d7bd8fe..e530d30 100644
--- a/docs/user-manual/modules/ROOT/pages/type-converter.adoc
+++ b/docs/user-manual/modules/ROOT/pages/type-converter.adoc
@@ -1,32 +1,24 @@
[[TypeConverter-TypeConverter]]
= Type Converter
-It is very common when routing messages from one endpoint to another to
-need to convert the body payloads from one type to another such as to
-convert to and from the following common types:
-
-* File
-* String
-* byte[] and ByteBuffer
-* InputStream and OutputStream
-* Reader and Writer
-* Document and Source
-* ...
+Converting body payloads from one type to another is common when routing
messages between endpoints.
+Conversions regularly occur between the following types:
-The
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Message.html[Message
-interface] defines a helper method to allow conversions to be done via
-the
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Message.html#getBody-java.lang.Class-[getBody(Class)]
-method.
+* `File`
+* `String`
+* `byte[]` and `ByteBuffer`
+* `InputStream` and `OutputStream`
+* `Reader` and `Writer`
+* `Document` and `Source`
-So in an endpoint you can convert a body to another type via:
+To convert the body of a message to another type:
[source,java]
----
Message message = exchange.getIn();
-Document document = message.getBody(Document.class);
+Document document = message.getBody(Document.class); // <1>
----
+<1> where
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Message.html#getBody-java.lang.Class-[`Message#getBody(Class)`]
performs the conversion.
[[TypeConverter-HowTypeConversionworks]]
== How Type Conversion works
@@ -37,48 +29,46 @@ interface that can be customized on a
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/CamelContext.html[CamelContext].
Camel provides a default type converter registry.
-From Camel 3 onwards there type converter registry implementation uses source
code generation via the Camel Maven
-Package Plugin to generate source code, that allows Camel at runtime to load
and invoke these type converters via
-quick java method invocations. The older implementation in Camel 2 uses a
annotation based discover to load and
-register type converters and invokes the type converters via Java method call
reflections.
+From Camel 3 onwards, the type converter registry implementation generates
source code using the Camel Maven
+Package Plugin, allowing Camel, at runtime, to load and invoke these type
converters via
+quick Java method invocations. In Camel 2, type converters are registered
using annotation based discovery, invoking the type converters via the
https://docs.oracle.com/javase/tutorial/reflect/[Java Reflection API].
[[TypeConverter-TypeConverterRegistry]]
== TypeConverterRegistry
-Exposed the
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/spi/TypeConverterRegistry.html[TypeConverterRegistry]
-from xref:camelcontext.adoc[CamelContext] so end users more easily will
-be able to add type converters at runtime. This is also usable in
-situations where the default discovering of type converters fails on
-platforms with classloading issues.
-
-To access the registry, you get it from the `CamelContext`:
+Add a `TypeConverter` to the
+https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/spi/TypeConverterRegistry.html[`TypeConverterRegistry`]
+at runtime using the xref:camelcontext.adoc[CamelContext]:
[source,java]
----
-CamelContext context = ...
-context.getTypeConverterRegistry()
+CamelContext context = ...;
+context.getTypeConverterRegistry();
----
+NOTE: This is useful on platforms where the automatic type converters
discovery fails due to classloading issues.
+
[[TypeConverter-TypeConverterRegistryutilizationstatistics]]
=== TypeConverterRegistry utilization statistics
Camel can gather utilization statistics of the runtime usage of type
-converters. These stats are available in JMX, and as well as from the
-`getStatistics()` method from `TypeConverterRegistry`.
+converters. These statistics are available in JMX as well as
+from
https://www.javadoc.io/doc/org.apache.camel/camel-api/latest/org/apache/camel/spi/TypeConverterRegistry.html#getStatistics--[`TypeConverterRegistry#getStatistics()`].
These statistics are turned off by
default as there is some performance overhead under very high concurrent
-load. To enable the statistics in Java, do the following:
+load.
+
+Enabling statistics in Java:
[source,java]
----
-CamelContext context = ...
+CamelContext context = ...;
context.setTypeConverterStatisticsEnabled(true);
----
-Or in the XML DSL with:
+Enabling statistics in XML DSL:
[source,xml]
----
@@ -90,10 +80,8 @@ Or in the XML DSL with:
[[TypeConverter-Addtypeconverterclassesatruntime]]
=== Add type converter classes at runtime
-You can add new type converters at runtime, by having your classes
-implement `org.apache.camel.TypeConverters` which is an marker
-interface. Then for each type converter you want use
-the `@Converter` annotation.
+Classes implementing
https://www.javadoc.io/doc/org.apache.camel/camel-api/latest/org/apache/camel/TypeConverters.html[`TypeConverters`]
are added to the type converter registry
+at runtime. Use
https://javadoc.io/doc/org.apache.camel/camel-api/latest/org/apache/camel/Converter.html[`@Converter`]
to mark each type converter.
[source,java]
----
@@ -107,11 +95,11 @@ private class MyOrderTypeConverters implements
TypeConverters {
}
----
-Then you can add these converters to the registry using:
+Then, add these converters to the registry:
[source,xml]
----
-MyOrderTypeConverters myClass = ...
+MyOrderTypeConverters myClass = ...;
context.getTypeConverterRegistry().addTypeConverters(myClass);
----
@@ -131,25 +119,27 @@ You can declare multiple `<bean>`s if you have more
classes.
[[TypeConverter-DiscoveringTypeConverters]]
== Discovering Type Converters
-Camel will automatic discover and load type converters from all the JARs in
the classpath on startup.
+Camel automatically discovers and loads the type converters from all JARs on
the classpath at startup.
-Camel will search the classpath for a file called
-`META-INF/services/org/apache/camel/TypeConverterLoader`, which lists
-all type converter loader classes (they are automatic source code generated by
the Camel Maven Package Plugin).
+Camel searches the classpath for a file called
+`META-INF/services/org/apache/camel/TypeConverterLoader` which lists
+all type converter loader classes. These are automatically generated by the
Camel Maven Package Plugin.
These _loader_ classes will load the type converters into the Camel type
converter registry
-and invoking these type converters is done in a _fast way_ using standard java
method calls.
+and invoke them in a _fast way_ using standard Java method calls.
=== Discovering Camel 2.x based type converters (not loader)
-Camel will not perform additional package scanning for type conveters which
has no source code generated loader classes.
-However this can be enabled by setting:
+Camel will not perform additional package scanning for type converters which
have no source code generated for loader classes.
+
+To enable additional package scanning in Java:
[source,java]
----
camelContext.setLoadTypeConverters(true);
----
-And in XML:
+In XML DSL:
+
[source,xml]
----
<camelContext loadTypeConverters="true">
@@ -157,27 +147,25 @@ And in XML:
</camelContext>
----
-And in Spring Boot `application.properties`:
+In Spring Boot `application.properties`:
+
[source,properties]
----
camel.springboot.load-type-converters=true
----
-Then Camel will discover discover Camel 2.x compatible type converters by
-search the classpath for a file called
`META-INF/services/org/apache/camel/TypeConverter`,
-which lists all the type converter classes. These classes will then automatic
-be registered in the type converter registry. However invoking these type
converters
-does **not** happen in a _fast way_ but uses Java method call reflection. It
is therefore
-recommended to migrate your type converters to use the faster way. See further
below.
+Camel will discover Camel 2.x compatible type converters by
+searching the classpath for a file called
`META-INF/services/org/apache/camel/TypeConverter`
+which lists all type converter classes. These classes are automatically
registered in the type converter
+registry. However, invoking these type converters does **not** happen in a
_fast way_ and uses the Java Reflection API.
+It is therefore recommended to upgrade any type converters to use the faster
way. See below for more details.
TIP: You can turn off the fallback of discovering Camel 2.x compatible type
converters by
-setting the `loadTypeConverters` option to `false` on `CamelContext`.
+setting `CamelContext.setLoadTypeConverters(false)`.
-The converter classes must be annotated on the top class level with the
`@Converter` annotation,
-and each converter method as well.
+`@Converter` must appear at the class and method level for each type converter.
-E.g. the following shows how to register a converter from `File` to
-`InputStream`:
+.Register a type converter from `File` to `InputStream`
[source,java]
----
