From commits-return-64936-apmail-camel-commits-archive=camel.apache.org@camel.apache.org Fri Sep 7 09:55:28 2018 Return-Path: X-Original-To: apmail-camel-commits-archive@www.apache.org Delivered-To: apmail-camel-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id D0A7D1E709 for ; Fri, 7 Sep 2018 09:55:28 +0000 (UTC) Received: (qmail 55963 invoked by uid 500); 7 Sep 2018 09:55:28 -0000 Delivered-To: apmail-camel-commits-archive@camel.apache.org Received: (qmail 55911 invoked by uid 500); 7 Sep 2018 09:55:28 -0000 Mailing-List: contact commits-help@camel.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@camel.apache.org Delivered-To: mailing list commits@camel.apache.org Received: (qmail 55901 invoked by uid 99); 7 Sep 2018 09:55:28 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 07 Sep 2018 09:55:28 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id C4BA78518F; Fri, 7 Sep 2018 09:55:27 +0000 (UTC) Date: Fri, 07 Sep 2018 09:55:27 +0000 To: "commits@camel.apache.org" Subject: [camel] branch master updated: CAMEL-11497: Migrate 'Working with Camel and ...' guides and related docs (#2512) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Message-ID: <153631412751.31340.4762509394227558055@gitbox.apache.org> From: acosentino@apache.org X-Git-Host: gitbox.apache.org X-Git-Repo: camel X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: 42a3adcb889881168455b5271f0c5e99d9a193d8 X-Git-Newrev: f303135d22d7dad4a68102f54ad3ea869d2ce500 X-Git-Rev: f303135d22d7dad4a68102f54ad3ea869d2ce500 X-Git-NotificationType: ref_changed_plus_diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated This is an automated email from the ASF dual-hosted git repository. acosentino pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/camel.git The following commit(s) were added to refs/heads/master by this push: new f303135 CAMEL-11497: Migrate 'Working with Camel and ...' guides and related docs (#2512) f303135 is described below commit f303135d22d7dad4a68102f54ad3ea869d2ce500 Author: Tadayoshi Sato AuthorDate: Fri Sep 7 18:55:24 2018 +0900 CAMEL-11497: Migrate 'Working with Camel and ...' guides and related docs (#2512) --- docs/user-manual/en/SUMMARY.md | 21 +- docs/user-manual/en/component.adoc | 42 + docs/user-manual/en/examples.adoc | 55 ++ docs/user-manual/en/guice-jms-example.adoc | 61 ++ docs/user-manual/en/guice-maven-plugin.adoc | 160 +++ docs/user-manual/en/guice.adoc | 155 +++ docs/user-manual/en/how-do-i-add-a-component.adoc | 72 ++ ...spring-property-placeholder-with-camel-xml.adoc | 77 ++ docs/user-manual/en/producertemplate.adoc | 103 ++ docs/user-manual/en/route-builder.adoc | 10 +- docs/user-manual/en/uris.adoc | 28 + docs/user-manual/en/using-propertyplaceholder.adoc | 1032 ++++++++++++++++++++ docs/user-manual/en/writing-components.adoc | 158 +++ 13 files changed, 1960 insertions(+), 14 deletions(-) diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index e72393e..dc14a25 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -15,6 +15,7 @@ * [Camel Core](camel-core.adoc) * [CamelContext](camelcontext.adoc) * [CEP](cep.adoc) + * [Component](component.adoc) * [Debugger](debugger.adoc) * [Delay Interceptor](delay-interceptor.adoc) * [Dependency Injection](dependency-injection.adoc) @@ -41,14 +42,13 @@ * [OnCompletion](oncompletion.adoc) * [Predicate](predicate.adoc) * [Registry](registry.adoc) - * [Scala DSL](scala-dsl.adoc) + * [RouteBuilder](route-builder.adoc) + * [Routes](routes.adoc) + + mypackage.boot.camel.CamelStartup + + +---- + +[[GuiceMavenPlugin-MakinguseofanoptionalJNDIpropertiesfile]] +==== Making use of an optional JNDI properties file + +*Available as of Camel 2.13.0* + +Optionally if the name of your JNDI properties file is something else +other than the default `jndi.properties` or if it's not on the default +classpath, then you can make use of the `jndiProperties` option as shown +below: + +[source,xml] +---- + + org.apache.camel + guice-maven-plugin + + /path/to/my/jndi/properties/my-guice-jndi.properties + + +---- + + +[[GuiceMavenPlugin-Classpath]] +==== Classpath + +The plugin will construct a classpath of any Maven dependency with scope +`compile`. The classpath is output as an `INFO` log statement upon +startup. + + +[[GuiceMavenPlugin-RouteInformation]] +==== Route Information + +Information about the generated routes is available through the GraphViz +report, and also through the log statements generated by the run goal. +If you would like to see this information then add a log4j (or other +commons-logging implementation) config file with the following levels. + +===== src/main/resources/log4.properties + +[source,java] +---- +log4j.rootLogger=INFO, stdout +log4j.appender.stdout=org.apache.log4j.ConsoleAppender +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout +log4j.appender.stdout.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n + +log4j.logger.org.apache.camel.impl.DefaultCamelContext=DEBUG, stdout +log4j.additivity.org.apache.camel.impl.DefaultCamelContext=false +---- + +This should produce a log statement similar to: + +.... +670 [org.apache.camel.guice.Main.main()] DEBUG org.apache.camel.impl.DefaultCamelContext - Adding routes from: Routes: [Route[ [From[jms:queue:queueA]] -> [To[jms:queue:queueB], To[jms:queue:queueC]]]] routes: [] +.... + + +[[GuiceMavenPlugin-IntegrationintoMavenReports]] +==== Integration into Maven Reports + +If you add the guice-maven-plugin to your `` section of your +pom you will automatically get the +link:visualisation.adoc[Visualisation] reporting generated for your +project as part of the regular maven site generation. + +For example add the following into your pom: + +[source,xml] +---- + + ... + + + + org.apache.camel + guice-maven-plugin + + + + +---- + +Then when you run: + +.... +mvn site +.... + +Your context will be booted up via the `jndi.properties` files, the DOT +file generated and a nice HTML report created. + +===== GraphViz DOT required + +Note to get the nice HTML, PNG and SVG outputs from the DOT files you +will need to install the http://graphviz.org[GraphViz] DOT executable +and add it to your PATH so that the plugin can invoke DOT to generate +the PNG/SVG files. + +For more details see the link:camel-dot-maven-goal.adoc[guice:dot]. diff --git a/docs/user-manual/en/guice.adoc b/docs/user-manual/en/guice.adoc new file mode 100644 index 0000000..36650e8 --- /dev/null +++ b/docs/user-manual/en/guice.adoc @@ -0,0 +1,155 @@ +[[Guice-CamelGuice]] +=== Camel Guice + +We have support for https://github.com/google/guice[Google Guice] +as a dependency injection framework. + +Maven users will need to add the following dependency to their `pom.xml` +for this component: + +[source,xml] +---- + + org.apache.camel + camel-guice + x.x.x + + +---- + +[[Guice-DependencyInjectingCamelwithGuice]] +==== Dependency Injecting Camel with Guice + +The +http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/GuiceCamelContext.html[GuiceCamelContext] +is designed to work nicely inside Guice. You then need to bind it using +some Guice Module. + +The camel-guice library comes with a number of reusable Guice Modules +you can use if you wish - or you can bind the GuiceCamelContext yourself +in your own module. + +* http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModule.html[CamelModule] +is the base module which binds the GuiceCamelContext but leaves it up +you to bind the RouteBuilder instances +* http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModuleWithRouteTypes.html[CamelModuleWithRouteTypes] +extends CamelModule so that in the constructor of the module you specify +the RouteBuilder classes or instances to use +* http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModuleWithMatchingRoutes.html[CamelModuleWithMatchingRoutes] +extends CamelModule so that all bound RouteBuilder instances will be +injected into the CamelContext or you can supply an optional Matcher to +find RouteBuilder instances matching some kind of predicate. + +So you can specify the exact link:route-builder.adoc[RouteBuilder] +instances you want: + +[source,java] +---- +Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes(MyRouteBuilder.class, AnotherRouteBuilder.class)); +// if required you can lookup the CamelContext +CamelContext camelContext = injector.getInstance(CamelContext.class); +---- + +Or inject them all: + +[source,java] +---- +Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes()); +// if required you can lookup the CamelContext +CamelContext camelContext = injector.getInstance(CamelContext.class); +---- + +You can then use Guice in the usual way to inject the route instances or +any other dependent objects. + +[[Guice-BootstrappingwithJNDI]] +==== Bootstrapping with JNDI + +A common pattern used in J2EE is to bootstrap your application or root +objects by looking them up in JNDI. This has long been the approach when +working with JMS for example - looking up the JMS ConnectionFactory in +JNDI for example. + +You can follow a similar pattern with Guice using the +https://code.google.com/archive/p/guiceyfruit/wikis/JNDI.wiki[GuiceyFruit JNDI +Provider] which lets you bootstrap Guice from a `jndi.properties` file +which can include the Guice Modules to create along with environment +specific properties you can inject into your modules and objects. + +If the `jndi.properties` is conflict with other component, you can +specify the jndi properties file name in the Guice Main with option `-j` +or `-jndiProperties` with the properties file location to let Guice Main +to load right jndi properties file. + +[[Guice-ConfiguringComponent,EndpointorRouteBuilderinstances]] +==== Configuring Component, Endpoint or RouteBuilder instances + +You can use Guice to dependency inject whatever objects +you need to create, be it an link:endpoint.adoc[Endpoint], +link:component.adoc[Component], link:route-builder.adoc[RouteBuilder] or +arbitrary link:bean-integration.adoc[bean used within a route]. + +The easiest way to do this is to create your own Guice Module class +which extends one of the above module classes and add a provider method +for each object you wish to create. A provider method is annotated with +`@Provides` as follows: + +[source,java] +---- +public class MyModule extends CamelModuleWithMatchingRoutes { + + @Provides + @JndiBind("jms") + JmsComponent jms(@Named("activemq.brokerURL") String brokerUrl) { + return JmsComponent.jmsComponent(new ActiveMQConnectionFactory(brokerUrl)); + } +} +---- + +You can optionally annotate the method with `@JndiBind` to bind the +object to JNDI at some name if the object is a component, endpoint or +bean you wish to refer to by name in your routes. + +You can inject any environment specific properties (such as URLs, +machine names, usernames/passwords and so forth) from the +`jndi.properties` file easily using the `@Named` annotation as shown +above. This allows most of your configuration to be in Java code which +is typesafe and easily refactorable - then leaving some properties to be +environment specific (the `jndi.properties` file) which you can then +change based on development, testing, production, etc. + +[[Guice-CreatingmultipleRouteBuilderinstancespertype]] +==== Creating multiple RouteBuilder instances per type + +It is sometimes useful to create multiple instances of a particular +link:route-builder.adoc[RouteBuilder] with different configurations. + +To do this just create multiple provider methods for each configuration; +or create a single provider method that returns a collection of +RouteBuilder instances. + +For example: + +[source,java] +---- +import org.apache.camel.guice.CamelModuleWithMatchingRoutes; +import com.google.common.collect.Lists; + +public class MyModule extends CamelModuleWithMatchingRoutes { + + @Provides + @JndiBind("foo") + Collection foo(@Named("fooUrl") String fooUrl) { + return Lists.newArrayList(new MyRouteBuilder(fooUrl), new MyRouteBuilder("activemq:CheeseQueue")); + } +} +---- + +[[Guice-SeeAlso]] +==== See Also + +* There are a number of link:examples.adoc[Examples] you can look at to +see Guice and Camel being used such as link:guice-jms-example.adoc[Guice +JMS Example] +* link:guice-maven-plugin.adoc[Guice Maven Plugin] for running your +Guice based routes via Maven diff --git a/docs/user-manual/en/how-do-i-add-a-component.adoc b/docs/user-manual/en/how-do-i-add-a-component.adoc new file mode 100644 index 0000000..9541e2d --- /dev/null +++ b/docs/user-manual/en/how-do-i-add-a-component.adoc @@ -0,0 +1,72 @@ +[[HowdoIaddacomponent-HowdoIaddacomponent]] +=== How do I add a component + +You might first want to read link:writing-components.adoc[Writing +Components] for a background in how to implement a new component. +Typically it means you write an implementation of the +http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Component.html[Component] +interface, usually deriving from +http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/impl/DefaultComponent.html[DefaultComponent]. + +You can then register your component explicitly via: + +[source,java] +---- +CamelContext context = new DefaultCamelContext(); +context.addComponent("foo", new FooComponent(context)); +---- + +However you can use the auto-discovery feature of Camel where by Camel +will automatically add a link:component.adoc[Component] when an endpoint +URI is used. To do this you would create a file called: + +.... +/META-INF/services/org/apache/camel/component/foo +.... + +with contents: + +[source,java] +---- +class=org.acme.FooComponent +---- + +(You can add other property configurations in there too if you like.) + +Then if you refer to an endpoint as `foo://somethingOrOther` Camel +will auto-discover your component and register it. + +The `FooComponent` can then be auto-injected with resources using the +http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/spi/Injector.html[Injector], +such as to support link:spring.adoc[Spring] based auto-wiring, or to +support `@Resource` (EJB3 style) injection or Guice style `@Inject` +injection. + + +[[HowdoIaddacomponent-WorkingwithSpringXML]] +==== Working with Spring XML + +You can configure a component via Spring using the following mechanism: + +include::../../../components/camel-jms/src/test/resources/org/apache/camel/component/jms/jmsRouteUsingSpring.xml[] + +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`. + +If you want to add explicit Spring 2.x XML objects to your XML then you +could use the `xbean-spring` which tries to automate most of the XML +binding work for you; or you could look in camel-spring +at `CamelNamespaceHandler` you'll see how we handle the Spring XML +stuff (warning it's kinda hairy code to look at :smile:). +If you wanted `` to be a standard part of the core Camel +schema then you'd hack that file to add your component & +link:contributing.adoc[contribute a patch] to the camel XSD. Otherwise +you could write your own namespace & schema if you prefer. + + +[[HowdoIaddacomponent-SeeAlso]] +==== See Also + +* link:writing-components.adoc[Writing Components] +* link:how-do-i-configure-endpoints.adoc[How do I configure endpoints?] diff --git a/docs/user-manual/en/how-do-i-use-spring-property-placeholder-with-camel-xml.adoc b/docs/user-manual/en/how-do-i-use-spring-property-placeholder-with-camel-xml.adoc new file mode 100644 index 0000000..7b9283c --- /dev/null +++ b/docs/user-manual/en/how-do-i-use-spring-property-placeholder-with-camel-xml.adoc @@ -0,0 +1,77 @@ +[[HowdoIuseSpringPropertyPlaceholderwithCamelXML-HowdoIuseSpringPropertyPlaceholderwithCamelXML]] +=== How do I use Spring Property Placeholder with Camel XML + +We do *NOT* yet support the `${something}` notation inside arbitrary +Camel XML. For example at the time of writing this is *NOT* supported +(due Spring limitations). + +*IS NOT SUPPORTED* + +[source,xml] +---- + + + + + + + + + + + + +---- + +However you can use the `` element to define endpoints which +does support the property resolving which you can then refer to by name, +using the <> component as shown below (notice the `ref:` +in the URI): + +*SUPPORTED* + +[source,xml] +---- + + + + + + + + + + + + + + +---- + +Camel does not yet fully support property placeholders as there is a +limitation in Spring. See JIRA +http://jira.springframework.org/browse/SPR-4466[SPR-4466] + +===== Bridge Spring and Camel property placeholders + +From Camel 2.10 onwards you can bridge Spring and Camel property +placeholders, see link:using-propertyplaceholder.adoc[Using +PropertyPlaceholder] for more details. + +Here is a trick that you can use to define the uri in a property file +using Spring injection and Camel endpoint: +http://cmoulliard.blogspot.com/2009/05/trick-to-pass-uri-declared-in-property.html. + +From Camel 2.3 onwards there is a <> +component build in Camel core which allows you to use properties in the +same way as Spring property placeholders, and even more. diff --git a/docs/user-manual/en/producertemplate.adoc b/docs/user-manual/en/producertemplate.adoc new file mode 100644 index 0000000..e6348a5 --- /dev/null +++ b/docs/user-manual/en/producertemplate.adoc @@ -0,0 +1,103 @@ +[[ProducerTemplate-ProducerTemplate]] +=== ProducerTemplate + +The ProducerTemplate interface allows you to send message exchanges to +endpoints in a variety of different ways to make it easy to work with +Camel link:endpoint.adoc[Endpoint] instances from Java code. + +It can be configured with a default endpoint if you just want to send +lots of messages to the same endpoint; or you can specify an +link:endpoint.adoc[Endpoint] or uri as the first parameter. + +The `sendBody()` method allows you to send any object to an endpoint +easily. + +[source,java] +---- +ProducerTemplate template = exchange.getContext().createProducerTemplate(); + +// send to default endpoint +template.sendBody("world!"); + +// send to a specific queue +template.sendBody("activemq:MyQueue", "world!"); + +// send with a body and header +template.sendBodyAndHeader("activemq:MyQueue", + "world!", + "CustomerRating", "Gold"); +---- + +You can also supply an `Exchange` or a `Processor` to customize the exchange. + + +[[ProducerTemplate-requestmethods]] +==== `request*()` methods + +The `send*()` methods use the default Message Exchange Pattern (InOnly, +InOut etc) as the endpoint. If you want to explicitly perform a +request/response (InOut) you can use the `request*()` methods instead of +the `send*()` methods. + +E.g. let's invoke an endpoint and get the response: + +[source,java] +---- +Object response = template.requestBody(""); + +// you can cast the response directly +String ret = template.requestBody("", String.class); + +// or specify the endpoint directly +String ret = template.requestBody("cxf:bean:HelloWorldService", "", String.class); +---- + + +[[ProducerTemplate-Fluentinterface]] +==== Fluent interface + +*Available as of Camel 2.18.0* + +The FluentProducerTemplate provides a fluent syntax to +ProducerTemplate. + +Examples: + +*Set headers and body* + +[source,java] +---- +Integer result = FluentProducerTemplate.on(context) + .withHeader("key-1", "value-1") + .withHeader("key-2", "value-2") + .withBody("Hello") + .to("direct:inout") + .request(Integer.class); +---- + +*Use a processor* + +[source,java] +---- +Integer result = FluentProducerTemplate.on(context) + .withProcessor(exchange -> exchange.getIn().setBody("Hello World")) + .to("direct:exception") + .request(Integer.class); +---- + +*Customize template* + +[source,java] +---- +Object result = FluentProducerTemplate.on(context) + .withTemplateCustomizer( + template -> { + template.setExecutorService(myExecutor); + template.setMaximumCacheSize(10); + } + ) + .withBody("the body") + .to("direct:start") + .request(); +  +---- diff --git a/docs/user-manual/en/route-builder.adoc b/docs/user-manual/en/route-builder.adoc index a021f9d..b5adcfe 100644 --- a/docs/user-manual/en/route-builder.adoc +++ b/docs/user-manual/en/route-builder.adoc @@ -1,9 +1,11 @@ [[RouteBuilder-RouteBuilder]] -RouteBuilder -~~~~~~~~~~~~ -The RouteBuilder is a base class which is derived from to create routing rules using the DSL. Instances of RouteBuilder are then added to the CamelContext. +=== RouteBuilder + +The RouteBuilder is a base class which is derived from to create routing rules using the DSL. +Instances of RouteBuilder are then added to the CamelContext. + +==== See Also -See Also * link:camelcontext.adoc[CamelContext] * link:routes.adoc[Routes] * link:architecture.adoc[Architecture] diff --git a/docs/user-manual/en/uris.adoc b/docs/user-manual/en/uris.adoc new file mode 100644 index 0000000..54a6c45 --- /dev/null +++ b/docs/user-manual/en/uris.adoc @@ -0,0 +1,28 @@ +[[URIs-URIs]] +=== URIs + +Camel makes extensive use of URIs to allow you to refer to endpoints +which are lazily created by a link:component.adoc[Component] if you +refer to them within link:routes.adoc[Routes]. + +[IMPORTANT] +==== +Make sure to read +link:how-do-i-configure-endpoints.adoc[How do I configure endpoints] +to learn more about configuring endpoints. For +example how to refer to beans in the link:registry.adoc[Registry] or how +to use raw values for password options, and using +link:using-propertyplaceholder.adoc[property placeholders] etc. +==== + + +[[URIs-CurrentSupportedURIs]] +==== Current Supported URIs + +===== Core Components + +include::../../../camel-core/readme.adoc[] + +===== Components + +include::../../../components/readme.adoc[] diff --git a/docs/user-manual/en/using-propertyplaceholder.adoc b/docs/user-manual/en/using-propertyplaceholder.adoc new file mode 100644 index 0000000..4f016b1 --- /dev/null +++ b/docs/user-manual/en/using-propertyplaceholder.adoc @@ -0,0 +1,1032 @@ +[[UsingPropertyPlaceholder-UsingPropertyPlaceholder]] +=== Using `PropertyPlaceholder` + +*Available as of Camel 2.3* + +Camel now provides a new `PropertiesComponent` in `camel-core` which +allows you to use property placeholders when defining Camel +link:endpoint.adoc[Endpoint] URIs. This works much like you would do if +using Spring's `` tag. However Spring has a +limitation that prevents third-party frameworks from fully leveraging +Spring property placeholders. + +For more details see: +link:how-do-i-use-spring-property-placeholder-with-camel-xml.adoc[How do +I use Spring Property Placeholder with Camel XML]. + +[[UsingPropertyPlaceholder-BridgingSpringandCamelPropertyPlaceholders]] +===== Bridging Spring and Camel Property Placeholders + +From *Camel 2.10*: Spring's property placeholder can be bridged with +Camel's. See below for more details. + +The property placeholder is typically used when trying to do any of the +following: + +* Lookup or creating endpoints +* Lookup of beans in the link:registry.adoc[Registry] +* Additional supported in Spring XML (see below in examples) +* Using Blueprint `PropertyPlaceholder` with Camel +<> component +* Using `@PropertyInject` to inject a property in a POJO +* *Camel 2.14.1* Using default value if a property does not exists +* *Camel 2.14.1* Include out of the box functions, to lookup property +values from OS environment variables, JVM system properties, or the +service idiom +* *Camel 2.14.1* Using custom functions, which can be plugged into the +property component + +[[UsingPropertyPlaceholder-Format]] +==== Format + +The value of a Camel property can be obtained by specifying its key name +within a property placeholder, using the following format: `{{key}}` + +For example: +.... +{{file.uri}} +.... + +where `file.uri` is the property key. + +Property placeholders can be used to specify parts, or all, of an +endpoint's URI by embedding one or more placeholders in the URI's string +definition. + +From *Camel 2.14.1*: you can specify a default value to use if a +property with the key does not exists, e.g., `file.url:/some/path` +where the default value is the text after the colon, e.g., +`/some/path`. + +From *Camel 2.14.1*: do _not_ use a colon in the property key. The colon +character is used as a token separator when providing a default value. + +[[UsingPropertyPlaceholder-UsingPropertyResolver]] +==== Using `PropertyResolver` + +Camel provides a pluggable mechanism that allows third-parties to +specify their own resolver to use for the lookup of properties. + +Camel provides a default implementation +`org.apache.camel.component.properties.DefaultPropertiesResolver` +which is capable of loading properties from the file system, classpath +or link:registry.adoc[Registry]. To indicate which source to use the +location must contain the appropriate prefix. + +The list of prefixes is: + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|Prefix |Description +|`ref:` |Lookup in the link:registry.adoc[Registry.] + +|`file:` |Load the from file system. + +|`classpath:` |Load from the classpath (this is also the default if no +prefix is provided). + +|`blueprint:` |Use a specific OSGi blueprint placeholder service. +|======================================================================= + +[[UsingPropertyPlaceholder-DefiningLocation]] +==== Defining Location + +The `PropertiesResolver` must be configured with the location(s) to +use when resolving properties. One or more locations can be given. +Specifying multiple locations can be done a couple of ways: using either +a single comma separated string, or an array of strings. + +[source,java] +---- +pc.setLocation("com/mycompany/myprop.properties,com/mycompany/other.properties"); +pc.setLocation(new String[] {"com/mycompany/myprop.properties", "com/mycompany/other.properties"}); +---- + +From *Camel 2.19.0*: you can set which location can be discarded if +missing by setting  `optional=true`, (`false` by default). + +Example: + +[source,java] +---- +pc.setLocations("com/mycompany/override.properties;optional=true,com/mycompany/defaults.properties"); +---- +  + +[[UsingPropertyPlaceholder-UsingSystemandEnvironmentVariablesinLocations]] +==== Using System and Environment Variables in Locations + +*Available as of Camel 2.7* + +The location now supports using placeholders for JVM system properties +and OS environments variables. + +Example: +.... +location=file:${karaf.home}/etc/foo.properties +.... + +In the location above we defined a location using the file scheme using +the JVM system property with key `karaf.home`. + +To use an OS environment variable instead you would have to prefix with +`env`: + +location=file:${env:APP_HOME}/etc/foo.properties + +Where `APP_HOME` is an OS environment variable. + +You can have multiple placeholders in the same location, such as: + +location=file:${env:APP_HOME}/etc/${prop.name}.properties + +[[UsingPropertyPlaceholder-UsingSystemorEnvironmentVariablestoConfigurePropertyPrefixesandSuffixes]] +==== Using System or Environment Variables to Configure Property Prefixes and Suffixes + +From *Camel 2.12.5, 2.13.3, 2.14.0*: `propertyPrefix`, +`propertySuffix` configuration properties support the use of +placeholders for de-referencing JVM system properties and OS +environments variables. + +Example: + +Assume the `PropertiesComponent` is configured with the following +properties file: + +[source,java] +---- +textdev.endpoint = result1 +test.endpoint = result2 +---- + +The same properties file is then referenced from a route definition: + + +[source,java] +---- +PropertiesComponent pc = context.getComponent("properties", +PropertiesComponent.class); pc.setPropertyPrefix("${stage}."); +// ... +context.addRoutes(new RouteBuilder() { + @Override + public void configure() throws Exception { + from("direct:start") + .to("properties:mock:{{endpoint}}"); + } +}); +---- + +By using the configuration options `propertyPrefix` it's possible to +change the target endpoint simply by changing the value of the system +property `stage` either to `dev` (the message will be routed +to `mock:result1`) or `test` (the message will be routed +to `mock:result2`). + +[[UsingPropertyPlaceholder-ConfiguringinJavaDSL]] +==== Configuring in Java DSL + +You have to create and register the `PropertiesComponent` under the +name `properties` such as: + + +[source,java] +---- +PropertiesComponent pc = new PropertiesComponent(); +pc.setLocation("classpath:com/mycompany/myprop.properties"); +context.addComponent("properties", pc); +---- + +[[UsingPropertyPlaceholder-ConfiguringinSpringXML]] +==== Configuring in Spring XML + +Spring XML offers two variations to configure. You can define a spring +bean as a `PropertiesComponent` which resembles the way done in Java +DSL. Or you can use the `` tag. + +[source,xml] +---- + + + +---- + +Using the `` tag makes the configuration a bit +more fresh such as: + +[source,xml] +---- + + + +---- + +Setting the properties location through the location tag works just fine +but sometime you have a number of resources to take into account and +starting from **Camel 2.19.0** you can set the properties location with +a dedicated `propertiesLocation`: + +[source,xml] +---- + + + + + + + +---- + +===== Specifying the cache option in XML + +From *Camel 2.10*: Camel supports specifying a value for the `cache` +option both inside the Spring as well as the Blueprint XML. + + +[[UsingPropertyPlaceholder-UsingaPropertiesfromthe]] +==== Using a Properties from the link:registry.adoc[Registry] + +*Available as of Camel 2.4* + +For example in OSGi you may want to expose a service which returns the +properties as a `java.util.Properties` object. + +Then you could setup the link:properties.adoc[Properties] component as +follows: + +[source,xml] +---- + +---- + +Where `myProperties` is the id to use for lookup in the OSGi registry. +Notice we use the `ref:` prefix to tell Camel that it should lookup +the properties for the link:registry.adoc[Registry]. + +[[UsingPropertyPlaceholder-ExamplesUsingPropertiesComponent]] +==== Examples Using Properties Component + +When using property placeholders in the endpoint URIs you can either use +the `properties:` component or define the placeholders directly in the +URI. We will show example of both cases, starting with the former. + +[source,java] +---- +// properties +cool.end=mock:result + +// route +from("direct:start") + .to("properties:{{cool.end}}"); +---- + +You can also use placeholders as a part of the endpoint URI: + +[source,java] +---- +// properties +cool.foo=result + +// route +from("direct:start") + .to("properties:mock:{{cool.foo}}"); +---- + +In the example above the to endpoint will be resolved to +`mock:result`. + +You can also have properties with refer to each other such as: + + +[source,java] +---- +// properties +cool.foo=result +cool.concat=mock:{{cool.foo}} + +// route +from("direct:start") + .to("properties:mock:{{cool.concat}}"); +---- + +Notice how `cool.concat` refer to another property. + +The `properties:` component also offers you to override and provide a +location in the given URI using the `locations` option: + + +[source,java] +---- +from("direct:start") + .to("properties:bar.end?locations=com/mycompany/bar.properties"); +---- + +[[UsingPropertyPlaceholder-Examples]] +==== Examples + +You can also use property placeholders directly in the endpoint URIs +without having to use `properties:`. + + +[source,java] +---- +// properties +cool.foo=result + +// route +from("direct:start") + .to("mock:{{cool.foo}}"); +---- + +And you can use them in multiple wherever you want them: + +[source,java] +---- +// properties +cool.start=direct:start +cool.showid=true +cool.result=result + +// route +from("{{cool.start}}") + .to("log:{{cool.start}}?showBodyType=false&showExchangeId={{cool.showid}}") + .to("mock:{{cool.result}}"); +---- + +You can also your property placeholders when using +link:producertemplate.adoc[ProducerTemplate] for example: + + +[source,java] +---- +template.sendBody("{{cool.start}}", "Hello World"); +---- + + +[[UsingPropertyPlaceholder-Examplewithlanguage]] +==== Example with <> language + +The <> language now also support using property +placeholders, for example in the route below: + + +[source,java] +---- +// properties +cheese.quote=Camel rocks + +// route from("direct:start") + .transform().simple("Hi ${body} do you think ${properties:cheese.quote}?"); +---- + +You can also specify the location in the <> +language for example: + + +[source,java] +---- +// bar.properties +bar.quote=Beer tastes good + +// route +from("direct:start") + .transform().simple("Hi ${body}. ${properties:com/mycompany/bar.properties:bar.quote}."); +---- + + +[[UsingPropertyPlaceholder-AdditionalPropertyPlaceholderSupportinSpringXML]] +==== Additional Property Placeholder Support in Spring XML + +The property placeholders is also supported in many of the Camel Spring +XML tags such as +``, ``, ``, ``, ``, ``, `` +and the others. + +Example using property placeholders in the `` tag: + +[source,xml] +---- + + + + + + + + + +---- + + +Example using property placeholders in the attributes of ``: + +[source,xml] +---- + + +