[
https://issues.apache.org/jira/browse/CAMEL-11497?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16376407#comment-16376407
]
ASF GitHub Bot commented on CAMEL-11497:
----------------------------------------
onderson closed pull request #2235: CAMEL-11497- add pipeline onFallback and
pollEnrich eips docs
URL: https://github.com/apache/camel/pull/2235
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/camel-core/src/main/docs/eips/enrich-eip.adoc
b/camel-core/src/main/docs/eips/enrich-eip.adoc
index ac1dece09ed..68cf1b78281 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 ca90c92b446..81686c4ea9a 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 00000000000..13c93095e4f
--- /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 00000000000..192f1765aa8
--- /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 00000000000..1306786212d
--- /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 to receive a message exchange, waiting up to the
given timeout to expire if a message is not yet available. Returns null if
timed out The default value is -1 and therefore the method could block
indefinitely, and therefore its recommended to use a timeout value | -1 | Long
+| *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>
+----
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
> Migrate the rest of the Confluence content
> ------------------------------------------
>
> Key: CAMEL-11497
> URL: https://issues.apache.org/jira/browse/CAMEL-11497
> Project: Camel
> Issue Type: Sub-task
> Components: website
> Reporter: Zoran Regvart
> Assignee: Önder Sezgin
> Priority: Major
> Fix For: Future
>
>
> There are still pages in the Confluence that are not migrated to Asciidoctor
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
