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 f4dd63e CAMEL-16861: Cleanup and update EIP docs
f4dd63e is described below
commit f4dd63e9182d29c794d5248c6ecda6f9ab1be74b
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Mon Oct 18 14:32:36 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../docs/modules/eips/pages/service-activator.adoc | 22 +--
.../docs/modules/eips/pages/serviceCall-eip.adoc | 189 ++++++++++-----------
2 files changed, 101 insertions(+), 110 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/service-activator.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/service-activator.adoc
index be9e75c..ef7390d 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/service-activator.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/service-activator.adoc
@@ -10,21 +10,21 @@ image::eip/MessagingAdapterSolution.gif[image]
Design a Service Activator that connects the messages on the channel to the
service being accessed.
-Camel has several endpoint components that support the Service Activator from
the EIP patterns.
+Camel has several xref:components::index.adoc[Components] that support the
Service Activator EIP.
-Components like xref:components::bean-component.adoc[Bean] and
xref:components::bean-component.adoc[CXF]
-provide a way to bind the message exchange to a Java interface/service where
the route defines the
-endpoints and wires it up to the bean.
+Components like xref:components::bean-component.adoc[Bean] and
xref:components::bean-component.adoc[CXF]
+provide a way to bind the message
xref:latest@manual:ROOT:exchange.adoc[Exchange] to a Java interface/service
+where the route defines the endpoints and wires it up to the bean.
-In addition you can use the xref:latest@manual:ROOT:bean-integration.adoc[Bean
Integration] to wire messages
-to a bean using annotation.
+In addition, you can use the
xref:latest@manual:ROOT:bean-integration.adoc[Bean Integration] to wire messages
+to a bean using Java annotation.
-== Sample
+== Example
-Here is a simple example of using a Direct endpoint to create a messaging
interface
-to a POJO Bean service.
+Here is a simple example of using a
xref:components::direct-component.adoc[Direct] endpoint
+to create a messaging interface to a POJO
xref:components::bean-component.adoc[Bean] service.
-Using Java DSL
+Using Java DSL:
[source,java]
----
@@ -32,7 +32,7 @@ from("direct:invokeMyService")
.to("bean:myService");
----
-Using the XML DSL
+Using the XML DSL:
[source,xml]
----
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/serviceCall-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/serviceCall-eip.adoc
index 3032749..b45a869 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/serviceCall-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/serviceCall-eip.adoc
@@ -5,7 +5,40 @@
:since:
:supportlevel: Stable
-The Service Call EIP allows to call remote services in a distributed system.
+How can I call a remote service in a distributed system where the service is
looked up from a service registry of some sorts?
+
+image::eip/MessagingGatewayIcon.gif[image]
+
+Use a Service Call acting as a xref:messaging-gateway.adoc[Messaging Gateway]
for distributed systems, that
+handles the complexity of calling the service in a reliable manner.
+
+The pattern has the following noteworthy features:
+
+* _Location transparency_ — Decouples Camel and the physical location of the
services
+using logical names representing the services.
+* _URI templating_ — Allows you to template the Camel endpoint URI as the
physical
+endpoint to use when calling the service.
+* _Service discovery_ - Looks up the service from a service registry of some
sort to know
+the physical locations of the services.
+* _Service filter_ — Allows you to filter unwanted services (for example,
blacklisted or
+unhealthy services).
+* _Service chooser_ — Allows you to choose the most appropriate service based
on
+factors such as geographical zone, affinity, plans, canary deployments, and
SLAs.
+* _Load balancer_ — A preconfigured Service Discovery, Filter, and Chooser
intended
+for a specific runtime (these three features combined as one).
+
+In a nutshell, the EIP pattern sits between your Camel application and the
services running
+in a distributed system (cluster). The pattern hides all the complexity of
keeping
+track of all the physical locations where the services are running and allows
you to call
+the service by a name.
+
+== Options
+// eip options: START
+include::partial$eip-options.adoc[]
+// eip options: END
+
+== Using Service Call
+
The service to call is looked up in a service registry of some sorts such as
Kubernetes, Consul, Etcd, Zookeeper, DNS.
The EIP separates the configuration of the service registry from the calling
of the service.
@@ -18,6 +51,8 @@ from("direct:start")
.to("mock:result");
----
+And in XML:
+
[source,xml]
----
<camelContext xmlns="http://camel.apache.org/schema/spring";>
@@ -37,14 +72,15 @@ Camel will then:
* select the server to use
* build a Camel URI using the chosen server info
-By default the Service Call EIP uses camel-http so assuming that the selected
service instance runs on host ```myhost.com``` on port ```80```, the computed
Camel URI will be:
+By default, the Service Call EIP uses `camel-http` so assuming that the
selected service
+instance runs on host ```myhost.com``` on port ```80```, the computed Camel
URI will be:
-[source]
+[source,text]
----
http:myhost.com:80
----
-== Service Name to Camel URI Examples
+=== Mapping Service Name to Endpoint URI
It is often needed to build more complex Camel URI which may include options
or paths which is possible through different options:name: value
@@ -71,7 +107,6 @@ If you want to have more control over the uri construction,
you can use the *uri
[width="100%",cols="25%a,40%a,35%a",options="header"]
|===
|Name | URI | Resolution
-
|foo | undertow:http://foo/hello | undertow:http://host:port/hello
|foo | undertow:http://foo.host:foo.port/hello |
undertow:http://host:port/hello
|===
@@ -94,18 +129,11 @@ from("direct:start")
.simple("undertow:http://${header.CamelServiceCallServiceHost}:${header.CamelServiceCallServicePort}/hello";);
----
-== Options
-// eip options: START
-include::partial$eip-options.adoc[]
-// eip options: END
-
-In addition to ref/binding configuration style you can leverage specific
configuration DSL to customize specific options:
-
-== Static Service Discovery
+=== Static Service Discovery
This service discovery implementation does not query any external services to
find out the list of services associated to a named service but keep them in
memory. Each service should be provided in the following form:
-[source]
+[source,text]
----
[service@]host:port
----
@@ -139,6 +167,8 @@ from("direct:start")
.to("mock:result");
----
+And in XML:
+
[source,xml]
----
<camelContext xmlns="http://camel.apache.org/schema/spring";>
@@ -149,13 +179,13 @@ from("direct:start")
<servers>service1@host1:80,service1@host2:80</servers>
<servers>service2@host1:8080,service2@host2:8080,service2@host3:8080</servers>
</staticServiceDiscovery>
- </serviceCall
+ </serviceCall>
<to uri="mock:result"/>
</route>
</camelContext>
----
-== Consul Service Discovery
+=== Consul Service Discovery
To leverage Consul for Service Discovery, maven users will need to add the
following dependency to their pom.xml
@@ -197,7 +227,7 @@ from("direct:start")
.to("mock:result");
----
-== DNS Service Discovery
+=== DNS Service Discovery
To leverage DNS for Service Discovery, maven users will need to add the
following dependency to their pom.xml
@@ -245,7 +275,7 @@ And in XML:
</camelContext>
----
-== Etcd Service Discovery
+=== Etcd Service Discovery
To leverage Etcd for Service Discovery, maven users will need to add the
following dependency to their pom.xml
@@ -272,7 +302,9 @@ Available options:
| type | String | To set the discovery type, valid values are "on-demand" and
"watch"
|===
-Example in Java
+Example in Java:
+
+[source,java]
----
from("direct:start")
.serviceCall("foo")
@@ -283,7 +315,8 @@ from("direct:start")
.to("mock:result");
----
-And in XML
+And in XML:
+
[source,xml]
----
<camelContext xmlns="http://camel.apache.org/schema/spring";>
@@ -297,7 +330,7 @@ And in XML
</camelContext>
----
-== Kubernetes Service Discovery
+=== Kubernetes Service Discovery
To leverage Kubernetes for Service Discovery, maven users will need to add the
following dependency to their pom.xml
@@ -334,7 +367,8 @@ Available options:
| trustCerts | Boolean | Sets whether to turn on trust certificate check when
using client lookup
|===
-Example in Java
+Example in Java:
+
[source,java]
----
from("direct:start")
@@ -347,7 +381,8 @@ from("direct:start")
.to("mock:result");
----
-And in XML
+And in XML:
+
[source,xml]
----
<camelContext xmlns="http://camel.apache.org/schema/spring";>
@@ -361,14 +396,16 @@ And in XML
</camelContext>
----
-== Service Filter
+=== Using service filtering
+
+The Service Call EIP supports filtering the services using built-in filters,
or a custom filter.
-=== Blacklist Service Filter
+==== Blacklist Service Filter
This service filter implementation removes the listed services from those
found by the service discovery.
Each service should be provided in the following form:
-[source]
+[source,text]
----
[service@]host:port
----
@@ -386,7 +423,8 @@ Available options:
| servers | String | A comma separated list of servers to blacklist:
[service@]host:port,[service@]host2:port,[service@]host3:port
|===
-Example in Java
+Example in Java:
+
[source,java]
----
from("direct:start")
@@ -401,7 +439,7 @@ from("direct:start")
.to("mock:result");
----
-And in XML
+And in XML:
[source,xml]
----
@@ -416,17 +454,17 @@ And in XML
<blacklistServiceFilter>
<servers>service2@host2:8080</servers>
</blacklistServiceFilter>
- </serviceCall
+ </serviceCall>
<to uri="mock:result"/>
</route>
</camelContext>
----
-=== Custom Service Filter
+==== Custom Service Filter
Service Filters choose suitable candidates from the service definitions found
in the service discovery.
-As of Camel 3.10.0 they have access to the current exchange, which allows you
to create service filters
+The service filter have access to the current exchange, which allows you to
create service filters
comparing service metadata with message content.
Assuming you have labeled one of the services in your service discovery to
support a certain type of requests:
@@ -441,7 +479,7 @@ The current exchange has a property which says that it
needs a foo service:
[source,java]
----
-exchange.setProperty("needs", "foo")
+exchange.setProperty("needs", "foo");
----
You can then use a `ServiceFilter` to select the service instances which match
the exchange:
@@ -461,9 +499,10 @@ from("direct:start")
.to("mock:result");
----
-== Load Balancer
+=== Load balancing services
-The Service Call EIP comes with its own loadbalancer which is instantiated by
default if a custom loadbalancer is not configured. It glues Service Discovery,
Service Filter, Service Chooser and Service Expression together to load balance
requests among the available services.
+The Service Call EIP comes with its own load-balancer which is instantiated by
default if a custom loadbalancer is not configured.
+It glues Service Discovery, Service Filter, Service Chooser and Service
Expression together to load balance requests among the available services.
If you need a more sophisticated load balancer you can use Ribbon by adding
camel-ribbon to the mix,
maven users will need to add the following dependency to their pom.xml
@@ -493,7 +532,7 @@ Available options:
To leverage Ribbon, it is required to explicit enable it:
-Java example
+Here is how to do that in Java:
[source,java]
----
@@ -503,18 +542,17 @@ from("direct:start")
.to("mock:result");
----
-And in XML
+And in XML:
+
[source,xml]
----
-<camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
+<route>
<from uri="direct:start"/>
<serviceCall name="foo">
- <ribbonLoadBalancer/>
+ <ribbonLoadBalancer/>
</serviceCall>
<to uri="mock:result"/>
- </route>
-</camelContext>
+</route>
----
You can configure Ribbon key programmatically using `RibbonConfiguration`:
@@ -534,23 +572,21 @@ Or leveraging XML specific configuration:
[source,xml]
----
-<camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
+<route>
<from uri="direct:start"/>
<serviceCall name="foo">
- <ribbonLoadBalancer>
- <properties key="listOfServers"
value="localhost:9090,localhost:9091"/>
- </ribbonLoadBalancer>
+ <ribbonLoadBalancer>
+ <properties key="listOfServers"
value="localhost:9090,localhost:9091"/>
+ </ribbonLoadBalancer>
</serviceCall>
<to uri="mock:result"/>
- </route>
-</camelContext>
+</route>
----
-== Shared configurations
+=== Shared configurations
The Service Call EIP can be configured straight on the route definition or
through shared configurations,
-here an example with two configurations registered in the Camel Context:
+here an example with two configurations registered in the `CamelContext`:
[source,java]
----
@@ -574,7 +610,7 @@ getContext().addServiceCallConfiguration("https",
httpsConf);
----
Each Service Call definition and configuration will inherit from the
`globalConf` which can be seen as default configuration,
-then you can reference the `httpsConf` in your route as follow:
+then you can reference the `httpsConf` in your route:
[source,java]
----
@@ -582,11 +618,11 @@ from("direct:start")
.serviceCall()
.name("foo")
.serviceCallConfiguration("https")
- .end()
+ .end()
.to("mock:result");
----
-This route will leverages the service discovery and service chooser from
`globalConf` and the service filter from `httpsConf`
+This route will leverage the service discovery and service chooser from
`globalConf` and the service filter from `httpsConf,
but you can override any of them if needed straight on the route:
[source,java]
@@ -596,52 +632,7 @@ from("direct:start")
.name("foo")
.serviceCallConfiguration("https")
.serviceChooser(list -> list.get(0))
- .end()
+ .end()
.to("mock:result");
----
-== Spring Boot support
-
-In a Spring-Boot application you can externalize most of the configuration
options:
-
-[source,properties]
-.application.properties
-----
-# this can be configured stright tot he route and it has been included to show
-# property placeholders support
-service.name = foo
-
-# this property is not mandatory and it has been included to show how to
configure
-# the service discovery implementation provided by camel-consul
-camel.cloud.consul.service-discovery.url = http://localhost:8500
-
-# Add a static list of servers for the service named foo
-camel.cloud.service-discovery.services[foo] =
host1.static:8080,host2.static:8080
-----
-
-[source,java]
-.Routes
-----
-@Component
-public class MyRouteBuilder implements RouteBuilder {
- @Override
- public void configure() throws Exception {
- from("direct:start")
- .serviceCall("{{service.name}}");
- }
-}
-----
-
-== Spring Cloud support
-
-If you are using Camel in an application based on Spring Cloud, you can
leverage Spring Cloud service discovery and load balancing capabilities by
adding the Spring Cloud related dependencies (i.e. spring-cloud-consul,
spring-cloud-kubernetes) as any Spring Boot/Cloud application in addition to
Camel's own camel-spring-cloud dependency.
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.camel</groupId>
- <artifactId>camel-spring-cloud dependency</artifactId>
- <!-- use the same version as your Camel core version -->
- <version>x.y.z</version>
-</dependency>
-----
