This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new 49ec7d8 Regen
49ec7d8 is described below
commit 49ec7d8022153dc7d52ffdf74a948dfce08b28d5
Author: Claus Ibsen <[email protected]>
AuthorDate: Sat Feb 16 08:15:57 2019 +0100
Regen
---
.../modules/ROOT/pages/jcache-policy.adoc | 109 ++++++++++++++++++++-
1 file changed, 105 insertions(+), 4 deletions(-)
diff --git a/docs/components/modules/ROOT/pages/jcache-policy.adoc
b/docs/components/modules/ROOT/pages/jcache-policy.adoc
index a7846e8..ea24b2e 100644
--- a/docs/components/modules/ROOT/pages/jcache-policy.adoc
+++ b/docs/components/modules/ROOT/pages/jcache-policy.adoc
@@ -3,15 +3,16 @@
The JCachePolicy is an interceptor around a route that caches the "result of
the route" - the message body - after the route is completed.
If next time the route is called with a "similar" Exchange, the cached value
is used on the Exchange instead of executing the route.
- The policy uses the JSR107/JCache API of a cache implementation.
+ The policy uses the JSR107/JCache API of a cache implementation, so it's
required to add one (e.g. Hazelcast, Ehcache) to the classpath.
The policy takes a _key_ value from the received Exchange to get or store
values in the cache. By default the _key_ is the message body.
For example if the route - having a JCachePolicy - receives an Exchange with
a String body "fruit" and the body at the
end of the route is "apple", it stores a _key/value_ pair "fruit=apple" in
the cache. If next time another Exchange arrives
with a body "fruit", the value "apple" is taken from the cache instead of
letting the route process the Exchange.
-So by default the message body at the beginning of the route is the cache
_key_ and the body at the end is the stored _value_. It's possible to use
something else as _key_ by setting a Camel Expression via _.setKeyExpression()_
-that will be used to determine the key.
+So by default the message body at the beginning of the route is the cache
_key_ and the body at the end is the stored _value_.
+ It's possible to use something else as _key_ by setting a Camel Expression
via _.setKeyExpression()_
+ that will be used to determine the key.
The policy needs a JCache Cache. It can be set directly by _.setCache()_ or
the policy will try to get or create the Cache
based on the other parameters set.
@@ -94,6 +95,23 @@ from("direct:get-orders").routeId("getorders")
.bean(OrderService.class,"findOrderById(${body})");
----------------------------
+### Partially wrapped route
+
+In the examples above the whole route was executed or skipped. A policy can be
used to wrap only a segment of the route instead of all processors.
+
+[source,java]
+----------------------------
+from("direct:get-orders")
+ .log("Order requested: ${body}")
+ .policy(new JCachePolicy())
+ .log("Getting order with id: ${body}")
+ .bean(OrderService.class,"findOrderById(${body})")
+ .end()
+ .log("Order found: ${body}");
+----------------------------
+
+The _.log()_ at the beginning and at the end of the route is always called,
but the section inside _.policy()_ and _.end()_ is executed based on the cache.
+
## KeyExpression
By default the policy uses the received Exchange body as _key_, so the default
expression is like _simple("${body})_.
@@ -122,7 +140,89 @@ from("direct:get-orders")
.bean(OrderService.class,"findOrderById(${header.orderId})");
----------------------------
-## Special scenarios and error handling
+## Camel XML DSL examples
+
+### Use JCachePolicy in an XML route
+
+In Camel XML DSL we need a named reference to the JCachePolicy instance
(registered in CamelContext or simply in Spring).
+ We have to wrap the route between <policy>...</policy> tags after <from>.
+
+[source,xml]
+----------------------------
+<camelContext xmlns="http://camel.apache.org/schema/spring";>
+ <route>
+ <from uri="direct:get-order"/>
+ <policy ref="jCachePolicy" >
+ <setBody>
+ <method ref="orderService" method="findOrderById(${body})"/>
+ </setBody>
+ </policy>
+ </route>
+</camelContext>
+----------------------------
+
+See this example when only a part of the route is wrapped:
+
+[source,xml]
+----------------------------
+<camelContext xmlns="http://camel.apache.org/schema/spring";>
+ <route>
+ <from uri="direct:get-order"/>
+ <log message="Start - This is always called. body:${body}"/>
+ <policy ref="jCachePolicy" >
+ <log message="Executing route, not found in cache. body:${body}"/>
+ <setBody>
+ <method ref="orderService" method="findOrderById(${body})"/>
+ </setBody>
+ </policy>
+ <log message="End - This is always called. body:${body}"/>
+ </route>
+</camelContext>
+----------------------------
+
+
+### Define CachePolicy in Spring
+
+It's more convenient to create a JCachePolicy in Java especially within a
RouteBuilder using the Camel DSL expressions,
+ but see this example to define it in a Spring XML:
+
+[source,xml]
+----------------------------
+<bean id="jCachePolicy"
class="org.apache.camel.component.jcache.policy.JCachePolicy">
+ <property name="cacheName" value="spring"/>
+ <property name="keyExpression">
+ <bean class="org.apache.camel.model.language.SimpleExpression">
+ <property name="expression" value="${header.mykey}"/>
+ </bean>
+ </property>
+</bean>
+----------------------------
+
+### Create Cache from XML
+
+It's not strictly speaking related to Camel XML DLS, but JCache providers
usually have a way to configure the cache in an XML file.
+ For example with Hazelcast you can add a _hazelcast.xml_ to classpath to
configure the cache "spring" used in the example above.
+
+[source,xml]
+----------------------------
+<?xml version="1.0" encoding="UTF-8"?>
+<hazelcast xmlns="http://www.hazelcast.com/schema/config";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://www.hazelcast.com/schema/config
hazelcast-config-3.11.xsd" >
+
+ <cache name="spring">
+ <key-type class-name="java.lang.String"/>
+ <value-type class-name="java.lang.String"/>
+ <expiry-policy-factory>
+ <timed-expiry-policy-factory expiry-policy-type="CREATED"
duration-amount="60" time-unit="MINUTES"/>
+ </expiry-policy-factory>
+ </cache>
+
+</hazelcast>
+----------------------------
+
+
+=== Special scenarios and error handling
If the Cache used by the policy is closed (can be done dynamically), the whole
caching functionality is skipped,
the route will be executed every time.
@@ -132,3 +232,4 @@ If the determined _key_ is _null_, nothing is looked up or
stored in cache.
In case of an exception during the route, the error handled is called as
always. If the exception gets _handled()_,
the policy stores the Exchange body, otherwise nothing is added to the cache.
If an exception happens during evaluating the keyExpression, the routing
fails, the error handler is called as normally.
+
