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
commit 9088ce2f0ef9e731dd08580ec850002be3d719e4
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Thu Aug 12 11:28:18 2021 +0200
Polish and cleanup documentation
---
.../apache/camel/support/RoutePolicySupport.java | 6 +--
.../modules/ROOT/pages/route-builder.adoc | 39 ++++++++++++++++-
.../modules/ROOT/pages/route-configuration.adoc | 4 +-
.../modules/ROOT/pages/route-controller.adoc | 16 +++----
.../modules/ROOT/pages/route-policy.adoc | 50 +++++++++++-----------
5 files changed, 73 insertions(+), 42 deletions(-)
diff --git
a/core/camel-support/src/main/java/org/apache/camel/support/RoutePolicySupport.java
b/core/camel-support/src/main/java/org/apache/camel/support/RoutePolicySupport.java
index c52e905..ea6eff6 100644
---
a/core/camel-support/src/main/java/org/apache/camel/support/RoutePolicySupport.java
+++
b/core/camel-support/src/main/java/org/apache/camel/support/RoutePolicySupport.java
@@ -79,8 +79,7 @@ public abstract class RoutePolicySupport extends
ServiceSupport implements Route
/**
* Starts the consumer.
*
- * @return the returned value is always <tt>true</tt> and should not be
used.
- * @see #resumeOrStartConsumer(Consumer)
+ * @see #resumeOrStartConsumer(Consumer)
*/
public void startConsumer(Consumer consumer) throws Exception {
ServiceHelper.startService(consumer);
@@ -89,8 +88,7 @@ public abstract class RoutePolicySupport extends
ServiceSupport implements Route
/**
* Stops the consumer.
*
- * @return the returned value is always <tt>true</tt> and should not be
used.
- * @see #suspendOrStopConsumer(Consumer)
+ * @see #suspendOrStopConsumer(Consumer)
*/
public void stopConsumer(Consumer consumer) throws Exception {
ServiceHelper.stopService(consumer);
diff --git a/docs/user-manual/modules/ROOT/pages/route-builder.adoc
b/docs/user-manual/modules/ROOT/pages/route-builder.adoc
index 4d488d5..f09d48c 100644
--- a/docs/user-manual/modules/ROOT/pages/route-builder.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-builder.adoc
@@ -2,5 +2,42 @@
= RouteBuilder
The `RouteBuilder` is a base class which is derived from to create routing
rules using the DSL.
-Instances of `RouteBuilder` are then added to the CamelContext.
+Instances of `RouteBuilder` are then added to the `CamelContext`.
+== RouteBuilder example
+
+The following shows an example of a `RouteBuilder`:
+
+[source,java]
+-------------------------------------------------------------------------
+import org.apache.camel.builder.RouteBuilder;
+
+/**
+ * A Camel Java DSL Router
+ */
+public class MyRouteBuilder extends RouteBuilder {
+
+ /**
+ * Let's configure the Camel routing rules using Java code...
+ */
+ public void configure() {
+
+ // here is a sample which processes the input files
+ // (leaving them in place - see the 'noop' flag)
+ // then performs content based routing on the message using XPath
+ from("file:src/data?noop=true")
+ .choice()
+ .when(xpath("/person/city = 'London'"))
+ .to("file:target/messages/uk")
+ .otherwise()
+ .to("file:target/messages/others");
+ }
+
+}
+-------------------------------------------------------------------------
+
+In the `configure` method we can define Camel xref:routes.adoc[Routes].
+
+== More Information
+
+See more in xref:dsl.adoc[DSL], xref:java-dsl.adoc[Java DSL] and
xref:routes.adoc[Routes].
diff --git a/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
b/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
index 3a8c9ed..e72c8c9 100644
--- a/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-configuration.adoc
@@ -285,9 +285,9 @@ And in Camel Main / Quarkus:
camel.main.startup-summary-level = verbose
----
-== See Also
+== More Information
-See the examples:
+See these examples:
-
https://github.com/apache/camel-examples/tree/main/examples/routes-configuration[camel-example-routes-configuration]
-
https://github.com/apache/camel-spring-boot-examples/tree/main/routes-configuration[camel-example-spring-boot-routes-configuration]
diff --git a/docs/user-manual/modules/ROOT/pages/route-controller.adoc
b/docs/user-manual/modules/ROOT/pages/route-controller.adoc
index c04fe98..3aa3447 100644
--- a/docs/user-manual/modules/ROOT/pages/route-controller.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-controller.adoc
@@ -29,8 +29,6 @@ recover from startup issues in the `Consumer` such as failing
to connect to the
The `SupervisingRouteController` is capable of handling this, and manage routes
that has failed to startup, by taking over and attempt to restart these routes.
-=== Example
-
Given the routes below:
[source,java]
@@ -55,8 +53,6 @@ after the camel context startup and takes control of starting
the routes in a sa
This controller is able to retry starting failing routes, and have various
options to configure
settings for backoff between restarting routes.
-=== Example
-
If we take the same example again:
[source,java]
@@ -71,6 +67,8 @@ from("salesforce:cheese")
Then we can tell Camel to use the supervising route controller to let Camel
attempt to
recover starting the salesforce route.
+=== Configuring Supervising Route Controller
+
Enabling and configuring supervising route controller from Java:
[source,java]
@@ -110,7 +108,7 @@ camel.springboot.routeControllerInitialDelay = 1000
camel.springboot.routeControllerThreadPoolSize = 2
----
-And for users with XML DSL in Spring or OSGi Blueprint, you can do as follows:
+And for users with XML DSL you can do as follows:
[source,xml]
----
@@ -129,7 +127,7 @@ And for users with XML DSL in Spring or OSGi Blueprint, you
can do as follows:
</camelContext>
----
-=== Supervising Options
+=== Supervising Route Controller Options
You can configure the `SupervisingRouteController` using the following options:
@@ -158,8 +156,6 @@ them in the background (with backoff).
You may have a critical route which must always startup, and if not, cause
Camel itself to fail starting.
This can be done by filter the route from the supervising with the
include/exclude options.
-=== Example
-
Given the routes below:
[source,java]
@@ -187,7 +183,9 @@ camel.springboot.routeControllerExcludeRoutes = aws*
The route controllers are manageable in JMX, where you can find their MBean
under the `routecontrollers` node.
-== See Also
+NOTE: To use JMX with Camel then `camel-management` JAR must be included in
the classpath.
+
+== More Information
When Camel is shutting down, then its xref:graceful-shutdown.adoc[Graceful
Shutdown]
that handles this to ensure all the routes are shutdown graceful and safely.
diff --git a/docs/user-manual/modules/ROOT/pages/route-policy.adoc
b/docs/user-manual/modules/ROOT/pages/route-policy.adoc
index 4cf663c..17aa72a 100644
--- a/docs/user-manual/modules/ROOT/pages/route-policy.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-policy.adoc
@@ -1,58 +1,56 @@
= RoutePolicy
-*Since Camel 2.1*
-
-A route policy *`org.apache.camel.spi.RoutePolicy`* is used to control
-route(s) at runtime. For example you can use it to determine whether a
-route should be running or not. However the policies can support any
+A route policy `org.apache.camel.spi.RoutePolicy` is used to control
+route(s) at runtime. For example, you can use it to determine whether a
+route should be running or not. However, the policies can support any
kind of use cases.
== How it works
-You associate a route with a given *`RoutePolicy`* and then during
+You associate a route with a given `RoutePolicy` and then during
runtime Camel will invoke callbacks on this policy where you can
implement your custom logic. Camel provides a support class that is a
-good base class to extend *`org.apache.camel.impl.RoutePolicySupport`*.
+good base class to extend `org.apache.camel.support.RoutePolicySupport`.
There are these callbacks invoked:
-* `onInit` *Camel 2.3*
-* `onRemove` *Camel 2.9*
-* `onStart` *Camel 2.9*
-* `onStop` *Camel 2.9*
-* `onSuspend` *Camel 2.9*
-* `onResume` *Camel 2.9*
+* `onInit`
+* `onRemove`
+* `onStart`
+* `onStop`
+* `onSuspend`
+* `onResume`
* `onExchangeBegin`
* `onExchangeDone`
-See the Javadoc of the *`org.apache.camel.spi.RoutePolicy`* for more
-details. And also the implementation of the
-*`org.apache.camel.impl.ThrottlingInflightRoutePolicy`* for a concrete
+See the Javadoc of the `org.apache.camel.spi.RoutePolicy` for more
+details; and also the implementation of the
+`org.apache.camel.throttling.ThrottlingInflightRoutePolicy` for a concrete
example.
Camel provides the following policies out of the box:
-* *`org.apache.camel.impl.ThrottlingInflightRoutePolicy`* - a throttling
+* `org.apache.camel.throttling.ThrottlingInflightRoutePolicy` - a throttling
based policy that automatic suspends/resumes route(s) based on metrics
from the current in flight exchanges. You can use this to dynamically
throttle e.g. a xref:components::jms-component.adoc[JMS] consumer, to avoid it
consuming too
fast.
-As of *Camel 2.5*, Camel also provides an ability to schedule routes to
+* `org.apache.camel.throttling.ThrottlingExceptionRoutePolicy` - a throttling
+based policy modeled after the circuit breaker. This policy will stop consuming
+from an endpoint based on the type of exceptions that are thrown and the
threshold setting.
+
+Camel also provides an ability to schedule routes to
be activated, deactivated, suspended and/or resumed at certain times
during the day using a
xref:scheduledroutepolicy.adoc[ScheduledRoutePolicy] (offered via the
-http://camel.apache.org/quartz.html[camel-quartz] component).
+xref:components::quartz-component.adoc[Quartz] component).
== SuspendableService
-If you want to dynamic suspend/resume routes as the
-*`org.apache.camel.impl.ThrottlingRoutePolicy`* does then its advised to
-use *`org.apache.camel.SuspendableService`* as it allows for fine
-grained *`suspend`* and *`resume`* operations. And use the
-*`org.apache.camel.util.ServiceHelper`* to aid when invoking these
-operations as it support fallback for regular
-*`org.apache.camel.Service`* instances.
+If you want to dynamic suspend/resume routes as the then it is advised to
+use `SuspendableService` as it allows for fine-grained
+suspend and resume operations.
== `ThrottlingInflightRoutePolicy`
