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 <[email protected]> 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 [email protected].
