This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 27ea322 CAMEL-16861: Cleanup docs
27ea322 is described below
commit 27ea3229fcd980ba925272debc33e9a562b04349
Author: Claus Ibsen <[email protected]>
AuthorDate: Wed Nov 3 09:40:28 2021 +0100
CAMEL-16861: Cleanup docs
---
.../main/docs/modules/eips/pages/filter-eip.adoc | 8 +-
.../images/images/EventDrivenConsumerSolution.gif | Bin 0 -> 2077 bytes
.../images/images/MessageEndpointSolution.gif | Bin 0 -> 3816 bytes
.../ROOT/assets/images/images/camel-context.png | Bin 0 -> 30667 bytes
.../ROOT/assets/images/images/endpoint-factory.png | Bin 0 -> 52188 bytes
.../assets/images/images/endpoint-uri-syntax.png | Bin 0 -> 35436 bytes
.../assets/images/images/message_flow_in_route.png | Bin 0 -> 13415 bytes
.../modules/ROOT/pages/camelcontext.adoc | 219 ++++++++++++++++++++-
8 files changed, 220 insertions(+), 7 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
index 41c7b02..9e05c29 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/filter-eip.adoc
@@ -9,11 +9,15 @@ The
http://www.enterpriseintegrationpatterns.com/Filter.html[Message
Filter] from the xref:enterprise-integration-patterns.adoc[EIP patterns]
allows you to filter messages.
-IMPORTANT: The message filter implemented in Camel is similar to `if
(predicate) { block }`
-in Java. The filter will *include* the message if the predicate evaluated to
`true`.
+How can a component avoid receiving uninteresting messages?
image::eip/MessageFilter.gif[image]
+Use a special kind of Message Router, a Message Filter, to eliminate undesired
messages from a channel based on a set of criteria.
+
+The message filter implemented in Camel is similar to `if (predicate) { block
}`
+in Java. The filter will *include* the message if the predicate evaluated to
`true`.
+
== EIP options
// eip options: START
diff --git
a/docs/user-manual/modules/ROOT/assets/images/images/EventDrivenConsumerSolution.gif
b/docs/user-manual/modules/ROOT/assets/images/images/EventDrivenConsumerSolution.gif
new file mode 100644
index 0000000..8e71efa
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/assets/images/images/EventDrivenConsumerSolution.gif
differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/images/MessageEndpointSolution.gif
b/docs/user-manual/modules/ROOT/assets/images/images/MessageEndpointSolution.gif
new file mode 100644
index 0000000..e5b7f88
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/assets/images/images/MessageEndpointSolution.gif
differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/images/camel-context.png
b/docs/user-manual/modules/ROOT/assets/images/images/camel-context.png
new file mode 100644
index 0000000..e104a46
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/assets/images/images/camel-context.png differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/images/endpoint-factory.png
b/docs/user-manual/modules/ROOT/assets/images/images/endpoint-factory.png
new file mode 100644
index 0000000..6566bc8
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/assets/images/images/endpoint-factory.png differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/images/endpoint-uri-syntax.png
b/docs/user-manual/modules/ROOT/assets/images/images/endpoint-uri-syntax.png
new file mode 100644
index 0000000..f32e3d1
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/assets/images/images/endpoint-uri-syntax.png
differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/images/message_flow_in_route.png
b/docs/user-manual/modules/ROOT/assets/images/images/message_flow_in_route.png
new file mode 100644
index 0000000..07b4637
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/assets/images/images/message_flow_in_route.png
differ
diff --git a/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
b/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
index 31d2082..3913f8f 100644
--- a/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
@@ -1,9 +1,218 @@
= CamelContext
-The
-https://www.javadoc.io/doc/org.apache.camel/camel-api/latest/org/apache/camel/CamelContext.html[CamelContext]
-represents a single Camel routing rulebase.
+The
https://www.javadoc.io/doc/org.apache.camel/camel-api/latest/org/apache/camel/CamelContext.html[CamelContext]
+is the container that is the runtime Camel. The `CamelContext` is the runtime
system, which
+holds everything together as depicted in the figure below.
-See xref:lifecycle.adoc[Lifecycle] to understand the overall lifecycle
-of the `CamelContext`.
+image::images/camel-context.png[image]
+The `CamelContext` provides access to many useful services, the most notable
+being components, type converters, a registry, endpoints, routes, data
formats, and languages.
+
+The following table lists the most common services provided by `CamelContext`:
+
+[width="100%",cols="50%,50%",options="header",]
+|=======================================================================
+|Service |Description
+|xref:component.adoc[Components] | Contains the components used.
+|xref:endpoint.adoc[Endpoints] | Contains the endpoints that have been used.
+|xref:routes.adoc[Routes] | The routes in use.
+|xref:data-format.adoc[Data formats] | Contains the loaded data formats.
+|xref:languages.adoc[Languages] | Contains the loaded languages.
+|xref:type-converter.adoc[Type converters] | Contains the loaded type
converters. Camel has a mechanism that allows you to manually or automatically
convert from one type to another.
+|xref:registry.adoc[Registry] | Contains a registry that allows you to look up
beans.
+|=======================================================================
+
+== CamelContext 101
+
+To better understand Apache Camel then lets talk a bit more about what is
inside the `CamelContext`.
+
+=== Routing Engine
+
+Camel’s routing engine is what moves messages under the hood. This engine isn’t
+exposed to the developer, but you should be aware that it’s there and that it
does all the
+heavy lifting, ensuring that messages are routed properly.
+
+=== Routes
+
+xref:routes.adoc[Routes] are a core abstraction for Camel. The simplest way to
define a route is
+as a chain of xref:processor.adoc[Processors]. There are many reasons for
using routers in messaging applications.
+By decoupling clients from servers, and producers from consumers, routes can
+for example do the following:
+
+* Decide dynamically what server a client will invoke
+* Provide a flexible way to add extra processing
+* Allow for clients and servers to be developed independently
+* Foster better design practices by connecting disparate systems that do one
+thing well
+* Allow for clients of servers to be stubbed out (using
xref:components::mock-component.adoc[mocks]) for testing purposes
+
+Each route in Camel has a unique identifier that’s used for logging,
debugging, monitoring,
+and starting and stopping routes.
+
+Routes also have exactly one input source for messages,
+so they’re effectively tied to an input xref:endpoint.adoc[endpoint].
+
+=== Domain Specific Language (DSL)
+
+To wire processors and endpoints together to form routes, Camel defines a
xref:dsl.adoc[DSL].
+
+In Camel with Java, DSL means a fluent Java API that contains methods named
for EIP terms.
+
+Consider this example:
+
+[source,java]
+----
+from("file:data/inbox")
+ .filter().xpath("/order[not(@test)]")
+ .to("jms:queue:order");
+----
+
+Here, in a single Java statement, you define a route that consumes files from
a xref:components::file-component.adoc[file] endpoint.
+Messages are then routed to the xref:components:eips:filter-eip.adoc[Filter]
EIP, which will use an XPath predicate to
+test whether the message is not a test order. If a message passes the test,
it’s forwarded
+to the xref:components::jms-component.adoc[JMS] endpoint. Messages failing the
filter test are skipped.
+
+Camel provides multiple DSL languages, so you could define the same route by
using
+the XML DSL, like this:
+
+[source,xml]
+----
+<route>
+ <from uri="file:data/inbox"/>
+ <filter>
+ <xpath>/order[not(@test)]</xpath>
+ <to uri="jms:queue:order"/>
+ </filter>
+</route>
+----
+
+And in YAML:
+
+[source,yaml]
+----
+- from:
+ uri: "file:data/inbox"
+ steps:
+ - filter:
+ xpath: "/order[not(@test)]"
+ steps:
+ - to: "jms:queue:order"
+----
+
+The DSLs provide a nice abstraction for Camel users to build applications
with. Under
+the hood, though, a route is composed of a graph of processors.
+
+=== Processors
+
+The xref:processor.adoc[processor] is a core Camel concept that represents a
node capable of using, creating,
+or modifying an incoming xref:exchange.adoc[exchange].
+
+During routing, exchanges flow from one processor to another; as such, you can
think of a route as a graph having specialized processors
+as the nodes, and lines that connect the output of one processor to the input
of another.
+Processors could be implementations of EIPs, producers for specific
components, or
+your own custom code. The figure below shows the flow between processors.
+
+image::images/message_flow_in_route.png[image]
+
+A route first starts with a consumer (i.e. `from` in the DSL) that populates
the initial
+xref:exchange.adoc[exchange]. At each processor step, the out message from the
previous step is the in
+message of the next. In many cases, processors don’t set an out message, so in
this case
+the in message is reused. At the end of a route, the
xref:exchange-pattern.adoc[MEP] of the exchange determines
+whether a reply needs to be sent back to the caller of the route. If the
xref:exchange-pattern.adoc[MEP] is InOnly,
+no reply will be sent back. If it’s InOut, Camel will take the out message
from the last
+step and return it.
+
+=== Component
+
+xref:components::index.adoc[Components] are the main extension point in Camel.
+
+From a programming point of view, components are fairly simple: they’re
associated
+with a name that’s used in a xref:uris.adoc[URI], and they act as a factory of
xref:endpoint.adoc[endpoints].
+
+For example, `FileComponent` is referred to by file in a URI, and it creates
`FileEndpoint`. The endpoint
+is perhaps an even more fundamental concept in Camel.
+
+=== Endpoint
+
+An xref:endpoint.adoc[endpoint] is the Camel abstraction that models the end
of a channel through which a
+system can send or receive messages.
+
+image::images/MessageEndpointSolution.gif[image]
+
+In Camel, you configure endpoints by using URIs, such as
`file:data/inbox?delay=5000`,
+and you also refer to endpoints this way. At runtime, Camel looks up an
endpoint based
+on the URI notation. The figure below shows how this works.
+
+image::images/endpoint-uri-syntax.png[image]
+
+The scheme (1) denotes which Camel component handles that type of endpoint. In
+this case, the scheme of `file` selects `FileComponent`. `FileComponent` then
works as a
+factory, creating `FileEndpoint` based on the remaining parts of the URI. The
context
+path `data/inbox` (2) tells `FileComponent` that the starting folder is
`data/inbox`. The
+option, `delay=5000` (3) indicates that files should be polled at a 5-second
interval.
+
+The next figure shows how an endpoint works together with an exchange,
producers,and consumers.
+
+image::images/endpoint-factory.png[image]
+
+An endpoint acts as a factory for creating consumers and producers that are
capable of
+receiving and sending messages to a particular endpoint.
+
+=== Producer
+
+A producer is the Camel abstraction that refers to an entity capable of
sending a message to
+an endpoint. When a message is sent to an endpoint, the producer handles the
details of getting
+the message data compatible with that particular endpoint. For example,
`FileProducer`
+will write the message body to a `java.io.File`. `JmsProducer`, on the other
hand, will map
+the Camel message to `javax.jms.Message` before sending it to a JMS
destination. This
+is an important feature in Camel, because it hides the complexity of
interacting with
+particular transports. All you need to do is route a message to an endpoint,
and the producer
+does the heavy lifting.
+
+=== Consumer
+
+A consumer is the service that receives messages produced by some external
system,
+wraps them in an xref:exchange.adoc[exchange], and sends them to be processed.
+Consumers are the source of the exchanges being routed in Camel.
+To create a new exchange, a consumer will use the endpoint that wraps
+the payload being consumed. A xref:processor.adoc[processor] is then used to
initiate the routing of the
+exchange in Camel via the routing engine.
+
+Camel has two kinds of consumers: event-driven consumers, and polling
consumers (or scheduled polling consumers).
+The differences between these consumers are important, because they help solve
different
+problems.
+
+==== Event Driven Consumer
+
+The most familiar consumer is the event-driven consumer, as illustrated:
+
+image::images/EventDrivenConsumerSolution.gif[image]
+
+This kind of consumer is mostly associated with client-server architectures
and web
+services. It’s also referred to as an asynchronous receiver in the EIP world.
An event-driven
+consumer listens on a particular messaging channel, such as a TCP/IP port, JMS
+queue, Twitter handle, Amazon SQS queue, WebSocket, and so on. It then waits
for a
+client to send messages to it. When a message arrives, the consumer wakes up
and takes
+the message for processing.
+
+==== Polling Consumer / Scheduled Polling Consumer
+
+In contrast to the event-driven consumer, the polling consumer actively goes
and
+fetches messages from a particular source, such as an FTP server. The polling
consumer
+is also known as a synchronous receiver in EIP lingo, because it won’t poll
for more
+messages until it’s finished processing the current message. A common flavor
of the
+polling consumer is the scheduled polling consumer, which polls at scheduled
intervals.
+File, FTP, and email components all use scheduled polling consumers.
+
+NOTE: In the Camel components its only either the event driven or scheduled
polling consumers that
+are in use. The polling consumer (non-scheduled) is only used to poll
on-demand, such as
+when using the xref:components:eips:pollEnrich-eip.adoc[Poll Enrich] EIP, or
from Java by
+creating a `PollingConsumer` instance via the `createPollingConsumer()` method
from `Endpoint`.
+
+
+== See Also
+
+See the following for high-level xref:architecture.adoc[architecture] of
Apache Camel.
+
+See xref:lifecycle.adoc[Lifecycle] to understand the overall lifecycle of the
`CamelContext`.
