You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ja...@apache.org on 2021/07/26 14:41:05 UTC
[camel-quarkus] 02/03: Automate the generation of documentation for
the transferException option
This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
commit ce860720074c8ebc1419f35e8624cf0acbb48856
Author: James Netherton <ja...@gmail.com>
AuthorDate: Fri Jul 23 11:44:38 2021 +0100
Automate the generation of documentation for the transferException option
---
.../ROOT/pages/reference/extensions/activemq.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/ahc-ws.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/ahc.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/amqp.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/core.adoc | 4 +---
.../ROOT/pages/reference/extensions/http.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/jms.adoc | 11 +++++++++++
.../pages/reference/extensions/netty-http.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/rabbitmq.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/servlet.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/sjms.adoc | 11 +++++++++++
.../ROOT/pages/reference/extensions/sjms2.adoc | 11 +++++++++++
.../pages/reference/extensions/vertx-http.adoc | 11 +++++++++++
.../org/apache/camel/quarkus/core/CamelConfig.java | 22 ++++------------------
.../quarkus/maven/UpdateExtensionDocPageMojo.java | 13 ++++++++-----
.../doc-templates/extension-doc-page.adoc | 13 +++++++++++++
16 files changed, 158 insertions(+), 26 deletions(-)
diff --git a/docs/modules/ROOT/pages/reference/extensions/activemq.adoc b/docs/modules/ROOT/pages/reference/extensions/activemq.adoc
index d3db74d..63a2acc 100644
--- a/docs/modules/ROOT/pages/reference/extensions/activemq.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/activemq.adoc
@@ -63,3 +63,14 @@ is excluded from the dependency tree, since none of the ActiveMQ broker function
This extension auto-enables SSL support in native mode. Hence you do not need to add
`quarkus.ssl.native=true` to your `application.properties` yourself. See also
https://quarkus.io/guides/native-and-ssl[Quarkus SSL guide].
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/docs/modules/ROOT/pages/reference/extensions/ahc-ws.adoc b/docs/modules/ROOT/pages/reference/extensions/ahc-ws.adoc
index c70eccb..000fe04 100644
--- a/docs/modules/ROOT/pages/reference/extensions/ahc-ws.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/ahc-ws.adoc
@@ -45,3 +45,14 @@ Check the xref:user-guide/index.adoc[User guide] for more information about writ
This extension auto-enables SSL support in native mode. Hence you do not need to add
`quarkus.ssl.native=true` to your `application.properties` yourself. See also
https://quarkus.io/guides/native-and-ssl[Quarkus SSL guide].
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/docs/modules/ROOT/pages/reference/extensions/ahc.adoc b/docs/modules/ROOT/pages/reference/extensions/ahc.adoc
index 89b3785..2d291dd 100644
--- a/docs/modules/ROOT/pages/reference/extensions/ahc.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/ahc.adoc
@@ -45,6 +45,17 @@ This extension auto-enables SSL support in native mode. Hence you do not need to
`quarkus.ssl.native=true` to your `application.properties` yourself. See also
https://quarkus.io/guides/native-and-ssl[Quarkus SSL guide].
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
+
== Additional Camel Quarkus configuration
* Check the xref:user-guide/native-mode.adoc#charsets[Character encodings section] of the Native mode guide if you expect
diff --git a/docs/modules/ROOT/pages/reference/extensions/amqp.adoc b/docs/modules/ROOT/pages/reference/extensions/amqp.adoc
index ddb3e1a..a778a1c 100644
--- a/docs/modules/ROOT/pages/reference/extensions/amqp.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/amqp.adoc
@@ -52,6 +52,17 @@ When sending JMS message payloads as `javax.jms.ObjectMessage`, you must annotat
Note that this extension automatically sets `quarkus.camel.native.reflection.serialization-enabled = true` for you. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide] for more information.
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
+
== Additional Camel Quarkus configuration
The extension leverages the https://github.com/amqphub/quarkus-qpid-jms/[Quarkus Qpid JMS] extension. A ConnectionFactory bean is automatically created
diff --git a/docs/modules/ROOT/pages/reference/extensions/core.adoc b/docs/modules/ROOT/pages/reference/extensions/core.adoc
index d04c38a..ce38e53 100644
--- a/docs/modules/ROOT/pages/reference/extensions/core.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/core.adoc
@@ -226,9 +226,7 @@ A comma separated list of Ant-path style patterns to match class names that shou
|icon:lock[title=Fixed at build time] [[quarkus.camel.native.reflection.serialization-enabled]]`link:#quarkus.camel.native.reflection.serialization-enabled[quarkus.camel.native.reflection.serialization-enabled]`
-If `true`, basic classes are registered for serialization; otherwise basic classes won't be registered automatically for serialization in native mode.
- List of basic classes: `java.lang.Boolean` `java.lang.Byte` `java.lang.Character` `java.lang.Float` `java.lang.Double` `java.lang.Integer` `java.lang.Long` `java.lang.Number` `java.lang.String` `java.math.BigInteger` `java.util.Date` `java.util.HashMap` `java.util.LinkedHashMap` `org.apache.camel.support.DefaultExchangeHolder`
- Setting this to `false` helps to reduce the size of the native image. In JVM mode, there is no real benefit of setting this flag to `true` except for making the behavior consistent with native mode.
+If `true`, basic classes are registered for serialization; otherwise basic classes won't be registered automatically for serialization in native mode. The list of classes automatically registered for serialization can be found in link:https://github.com/apache/camel-quarkus/blob/main/extensions-core/core/deployment/src/main/java/org/apache/camel/quarkus/core/deployment/CamelSerializationProcessor.java[CamelSerializationProcessor.BASE_SERIALIZATION_CLASSES]. Setting this to `false` helps [...]
| `boolean`
| `false`
diff --git a/docs/modules/ROOT/pages/reference/extensions/http.adoc b/docs/modules/ROOT/pages/reference/extensions/http.adoc
index f2c6e0c..63e7eb4 100644
--- a/docs/modules/ROOT/pages/reference/extensions/http.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/http.adoc
@@ -46,6 +46,17 @@ This extension auto-enables SSL support in native mode. Hence you do not need to
`quarkus.ssl.native=true` to your `application.properties` yourself. See also
https://quarkus.io/guides/native-and-ssl[Quarkus SSL guide].
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
+
== Additional Camel Quarkus configuration
* Check the xref:user-guide/native-mode.adoc#charsets[Character encodings section] of the Native mode guide if you expect
diff --git a/docs/modules/ROOT/pages/reference/extensions/jms.adoc b/docs/modules/ROOT/pages/reference/extensions/jms.adoc
index 2db5e96..9f98034 100644
--- a/docs/modules/ROOT/pages/reference/extensions/jms.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/jms.adoc
@@ -51,3 +51,14 @@ you must ensure that the `camel-quarkus-jaxp` extension is present on the classp
When sending JMS message payloads as `javax.jms.ObjectMessage`, you must annotate the relevant classes to be registered for serialization with `@RegisterForReflection(serialization = true)`.
Note that this extension automatically sets `quarkus.camel.native.reflection.serialization-enabled = true` for you. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide] for more information.
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/docs/modules/ROOT/pages/reference/extensions/netty-http.adoc b/docs/modules/ROOT/pages/reference/extensions/netty-http.adoc
index 67dc543..c36f9a4 100644
--- a/docs/modules/ROOT/pages/reference/extensions/netty-http.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/netty-http.adoc
@@ -40,6 +40,17 @@ Or add the coordinates to your existing project:
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
+
== Additional Camel Quarkus configuration
* Check the xref:user-guide/native-mode.adoc#charsets[Character encodings section] of the Native mode guide if you expect
diff --git a/docs/modules/ROOT/pages/reference/extensions/rabbitmq.adoc b/docs/modules/ROOT/pages/reference/extensions/rabbitmq.adoc
index 33a9281..f0c6534 100644
--- a/docs/modules/ROOT/pages/reference/extensions/rabbitmq.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/rabbitmq.adoc
@@ -38,3 +38,14 @@ Or add the coordinates to your existing project:
----
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/docs/modules/ROOT/pages/reference/extensions/servlet.adoc b/docs/modules/ROOT/pages/reference/extensions/servlet.adoc
index c27f993..01c933b 100644
--- a/docs/modules/ROOT/pages/reference/extensions/servlet.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/servlet.adoc
@@ -39,6 +39,17 @@ Or add the coordinates to your existing project:
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
+
== Additional Camel Quarkus configuration
[width="100%",cols="80,5,15",options="header"]
diff --git a/docs/modules/ROOT/pages/reference/extensions/sjms.adoc b/docs/modules/ROOT/pages/reference/extensions/sjms.adoc
index d029fec..2cb6c05 100644
--- a/docs/modules/ROOT/pages/reference/extensions/sjms.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/sjms.adoc
@@ -51,3 +51,14 @@ you must ensure that the `camel-quarkus-jaxp` extension is present on the classp
When sending JMS message payloads as `javax.jms.ObjectMessage`, you must annotate the relevant classes to be registered for serialization with `@RegisterForReflection(serialization = true)`.
Note that this extension automatically sets `quarkus.camel.native.reflection.serialization-enabled = true` for you. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide] for more information.
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/docs/modules/ROOT/pages/reference/extensions/sjms2.adoc b/docs/modules/ROOT/pages/reference/extensions/sjms2.adoc
index dd5569c..fbee92a 100644
--- a/docs/modules/ROOT/pages/reference/extensions/sjms2.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/sjms2.adoc
@@ -51,3 +51,14 @@ you must ensure that the `camel-quarkus-jaxp` extension is present on the classp
When sending JMS message payloads as `javax.jms.ObjectMessage`, you must annotate the relevant classes to be registered for serialization with `@RegisterForReflection(serialization = true)`.
Note that this extension automatically sets `quarkus.camel.native.reflection.serialization-enabled = true` for you. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide] for more information.
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/docs/modules/ROOT/pages/reference/extensions/vertx-http.adoc b/docs/modules/ROOT/pages/reference/extensions/vertx-http.adoc
index 81f329c..c70d6a0 100644
--- a/docs/modules/ROOT/pages/reference/extensions/vertx-http.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/vertx-http.adoc
@@ -37,3 +37,14 @@ Or add the coordinates to your existing project:
----
Check the xref:user-guide/index.adoc[User guide] for more information about writing Camel Quarkus applications.
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
diff --git a/extensions-core/core/runtime/src/main/java/org/apache/camel/quarkus/core/CamelConfig.java b/extensions-core/core/runtime/src/main/java/org/apache/camel/quarkus/core/CamelConfig.java
index a413fbf..0d8a6bc 100644
--- a/extensions-core/core/runtime/src/main/java/org/apache/camel/quarkus/core/CamelConfig.java
+++ b/extensions-core/core/runtime/src/main/java/org/apache/camel/quarkus/core/CamelConfig.java
@@ -284,24 +284,10 @@ public class CamelConfig {
/**
* If {@code true}, basic classes are registered for serialization; otherwise basic classes won't be registered
* automatically for serialization in native mode.
- * <p>
- * List of basic classes:
- * {@code java.lang.Boolean}
- * {@code java.lang.Byte}
- * {@code java.lang.Character}
- * {@code java.lang.Float}
- * {@code java.lang.Double}
- * {@code java.lang.Integer}
- * {@code java.lang.Long}
- * {@code java.lang.Number}
- * {@code java.lang.String}
- * {@code java.math.BigInteger}
- * {@code java.util.Date}
- * {@code java.util.HashMap}
- * {@code java.util.LinkedHashMap}
- * {@code org.apache.camel.support.DefaultExchangeHolder}
- *
- * <p>
+ *
+ * The list of classes automatically registered for serialization can be found in <a href=
+ * "https://github.com/apache/camel-quarkus/blob/main/extensions-core/core/deployment/src/main/java/org/apache/camel/quarkus/core/deployment/CamelSerializationProcessor.java">CamelSerializationProcessor.BASE_SERIALIZATION_CLASSES</a>.
+ *
* Setting this to {@code false} helps to reduce the size of the native image. In JVM mode, there is no real
* benefit of setting this flag to {@code true} except for making the behavior consistent with native mode.
*/
diff --git a/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java b/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java
index e57da0f..c69e764 100644
--- a/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java
+++ b/tooling/maven-plugin/src/main/java/org/apache/camel/quarkus/maven/UpdateExtensionDocPageMojo.java
@@ -129,7 +129,11 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo {
model.put("activatesNativeSsl", ext.isNativeSupported() && detectNativeSsl(multiModuleProjectDirectory.toPath(),
basePath, ext.getRuntimeArtifactId(), ext.getDependencies(), nativeSslActivators));
model.put("activatesContextMapAll",
- ext.isNativeSupported() && detectAllowContextMapAll(catalog, ext.getRuntimeArtifactIdBase()));
+ ext.isNativeSupported()
+ && detectComponentOrEndpointOption(catalog, ext.getRuntimeArtifactIdBase(), "allowContextMapAll"));
+ model.put("activatesTransferException",
+ ext.isNativeSupported()
+ && detectComponentOrEndpointOption(catalog, ext.getRuntimeArtifactIdBase(), "transferException"));
model.put("configOptions", listConfigOptions(basePath, multiModuleProjectDirectory.toPath()));
model.put("humanReadableKind", new TemplateMethodModelEx() {
@Override
@@ -326,20 +330,19 @@ public class UpdateExtensionDocPageMojo extends AbstractDocGeneratorMojo {
}
}
- static boolean detectAllowContextMapAll(CqCatalog catalog, String artifactId) {
- final String allowContextMapAll = "allowContextMapAll";
+ static boolean detectComponentOrEndpointOption(CqCatalog catalog, String artifactId, String option) {
return catalog.filterModels(artifactId)
.filter(m -> m instanceof ComponentModel)
.map(m -> (ComponentModel) m)
.anyMatch(componentModel -> {
for (ComponentModel.ComponentOptionModel model : componentModel.getOptions()) {
- if (model.getName().equals(allowContextMapAll)) {
+ if (model.getName().equals(option)) {
return true;
}
}
for (ComponentModel.EndpointOptionModel model : componentModel.getEndpointOptions()) {
- if (model.getName().equals(allowContextMapAll)) {
+ if (model.getName().equals(option)) {
return true;
}
}
diff --git a/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc b/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc
index ed689e0..92c2e71 100644
--- a/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc
+++ b/tooling/maven-plugin/src/main/resources/doc-templates/extension-doc-page.adoc
@@ -68,6 +68,19 @@ https://quarkus.io/guides/native-and-ssl[Quarkus SSL guide].
The `allowContextMapAll` option is not supported in native mode as it requires reflective access to security sensitive camel core classes such as
`CamelContext` & `Exchange`. This is considered a security risk and thus access to the feature is not provided by default.
[/#if]
+[#if activatesTransferException ]
+
+== transferException option in native mode
+
+To use the `transferException` option in native mode, you must enable support for object serialization. Refer to the xref:user-guide/native-mode.adoc#serialization[native mode user guide]
+for more information.
+
+You will also need to enable serialization for the exception classes that you intend to serialize. For example.
+[source,java]
+----
+@RegisterForReflection(targets = { IllegalStateException.class, MyCustomException.class }, serialization = true)
+----
+[/#if]
[#if configuration?? || configOptions?size != 0 ]
== Additional Camel Quarkus configuration