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 2018/02/05 15:28:26 UTC
[camel] 05/07: CAMEL-8958: Claim Check EIP with push/pop. Work in
progress.
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch 8958
in repository https://gitbox.apache.org/repos/asf/camel.git
commit dd38a8c2eb77aa9a5ef52048d72195df47601664
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Feb 5 10:45:54 2018 +0100
CAMEL-8958: Claim Check EIP with push/pop. Work in progress.
---
camel-core/src/main/docs/eips/claimCheck-eip.adoc | 178 +++++++++++++++++++++
.../apache/camel/model/ClaimCheckDefinition.java | 8 +-
.../apache/camel/model/ProcessorDefinition.java | 29 ++++
3 files changed, 213 insertions(+), 2 deletions(-)
diff --git a/camel-core/src/main/docs/eips/claimCheck-eip.adoc b/camel-core/src/main/docs/eips/claimCheck-eip.adoc
new file mode 100644
index 0000000..f9d34e0
--- /dev/null
+++ b/camel-core/src/main/docs/eips/claimCheck-eip.adoc
@@ -0,0 +1,178 @@
+[[claimCheck-eip]]
+== Claim Check EIP
+
+The Claim Check EIP allows you to replace message content with a claim check (a unique key),
+which can be used to retrieve the message content at a later time.
+
+It can also be useful in situations where you cannot trust the information with an outside party; in this case, you can use the Claim Check to hide the sensitive portions of data.
+
+NOTE: The Camel implementation of this EIP pattern stores the message content temporarily in an internal memory store.
+
+
+// eip options: START
+The Claim Check EIP supports 5 options which are listed below:
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *operation* | *Required* The claim check operation to use. The following operations is supported: Get - Gets (does not remove) the claim check by the given key. GetAndRemove - Gets and remove the claim check by the given key. Set - Sets a new (will override if key already exists) claim check with the given key. Push - Sets a new claim check on the stack (does not use key). Pop - Gets the latest claim check from the stack (does not use key). | | ClaimCheckOperation
+| *key* | To use a specific key for claim check id. | | String
+| *data* | What data to merge when claiming from the repository. The following syntax is supported: body - to aggregate the message body headers - to aggregate all the message headers header:pattern - to aggregate all the message headers that matches the pattern. The pattern syntax is documented by: link EndpointHelpermatchPattern(String String). You can specify multiple rules separated by comma. For example to include the message body and all headers starting with foo bodyheader:foo. If [...]
+| *strategyRef* | To use a custom AggregationStrategy instead of the default implementation. Notice you cannot use both custom aggregation strategy and configure data at the same time. | | String
+| *strategyMethodName* | This option can be used to explicit declare the method name to use when using POJOs as the AggregationStrategy. | | String
+|===
+// eip options: END
+
+
+=== Claim Check Operation
+
+When using this EIP you must specify the operation to use which can be of the following:
+
+* Get - Gets (does not remove) the claim check by the given key.
+* GetAndRemove - Gets and remove the claim check by the given key.
+* Set - Sets a new (will override if key already exists) claim check with the given key.
+* Push - Sets a new claim check on the stack (does not use key).
+* Pop - Gets the latest claim check from the stack (does not use key).
+
+When using the `Get`, `GetAndRemove`, or `Set` operation you must specify a key.
+These operations will then store and retrieve the data using this key. You can use this to store multiple data in different keys.
+
+The `Push` and `Pop` operations do *not* use a key but stores the data in a stack structure.
+
+
+=== What data to merge back
+
+The `data` option is used to define what data to merge back when using the `Get` or `Pop` operation. When data is merged back
+then its merged using a `AggregationStrategy`. The default strategy uses the `data` option to easily specify what data to merge back.
+
+The `data` option takes a String value with the following syntax:
+
+* body - to aggregate the message body
+* headers - to aggregate all the message headers
+* header:pattern - to aggregate all the message headers that matches the pattern.
+
+The pattern rule supports wildcard and regular expression:
+
+* wildcard match (pattern ends with a * and the name starts with the pattern)
+* regular expression match
+
+You can specify multiple rules separated by comma.
+
+For example to include the message body and all headers starting with _foo_:
+
+[text]
+----
+body,header:foo*
+----
+
+To only merge back the message body:
+
+[text]
+----
+body
+----
+
+To only merge back headers:
+
+[text]
+----
+headers
+----
+
+To only merge back a header name foo:
+
+[text]
+----
+header:foo
+----
+
+If the data rule is specified as empty or as wildcard then everything is merged.
+
+Notice that when merging back data, then any existing data is overriden, and any other existing data is preserved.
+
+
+=== Java Examples
+
+The following example shows the `Push` and `Pop` operations in action;
+
+[java]
+----
+from("direct:start")
+ .to("mock:a")
+ .claimCheck(ClaimCheckOperation.Push)
+ .transform().constant("Bye World")
+ .to("mock:b")
+ .claimCheck(ClaimCheckOperation.Pop)
+ .to("mock:c");
+----
+
+For example if the message body from the beginning is `Hello World` then that data is pushed on the stack of the Claim Check EIP.
+And then the message body is transformed to `Bye World`, which is what `mock:b` endpoint receives. When we `Pop` from the Claim Check EIP
+then the original message body is retrieved and merged back so `mock:c` will retrieve the message body with `Hello World`.
+
+Here is an example using `Get` and `Set` operations, which uses the key `foo`:
+
+[java]
+----
+from("direct:start")
+ .to("mock:a")
+ .claimCheck(ClaimCheckOperation.Set, "foo")
+ .transform().constant("Bye World")
+ .to("mock:b")
+ .claimCheck(ClaimCheckOperation.Get, "foo")
+ .to("mock:c")
+ .transform().constant("Hi World")
+ .to("mock:d")
+ .claimCheck(ClaimCheckOperation.Get, "foo")
+ .to("mock:e");
+----
+
+Notice how we can `Get` the same data twice using the `Get` operation as it will not remove the data. If you only want
+to get the data once, you can use `GetAndRemove`.
+
+The last example shows how to use the `data` option where we only want to get back header named `foo` or `bar`:
+
+[java]
+----
+from("direct:start")
+ .to("mock:a")
+ .claimCheck(ClaimCheckOperation.Push)
+ .transform().constant("Bye World")
+ .setHeader("foo", constant(456))
+ .removeHeader("bar")
+ .to("mock:b")
+ // only merge in the message headers foo or bar
+ .claimCheck(ClaimCheckOperation.Pop, null, "header:(foo|bar)")
+ .to("mock:c");
+----
+
+=== XML examples
+
+The following example shows the `Push` and `Pop` operations in action;
+
+[xml]
+----
+TODO: XML example
+----
+
+For example if the message body from the beginning is `Hello World` then that data is pushed on the stack of the Claim Check EIP.
+And then the message body is transformed to `Bye World`, which is what `mock:b` endpoint receives. When we `Pop` from the Claim Check EIP
+then the original message body is retrieved and merged back so `mock:c` will retrieve the message body with `Hello World`.
+
+Here is an example using `Get` and `Set` operations, which uses the key `foo`:
+
+[xml]
+----
+TODO: XML example
+----
+
+Notice how we can `Get` the same data twice using the `Get` operation as it will not remove the data. If you only want
+to get the data once, you can use `GetAndRemove`.
+
+The last example shows how to use the `data` option where we only want to get back header named `foo` or `bar`:
+
+[xml]
+----
+TODO: XML example
+----
diff --git a/camel-core/src/main/java/org/apache/camel/model/ClaimCheckDefinition.java b/camel-core/src/main/java/org/apache/camel/model/ClaimCheckDefinition.java
index 8b9080e..d38460f 100644
--- a/camel-core/src/main/java/org/apache/camel/model/ClaimCheckDefinition.java
+++ b/camel-core/src/main/java/org/apache/camel/model/ClaimCheckDefinition.java
@@ -33,7 +33,7 @@ import org.apache.camel.util.EndpointHelper;
import org.apache.camel.util.ObjectHelper;
/**
- * The Claim Check from the EIP patterns allows you to replace message content with a claim check (a unique key),
+ * The Claim Check EIP allows you to replace message content with a claim check (a unique key),
* which can be used to retrieve the message content at a later time.
*/
@Metadata(label = "eip,routing")
@@ -59,7 +59,11 @@ public class ClaimCheckDefinition extends NoOutputDefinition<ClaimCheckDefinitio
@Override
public String toString() {
- return "ClaimCheck";
+ if (operation != null) {
+ return "ClaimCheck[" + operation + "]";
+ } else {
+ return "ClaimCheck";
+ }
}
@Override
diff --git a/camel-core/src/main/java/org/apache/camel/model/ProcessorDefinition.java b/camel-core/src/main/java/org/apache/camel/model/ProcessorDefinition.java
index 9d168b1..19ac9c8 100644
--- a/camel-core/src/main/java/org/apache/camel/model/ProcessorDefinition.java
+++ b/camel-core/src/main/java/org/apache/camel/model/ProcessorDefinition.java
@@ -3445,12 +3445,24 @@ public abstract class ProcessorDefinition<Type extends ProcessorDefinition<Type>
return ExpressionClause.createAndSetExpression(answer);
}
+ /**
+ * The <a href="http://camel.apache.org/claim-check.html">Claim Check EIP</a>
+ * allows you to replace message content with a claim check (a unique key),
+ * which can be used to retrieve the message content at a later time.
+ */
public ClaimCheckDefinition claimCheck() {
ClaimCheckDefinition answer = new ClaimCheckDefinition();
addOutput(answer);
return answer;
}
+ /**
+ * The <a href="http://camel.apache.org/claim-check.html">Claim Check EIP</a>
+ * allows you to replace message content with a claim check (a unique key),
+ * which can be used to retrieve the message content at a later time.
+ *
+ * @param operation the claim check operation to use.
+ */
public Type claimCheck(ClaimCheckOperation operation) {
ClaimCheckDefinition answer = new ClaimCheckDefinition();
answer.setOperation(operation);
@@ -3458,6 +3470,14 @@ public abstract class ProcessorDefinition<Type extends ProcessorDefinition<Type>
return (Type) this;
}
+ /**
+ * The <a href="http://camel.apache.org/claim-check.html">Claim Check EIP</a>
+ * allows you to replace message content with a claim check (a unique key),
+ * which can be used to retrieve the message content at a later time.
+ *
+ * @param operation the claim check operation to use.
+ * @param key the unique key to use for the get and set operations, can be <tt>null</tt> for push/pop operations
+ */
public Type claimCheck(ClaimCheckOperation operation, String key) {
ClaimCheckDefinition answer = new ClaimCheckDefinition();
answer.setOperation(operation);
@@ -3466,6 +3486,15 @@ public abstract class ProcessorDefinition<Type extends ProcessorDefinition<Type>
return (Type) this;
}
+ /**
+ * The <a href="http://camel.apache.org/claim-check.html">Claim Check EIP</a>
+ * allows you to replace message content with a claim check (a unique key),
+ * which can be used to retrieve the message content at a later time.
+ *
+ * @param operation the claim check operation to use.
+ * @param key the unique key to use for the get and set operations, can be <tt>null</tt> for push/pop operations
+ * @param data describes what data to retrieve and merge back when using get or pop operations.
+ */
public Type claimCheck(ClaimCheckOperation operation, String key, String data) {
ClaimCheckDefinition answer = new ClaimCheckDefinition();
answer.setOperation(operation);
--
To stop receiving notification emails like this one, please contact
davsclaus@apache.org.