You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by on...@apache.org on 2018/02/26 05:44:20 UTC
[camel] branch master updated: CAMEL-11497- add pipeline onFallback
and pollEnrich eips docs
This is an automated email from the ASF dual-hosted git repository.
onders 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 0444a4a CAMEL-11497- add pipeline onFallback and pollEnrich eips docs
0444a4a is described below
commit 0444a4a1125d15b826c7c5da3cea92ad83ae974c
Author: onders86 <on...@gmail.com>
AuthorDate: Sat Feb 24 23:53:02 2018 +0300
CAMEL-11497- add pipeline onFallback and pollEnrich eips docs
---
camel-core/src/main/docs/eips/enrich-eip.adoc | 139 +---------------------
camel-core/src/main/docs/eips/hystrix-eip.adoc | 68 +----------
camel-core/src/main/docs/eips/onFallback-eip.adoc | 68 +++++++++++
camel-core/src/main/docs/eips/pipeline-eip.adoc | 91 ++++++++++++++
camel-core/src/main/docs/eips/pollEnrich-eip.adoc | 136 +++++++++++++++++++++
5 files changed, 298 insertions(+), 204 deletions(-)
diff --git a/camel-core/src/main/docs/eips/enrich-eip.adoc b/camel-core/src/main/docs/eips/enrich-eip.adoc
index ac1dece..68cf1b7 100644
--- a/camel-core/src/main/docs/eips/enrich-eip.adoc
+++ b/camel-core/src/main/docs/eips/enrich-eip.adoc
@@ -67,15 +67,11 @@ from("activemq:My.Queue").
=== Content enrichment using the `enrich` DSL element
-Camel comes with two flavors of content enricher in the DSL
-
-* `enrich`
-* `pollEnrich`
+Camel comes with flavor `enrich` as a choice of content enricher in the DSL.
+The other one is `pollEnrich`
`enrich` uses a Producer to obtain the additional data. It is usually used for Request Reply messaging, for instance to invoke an external web service.
-`pollEnrich` on the other hand uses a Polling Consumer to obtain the additional data. It is usually used for Event Message messaging, for instance to read a file or download a FTP file.
-
[WARNING]
.Camel 2.15 or older - Data from current Exchange not used
====
@@ -83,8 +79,6 @@ Camel comes with two flavors of content enricher in the DSL
Instead of using enrich you can use Recipient List and have dynamic endpoints and define an `AggregationStrategy` on the Recipient List which then would work as a enrich would do.
-`pollEnrich` only accept one message as response. That means that if you target to enrich your original message with the enricher collecting messages from a seda, ... components using an aggregation strategy. Only one response message will be aggregated with the original message.
-
From *Camel 2.16* onwards both `enrich` and `pollEnrich` supports dynamic endpoints that uses an Expression to compute the uri, which allows to use data from the current Exchange. In other words all what is told above no longer apply and it just works.
====
@@ -238,132 +232,3 @@ And in XML DSL
<to uri="direct:result"/>
</route>
----
-
-=== Content enrichment using pollEnrich
-The `pollEnrich` works just as the `enrich` however as it uses a Polling Consumer we have 3 methods when polling
-
-* `receive`
-* `receiveNoWait`
-* `receive(timeout)`
-
-=== PollEnrich Options
-
-// eip options: START
-The Enrich EIP supports 7 options which are listed below:
-
-
-[width="100%",cols="2,5,^1,2",options="header"]
-|===
-| Name | Description | Default | Type
-| *strategyRef* | Refers to an AggregationStrategy to be used to merge the reply from the external service, into a single outgoing message. By default Camel will use the reply from the external service as outgoing message. | | String
-| *strategyMethodName* | This option can be used to explicit declare the method name to use, when using POJOs as the AggregationStrategy. | | String
-| *strategyMethodAllowNull* | If this option is false then the aggregate method is not used if there was no data to enrich. If this option is true then null values is used as the oldExchange (when no data to enrich), when using POJOs as the AggregationStrategy. | false | Boolean
-| *aggregateOnException* | If this option is false then the aggregate method is not used if there was an exception thrown while trying to retrieve the data to enrich from the resource. Setting this option to true allows end users to control what to do if there was an exception in the aggregate method. For example to suppress the exception or set a custom message body etc. | false | Boolean
-| *shareUnitOfWork* | Shares the org.apache.camel.spi.UnitOfWork with the parent and the resource exchange. Enrich will by default not share unit of work between the parent exchange and the resource exchange. This means the resource exchange has its own individual unit of work. | false | Boolean
-| *cacheSize* | Sets the maximum size used by the org.apache.camel.impl.ProducerCache which is used to cache and reuse producer when uris are reused. | | Integer
-| *ignoreInvalidEndpoint* | Ignore the invalidate endpoint exception when try to create a producer with that endpoint | false | Boolean
-|===
-// eip options: END
-
-[NOTE]
-.Good practice to use timeout value
-====
-By default Camel will use the receive. Which may block until there is a message available. It is therefore recommended to always provide a timeout value, to make this clear that we may wait for a message, until the timeout is hit.
-====
-
-If there is no data then the `newExchange` in the aggregation strategy is `null`.
-
-You can pass in a timeout value that determines which method to use
-
-* if timeout is -1 or other negative number then `receive` is selected (*Important:* the `receive` method may block if there is no message)
-* if timeout is 0 then `receiveNoWait` is selected
-* otherwise `receive(timeout)` is selected
-
-The timeout values is in millis.
-
-[IMPORTANT]
-.Camel 2.15 or older - Data from current Exchange not used
-====
-`pollEnrich` does *not* access any data from the current Exchange which means when polling it cannot use any of the existing headers you may have set on the Exchange. For example you cannot set a filename in the `Exchange.FILE_NAME` header and use `pollEnrich` to consume only that file. For that you *must* set the filename in the endpoint URI.
-From *Camel 2.16* onwards both `enrich` and `pollEnrich` supports dynamic endpoints that uses an Expression to compute the uri, which allows to use data from the current Exchange. In other words all what is told above no longer apply and it just works.
-====
-
-=== PollEnrich Example
-
-In this example we enrich the message by loading the content from the file named inbox/data.txt.
-[source,java]
-----
-from("direct:start")
- .pollEnrich("file:inbox?fileName=data.txt")
- .to("direct:result");
-----
-
-And in XML DSL (Camel 2.15 or older) you do:
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <pollEnrich uri="file:inbox?fileName=data.txt"/>
- <to uri="direct:result"/>
-</route>
-----
-
-And in XML DSL (Camel 2.16 or newer) you do:
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <pollEnrich>
- <constant>file:inbox?fileName=data.txt</constant>
- </pollEnrich>
- <to uri="direct:result"/>
-</route>
-----
-
-If there is no file then the message is empty. We can use a timeout to either wait (potentially forever) until a file exists, or use a timeout to wait a certain period.
-
-For example to wait up to 5 seconds you can do (Camel 2.15 or older):
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <pollEnrich uri="file:inbox?fileName=data.txt" timeout="5000"/>
- <to uri="direct:result"/>
-</route>
-----
-
-For example to wait up to 5 seconds you can do (Camel 2.16 or newer):
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <pollEnrich timeout="5000">
- <constant>file:inbox?fileName=data.txt</constant>
- </pollEnrich>
- <to uri="direct:result"/>
-</route>
-----
-
-=== Using dynamic uris
-
-*Available as of Camel 2.16*
-
-From Camel 2.16 onwards `enrich` and `pollEnrich` supports using dynamic uris computed based on information from the current Exchange. For example to `pollEnrich` from an endpoint that uses a header to indicate a SEDA queue name:
-[source,java]
-----
-from("direct:start")
- .pollEnrich().simple("seda:${header.name}")
- .to("direct:result");
-----
-
-And in XML DSL
-[source,xml]
-----
-<route>
- <from uri="direct:start"/>
- <pollEnrich>
- <simple>seda:${header.name}</simple>
- </pollEnrich>
- <to uri="direct:result"/>
-</route>
-----
diff --git a/camel-core/src/main/docs/eips/hystrix-eip.adoc b/camel-core/src/main/docs/eips/hystrix-eip.adoc
index ca90c92..81686c4 100644
--- a/camel-core/src/main/docs/eips/hystrix-eip.adoc
+++ b/camel-core/src/main/docs/eips/hystrix-eip.adoc
@@ -63,73 +63,7 @@ And in XML DSL:
</camelContext>
----
-=== onFallback vs onFallbackViaNetwork
-
-If you are using *onFallback* then that is intended to be local processing only where you can do a message transformation or call a bean or something as the fallback. If you need to call an external service over the network then you should use *onFallbackViaNetwork* that runs in another independent *HystrixCommand* that uses its own thread pool to not exhaust the first command.
-Configuring Hystrix Example
-Hystrix has many options as listed in the table above. For example to set a higher timeout to *5* seconds, and also let the circuit breaker wait *10* seconds before attempting a request again when the state was tripped to be open.
-
-[source,java]
-----
-from("direct:start")
- .hystrix()
- .hystrixConfiguration()
- .executionTimeoutInMilliseconds(5000)
- .circuitBreakerSleepWindowInMilliseconds(10000)
- .end() // end Hystrix configuration
- .to("http://fooservice.com/slow")
- .onFallback()
- .transform().constant("Fallback message")
- .end()
- .to("mock:result");
-----
-
-And in XML DSL:
-[source,xml]
-----
-<camelContext xmlns="http://camel.apache.org/schema/spring">
- <route>
- <from uri="direct:start"/>
- <hystrix>
- <hystrixConfiguration executionTimeoutInMilliseconds="5000"
- circuitBreakerSleepWindowInMilliseconds="10000"/>
- <to uri="http://fooservice.com/slow"/>
- <onFallback>
- <transform>
- <constant>Fallback message</constant>
- </transform>
- </onFallback>
- </hystrix>
- <to uri="mock:result"/>
- </route>
-</camelContext>
-----
-
-You can also configure Hystrix globally and then refer to that configuration:
-
-[source,xml]
-----
-<camelContext xmlns="http://camel.apache.org/schema/spring">
-
- <!-- a shared config which you can refer to from all your Hystrix EIPs -->
- <hystrixConfiguration id="sharedConfig"
- executionTimeoutInMilliseconds="5000"
- circuitBreakerSleepWindowInMilliseconds="10000"/>
-
- <route>
- <from uri="direct:start"/>
- <hystrix hystrixConfigurationRef="sharedConfig">
- <to uri="http://fooservice.com/slow"/>
- <onFallback>
- <transform>
- <constant>Fallback message</constant>
- </transform>
- </onFallback>
- </hystrix>
- <to uri="mock:result"/>
- </route>
-</camelContext>
-----
+See link:https://github.com/apache/camel/blob/master/camel-core/src/main/docs/eips/onFallback-eip.adoc[onFallback]
=== Other examples
diff --git a/camel-core/src/main/docs/eips/onFallback-eip.adoc b/camel-core/src/main/docs/eips/onFallback-eip.adoc
new file mode 100644
index 0000000..13c9309
--- /dev/null
+++ b/camel-core/src/main/docs/eips/onFallback-eip.adoc
@@ -0,0 +1,68 @@
+[[onFallback-eip]]
+== On Fallback EIP
+
+If you are using *onFallback* then that is intended to be local processing only where you can do a message transformation or call a bean or something as the fallback. If you need to call an external service over the network then you should use *onFallbackViaNetwork* that runs in another independent *HystrixCommand* that uses its own thread pool to not exhaust the first command.
+Configuring Hystrix Example
+Hystrix has many options as listed in the table above. For example to set a higher timeout to *5* seconds, and also let the circuit breaker wait *10* seconds before attempting a request again when the state was tripped to be open.
+
+[source,java]
+----
+from("direct:start")
+ .hystrix()
+ .hystrixConfiguration()
+ .executionTimeoutInMilliseconds(5000)
+ .circuitBreakerSleepWindowInMilliseconds(10000)
+ .end() // end Hystrix configuration
+ .to("http://fooservice.com/slow")
+ .onFallback()
+ .transform().constant("Fallback message")
+ .end()
+ .to("mock:result");
+----
+
+And in XML DSL:
+[source,xml]
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <hystrix>
+ <hystrixConfiguration executionTimeoutInMilliseconds="5000"
+ circuitBreakerSleepWindowInMilliseconds="10000"/>
+ <to uri="http://fooservice.com/slow"/>
+ <onFallback>
+ <transform>
+ <constant>Fallback message</constant>
+ </transform>
+ </onFallback>
+ </hystrix>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
+
+You can also configure Hystrix globally and then refer to that configuration:
+
+[source,xml]
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+
+ <!-- a shared config which you can refer to from all your Hystrix EIPs -->
+ <hystrixConfiguration id="sharedConfig"
+ executionTimeoutInMilliseconds="5000"
+ circuitBreakerSleepWindowInMilliseconds="10000"/>
+
+ <route>
+ <from uri="direct:start"/>
+ <hystrix hystrixConfigurationRef="sharedConfig">
+ <to uri="http://fooservice.com/slow"/>
+ <onFallback>
+ <transform>
+ <constant>Fallback message</constant>
+ </transform>
+ </onFallback>
+ </hystrix>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
\ No newline at end of file
diff --git a/camel-core/src/main/docs/eips/pipeline-eip.adoc b/camel-core/src/main/docs/eips/pipeline-eip.adoc
new file mode 100644
index 0000000..192f176
--- /dev/null
+++ b/camel-core/src/main/docs/eips/pipeline-eip.adoc
@@ -0,0 +1,91 @@
+[[pipeline-eip]]
+== Pipeline EIP
+== Pipes and Filters
+
+Camel supports the link:http://www.enterpriseintegrationpatterns.com/PipesAndFilters.html[Pipes and Filters] from the link:https://github.com/apache/camel/blob/master/docs/user-manual/en/enterprise-integration-patterns.adoc[EIP patterns] in various ways.
+
+image:http://www.enterpriseintegrationpatterns.com/img/PipesAndFilters.gif[image]
+
+With Camel you can split your processing across multiple independent
+link:https://github.com/apache/camel/blob/master/docs/user-manual/en/endpoint.adoc[Endpoint] instances which can then be chained
+together.
+
+[[PipesandFilters-Samples]]
+=== Samples
+
+You can create pipelines of logic using multiple
+link:https://github.com/apache/camel/blob/master/docs/user-manual/en/endpoint.adoc[Endpoint] or link:https://github.com/apache/camel/blob/master/camel-core/src/main/docs/eips/message-translator.adoc[Message
+Translator] instances as follows
+
+Though pipeline is the default mode of operation when you specify
+multiple outputs in Camel. The opposite to pipeline is multicast; which
+fires the same message into each of its outputs. (See the example
+below).
+
+In Java you do:
+[source,java]
+----
+from("activemq:SomeQueue")
+ .pipeline()
+ .bean("foo")
+ .bean("bar")
+ .to("acitvemq:OutputQueueu");
+----
+
+The pipeline is the default mode, which can be omitted, and therefore you almost often write as:
+
+[source,java]
+----
+from("activemq:SomeQueue")
+ .bean("foo")
+ .bean("bar")
+ .to("acitvemq:OutputQueueu");
+----
+
+In XML you can use the `<pipeline>` element
+
+[source,xml]
+----
+<route>
+ <from uri="activemq:SomeQueue"/>
+ <pipeline>
+ <bean ref="foo"/>
+ <bean ref="bar"/>
+ <to uri="activemq:OutputQueue"/>
+ </pipeline>
+</route>
+----
+
+In the above the pipeline element is actually unnecessary, you could use this:
+
+[source,xml]
+----
+<route>
+ <from uri="activemq:SomeQueue"/>
+ <bean ref="foo"/>
+ <bean ref="bar"/>
+ <to uri="activemq:OutputQueue"/>
+</route>
+----
+
+Its just a bit more explicit. However if you wish to use `<multicast/>` to
+avoid a pipeline - to send the same message into multiple pipelines -
+then the `<pipeline>` element comes into its own.
+
+[source,xml]
+----
+<route>
+ <from uri="activemq:SomeQueue"/>
+ <multicast>
+ <pipeline>
+ <bean ref="something"/>
+ <to uri="log:Something"/>
+ </pipeline>
+ <pipeline>
+ <bean ref="foo"/>
+ <bean ref="bar"/>
+ <to uri="activemq:OutputQueue"/>
+ </pipeline>
+ </multicast>
+</route>
+----
\ No newline at end of file
diff --git a/camel-core/src/main/docs/eips/pollEnrich-eip.adoc b/camel-core/src/main/docs/eips/pollEnrich-eip.adoc
new file mode 100644
index 0000000..1306786
--- /dev/null
+++ b/camel-core/src/main/docs/eips/pollEnrich-eip.adoc
@@ -0,0 +1,136 @@
+[[pollEnrich-eip]]
+== Poll Enrich EIP
+
+Camel comes with flavor `pollEnrich` as a choice of content enricher in the DSL.
+The other one is `enrich`
+
+`pollEnrich` uses a Polling Consumer to obtain the additional data. It is usually used for Event Message messaging, for instance to read a file or download a FTP file.
+
+[NOTE]
+.Good practice to use timeout value
+====
+By default Camel will use the receive. Which may block until there is a message available. It is therefore recommended to always provide a timeout value, to make this clear that we may wait for a message, until the timeout is hit.
+====
+
+If there is no data then the `newExchange` in the aggregation strategy is `null`.
+
+You can pass in a timeout value that determines which method to use
+
+* if timeout is -1 or other negative number then `receive` is selected (*Important:* the `receive` method may block if there is no message)
+* if timeout is 0 then `receiveNoWait` is selected
+* otherwise `receive(timeout)` is selected
+
+The timeout values is in millis.
+
+[IMPORTANT]
+.Camel 2.15 or older - Data from current Exchange not used
+====
+`pollEnrich` does *not* access any data from the current Exchange which means when polling it cannot use any of the existing headers you may have set on the Exchange. For example you cannot set a filename in the `Exchange.FILE_NAME` header and use `pollEnrich` to consume only that file. For that you *must* set the filename in the endpoint URI.
+From *Camel 2.16* onwards both `enrich` and `pollEnrich` supports dynamic endpoints that uses an Expression to compute the uri, which allows to use data from the current Exchange. In other words all what is told above no longer apply and it just works.
+====
+
+=== Content enrichment using pollEnrich
+The `pollEnrich` works just as the `enrich` however as it uses a Polling Consumer we have 3 methods when polling
+
+* `receive`
+* `receiveNoWait`
+* `receive(timeout)`
+
+=== PollEnrich Options
+
+// eip options: START
+The Poll Enrich EIP supports 7 options which are listed below:
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *timeout* | Timeout in millis when polling from the external service. The timeout has influence about the poll enrich behavior. It basically operations in three different modes: negative value - Waits until a message is available and then returns it. Warning that this method could block indefinitely if no messages are available. 0 - Attempts to receive a message exchange immediately without waiting and returning null if a message exchange is not available yet. positive value - Attempts [...]
+| *strategyRef* | Refers to an AggregationStrategy to be used to merge the reply from the external service, into a single outgoing message. By default Camel will use the reply from the external service as outgoing message. | | String
+| *strategyMethodName* | This option can be used to explicit declare the method name to use, when using POJOs as the AggregationStrategy. | | String
+| *strategyMethodAllowNull* | If this option is false then the aggregate method is not used if there was no data to enrich. If this option is true then null values is used as the oldExchange (when no data to enrich), when using POJOs as the AggregationStrategy. | false | Boolean
+| *aggregateOnException* | If this option is false then the aggregate method is not used if there was an exception thrown while trying to retrieve the data to enrich from the resource. Setting this option to true allows end users to control what to do if there was an exception in the aggregate method. For example to suppress the exception or set a custom message body etc. | false | Boolean
+| *cacheSize* | Sets the maximum size used by the org.apache.camel.impl.ConsumerCache which is used to cache and reuse consumers when uris are reused. | | Integer
+| *ignoreInvalidEndpoint* | Ignore the invalidate endpoint exception when try to create a producer with that endpoint | false | Boolean
+|===
+// eip options: END
+
+=== PollEnrich Example
+
+In this example we enrich the message by loading the content from the file named inbox/data.txt.
+[source,java]
+----
+from("direct:start")
+ .pollEnrich("file:inbox?fileName=data.txt")
+ .to("direct:result");
+----
+
+And in XML DSL (Camel 2.15 or older) you do:
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <pollEnrich uri="file:inbox?fileName=data.txt"/>
+ <to uri="direct:result"/>
+</route>
+----
+
+And in XML DSL (Camel 2.16 or newer) you do:
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <pollEnrich>
+ <constant>file:inbox?fileName=data.txt</constant>
+ </pollEnrich>
+ <to uri="direct:result"/>
+</route>
+----
+
+If there is no file then the message is empty. We can use a timeout to either wait (potentially forever) until a file exists, or use a timeout to wait a certain period.
+
+For example to wait up to 5 seconds you can do (Camel 2.15 or older):
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <pollEnrich uri="file:inbox?fileName=data.txt" timeout="5000"/>
+ <to uri="direct:result"/>
+</route>
+----
+
+For example to wait up to 5 seconds you can do (Camel 2.16 or newer):
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <pollEnrich timeout="5000">
+ <constant>file:inbox?fileName=data.txt</constant>
+ </pollEnrich>
+ <to uri="direct:result"/>
+</route>
+----
+
+=== Using dynamic uris
+
+*Available as of Camel 2.16*
+
+From Camel 2.16 onwards `enrich` and `pollEnrich` supports using dynamic uris computed based on information from the current Exchange. For example to `pollEnrich` from an endpoint that uses a header to indicate a SEDA queue name:
+[source,java]
+----
+from("direct:start")
+ .pollEnrich().simple("seda:${header.name}")
+ .to("direct:result");
+----
+
+And in XML DSL
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <pollEnrich>
+ <simple>seda:${header.name}</simple>
+ </pollEnrich>
+ <to uri="direct:result"/>
+</route>
+----
--
To stop receiving notification emails like this one, please contact
onders@apache.org.