This is an automated email from the ASF dual-hosted git repository.
ppalaga pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new b140ca2 Improve the User guide
b140ca2 is described below
commit b140ca220ddeb4be5f99d2ba11d63b669fd5ab06
Author: Peter Palaga <ppal...@redhat.com>
AuthorDate: Thu Oct 14 12:34:43 2021 +0200
Improve the User guide
---
.../pages/contributor-guide/release-guide.adoc | 2 +-
docs/modules/ROOT/pages/user-guide/cdi.adoc | 2 +-
.../ROOT/pages/user-guide/command-mode.adoc | 4 +--
.../pages/user-guide/dependency-management.adoc | 5 ++--
.../modules/ROOT/pages/user-guide/first-steps.adoc | 18 ++++++-------
.../modules/ROOT/pages/user-guide/native-mode.adoc | 30 ++++++++++++++++++----
docs/modules/ROOT/pages/user-guide/testing.adoc | 18 ++++++-------
7 files changed, 50 insertions(+), 29 deletions(-)
diff --git a/docs/modules/ROOT/pages/contributor-guide/release-guide.adoc
b/docs/modules/ROOT/pages/contributor-guide/release-guide.adoc
index 5ea439d..0ef9e1e 100644
--- a/docs/modules/ROOT/pages/contributor-guide/release-guide.adoc
+++ b/docs/modules/ROOT/pages/contributor-guide/release-guide.adoc
@@ -164,7 +164,7 @@ from the local Maven repository and then checks that they
are available in Maven
As long as there are unavailable artifacts, the requests are re-tried with a
(configurable) delay of 60 seconds.
====
-[INFO]
+[NOTE]
====
https://github.com/quarkusio/quarkus-platform[Quarkus Platform] hosts the
metadata and Maven BOMs necessary for
https://code.quarkus.io/[code.quarkus.io] as well as for
https://quarkus.io/guides/tooling[Quarkus tools].
diff --git a/docs/modules/ROOT/pages/user-guide/cdi.adoc
b/docs/modules/ROOT/pages/user-guide/cdi.adoc
index afc96e2..cf45504 100644
--- a/docs/modules/ROOT/pages/user-guide/cdi.adoc
+++ b/docs/modules/ROOT/pages/user-guide/cdi.adoc
@@ -178,7 +178,7 @@ public class CamelRoute extends RouteBuilder {
}
----
-[INFO]
+[NOTE]
====
We aim at supporting all use cases listed in
xref:latest@manual::bean-binding.adoc[Bean binding] section of Camel
documentation.
Do not hesitate to https://github.com/apache/camel-quarkus/issues[file an
issue] if some bean binding scenario does not work for you.
diff --git a/docs/modules/ROOT/pages/user-guide/command-mode.adoc
b/docs/modules/ROOT/pages/user-guide/command-mode.adoc
index 8bc975f..d93183a 100644
--- a/docs/modules/ROOT/pages/user-guide/command-mode.adoc
+++ b/docs/modules/ROOT/pages/user-guide/command-mode.adoc
@@ -207,14 +207,14 @@ $ target/*runner -Dgreeted.subject=Joe
== Source code
-The sources of the application used in this blog post are based on the
`main-command-mode` integration test in the Camel Quarkus source tree:
+The sources of the application used in this section are based on the
`main-command-mode` integration test in the Camel Quarkus source tree:
https://github.com/apache/camel-quarkus/tree/main/integration-tests/main-command-mode[https://github.com/apache/camel-quarkus/tree/main/integration-tests/main-command-mode]
Bonus: The integration test module shows a way how to test command line
applications.
== Full control over starting Camel by invoking `CamelMainApplication`
directly.
-If you need perform some custom logic before starting Camel (or even not
starting it at all),
+If you need to perform some custom logic before starting Camel (or even not
starting it at all),
you can do so by implementing a `@QuarkusMain` class and starting
`CamelMainApplication` yourself
after your custom logic is executed.
diff --git a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
index 065e5a6..3d8d746 100644
--- a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
+++ b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
@@ -5,6 +5,7 @@ A specific Camel Quarkus release is supposed to work only with
a specific Quarku
== Quarkus tooling for starting a new project
The easiest and most straightforward way to get the dependency versions right
in a new project is to use one of the Quarkus tools:
+
* https://code.quarkus.io/[code.quarkus.io] - an online project generator,
* https://quarkus.io/guides/cli-tooling[Quarkus CLI tool]
* https://quarkus.io/guides/maven-tooling[Quarkus Maven plugin]
@@ -12,7 +13,7 @@ The easiest and most straightforward way to get the
dependency versions right in
All of these allow you to select extensions and scaffold a new Maven or Gradle
project.
-[INFO]
+[TIP]
====
The universe of available extensions spans over Quarkus Core, Camel Quarkus
and several other third party participating projects,
such as Hazelcast, Cassandra, Kogito, OptaPlanner, etc.
@@ -89,7 +90,7 @@ As long as you do not plan to use any dependencies beyond
those from Quarkus and
you may consider switching to `org.apache.camel.quarkus:camel-quarkus-bom`.
It manages all supported Camel artifacts and imports `io.quarkus:quarkus-bom`.
-[INFO]
+[NOTE]
====
`io.quarkus:quarkus-bom` manages the core Quarkus dependencies,
such as `io.quarkus:quarkus-arc` (CDI), `io.quarkus:quarkus-hibernate-orm`,
`io.quarkus:quarkus-resteasy` (JAX-RS), etc.
diff --git a/docs/modules/ROOT/pages/user-guide/first-steps.adoc
b/docs/modules/ROOT/pages/user-guide/first-steps.adoc
index 6f877d9..2639d73 100644
--- a/docs/modules/ROOT/pages/user-guide/first-steps.adoc
+++ b/docs/modules/ROOT/pages/user-guide/first-steps.adoc
@@ -7,7 +7,7 @@ This guide outlines various ways to create a new Camel Quarkus
application.
* A `git` client
* An IDE
-* JDK 11+ with JAVA_HOME configured appropriately
+* JDK 11+ with `JAVA_HOME` configured appropriately
* Apache Maven {min-maven-version}+ ({target-maven-version} is recommended)
* GraalVM with the `native-image` command installed and the `GRAALVM_HOME`
environment variable set. See
https://quarkus.io/guides/building-native-image-guide[Building a native
executable] section of the Quarkus
@@ -18,7 +18,7 @@ This guide outlines various ways to create a new Camel
Quarkus application.
== code.quarkus.io
Projects can be generated at https://code.quarkus.io[code.quarkus.io].
-All of the Camel Quarkus extensions can be found under the 'Integration'
heading.
+All of the Camel Quarkus extensions can be found under the 'Integration'
category.
Use the 'search' field to help with finding extensions that you are interested
in.
Simply select the component extensions that you want to work with
@@ -76,14 +76,14 @@ The main branch is always aligned with the latest Camel
Quarkus release.
=== Step by step with the `rest-json` example
-1. Clone the Camel Quarkus example projects.
+1. Clone the Camel Quarkus examples repository:
+
[source,shell]
----
$ git clone https://github.com/apache/camel-quarkus-examples.git
----
-2. Copy the `rest-json` example out of the source tree.
+2. Copy the `rest-json` example out of the source tree:
+
[source,shell]
----
@@ -95,7 +95,7 @@ $ cd rest-json
==== Explore the application code
-The application has three compile dependencies:
+The application has two compile dependencies:
[source,xml,subs="attributes+"]
----
@@ -109,7 +109,7 @@ The application has three compile dependencies:
</dependency>
----
-They are managed within the `camel-quarkus-bom` that is imported in
`<dependencyManagement>`.
+They are managed within the `io.quarkus.platform:quarkus-camel-bom` that is
imported in `<dependencyManagement>`.
[NOTE]
====
@@ -135,12 +135,12 @@ for the `rest-json` example
Then change something in the code and see the changes applied by refreshing
the browser.
-Please refer to
https://quarkus.io/guides/maven-tooling#development-mode[Quarkus documentation]
for more details.
+Please refer to https://quarkus.io/guides/maven-tooling#dev-mode[Quarkus
documentation] for more details about the development mode.
==== Testing
-There are two test classes in our example: `RestJsonTest` is for the JVM mode
while `RestJsonIT` is there for the native
-mode.
+There are two test classes in our example: `RestJsonTest` is for the JVM mode
+while `RestJsonIT` is there for the native mode.
The JVM mode tests are run by `maven-surefire-plugin` in the `test` Maven
phase:
diff --git a/docs/modules/ROOT/pages/user-guide/native-mode.adoc
b/docs/modules/ROOT/pages/user-guide/native-mode.adoc
index 7f1b4bd..89ab323 100644
--- a/docs/modules/ROOT/pages/user-guide/native-mode.adoc
+++ b/docs/modules/ROOT/pages/user-guide/native-mode.adoc
@@ -65,9 +65,9 @@ Please refer to
https://quarkus.io/guides/building-native-image#quarkus-native-p
[[using-onexception-clause-in-native-mode]]
== Using the onException clause in native mode
-When using xref:latest@manual::exception-clause.adoc[camel onException
handling] in native mode, it is the application developers responsibility to
register exception classes for reflection.
+When using xref:latest@manual::exception-clause.adoc[Camel `onException`
handling] in native mode, it is the application developers responsibility to
register the exception classes for reflection.
-For instance, having a camel context with onException handling as below:
+For instance, with an exception handler like this
[source,java]
----
@@ -75,7 +75,7 @@ onException(MyException.class).handled(true);
from("direct:route-that-could-produce-my-exception").throw(MyException.class);
----
-The class `mypackage.MyException` should be registered for reflection, see
more in xref:user-guide/native-mode.adoc#reflection[Registering classes for
reflection].
+the class `MyException` should be registered for reflection, see more in
xref:user-guide/native-mode.adoc#reflection[Registering classes for reflection].
[[reflection]]
== Registering classes for reflection
@@ -84,7 +84,7 @@ By default, dynamic reflection is not available in native
mode. Classes for whic
registered for reflection at compile time.
In many cases, application developers do not need to care because Quarkus
extensions are able to detect the classes that
-require the reflection and register them automatically.
+require reflection and register them automatically.
However, in some situations, Quarkus extensions may miss some classes and it
is up to the application developer to
register them. There are two ways to do that:
@@ -92,6 +92,26 @@ register them. There are two ways to do that:
1. The
`https://quarkus.io/guides/writing-native-applications-tips#alternative-with-registerforreflection[@io.quarkus.runtime.annotations.RegisterForReflection]`
annotation can be used to register classes on which it is used, or it can also
register third party classes via
its `targets` attribute.
++
+[source,java]
+----
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+@RegisterForReflection
+class MyClassAccessedReflectively {
+}
+
+@RegisterForReflection(
+ targets = {
+ org.third-party.Class1.class,
+ org.third-party.Class2.class
+ }
+)
+class ReflectionRegistrations {
+}
+
+----
+
2. The `quarkus.camel.native.reflection` options in `application.properties`:
+
@@ -117,4 +137,4 @@ quarkus.index-dependency.commons-lang3.artifact-id =
commons-lang3
If serialization support is requested via
`quarkus.camel.native.reflection.serialization-enabled`, the classes listed in
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]
are automatically registered for serialization.
-Users can register more classes using `@RegisterForReflection(serialization =
true)`.
+Users can register more classes using
`@io.quarkus.runtime.annotations.RegisterForReflection(serialization = true)`.
diff --git a/docs/modules/ROOT/pages/user-guide/testing.adoc
b/docs/modules/ROOT/pages/user-guide/testing.adoc
index fea30ad..586d35a 100644
--- a/docs/modules/ROOT/pages/user-guide/testing.adoc
+++ b/docs/modules/ROOT/pages/user-guide/testing.adoc
@@ -5,10 +5,10 @@ Testing offers a good way to ensure camel routes behave as
expected over time.
Before going deeper in the subject, it is strongly advised to read
xref:user-guide/first-steps.adoc[First Steps] and
https://quarkus.io/guides/getting-started-testing[Quarkus testing].
When it comes to testing a route in the context of Quarkus, the paved road is
to write local integration tests.
-This way of doing offers the advantage of running both in JVM and native mode.
+This has the advantage of covering both JVM and native mode.
The flip side is that the standard Camel testing approach with `camel-test`
and `CamelTestSupport` is not supported.
-Let's enumerate below some points of interest.
+Let's enumerate some points of interest below.
== A test running in JVM mode
@@ -38,7 +38,7 @@ An example implementation can be found
https://github.com/apache/camel-quarkus/b
As long as all extensions your application depends on are supported in native
mode,
you should definitely test that your application really works in native mode.
-The test logic defined in JVM mode can then be reused in native mode thanks to
inheriting from the respective JVM mode test.
+The test logic defined in JVM mode can then be reused in native mode thanks to
inheriting from the respective JVM mode class.
`@NativeImageTest` annotation is there to instruct the Quarkus JUnit extension
to compile the application under test to native image
and start it before running the tests.
@@ -71,7 +71,7 @@ On the other hand, there is no point in compiling tests to
native code. So they
An important consequence of this setup is that all communication between tests
and the application
must go over network (HTTP/REST, or any other protocol your application speaks)
-or through watching filesystem (log files, etc.) or any kind of interprocess
communication.
+or through watching filesystem (log files, etc.) or any other kind of
interprocess communication.
== Testing with external services
@@ -147,11 +147,11 @@ Please refer to Camel Quarkus source tree for a
https://github.com/apache/camel-
It is sometimes useful to stub HTTP interactions with third party services &
APIs so that tests do not have to connect to live endpoints, as this can incur
costs and the service may not always be 100% available or reliable.
-An excellent tool for mocking & recording HTTP interactions is
http://wiremock.org/[WireMock]. It is used extensively throughout the Camel
Quarkus test suite for various component extensions. Here follows a typical
workflow
+An excellent tool for mocking & recording HTTP interactions is
http://wiremock.org/[WireMock]. It is used extensively throughout the Camel
Quarkus test suite for various component extensions. Here follows a typical
workflow
for setting up WireMock.
-First set up the WireMock server. Note that it is important to configure the
Camel component under test to pass any HTTP interactions through the WireMock
proxy. This is usually achieved by configuring a component property
-that determines the API endpoint URL. Sometimes things are less
straightforward and some extra work is required to configure the API client
library, as was the case for
https://github.com/apache/camel-quarkus/blob/main/integration-tests/twilio/src/main/java/org/apache/camel/quarkus/component/twilio/it/TwilioResource.java#L83[Twilio].
+First set up the WireMock server. Note that it is important to configure the
Camel component under test to pass any HTTP interactions through the WireMock
proxy. This is usually achieved by configuring a component property
+that determines the API endpoint URL. Sometimes things are less
straightforward and some extra work is required to configure the API client
library, as was the case for
https://github.com/apache/camel-quarkus/blob/main/integration-tests/twilio/src/main/java/org/apache/camel/quarkus/component/twilio/it/TwilioResource.java#L83[Twilio].
[source,java]
----
@@ -187,7 +187,7 @@ public class WireMockTestResource implements
QuarkusTestResourceLifecycleManager
.withHeader("Content-Type", "application/json")
.withBody("{\"message\": \"Hello World\"}")));
- // Ensure the camel component API client passes requests through the
WireMock proxy
+ // Ensure the camel component API client passes requests through the
WireMock proxy
Map<String, String> conf = new HashMap<>();
conf.put("camel.component.foo.server-url", server.baseUrl());
return conf;
@@ -202,7 +202,7 @@ public class WireMockTestResource implements
QuarkusTestResourceLifecycleManager
}
----
-Finally, ensure your test class has the `@QuarkusTestResource` annotation with
the appropriate test resource class specified as the value. The WireMock server
will be started before all tests are
+Finally, ensure your test class has the `@QuarkusTestResource` annotation with
the appropriate test resource class specified as the value. The WireMock server
will be started before all tests are
executed and will be shut down when all tests are finished.
[source,java]
