You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by lb...@apache.org on 2017/04/18 11:09:43 UTC
camel git commit: Add ServiceCall EIP documentation
Repository: camel
Updated Branches:
refs/heads/master 89ba56d3d -> 60675efc3
Add ServiceCall EIP documentation
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/60675efc
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/60675efc
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/60675efc
Branch: refs/heads/master
Commit: 60675efc3ac420b35da219542607bdc01e9f9598
Parents: 89ba56d
Author: lburgazzoli <lb...@gmail.com>
Authored: Tue Apr 18 13:09:12 2017 +0200
Committer: lburgazzoli <lb...@gmail.com>
Committed: Tue Apr 18 13:09:30 2017 +0200
----------------------------------------------------------------------
.../src/main/docs/eips/serviceCall-eip.adoc | 420 +++++++++++++++++++
1 file changed, 420 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/60675efc/camel-core/src/main/docs/eips/serviceCall-eip.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/eips/serviceCall-eip.adoc b/camel-core/src/main/docs/eips/serviceCall-eip.adoc
new file mode 100644
index 0000000..35965ea
--- /dev/null
+++ b/camel-core/src/main/docs/eips/serviceCall-eip.adoc
@@ -0,0 +1,420 @@
+## Service Call EIP
+
+The serviceCall EIP allows to call remote services in a distributed system. 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.
+
+When calling a service you may just refer to the name of the service in the EIP as shown below:
+
+[source,java]
+.Java DSL
+----
+from("direct:start")
+ .serviceCall("foo")
+ .to("mock:result");
+----
+
+[source,xml]
+.XML DSL
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <serviceCall name="foo"/>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
+
+Camel will then:
+
+* search for a service call configuration from the Camel context and registry
+* lookup a service with the name ```foo``` from an external service registry
+* filter the servers
+* select the server to use
+* build a Camel URI using the choosen server info
+
+By default the Service Call EIP uses camel-http4 so assuming that the selected service instance runs on host ```myhost.com``` on port ```80```, the computed Camel URI will be:
+
+[source]
+----
+ http4:myhost.com:80
+----
+
+### Service Name to Camel URI Examples
+
+It is often needed to build more complex Camel URI which may include options or paths which is possible through different options:name: value
+
+* The *service name* supports a limited uri like syntax, here some examples
++
+[width="100%",cols="25%a,75%a",options="header"]
+|===
+|Name |Resolution
+
+|foo | http4://host:port
+|foo/path | http4://host:port/path
+|foo/path?foo=bar | http4://host:port/path?foo=bar
+|===
++
+[source,java]
+----
+from("direct:start")
+ .serviceCall("foo/hello")
+ .to("mock:result");
+----
++
+* If you wan to have more control over the uri construction, you can use the *uri* directive:
++
+[width="100%",cols="25%a,40%a,35%a",options="header"]
+|===
+|Name | URI | Resolution
+
+|foo | undertow:http://foo/hellp | undertow:http://host:port/hello
+|foo | undertow:http://foo.host:foo.port/hello | undertow:http://host:port/hello
+|===
++
+[source,java]
+----
+from("direct:start")
+ .serviceCall("foo", "undertow:http://foo/hello")
+ .to("mock:result");
+----
++
+* Advanced users can have full control over the uri construction through expressions:
++
+[source,java]
+----
+from("direct:start")
+ .serviceCall()
+ .name("foo")
+ .expression()
+ .simple("undertow:http://${header.CamelServiceCallServiceHost}:${header.CamelServiceCallServicePort}/hello");
+----
+
+### Configuring Service Call
+
+The Service Call EIP can be configured through the following options:
+
+[width="100%",cols="3,1m,6",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| name | String | *Required* Sets the name of the service to use
+| uri | String | The uri of the endpoint to send to.
+| component | String | The component to use.
+| pattern | ExchangePattern | Sets the optional ExchangePattern used to invoke this endpoint
+| configurationRef | String | Refers to a ServiceCall configuration to use
+| serviceDiscoveryRef | String | Sets a reference to a custom ServiceDiscovery to use.
+| serviceDiscovery | ServiceDiscovery | Sets the ServiceDiscovery to use ([.underline]_Java DSL only_).
+| serviceFilterRef | String | Sets a reference to a custom ServiceFilter to use.
+| serviceFilter | ServiceFilter | Sets the ServiceFilter to use ([.underline]_Java DSL only_).
+| serviceChooserRef | String | Sets a reference to a custom ServiceChooser to use.
+| serviceChooser | ServiceChooser | Sets the ServiceChooser to use ([.underline]_Java DSL only_).
+| loadBalancerRef | String | Sets a reference to a custom LoadBalancer to use.
+| loadBalancer | LoadBalancer | Sets the LoadBalancer to use ([.underline]_Java DSL only_).
+| expressionRef | String | Set a reference to a custom Expression to use.
+| expression | Expression | Set the Expression to use to compute the Camel URI ([.underline]_Java DSL only_).
+|=======================================================================
+
+In addition to ref/binding configuration style you can leverage specific configuration DSL to customize specific options:
+
+* *Consul Service Discovery:*
++
+To leverage Consul for Service Discover, maven users will need to add the following dependency to their pom.xml
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-consul</artifactId>
+ <!-- use the same version as your Camel core version -->
+ <version>x.y.z</version>
+</dependency>
+----
++
+*Available options:*
++
+[width="100%",cols="3,1m,6",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| url | String | The Consul agent URL
+| datacenter | String | The data center
+| aclToken | String | Sets the ACL token to be used with Consul
+| userName | String | Sets the username to be used for basic authentication
+| password | String | Sets the password to be used for basic authentication
+| connectTimeoutMillis | Long | Connect timeout for OkHttpClient
+| readTimeoutMillis | Long | Read timeout for OkHttpClient
+| writeTimeoutMillis | Long | Write timeout for OkHttpClient
+|=======================================================================
++
+[source,java]
+.Example
+----
+from("direct:start")
+ .serviceCall("foo")
+ .consulServiceDiscovery()
+ .url("http://consul-cluster:8500")
+ .datacenter("neverland")
+ .end()
+ .to("mock:result");
+----
+
+* *DNS Service Discovery:*
++
+To leverage DNS for Service Discover, maven users will need to add the following dependency to their pom.xml
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-dns</artifactId>
+ <!-- use the same version as your Camel core version -->
+ <version>x.y.z</version>
+</dependency>
+----
++
+[source,xml]
+.XML DSL
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <serviceCall name="foo">
+ <consulServiceDiscovery url="http://consul-cluster:8500" datacenter="neverland"/>
+ </serviceCall>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
+
++
+*Available options:*
++
+[width="100%",cols="3,1m,6",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| proto | String | The transport protocol of the desired service, default "_tcp"
+| domain | String | The user name to use for basic authentication
+|=======================================================================
++
+[source,java]
+.Example
+----
+from("direct:start")
+ .serviceCall("foo")
+ .dnsServiceDiscovery("my.domain.com")
+ .to("mock:result");
+----
++
+[source,xml]
+.XML DSL
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <serviceCall name="foo">
+ <dnsServiceDiscovery domain="my.domain.com"/>
+ </serviceCall>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
+
+* *Etcd Service Discovery:*
++
+To leverage Etcd for Service Discover, maven users will need to add the following dependency to their pom.xml
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-etcd</artifactId>
+ <!-- use the same version as your Camel core version -->
+ <version>x.y.z</version>
+</dependency>
+----
++
+*Available options:*
++
+[width="100%",cols="3,1m,6",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| uris | String | The URIs the client can connect to
+| userName | String | The user name to use for basic authentication
+| password | String | The password to use for basic authentication
+| timeout | Long | To set the maximum time an action could take to complete
+| servicePath | String | The path to look for for service discovery, default "/services"
+| type | String | To set the discovery type, valid values are on-demand and watch.
+|=======================================================================
++
+[source,java]
+.Example
+----
+from("direct:start")
+ .serviceCall("foo")
+ .etcdServiceDiscovery()
+ .uris("http://etcd1:4001,http://etcd2:4001")
+ .servicePath("/camel/services")
+ .end()
+ .to("mock:result");
+----
++
+[source,xml]
+.XML DSL
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <serviceCall name="foo">
+ <etcdServiceDiscovery uris="http://etcd1:4001,http://etcd2:4001" servicePath="/camel/services"/>
+ </serviceCall>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
+
+* *Kubernetes Service Discovery:*
++
+To leverage Kubernetes for Service Discover, maven users will need to add the following dependency to their pom.xml
++
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-kubernetes</artifactId>
+ <!-- use the same version as your Camel core version -->
+ <version>x.y.z</version>
+</dependency>
+----
++
+*Available options:*
++
+[width="100%",cols="3,1m,6",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| lookup | String | How to perform service lookup. Possible values: client, dns, environment
+| apiVersion | String | Kubernetes API version when using client lookup
+| caCertData | String | Sets the Certificate Authority data when using client lookup
+| caCertFile | String | Sets the Certificate Authority data that are loaded from the file when using client lookup
+| clientCertData | String | Sets the Client Certificate data when using client lookup
+| clientCertFile | String | Sets the Client Certificate data that are loaded from the file when using client lookup
+| clientKeyAlgo | String | Sets the Client Keystore algorithm, such as RSA when using client lookup
+| clientKeyData | String | Sets the Client Keystore data when using client lookup
+| clientKeyFile | String | Sets the Client Keystore data that are loaded from the file when using client lookup
+| clientKeyPassphrase | String | Sets the Client Keystore passphrase when using client lookup
+| dnsDomain | String | Sets the DNS domain to use for dns lookup
+| namespace | String | The Kubernetes namespace to use. By default the namespace's name is taken from the environment variable KUBERNETES_MASTER
+| oauthToken | String | Sets the OAUTH token for authentication (instead of username/password) when using client lookup
+| username | String | Sets the username for authentication when using client lookup
+| password | String | Sets the password for authentication when using client lookup
+| trustCerts | Boolean | Sets whether to turn on trust certificate check when using client lookup
+|=======================================================================
++
+[source,java]
+.Java DSL
+----
+from("direct:start")
+ .serviceCall("foo")
+ .kubernetesServiceDiscovery()
+ .lookup("dns")
+ .namespace("myNamespace")
+ .dnsDomain("my.domain.com")
+ .end()
+ .to("mock:result");
+----
++
+[source,xml]
+.XML DSL
+----
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:start"/>
+ <serviceCall name="foo">
+ <kubernetesServiceDiscovery lookup="dns" namespace="myNamespace" dnsDomain="my.domain.com"/>
+ </serviceCall>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+----
+
+### 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:
+
+[source,java]
+.Example
+----
+ServiceCallConfigurationDefinition globalConf = new ServiceCallConfigurationDefinition();
+globalConf.setServiceDiscovery(
+ name -> Arrays.asList(
+ new DefaultServiceDefinition(name, "my.host1.com", 8080),
+ new DefaultServiceDefinition(name, "my.host2.com", 443))
+);
+globalConf.setServiceChooser(
+ list -> list.get(ThreadLocalRandom.current().nextInt(list.size()))
+);
+
+ServiceCallConfigurationDefinition httpsConf = new ServiceCallConfigurationDefinition();
+httpsConf.setServiceFilter(
+ list -> list.stream().filter(s -> s.getPort() == 443).collect(toList())
+);
+
+getContext().setServiceCallConfiguration(globalConf);
+getContext().addServiceCallConfiguration("https", httpsConf);
+----
+
+Each Service Call definition and configuration will inheriths from the ```globalConf``` which can be see as default configuration, then you can reference the ```httpsConf``` in your rute as follow:
+
+[source,java]
+.Example
+----
+rom("direct_:start")
+ .serviceCall()
+ .name("foo")
+ .serviceCallConfiguration("https")
+ .end()
+ .to("mock:result");
+----
+
+This route will leverages 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]
+.Example
+----
+rom("direc_:start")
+ .serviceCall()
+ .name("foo")
+ .serviceCallConfiguration("https")
+ .serviceChooser(list -> list.get(0))
+ .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}}");
+ }
+}
+----