You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2021/08/12 09:39:16 UTC
[camel] branch main updated (9484f37 -> 2b6e947)
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git.
from 9484f37 Small BlobOperationResponse refactor in camel-azure-storage-blob component
new 9088ce2 Polish and cleanup documentation
new 2b6e947 Polish and cleanup documentation
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../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 | 165 +++++++++------------
5 files changed, 123 insertions(+), 107 deletions(-)
[camel] 01/02: Polish and cleanup documentation
Posted by da...@apache.org.
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 <cl...@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`
[camel] 02/02: Polish and cleanup documentation
Posted by da...@apache.org.
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 2b6e947bc54228c1fae3cb9d5a3b9cfb95e28855
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Thu Aug 12 11:38:36 2021 +0200
Polish and cleanup documentation
---
.../modules/ROOT/pages/route-policy.adoc | 115 +++++++++------------
1 file changed, 50 insertions(+), 65 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/route-policy.adoc b/docs/user-manual/modules/ROOT/pages/route-policy.adoc
index 17aa72a..3ae225d 100644
--- a/docs/user-manual/modules/ROOT/pages/route-policy.adoc
+++ b/docs/user-manual/modules/ROOT/pages/route-policy.adoc
@@ -66,7 +66,7 @@ The throttling inflight route policy has the following options:
|Option |Default |Description
-|`scope` |`Route` |A scope for either *`Route`* or *`Context`* which defines if the current
+|`scope` |`Route` |A scope for either `Route` or `Context` which defines if the current
number of inflight exchanges is context based or for that particular
route.
@@ -74,7 +74,7 @@ route.
route if the current number of inflight exchanges is higher than this
value.
-|`resumePercentOfMax` |`70` |A percentage *`0..100`* which defines when the throttling should resume
+|`resumePercentOfMax` |`70` |A percentage `0..100` which defines when the throttling should resume
again in case it has been suspended.
|`loggingLevel` |`INFO` |The logging level used for logging the throttling activity.
@@ -82,38 +82,40 @@ again in case it has been suspended.
|`logger` |`ThrottlingInflightRoutePolicy` |The logger category.
|===
-== ThrottlingInflightRoutePolicy compared to the Throttler EIP
+=== ThrottlingInflightRoutePolicy compared to the Throttler EIP
-The *`ThrottlingInflightRoutePolicy`* compared to
-xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] is that it does *not* block during
+The `ThrottlingInflightRoutePolicy` compared to
+xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] EIP is that it does *not* block during
throttling. It does throttling that is approximate based, meaning that
its more coarse grained and not explicit precise as the
-xref:{eip-vc}:eips:throttle-eip.adoc[Throttler]. The xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] can
+xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] EIP.
+
+The xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] EIP can
be much more accurate and only allow a specific number of messages being
-passed per a given time unit. Also the *`ThrottlingInflightRoutePolicy`*
+passed per a given time unit. Also the `ThrottlingInflightRoutePolicy`
is based its metrics on number of inflight exchanges where as
-xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] is based on number of messages per time
-unit.
+xref:{eip-vc}:eips:throttle-eip.adoc[Throttler] EIP is based on number o
+messages per time unit.
-== `ScheduledRoutePolicy` (Simple and Cron based) using camel Quartz
+== ScheduledRoutePolicy
-For more details check out the following links
+See xref:scheduledroutepolicy.adoc[Scheduled Route Policy] for scheduling based route policy.
-== Configuring Policy
+== Using route policies in Camel routes
You configure the route policy as follows from Java DSL, using the
-*`routePolicy`* method:
+`routePolicy` method:
[source,java]
-----------------------------------------------------------
RoutePolicy myPolicy = new MyRoutePolicy();
+
from("seda:foo").routePolicy(myPolicy).to("mock:result");
-----------------------------------------------------------
-In Spring XML its a bit different as follows using the
-*`routePolicyRef`* attribute:
+In Spring XML you configure using the `routePolictRef` attribute on `<route>` as shown:
-[source,java]
+[source,xml]
---------------------------------------------------------
<bean id="myPolicy" class="com.mycompany.MyRoutePolicy"/>
@@ -123,77 +125,60 @@ In Spring XML its a bit different as follows using the
</route>
---------------------------------------------------------
-== Configuring Policy Sets
+You can configure one or more route policies (separated by comma), such as:
-*`RoutePolicy`* has been further improved to allow addition of policy
-sets or a collection of policies that are concurrently applied on a
-route. The addition of policies is done as follows.
+[source,java]
+----
+from("seda:foo").routePolicy(myPolicy, myOtherPolicy).to("mock:result");
+----
-In the example below, the route *`testRoute`* has a *`startPolicy`*
-and *`throttlePolicy`* applied concurrently. Both policies are applied
-as necessary on the route.
+And in XML:
[source,xml]
-----------------------------------------------------------------------------------------------
-<bean id="date" class="org.apache.camel.routepolicy.quartz.SimpleDate"/>
-
-<bean id="startPolicy" class="org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy">
- <property name="routeStartDate" ref="date"/>
- <property name="routeStartRepeatCount" value="1"/>
- <property name="routeStartRepeatInterval" value="3000"/>
-</bean>
-
-<bean id="throttlePolicy" class="org.apache.camel.impl.ThrottlingInflightRoutePolicy">
- <property name="maxInflightExchanges" value="10"/>
-</bean>
-
-<camelContext id="testRouteContext" xmlns="http://camel.apache.org/schema/spring">
- <route id="testRoute" autoStartup="false" routePolicyRef="startPolicy, throttlePolicy">
- <from uri="seda:foo?concurrentConsumers=20"/>
+---------------------------------------------------------
+<route routePolicyRef="myPolicy,myOtherPolicy">
+ <from uri="seda:foo"/>
<to uri="mock:result"/>
- </route>
-</camelContext>
-----------------------------------------------------------------------------------------------
+</route>
+---------------------------------------------------------
-== Using `RoutePolicyFactory`
+== Using RoutePolicyFactory
If you want to use a route policy for every route, you can use
-a *`org.apache.camel.spi.RoutePolicyFactory`* as a factory for creating
-a *`RoutePolicy`* instance for each route. This can be used when you
-want to use the same kind of route policy for every routes. Then you
-need to only configure the factory once, and every route created will
+a `org.apache.camel.spi.RoutePolicyFactory` as a factory for creating
+a `RoutePolicy` instance for each route. This can be used when you
+want to use the same kind of route policy for all or some routes.
+
+With the factory you only need to configure this once, and every route created will
have the policy assigned.
-There is API on CamelContext to add a factory, as shown below
+There is API on `CamelContext` to add a factory, as shown below
[source,java]
----------------------------------------------------------
context.addRoutePolicyFactory(new MyRoutePolicyFactory());
----------------------------------------------------------
-And from XML DSL you just define a *`<bean>`* with the factory
+And from XML DSL you just define a `<bean>` with the factory, and Camel wil automatic detect this factory:
[source,xml]
----------------------------------------------------------------------
<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>
----------------------------------------------------------------------
-The factory has a single method that creates the route policy
+You can have as many route policy factories as you want, so if you have two factories,
+you can just add them both as shown:
[source,java]
-------------------------------------------------------------------------------------------------------------------------
-/**
- * Creates a new {@link org.apache.camel.spi.RoutePolicy} which will be assigned to the given route.
- *
- * @param camelContext the camel context
- * @param routeId the route id
- * @param route the route definition
- * @return the created {@link org.apache.camel.spi.RoutePolicy}, or <tt>null</tt> to not use a policy for this route
- */
-RoutePolicy createRoutePolicy(CamelContext camelContext, String routeId, RouteDefinition route);
-------------------------------------------------------------------------------------------------------------------------
-
-Note you can have as many route policy factories as you want. Just call
-the *`addRoutePolicyFactory`* again, or declare the other factories
-as *`<bean>`* in XML.
+----------------------------------------------------------
+context.addRoutePolicyFactory(new MyRoutePolicyFactory());
+context.addRoutePolicyFactory(new MyOtherRoutePolicyFactory());
+----------------------------------------------------------
+
+And in XML:
+[source,xml]
+----------------------------------------------------------------------
+<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>
+<bean id="myOtherRoutePolicyFactory" class="com.foo.MyOtherRoutePolicyFactory"/>
+----------------------------------------------------------------------