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 f493999 Polish and cleanup documentation
f493999 is described below
commit f493999c04b319f5fa4037cd31083afb29a8379f
Author: Claus Ibsen <[email protected]>
AuthorDate: Tue Aug 10 15:12:31 2021 +0200
Polish and cleanup documentation
---
docs/user-manual/modules/ROOT/pages/examples.adoc | 10 +-
.../modules/ROOT/pages/exception-clause.adoc | 134 +++++++--------------
.../modules/ROOT/pages/exchange-pattern.adoc | 21 ++--
docs/user-manual/modules/ROOT/pages/exchange.adoc | 14 +--
4 files changed, 64 insertions(+), 115 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/examples.adoc
b/docs/user-manual/modules/ROOT/pages/examples.adoc
index 150182e..70e1736 100644
--- a/docs/user-manual/modules/ROOT/pages/examples.adoc
+++ b/docs/user-manual/modules/ROOT/pages/examples.adoc
@@ -4,8 +4,6 @@ Once you have read about xref:getting-started.adoc[Getting
Started] and
looked at the
xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise
Integration Patterns], you might want to try out some examples.
-The xref:running-examples.adoc[Running Examples] describes
-how to get the examples to run
== Walk-throughs
@@ -13,7 +11,7 @@ how to get the examples to run
xref:walk-through-an-example.adoc[beginner's example] so you can
understand how things fit together using the Java xref:dsl.adoc[DSL] to
set up some routes in a simple `main(...)` method.
-* Walk through the xref:walk-through-another-example.adoc[Spring DSL
+* Walk through the xref:walk-through-another-example.adoc[Spring XML DSL
example] to look at XML-based routing.
[NOTE]
@@ -31,9 +29,7 @@ the words "Apache Camel".
== Examples
-Browse the examples from github where each example is documented and up
-to date:
-
-https://github.com/apache/camel-examples/tree/master/examples#welcome-to-the-apache-camel-examples
+Browse the
https://github.com/apache/camel-examples/tree/master/examples#welcome-to-the-apache-camel-examples[camel-examples]
+from github where each example is documented with instructions how to run, and
are up-to-date.
diff --git a/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
b/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
index 222c6ba..3b66e0d 100644
--- a/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exception-clause.adoc
@@ -43,7 +43,6 @@ from("seda:order")
.to("bean:processOrder");
----
-[[ExceptionClause-Scopes]]
== Scopes
Exception clauses is scoped as either:
@@ -63,7 +62,6 @@ its *`configure`* method. And then extend this class, and
make sure to
class *`super.configure()`*. We are just using the Java inheritance
technique.
-[[ExceptionClause-HowDoesCamelSelectWhichClauseShouldHandleaGivenThrownException]]
== How Does Camel Select Which Clause Should Handle a Given Thrown Exception?
Camel uses *`DefaultExceptionPolicyStrategy`* to determine a strategy
@@ -156,7 +154,6 @@ exception in the *`onException`* clause. Illustrated as:
Since *`SocketException`* is an *`instanceof IOException`*, Camel will
select the *`onException(IOException.class)`* clause.
-[[ExceptionClause-ConfiguringRedeliveryPolicyredeliveroptions]]
== Configuring RedeliveryPolicy (redeliver options)
https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/errorhandler/RedeliveryPolicy.html[RedeliveryPolicy]
@@ -192,7 +189,7 @@ onException(ValidationException.class)
.maximumRedeliveries(2);
----
-*Spring XML DSL*:
+*XML DSL*:
[source,xml]
----
@@ -214,7 +211,6 @@ so we can for instance set a different delay of *`5000`*
millis:
</onException>
----
-[[ExceptionClause-PointofEntryforRedeliveryAttempts]]
== Point of Entry for Redelivery Attempts
All redelivery attempts start at the point of the failure. So the route:
@@ -230,7 +226,6 @@ onException(ConnectException.class)
Will retry from *`processor2`* - not the complete route.
-[[ExceptionClause-ReusingRedeliveryPolicy]]
== Reusing RedeliveryPolicy
You can reference a *`RedeliveryPolicy`* so you can reuse existing
@@ -251,10 +246,9 @@ supports property placeholders.
</onException>
----
-[[ExceptionClause-AsynchronousDelayedRedelivery]]
== Asynchronous Delayed Redelivery
-From *Camel 2.4*: Camel has a feature to *not block* while waiting for a
+Camel has a feature to _not block_ while waiting for a
delayed redelivery to occur. However if you use transacted routes then
Camel will block as its mandated by the transaction manager to execute
all the work in the same thread context. You can enable the non blocking
@@ -263,13 +257,12 @@ option can be set on the *`errorHandler`*,
*`onException`* or the
redelivery policies.
By default the error handler will create and use a scheduled thread pool
-to trigger redelivery in the future. From *Camel 2.8*: you can configure
+to trigger redelivery in the future. You can also configure
the *`executorServiceRef`* on the xref:error-handler.adoc[Error Handler]
to indicate a reference to either a shared thread pool you can enlist in
the registry, or a thread pool profile in case you want to be able to
control pool settings.
-[[ExceptionClause-CatchingMultipleExceptions]]
== Catching Multiple Exceptions
Multiple exception can be caught as shown:
@@ -293,18 +286,19 @@ And in XML DSL you just add another exception element:
</onException>
----
-[[ExceptionClause-UsingaProcessorasaFailureHandler]]
== Using a Processor as a Failure Handler
-We want to handle certain exceptions specially so we add
-a *`onException`* clause for that exception.
+We want to handle certain exceptions in a specific way, so we add
+a *`onException`* clause for the particular exception.
[source,java]
----
// here we register exception cause for MyFunctionException
// when this exception occur we want it to be processed by our
// processor
-onException(MyFunctionalException.class).process(new
MyFunctionFailureHandler()).stop();
+onException(MyFunctionalException.class)
+ .process(new MyFunctionFailureHandler())
+ .stop();
----
@@ -329,15 +323,8 @@ of the route. So lets look the code for our processor.
Throwable caused = exchange.getProperty(Exchange.EXCEPTION_CAUGHT,
Throwable.class);
assertNotNull(caused);
// here you can do what you want, but Camel regard this exception
as
- // handled, and
- // this processor as a failurehandler, so it wont do redeliveries.
- // So this is the
- // end of this route. But if we want to route it somewhere we can
- // just get a
- // producer template and send it.
-
- // send it to our mock endpoint
-
exchange.getContext().createProducerTemplate().send("mock:myerror", exchange);
+ // handled, and this processor as a failurehandler, so it wont do
redeliveries.
+ // So this is the end of this route.
}
}
----
@@ -345,10 +332,8 @@ of the route. So lets look the code for our processor.
Notice how we get the *caused by* exception using a property on the Exchange.
This is where Camel stores any caught exception during processing. So
you can fetch this property and check what the exception message and do
-what you want. In the code above we just route it to a mock endpoint
-using a producer template from Exchange.
+what you want.
-[[ExceptionClause-MarkingExceptionsasHandled]]
== Marking Exceptions as Handled
See also the section xref:exception-clause.adoc[Handle and continue
exceptions] below.
@@ -377,7 +362,6 @@ onException(ValidationException)
.handled(true);
----
-[[ExceptionClause-ExampleUsingHandled]]
== Example Using Handled
In this route below we want to do special handling of
@@ -427,12 +411,6 @@ being tied to the Camel API:
/**
* This method handle our order input and return the order
- *
- * @param headers the in headers
- * @param payload the in payload
- * @return the out payload
- * @throws OrderFailedException is thrown if the order cannot be
- * processed
*/
public Object handleOrder(@Headers Map headers, @Body String payload)
throws OrderFailedException {
headers.put("customerid", headers.get("customerid"));
@@ -447,10 +425,6 @@ being tied to the Camel API:
/**
* This method creates the response to the caller if the order could
not
* be processed
- *
- * @param headers the in headers
- * @param payload the in payload
- * @return the out payload
*/
public Object orderFailed(@Headers Map headers, @Body String payload) {
headers.put("customerid", headers.get("customerid"));
@@ -464,9 +438,6 @@ And finally the exception that is being thrown is just a
regular exception:
[source,java]
----
- /**
- * Exception thrown if the order cannot be processed
- */
public static class OrderFailedException extends Exception {
private static final long serialVersionUID = 1L;
@@ -492,10 +463,9 @@ fabricated in the *`orderFailed`* method in our
*`OrderService`*. So the
caller receives an Exchange with the payload *`Order ERROR`* and a
*`orderid=failed`* in a header.
-[[ExceptionClause-UsingHandledwithSpringDSL]]
-== Using Handled with Spring DSL
+== Using Handled with Spring XML DSL
-The same route as above in Spring DSL:
+The same route as above in Spring XML DSL:
[source,xml]
----
@@ -539,7 +509,6 @@ The same route as above in Spring DSL:
</camelContext>
----
-[[ExceptionClause-HandlingandSendingaFixedResponseBacktotheClient]]
== Handling and Sending a Fixed Response Back to the Client
In the route above we handled the exception but routed it to a different
@@ -555,7 +524,9 @@ the sample below:
// (= no failure returned to client)
// but we want to return a fixed text response, so we transform
// OUT body as Sorry.
-onException(MyFunctionalException.class).handled(true).transform().constant("Sorry");
+onException(MyFunctionalException.class)
+ .handled(true)
+ .transform().constant("Sorry");
----
We modify the sample slightly to return the original caused exception
@@ -567,7 +538,9 @@ message instead of the fixed text `Sorry`:
// (= no failure returned to client)
// but we want to return a fixed text response, so we transform
// OUT body and return the exception message
-onException(MyFunctionalException.class).handled(true).transform(exceptionMessage());
+onException(MyFunctionalException.class)
+ .handled(true)
+ .transform(exceptionMessage());
----
And we can use the xref:components:languages:simple-language.adoc[Simple]
language to set a readable error
@@ -581,15 +554,14 @@ message with the caused exception message:
// OUT body and return a nice message
// using the simple language where we want insert the exception
// message
-onException(MyFunctionalException.class).handled(true).transform().simple("Error
reported: ${exception.message} - cannot process this message.");
+onException(MyFunctionalException.class)
+ .handled(true)
+ .transform().simple("Error reported: ${exception.message} - cannot process
this message.");
----
-[[ExceptionClause-HandleandContinueExceptions]]
== Handle and Continue Exceptions
-*Since Camel 2.3*
-
-In Camel 2.3 we introduced a new option `continued` which allows you to
+The option `continued` allows you to
both *`handle`* and *`continue`* routing in the original route as if the
exception did not occur.
@@ -608,8 +580,7 @@ makes it easier in Camel as you otherwise had to use
xref:try-catch-finally.adoc[Try Catch Finally] style for this kind of
use case.
-[[ExceptionClause-ExampleUsingcontinued]]
-== Example Using continued
+=== Example Using continued
In this route below we want to do special handling of
all *`IllegalArgumentException`* as we just want to continue routing.
@@ -618,10 +589,13 @@ all *`IllegalArgumentException`* as we just want to
continue routing.
----
onException(IllegalArgumentException.class).continued(true);
-from("direct:start").to("mock:start").throwException(new
IllegalArgumentException("Forced")).to("mock:result");
+from("direct:start")
+ .to("mock:start")
+ .throwException(new IllegalArgumentException("Forced"))
+ .to("mock:result");
----
-And the same example in Spring XML:
+And the same example in Spring XML DSL:
[source,xml]
----
@@ -643,7 +617,6 @@ And the same example in Spring XML:
</camelContext>
----
-[[ExceptionClause-WhatistheDifferenceBetweenHandledandContinued]]
== What is the Difference Between Handled and Continued?
If handled is true, then the thrown exception will be _handled_ and
@@ -658,7 +631,7 @@ just ignore it and continue routing in the original route.
However if
you have a route configured in the *`onException`* it will route that
route first, before it will continue routing in the original route.
-[[ExceptionClause-UsinguseOriginalMessage]]
+
== Using `useOriginalMessage`
The option *`useOriginalMessage`* is used for routing the original input
@@ -699,7 +672,6 @@ original input. If we want to manually retry we can move
the JMS message
from the failed to the input queue, with no problem as the message is
the same as the original we received.
-[[ExceptionClause-useOriginalMessagewithSpringDSL]]
== `useOriginalMessage` with Spring DSL
The *`useOriginalMessage`* option is defined as a boolean attribute on
@@ -750,14 +722,12 @@ from("jms:queue:order:input")
Then the message has been enriched with a header named application after the
original message was received by the JMS endpoint. And in case of an error
`onException`
will handle the exception and use the original message body and the headers
from the current message as-is, which means the headers will include the
application header.
-[[ExceptionClause-AdvancedUsageofExceptionClause]]
-== Advanced Usage of xref:exception-clause.adoc[Exception Clause]
-
-[[ExceptionClause-UsingGlobalandPerRouteExceptionClauses]]
-== Using Global and Per Route Exception Clauses
+== Advanced Usage of Exception Clause
Camel supports advanced configuration of exception clauses.
+=== Using Global and Per Route Exception Clauses
+
You can define exception clauses either as:
* global
@@ -892,7 +862,6 @@ they also applies for nested error handlers. So if a
*`MyTechnicalException`* is thrown then it's the global exception policy
that is selected.
-[[ExceptionClause-UsingFineGrainedSelectionUsingonWhenPredicate]]
== Using Fine Grained Selection Using `onWhen` Predicate
You can attach an xref:expression.adoc[Expression] to the exception
@@ -933,8 +902,7 @@ This is not required, if the second clause is omitted, then
the
default error handler will kick in.
====
-[[ExceptionClause-UsingonRedeliveryProcessor]]
-== Using `onRedelivery` Processor
+== Using onRedelivery Processor
xref:{eip-vc}:eips:dead-letter-channel.adoc[Dead Letter Channel] has support
for *`onRedelivery`* to allow custom processing of a Message before its
@@ -987,8 +955,7 @@ public static class MyRedeliverProcessor implements
Processor {
}
----
-[[ExceptionClause-UsingonRedeliveryinSpringDSL]]
-== Using `onRedelivery` in Spring DSL
+== Using onRedelivery in Spring XML DSL
In Spring DSL you need to use the *`onRedeliveryRef`* attribute to refer
to a spring bean id that is your custom processor:
@@ -1009,10 +976,7 @@ class as this code is based on unit testing):
class="org.apache.camel.processor.DeadLetterChannelOnExceptionOnRedeliveryTest$MyRedeliverProcessor"/>
----
-[[ExceptionClause-UsingonExceptionOccurredProcessor]]
-== Using `onExceptionOccurred` Processor
-
-*Since Camel 2.17*
+== Using onExceptionOccurred Processor
xref:{eip-vc}:eips:dead-letter-channel.adoc[Dead Letter Channel] has support
for *`onExceptionOccurred`* to allow custom processing of a Message just
@@ -1046,8 +1010,7 @@ errorHandler(defaultErrorHandler()
.onExceptionOccurred(myProcessor));
----
-[[ExceptionClause-UsingonRedeliveryinSpringDSL.1]]
-=== Using `onRedelivery` in Spring DSL
+=== Using onRedelivery in Spring XML DSL
In Spring DSL you need to use the *`onExceptionOccurredRef`* attribute
to refer to a spring bean id that is your custom processor:
@@ -1064,14 +1027,7 @@ to refer to a spring bean id that is your custom
processor:
</camelContext>
----
-[[ExceptionClause-UsingFineGrainedRetryUsingretryWhilePredicate]]
-== Using Fine Grained Retry Using `retryWhile` Predicate
-
-=== RetryUntil
-
-In Camel 2.0 to 2.3 its called *`retryUntil`*. From *Camel 2.4*: its
-named *`retryWhile`* because Camel will continue doing retries _while_
-the predicate returns true.
+== Using Fine Grained Retry Using retryWhile Predicate
When you need fine grained control for determining if an exchange should
be retried or not you can use the *`retryWhile`* predicate. Camel will
@@ -1111,13 +1067,11 @@ public class MyRetryBean {
}
----
-[[ExceptionClause-UsingCustomExceptionPolicyStrategy]]
-== Using Custom `ExceptionPolicyStrategy`
+== Using Custom ExceptionPolicyStrategy
The default
https://www.javadoc.io/doc/org.apache.camel/camel-base/current/org/apache/camel/processor/errorhandler/ExceptionPolicyStrategy.html[ExceptionPolicyStrategy]
-in Camel should be sufficient in nearly all use-cases (see section
-xref:exception-clause.adoc#ExceptionClause-HowDoesCamelSelectWhichClauseShouldHandleaGivenThrownException[How
does Camel select which clause should handle a given thrown Exception]).
+in Camel should be sufficient in nearly all use-cases.
However, if you need to use your own (use only for rare and advanced
use-cases) this can be configured as the
sample below illustrates:
@@ -1138,19 +1092,17 @@ public static class MyPolicy implements
ExceptionPolicyStrategy {
@Override
public ExceptionPolicyKey getExceptionPolicy(Set<ExceptionPolicyKey>
exceptionPolicices, Exchange exchange, Throwable exception) {
- // This is just an example that always forces the exception type
- // configured
+ // This is just an example that always forces the exception type
configured
// with MyPolicyException to win.
return new ExceptionPolicyKey(null, MyPolicyException.class, null);
}
}
----
-[[ExceptionClause-UsingtheExceptionClauseinSpringDSL]]
-== Using the Exception Clause in Spring DSL
+== Using the Exception Clause in Spring XML DSL
You can use all of the above mentioned exception clause features in the
-Spring DSL as well. Here are a few examples:
+Spring XML DSL as well. Here are a few examples:
* Global scoped
diff --git a/docs/user-manual/modules/ROOT/pages/exchange-pattern.adoc
b/docs/user-manual/modules/ROOT/pages/exchange-pattern.adoc
index c339581..d5828fd 100644
--- a/docs/user-manual/modules/ROOT/pages/exchange-pattern.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exchange-pattern.adoc
@@ -2,25 +2,26 @@
= Exchange Pattern
There are many different _Message Exchange Patterns_ you can use in
-messaging. This concept is also demonstrated in WSDL and JBI's MEPs.
+messaging.
From there xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise
-Integration Patterns] the common examples are
+Integration Patterns] the common examples are:
+* Event Message (or one-way)
* Request Reply
-* Event Message (or one way)
In Camel we have an
`org.apache.camel.ExchangePattern`
enumeration which can be configured on the *exchangePattern* property on
the Message Exchange indicating if a message
-exchange is a one way Event Message (InOnly) or
-a Request Reply message exchange (InOut).
+exchange is a one way Event Message (*InOnly*) or
+a Request Reply message exchange (*InOut*).
For example to override the default pattern on a
xref:components::jms-component.adoc[JMS]
-endpoint you could use this URI
+endpoint you could use the `exchangePattern` parameter in the Endpoint
xref:uris.adoc[URI]
+as shown:
-[source,java]
----------------------------------
-jms:MyQueue?exchangePattern=InOut
----------------------------------
+[source,text]
+----
+jms:myQueue?exchangePattern=InOut
+----
diff --git a/docs/user-manual/modules/ROOT/pages/exchange.adoc
b/docs/user-manual/modules/ROOT/pages/exchange.adoc
index d722374..31804d4 100644
--- a/docs/user-manual/modules/ROOT/pages/exchange.adoc
+++ b/docs/user-manual/modules/ROOT/pages/exchange.adoc
@@ -2,11 +2,11 @@
= Message Exchange
To support various message exchange patterns
-like one way Event Message and
-Request Reply messages Camel uses an Exchange
-interface which has a *pattern* property which can be set to *InOnly*
-for an Event Message which has a single inbound
-Message, or *InOut* for a
-Request Reply where there is an inbound and
-outbound Message.
+like one way xref:{eip-vc}:eips:event-message.adoc[Event Message] and
+xref:{eip-vc}:eips:requestReply-eip.adoc[Request Reply] messages Camel
+uses an `Exchange` interface which has a xref:exchange-pattern.adoc[Exchange
Pattern]
+property which can be set to *InOnly* for an
+xref:{eip-vc}:eips:event-message.adoc[Event Message] which has a single
inbound Message,
+or *InOut* for a xref:{eip-vc}:eips:requestReply-eip.adoc[Request Reply]
+where there is an inbound and outbound Message.
