Asciidoc How Do I Configure Endpoints
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/0acecac1 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/0acecac1 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/0acecac1 Branch: refs/heads/master Commit: 0acecac1d23435ef54a48afa5c65dad8d7a590df Parents: 057ac8b Author: Antonin Stefanutti <anto...@stefanutti.fr> Authored: Wed Feb 24 19:48:35 2016 +0100 Committer: Claus Ibsen <davscl...@apache.org> Committed: Thu Feb 25 08:20:35 2016 +0100 ---------------------------------------------------------------------- docs/user-manual/en/SUMMARY.md | 5 + .../en/how-do-i-configure-endpoints.adoc | 272 +++++++++++++++++++ 2 files changed, 277 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/0acecac1/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index ad2266c..3f48a41 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -69,6 +69,11 @@ * [Message](message.adoc) * [Request Reply](request-reply.adoc) +* Community + * FAQ + * Using Camel questions + * [How do I configure endpoints](how-do-i-configure-endpoints.adoc) + * Components * [Async Http Client (AHC)](ahc.adoc) * [AHC Websocket (AHC-WS)](ahc-ws.adoc) http://git-wip-us.apache.org/repos/asf/camel/blob/0acecac1/docs/user-manual/en/how-do-i-configure-endpoints.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/how-do-i-configure-endpoints.adoc b/docs/user-manual/en/how-do-i-configure-endpoints.adoc new file mode 100644 index 0000000..70639d0 --- /dev/null +++ b/docs/user-manual/en/how-do-i-configure-endpoints.adoc @@ -0,0 +1,272 @@ +[[HowdoIconfigureendpoints-HowdoIconfigureendpoints]] +How do I configure endpoints? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few different approaches to configuring components and +endpoints. + +[[HowdoIconfigureendpoints-UsingJavaCode]] +Using Java Code +^^^^^^^^^^^^^^^ + +You can explicitly configure a link:component.html[Component] using Java +code as shown in this link:walk-through-an-example.html[example] + +Or you can explicitly get hold of an link:endpoint.html[Endpoint] and +configure it using Java code as shown in the link:mock.html[Mock +endpoint examples]. + +[source,java] +---- +SomeEndpoint endpoint = camelContext.getEndpoint("someURI", SomeEndpoint.class); +endpoint.setSomething("aValue"); +---- + +[[HowdoIconfigureendpoints-UsingGuice]] +Using Guice +^^^^^^^^^^^ + +You can also use link:guice.html[Guice] as the dependency injection +framework. For example see the link:guice-jms-example.html[Guice JMS +Example]. + +[[HowdoIconfigureendpoints-UsingSpringXML]] +Using Spring XML +^^^^^^^^^^^^^^^^ + +You can configure your link:component.html[Component] or +link:endpoint.html[Endpoint] instances in your link:spring.html[Spring] +XML as follows: + +[source,xml] +---- +<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> + <jmxAgent id="agent" disabled="true"/> +</camelContext> + +<bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent"> + <property name="connectionFactory"> + <bean class="org.apache.activemq.ActiveMQConnectionFactory"> + <property name="brokerURL" value="vm://localhost?broker.persistent=false&broker.useJmx=false"/> + </bean> + </property> +</bean> +---- + +Which allows you to configure a component using some name (activemq in +the above example), then you can refer to the component using +`activemq:[queue:|topic:]destinationName`. This works by the +`SpringCamelContext` lazily fetching components from the spring context +for the scheme name you use for link:endpoint.html[Endpoint] +link:uris.html[URIs] + +[[HowdoIconfigureendpoints-UsingEndpointURIs]] +Using Endpoint URIs +^^^^^^^^^^^^^^^^^^^ + +Another approach is to use the URI syntax. The URI syntax supports the +query notation. So for example with the link:mail.html[Mail] component +you can configure the password property via the URI + +[source] +---- +pop3://host:port?password=foo +---- + +[[HowdoIconfigureendpoints-ReferringbeansfromEndpointURIs]] +Referring beans from Endpoint URIs +++++++++++++++++++++++++++++++++++ + +*Available as of Camel 2.0* + +When configuring endpoints using URI syntax you can now refer to beans +in the link:registry.html[Registry] using the `#` notation. + +If the parameter value starts with a `#` sign then Camel will lookup in +the link:registry.html[Registry] for a bean of the given type. For +instance: + +[source] +---- +file://inbox?sorter=#mySpecialFileSorter +---- + +Will lookup a bean with the id `mySpecialFileSorter` in the +link:registry.html[Registry]. + +[[HowdoIconfigureendpoints-Configuringparametervaluesusingrawvalues,egsuchaspasswords]] +Configuring parameter values using raw values, eg such as passwords ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +*Available as of Camel 2.11* + +When configuring endpoint options using URI syntax, then the values is +by default URI encoded. This can be a problem if you want to configure +passwords and just use the value _as is_ without any encoding. For +example you may have a plus sign in the password, which would be decimal +encoded by default. + +So from Camel 2.11 onwards we made this easier as you can denote a +parameter value to be *raw* using the following syntax `RAW(value)`, e.g. +the value starts with `RAW(` and then ends with the parenthesis `)`. +Here is a little example: + +[source,java] +---- +.to("ftp:j...@myftpserver.com?password=RAW(se+re?t&23)&binary=true") +---- + +In the above example, we have declare the password value as raw, and the +actual password would be as typed, eg `se+re?t&23`. + +[[HowdoIconfigureendpoints-Usingpropertyplaceholders]] +Using property placeholders ++++++++++++++++++++++++++++ + +Camel have extensive support for using property placeholders, which you +can read more link:using-propertyplaceholder.html[about here]. For +example in the ftp example above we can externalize the password to a +`.properties` file. + +For example configuring the property placeholder when using a +link:dsl.html[XML DSL], where we declare the location of the `.properties` +file. Though we can also define this in Java code. See the +link:using-propertyplaceholder.html[documentation] for more details. + +[source,xml] +---- +<camelContext ...> + <propertyPlaceholder id="properties" location="myftp.properties"/> + ... +</camelContext> +---- + +And the Camel route now refers to the placeholder using the `{{key}}` +notation: + +[source,java] +---- +.to("ftp:j...@myftpserver.com?password={{myFtpPassword}}&binary=true" +---- + +And have a `myftp.properties` file with password. Notice we still define +the `RAW(value)` style to ensure the password is used _as is_: + +[source] +---- +myFtpPassword=RAW(se+re?t&23) +---- + +We could still have used the `RAW(value)` in the Camel route instead: + +[source,java] +---- +.to("ftp:j...@myftpserver.com?password=RAW({{myFtpPassword}})&binary=true") +---- + +And then we would need to remove the `RAW` from the properties file: + +[source] +---- +myFtpPassword=se+re?t&23 +---- + +To understand more about property placeholders, read the +link:using-propertyplaceholder.html[documentation]. + +[[HowdoIconfigureendpoints-Configuringurisusingendpointwithbeanpropertystyle]] +Configuring URIs using endpoint with bean property style +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.15* + +Sometimes configuring endpoint URIs may have many options, and therefore +the URI can become long. In Java DSL you can break the URIs into new +lines as its just Java code, e.g. just concat the `String`. When using XML +DSL then the URI is an attribute, e.g. `<from uri="bla bla"/>`. From Camel +2.15 onwards you can configure the endpoint separately, and from the +routes refer to the endpoints using their shorthand ids. + +[source,xml] +---- +<camelContext ...> + + <endpoint id="foo" uri="ftp://foo@myserver";> + <property name="password" value="secret"/> + <property name="recursive" value="true"/> + <property name="ftpClient.dataTimeout" value="30000"/> + <property name="ftpClient.serverLanguageCode" value="fr"/> + </endpoint> + + <route> + <from uri="ref:foo"/> + ... + </route> +</camelContext> +---- + + + +In the example above, the endpoint with id `foo`, is defined using +`<endpoint>` which under the covers assembles this as an URI, with all the +options, as if you have defined all the options directly in the URI. You +can still configure some options in the URI, and then use `<property>` +style for additional options, or to override options from the URI, such +as: + +[source] +---- +<endpoint id="foo" uri="ftp://foo@myserver?recursive=true";> + <property name="password" value="secret"/> + <property name="ftpClient.dataTimeout" value="30000"/> + <property name="ftpClient.serverLanguageCode" value="fr"/> +</endpoint> +---- + + + +[[HowdoIconfigureendpoints-Configuringlongurisusingnewlines]] +Configuring long URIs using new lines +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.15* + +Sometimes configuring endpoint URIs may have many options, and therefore +the URI can become long. In Java DSL you can break the URIs into new +lines as its just Java code, e.g. just concat the `String`. When using XML +DSL then the URI is an attribute, e.g. `<from uri="bla bla"/>`. From Camel +2.15 onwards you can break the URI attribute using new line, such as +shown below: + +[source,xml] +---- +<route> + <from uri="ftp://foo@myserver?password=secret& + recursive=true& + ftpClient.dataTimeout=30000& + ftpClientConfig.serverLanguageCode=fr"/> + <to uri="bean:doSomething"/> +</route> +---- + +Notice that it still requires to use escape `&` as `&l;` in XML. Also you +can have multiple options in one line, eg this is the same: + +[source,xml] +---- +<route> + <from uri="ftp://foo@myserver?password=secret& + recursive=true&ftpClient.dataTimeout=30000& + ftpClientConfig.serverLanguageCode=fr"/> + <to uri="bean:doSomething"/> +</route> +---- + +[[HowdoIconfigureendpoints-SeeAlso]] +See Also +~~~~~~~~ + +* link:how-do-i-add-a-component.html[How do I add a component] +* link:spring.html[Spring] +* link:uris.html[URIs] +* link:using-propertyplaceholder.html[Using `PropertyPlaceholder`]
