This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 87ad2def611 (chores) documentation: updates to the Exchange guides
(#9357)
87ad2def611 is described below
commit 87ad2def6113170e11d6504ef8e487576351206b
Author: Otavio Rodolfo Piske <orpi...@users.noreply.github.com>
AuthorDate: Thu Feb 16 07:00:07 2023 +0100
(chores) documentation: updates to the Exchange guides (#9357)
* (chores) docs: updated the using exchange patterns annotations guide
* (chores) doc: reorganize the Exchange documentation
---
.../working-with-camel-core/pages/index.adoc | 13 +++--
docs/user-manual/modules/ROOT/pages/exchange.adoc | 5 ++
.../pages/using-exchange-pattern-annotations.adoc | 61 +++++++++++-----------
3 files changed, 43 insertions(+), 36 deletions(-)
diff --git a/docs/main/modules/working-with-camel-core/pages/index.adoc
b/docs/main/modules/working-with-camel-core/pages/index.adoc
index fd618961ec9..1db9c0271b7 100644
--- a/docs/main/modules/working-with-camel-core/pages/index.adoc
+++ b/docs/main/modules/working-with-camel-core/pages/index.adoc
@@ -57,15 +57,18 @@ The following guides can help you discover ways to
manipulate the data:
* Data Transformation
** xref:manual::data-format.adoc[Data Format]
-== Other Guides
+== Exchanges
-Learn about additional ways to customize your integrations. Explore
alternatives to consume and produce data as well as writing and defining routes.
+The exchange is a core concept of Apache Camel and is used to abstract
different patterns of communication within Camel. Read the following guides to
have a better understanding of it:
* Exchange
** xref:manual::exchange.adoc[Exchange]
-** xref:manual::exchange-pattern.adoc[Exchange Pattern]
-** xref:manual::exchange-pooling.adoc[Exchange Pooling]
-** xref:manual::using-exchange-pattern-annotations.adoc[Using Exchange Pattern
Annotations]
+
+== Other Guides
+
+Learn about additional ways to customize your integrations. Explore
alternatives to consume and produce data as well as writing and defining routes.
+
+
* Context
** xref:manual::camelcontext.adoc[Camel Context]
** xref:manual::camelcontext-autoconfigure.adoc[Camel Context Auto
Configuration]
diff --git a/docs/user-manual/modules/ROOT/pages/exchange.adoc
b/docs/user-manual/modules/ROOT/pages/exchange.adoc
index 02aed3d9b77..1aef955811c 100644
--- a/docs/user-manual/modules/ROOT/pages/exchange.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exchange.adoc
@@ -8,6 +8,11 @@ Thanks to this, Apache Camel can support different integration
patterns such as:
* xref:components:eips:event-message.adoc[Event Messages]: messages that have
only an inbound message
* xref:components:eips:requestReply-eip.adoc[Request and Reply]: messages that
have an inbound and an outbound message.
+== Learn More About Exchanges
+
+* xref:manual::exchange-pooling.adoc[Exchange Pooling]
+* xref:manual::using-exchange-pattern-annotations.adoc[Using Exchange Pattern
Annotations]
+
== Implementation Details
There are concrete classes that implement the `Exchange` interface for each
Camel-supported communications technology. For example, the `JmsExchange` class
provides a JMS-specific implementation of the `Exchange` interface. The public
API of the `Exchange` interface is limited intentionally: we expect that each
class that implements this interface will provide its own technology-specific
operations.
diff --git
a/docs/user-manual/modules/ROOT/pages/using-exchange-pattern-annotations.adoc
b/docs/user-manual/modules/ROOT/pages/using-exchange-pattern-annotations.adoc
index 3336572cbe3..b86fc5f5623 100644
---
a/docs/user-manual/modules/ROOT/pages/using-exchange-pattern-annotations.adoc
+++
b/docs/user-manual/modules/ROOT/pages/using-exchange-pattern-annotations.adoc
@@ -1,25 +1,27 @@
= Using Exchange Pattern Annotations
-When working with xref:pojo-producing.adoc[POJO Producing] you invoke methods
which
-typically by default are InOut for
xref:components:eips:requestReply-eip.adoc[Request
-Reply]. That is there is an In message and an Out for the result.
-Typically invoking this operation will be synchronous, the caller will
-block until the server returns a result.
+Invoking InOut methods for
ref:components:eips:requestReply-eip.adoc[request/reply] when working with
xref:pojo-producing.adoc[POJO Producing] is typically synchronous. As such, the
caller will block until the server returns a result.
-Camel has flexible xref:exchange-pattern.adoc[Exchange Pattern] support
-- so you can also support the xref:components:eips:event-message.adoc[Event
Message]
-pattern to use InOnly for asynchronous or one way operations. These are
-often called 'fire and forget' like sending a JMS message but not
-waiting for any response.
+[NOTE]
+====
+InOut means that there is an In message for the input and an Out for the
output/result.
+====
-From 1.5 onwards Camel supports annotations for specifying the message
-exchange pattern on regular Java methods, classes or interfaces.
+[NOTE]
+====
+Other books, posts and reference guides may use the terms In/Out and In/Only
for the patterns. In this guide we use InOut and InOnly respectively, as these
are the names used within Camel.
+====
+
+You can also implement support for
xref:components:eips:event-message.adoc[Event Messages] with Apache Camel,
using the InOnly xref:exchange-pattern.adoc[pattern]. These are often called
"fire and forget" (i.e., like sending a JMS message but not waiting for any
response).
+
+Since version 1.5 Camel supports annotations for specifying the message
+exchange pattern on Java methods, classes or interfaces.
[[UsingExchangePatternAnnotations-SpecifyingInOnlymethods]]
== Specifying InOnly methods
-Typically the default InOut is what most folks want but you can
-customize to use InOnly using an annotation.
+Typically the InOut pattern is what most users want, but you can
+customize to use InOnly using an annotation. For instance:
[source,syntaxhighlighter-pre]
----
@@ -32,15 +34,15 @@ public interface Foo {
}
----
-The above code shows three methods on an interface; the first two use
-the default InOut mechanism but the *someInOnlyMethod* uses the InOnly
-annotation to specify it as being a oneway method call.
+The above code shows three methods on an interface:
+* the first two use the default InOut mechanism
+* the third one, `someInOnlyMethod` uses the InOnly annotation to specify it
as being a one-way method call.
[[UsingExchangePatternAnnotations-Classlevelannotations]]
== Class level annotations
You can also use class level annotations to default all methods in an
-interface to some pattern such as
+interface to a pattern:
[source,syntaxhighlighter-pre]
----
@@ -51,8 +53,7 @@ public interface Foo {
}
----
-Annotations will also be detected on base classes or interfaces. So for
-example if you created a client side proxy for
+Apache Camel will detect annotations on base classes or interfaces. For
instance, suppose you created a client side proxy for the following code:
[source,syntaxhighlighter-pre]
----
@@ -61,14 +62,13 @@ public class MyFoo implements Foo {
}
----
-Then the methods inherited from Foo would be InOnly.
+In this case, the methods inherited from Foo would be InOnly.
[[UsingExchangePatternAnnotations-Overloadingaclasslevelannotation]]
== Overloading a class level annotation
-You can overload a class level annotation on specific methods. A common
-use case for this is if you have a class or interface with many InOnly
-methods but you want to just annote one or two methods as InOut
+
+You can overload a class level annotation on specific methods. Suppose you
have a class or interface with many InOnly methods, but you want to annote just
one or two methods as InOut. You can do it like this:
[source,syntaxhighlighter-pre]
----
@@ -82,7 +82,7 @@ public interface Foo {
}
----
-In the above Foo interface the *someInOutMethod* will be InOut
+In the above `Foo` interface the only the `someInOutMethod` will be InOut.
[[UsingExchangePatternAnnotations-Usingyourownannotations]]
== Using your own annotations
@@ -91,11 +91,10 @@ You might want to create your own annotations to represent
a group of
different bits of metadata; such as combining synchrony, concurrency and
transaction behaviour.
-So you could annotate your annotation with the @Pattern annotation to
-default the exchange pattern you wish to use.
+In this case you can annotate your annotation with the `@Pattern` annotation
to the default exchange pattern you wish to use.
-For example lets say we want to create our own annotation called
-@MyAsyncService
+For example, lets say we want to create our own annotation called
+`@MyAsyncService`:
[source,syntaxhighlighter-pre]
----
@@ -111,8 +110,8 @@ public @interface MyAsyncService {
}
----
-Now we can use this annotation and Camel will figure out the correct
-exchange pattern...
+Now we can use this annotation, and Camel will figure out the correct
+exchange pattern.
[source,syntaxhighlighter-pre]
----
