Properties component Asciidoc documentation
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/6fb1216b Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/6fb1216b Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/6fb1216b Branch: refs/heads/master Commit: 6fb1216b7a7e862d49b5203fd795e091b4c15317 Parents: 456928d Author: Antonin Stefanutti <[email protected]> Authored: Wed Jan 27 11:04:19 2016 +0100 Committer: Andrea Cosentino <[email protected]> Committed: Wed Jan 27 13:03:32 2016 +0100 ---------------------------------------------------------------------- camel-core/src/main/docs/properties.adoc | 989 ++++++++++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 990 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/6fb1216b/camel-core/src/main/docs/properties.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/properties.adoc b/camel-core/src/main/docs/properties.adoc new file mode 100644 index 0000000..5ed4cd7 --- /dev/null +++ b/camel-core/src/main/docs/properties.adoc @@ -0,0 +1,989 @@ +[[Properties-PropertiesComponent]] +Properties Component +~~~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.3* + +[[Properties-URIformat]] +URI format +^^^^^^^^^^ + +[source] +---- +properties:key[?options] +---- + +Where *key* is the key for the property to lookup + +[[Properties-Options]] +Options +^^^^^^^ + +[width="100%",cols="10%,10%,10%,70%",options="header",] +|======================================================================= +|Name |Type |Default |Description +|`cache` |`boolean` |`true` |Whether or not to cache loaded properties. + +|`locations` |`String` |`null` |A list of locations to load properties. +You can use comma to separate multiple locations. This option will +override any default locations and *only* use the locations from this +option. + +|`encoding` |`String` |`null` |*Camel 2.14.3/2.15.1:* To use a specific +charset to load the properties, such as UTF-8. By default ISO-8859-1 +(latin1) is used. + +|`ignoreMissingLocation` |`boolean` |`false` |*Camel 2.10:* Whether to +silently ignore if a location cannot be located, such as a properties +file not found. + +|`propertyPrefix` |`String` |`null` |*Camel 2.9* Optional prefix +prepended to property names before resolution. + +|`propertySuffix` |`String` |`null` |*Camel 2.9* Optional suffix +appended to property names before resolution. + +|`fallbackToUnaugmentedProperty` |`boolean` |`true` |*Camel 2.9* If +true, first attempt resolution of property name augmented with +`propertyPrefix` and `propertySuffix` before falling back the plain +property name specified. If false, only the augmented property name is +searched. + +|`prefixToken` |`String` |`{{` |*Camel 2.9* The token to indicate the +beginning of a property token. + +|`suffixToken` |`String` |`}}` |*Camel 2.9* The token to indicate the end +of a property token. + +|`systemPropertiesMode` |`int` |`2` a| +*Camel 2.16:* The mode to use for whether to resolve and use system +properties + +0 = never (JVM system properties is never used) + +1 = fallback (JVM system properties is only used as fallback if no +regular property with the key exists) + +2 = override (JVM system properties is used if exists, otherwise a the +regular property will be used) + +Notice when bridging this to Spring's property placeholder with +`org.apache.camel.spring.spi.BridgePropertyPlaceholderConfigurer` then +the configuration on `BridgePropertyPlaceholderConfigurer` takes +precedence over the configuration on the `PropertiesComponent`. + +|======================================================================= + +[Tip] +==== +**Resolving property from Java code** + +You can use the method `resolvePropertyPlaceholders` on the +`CamelContext` to resolve a property from any Java code. +==== + +[[Properties-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.html[Endpoint] URIs. + +This works much like you would do if using Spring's +`<property-placeholder>` tag. However Spring have a limitation which +prevents 3rd party frameworks to leverage Spring property placeholders +to the fullest. See more at +link:how-do-i-use-spring-property-placeholder-with-camel-xml.html[How do +I use Spring Property Placeholder with Camel XML]. + +[Tip] +==== +**Bridging Spring and Camel property placeholders** + +From Camel 2.10 onwards, you can bridge the Spring property placeholder +with Camel, see further below for more details. +==== + +The property placeholder is generally in use when doing: + +* lookup or creating endpoints +* lookup of beans in the link:registry.html[Registry] +* additional supported in Spring XML (see below in examples) +* using Blueprint PropertyPlaceholder with Camel +link:properties.html[Properties] 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. + +[[Properties-Syntax]] +Syntax +^^^^^^ + +The syntax to use Camel's property placeholder is to use `{{key}}` for +example `{{file.uri}}` where `file.uri` is the property key. + +You can use property placeholders in parts of the endpoint URI's which +for example you can use placeholders for parameters in the URIs. + +From **Camel 2.14.1** onwards you can specify a default value to use if +a property with the key does not exists, eg `file.url:/some/path` where +the default value is the text after the colon (eg /some/path). + +NOTE: Do not use colon in the property key. The colon is used as a separator +token when you are providing a default value, which is supported from +*Camel 2.14.1* onwards. + +[[Properties-PropertyResolver]] +PropertyResolver +^^^^^^^^^^^^^^^^ + +Camel provides a pluggable mechanism which allows 3rd part to provide +their own resolver to lookup 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.html[Registry]. You can prefix the locations with either: + +* `ref:` *Camel 2.4:* to lookup in the link:registry.html[Registry] +* `file:` to load the from file system +* `classpath:` to load from classpath (this is also the default if no +prefix is provided) +* `blueprint:` *Camel 2.7:* to use a specific OSGi blueprint placeholder +service + +[[Properties-Defininglocation]] +Defining location +^^^^^^^^^^^^^^^^^ + +The `PropertiesResolver` need to know a location(s) where to resolve the +properties. You can define 1 to many locations. If you define the +location in a single String property you can separate multiple locations +with comma such as: + +[source,java] +---- +pc.setLocation("com/mycompany/myprop.properties,com/mycompany/other.properties"); +---- + +[[Properties-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. + +For example: + +[source] +---- +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: + +[source] +---- +location=file:${env:APP_HOME}/etc/foo.properties +---- + +Where `APP_HOME` is an OS environment. + +You can have multiple placeholders in the same location, such as: + +[source] +---- +location=file:${env:APP_HOME}/etc/${prop.name}.properties +---- + +[[Properties-Usingsystemandenvironmentvariablestoconfigurepropertyprefixesandsuffixes]] +Using system and environment variables to configure property prefixes and suffixes +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +*Available as of Camel 2.12.5, 2.13.3, 2.14.0* + +`propertyPrefix`, `propertySuffix` configuration properties support +using placeholders for JVM system properties and OS environments +variables. + +For example. if `PropertiesComponent` is configured with the following +properties file: + +[source] +---- +dev.endpoint = result1 +test.endpoint = result2 +---- + +Then with the following 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}}"); + } +}); +---- + +it is possible to change the target endpoint by changing system +property `stage` either to `dev` (the message will be routed +to `mock:result1`) or `test` (the message will be routed +to `mock:result2`). + +[[Properties-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); +---- + +[[Properties-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 `<propertyPlaceholder>` tag. + +[source,xml] +---- +<bean id="properties" class="org.apache.camel.component.properties.PropertiesComponent"> + <property name="location" value="classpath:com/mycompany/myprop.properties"/> +</bean> +---- + +Using the `<propertyPlaceholder>` tag makes the configuration a bit more +fresh such as: + +[source,xml] +---- +<camelContext ...> + <propertyPlaceholder id="properties" location="com/mycompany/myprop.properties"/> +</camelContext> +---- + +[Tip] +==== +**Specifying the cache option inside XML** + +Camel 2.10 onwards supports specifying a value for the cache option both +inside the Spring as well as the Blueprint XML. +==== + +[[Properties-UsingaPropertiesfromthe]] +Using a Properties from the link:registry.html[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.html[Properties] component as +follows: + +[source,xml] +---- + <propertyPlaceholder id="properties" location="ref:myProperties"/> +---- + +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.html[Registry]. + +[[Properties-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"); +---- + +[[Properties-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.html[ProducerTemplate] for example: + +[source,java] +---- +template.sendBody("{{cool.start}}", "Hello World"); +---- + +[[Properties-Examplewithlanguage]] +Example with link:simple.html[Simple] language +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The link:simple.html[Simple] 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 link:simple.html[Simple] +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}."); +---- + +[[Properties-AdditionalpropertyplaceholdersupportedinSpringXML]] +Additional property placeholder supported in Spring XML +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The property placeholders is also supported in many of the Camel Spring +XML tags such as +`<package>, <packageScan>, <contextScan>, <jmxAgent>, <endpoint>, <routeBuilder>, <proxy>` +and the others. + +The example below has property placeholder in the `<jmxAgent>` tag: + +You can also define property placeholders in the various attributes on +the `<camelContext>` tag such as `trace` as shown here: + +[[Properties-OverridingapropertysettingusingaJVMSystemProperty]] +Overriding a property setting using a JVM System Property +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.5* + +It is possible to override a property value at runtime using a JVM +System property without the need to restart the application to pick up +the change. This may also be accomplished from the command line by +creating a JVM System property of the same name as the property it +replaces with a new value. An example of this is given below + +[source,java] +---- +PropertiesComponent pc = context.getComponent("properties", PropertiesComponent.class); +pc.setCache(false); + +System.setProperty("cool.end", "mock:override"); +System.setProperty("cool.result", "override"); + +context.addRoutes(new RouteBuilder() { + @Override + public void configure() throws Exception { + from("direct:start").to("properties:cool.end"); + from("direct:foo").to("properties:mock:{{cool.result}}"); + } +}); +context.start(); + +getMockEndpoint("mock:override").expectedMessageCount(2); + +template.sendBody("direct:start", "Hello World"); +template.sendBody("direct:foo", "Hello Foo"); + +System.clearProperty("cool.end"); +System.clearProperty("cool.result"); + +assertMockEndpointsSatisfied(); +---- + +[[Properties-UsingpropertyplaceholdersforanykindofattributeintheXMLDSL]] +Using property placeholders for any kind of attribute in the XML DSL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.7* + +NOTE: If you use OSGi Blueprint then this only works from *2.11.1* or *2.10.5* +onwards. + +Previously it was only the `xs:string` type attributes in the XML DSL +that support placeholders. For example often a timeout attribute would +be a `xs:int` type and thus you cannot set a string value as the +placeholder key. This is now possible from Camel 2.7 onwards using a +special placeholder namespace. + +In the example below we use the `prop` prefix for the namespace +`http://camel.apache.org/schema/placeholder` by which we can use the +`prop` prefix in the attributes in the XML DSLs. Notice how we use that +in the link:multicast.html[Multicast] to indicate that the option +`stopOnException` should be the value of the placeholder with the key +"stop". + +In our properties file we have the value defined as + +[source] +---- +stop=true +---- + +[[Properties-UsingpropertyplaceholderintheJavaDSL]] +Using property placeholder in the Java DSL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.7* + +Likewise we have added support for defining placeholders in the Java DSL +using the new `placeholder` DSL as shown in the following equivalent +example: + +[[Properties-UsingBlueprintpropertyplaceholderwithCamelroutes]] +Using Blueprint property placeholder with Camel routes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.7* + +Camel supports link:using-osgi-blueprint-with-camel.html[Blueprint] +which also offers a property placeholder service. Camel supports +convention over configuration, so all you have to do is to define the +OSGi Blueprint property placeholder in the XML file as shown below: + +*Using OSGi blueprint property placeholders in Camel routes* + +By default Camel detects and uses OSGi blueprint property placeholder +service. You can disable this by setting the attribute +`useBlueprintPropertyResolver` to false on the `<camelContext>` +definition. + +[Info] +==== +**About placeholder syntaxes** + +Notice how we can use the Camel syntax for placeholders `{{ }}` in the +Camel route, which will lookup the value from OSGi blueprint. + +The blueprint syntax for placeholders is `${ }`. So outside the +`<camelContext>` you must use the `${ }` syntax. Where as inside +`<camelContext>` you must use `{{ }}` syntax. + +OSGi blueprint allows you to configure the syntax, so you can actually +align those if you want. +==== + +You can also explicit refer to a specific OSGi blueprint property +placeholder by its id. For that you need to use the Camel's +`<propertyPlaceholder>` as shown in the example below: + +*Explicit referring to a OSGi blueprint placeholder in Camel* + +Notice how we use the `blueprint` scheme to refer to the OSGi blueprint +placeholder by its id. This allows you to mix and match, for example you +can also have additional schemes in the location. For example to load a +file from the classpath you can do: + +[source] +---- +location="blueprint:myblueprint.placeholder,classpath:myproperties.properties" +---- + +Each location is separated by comma. + +[[Properties-OverridingBlueprintpropertyplaceholdersoutsideCamelContext]] +Overriding Blueprint property placeholders outside CamelContext ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +*Available as of Camel 2.10.4* + +When using Blueprint property placeholder in the Blueprint XML file, you +can declare the properties directly in the XML file as shown below: + +Notice that we have a `<bean>` which refers to one of the properties. And +in the Camel route we refer to the other using the `{{ }}` notation. + +Now if you want to override these Blueprint properties from an unit +test, you can do this as shown below: + +To do this we override and implement the +`useOverridePropertiesWithConfigAdmin` method. We can then put the +properties we want to override on the given props parameter. And the +return value *must* be the `persistence-id` of the +`<cm:property-placeholder>` tag, which you define in the blueprint XML +file. + +[[Properties-Using.cfgor.propertiesfileforBlueprintpropertyplaceholders]] +Using .cfg or .properties file for Blueprint property placeholders +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +*Available as of Camel 2.10.4* + +When using Blueprint property placeholder in the Blueprint XML file, you +can declare the properties in a `.properties` or `.cfg` file. If you use +Apache ServieMix / Karaf then this container has a convention that it +loads the properties from a file in the etc directory with the naming +`etc/pid.cfg`, where `pid` is the `persistence-id`. + +For example in the blueprint XML file we have the +`persistence-id="stuff"`, which mean it will load the configuration file +as `etc/stuff.cfg`. + +Now if you want to unit test this blueprint XML file, then you can +override the `loadConfigAdminConfigurationFile` and tell Camel which +file to load as shown below: + +Notice that this method requires to return a `String[]` with 2 values. The +1st value is the path for the configuration file to load. +The 2nd value is the `persistence-id` of the `<cm:property-placeholder>` +tag. + +The `stuff.cfg` file is just a plain properties file with the property +placeholders such as: + +[source] +---- +## this is a comment +greeting=Bye +---- + +[[Properties-Using.cfgfileandoverridingpropertiesforBlueprintpropertyplaceholders]] +Using .cfg file and overriding properties for Blueprint property placeholders ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +You can do both as well. Here is a complete example. First we have the +Blueprint XML file: + +And in the unit test class we do as follows: + +And the `etc/stuff.cfg` configuration file contains + +[source] +---- +greeting=Bye +echo=Yay +destination=mock:result +---- + +[[Properties-BridgingSpringandCamelpropertyplaceholders]] +Bridging Spring and Camel property placeholders +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.10* + +The Spring Framework does not allow 3rd party frameworks such as Apache +Camel to seamless hook into the Spring property placeholder mechanism. +However you can easily bridge Spring and Camel by declaring a Spring +bean with the type +`org.apache.camel.spring.spi.BridgePropertyPlaceholderConfigurer`, which +is a Spring +`org.springframework.beans.factory.config.PropertyPlaceholderConfigurer` +type. + +To bridge Spring and Camel you must define a single bean as shown below: + +*Bridging Spring and Camel property placeholders* + +You *must not* use the spring <context:property-placeholder> namespace +at the same time; this is not possible. + +After declaring this bean, you can define property placeholders using +both the Spring style, and the Camel style within the <camelContext> tag +as shown below: + +*Using bridge property placeholders* + +Notice how the hello bean is using pure Spring property placeholders +using the `${ }` notation. And in the Camel routes we use the Camel +placeholder notation with `{{ }}`. + +[[Properties-ClashingSpringpropertyplaceholderswithCamelslanguage]] +Clashing Spring property placeholders with Camels link:simple.html[Simple] language ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Take notice when using Spring bridging placeholder then the spring `${ }` +syntax clashes with the link:simple.html[Simple] in Camel, and therefore +take care. For example: + +[source,xml] +---- +<setHeader headerName="Exchange.FILE_NAME"> + <simple>{{file.rootdir}}/${in.header.CamelFileName}</simple> +</setHeader> +---- + +clashes with Spring property placeholders, and you should use `$simple{ }` +to indicate using the link:simple.html[Simple] language in Camel. + +[source,xml] +---- +<setHeader headerName="Exchange.FILE_NAME"> + <simple>{{file.rootdir}}/$simple{in.header.CamelFileName}</simple> +</setHeader> +---- + +An alternative is to configure the `PropertyPlaceholderConfigurer` with +`ignoreUnresolvablePlaceholders` option to `true`. + +[[Properties-OverridingpropertiesfromCameltestkit]] +Overriding properties from Camel test kit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.10* + +When link:testing.html[Testing] with Camel and using the +link:properties.html[Properties] component, you may want to be able to +provide the properties to be used from directly within the unit test +source code. + +This is now possible from Camel 2.10 onwards, as the Camel test kits, eg +`CamelTestSupport` class offers the following methods + +* `useOverridePropertiesWithPropertiesComponent` +* `ignoreMissingLocationWithPropertiesComponent` + +So for example in your unit test classes, you can override the +`useOverridePropertiesWithPropertiesComponent` method and return a +`java.util.Properties` that contains the properties which should be +preferred to be used. + +*Providing properties from within unit test source* + +This can be done from any of the Camel Test kits, such as camel-test, +camel-test-spring, and camel-test-blueprint. + +The `ignoreMissingLocationWithPropertiesComponent` can be used to +instruct Camel to ignore any locations which was not discoverable, for +example if you run the unit test, in an environment that does not have +access to the location of the properties. + +[[Properties-UsingPropertyInject]] +Using @PropertyInject +^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.12* + +Camel allows to inject property placeholders in POJOs using the +`@PropertyInject` annotation which can be set on fields and setter +methods. + +For example you can use that with `RouteBuilder` classes, such as shown +below: + +[source,java] +---- +public class MyRouteBuilder extends RouteBuilder { + + @PropertyInject("hello") + private String greeting; + + @Override + public void configure() throws Exception { + from("direct:start") + .transform().constant(greeting) + .to("{{result}}"); + } + +} +---- + +Notice we have annotated the greeting field with `@PropertyInject` and +define it to use the key `"hello"`. Camel will then lookup the property +with this key and inject its value, converted to a String type. + +You can also use multiple placeholders and text in the key, for example +we can do: + +[source,java] +---- + @PropertyInject("Hello {{name}} how are you?") + private String greeting; +---- + +This will lookup the placeholder with they key `"name"`. + +You can also add a default value if the key does not exists, such as: + +[source,java] +---- + @PropertyInject(value = "myTimeout", defaultValue = "5000") + private int timeout; +---- + +[[Properties-Usingoutoftheboxfunctions]] +Using out of the box functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.14.1* + +The link:properties.html[Properties] component includes the following +functions out of the box + +* `env` - A function to lookup the property from OS environment variables +* `sys` - A function to lookup the property from Java JVM system +properties +* `service` - A function to lookup the property from OS environment +variables using the service naming idiom +* `service.name` - **Camel 2.16.1: **A function to lookup the +property from OS environment variables using the service naming idiom +returning the hostname part only +* `service.port` - **Camel 2.16.1: **A function to lookup the +property from OS environment variables using the service naming idiom +returning the port part only + +As you can see these functions is intended to make it easy to lookup +values from the environment. As they are provided out of the box, they +can easily be used as shown below: + +[source,xml] +---- + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + + <route> + <from uri="direct:start"/> + <to uri="{{env:SOMENAME}}"/> + <to uri="{{sys:MyJvmPropertyName}}"/> + </route> + </camelContext> +---- + +You can use default values as well, so if the property does not exists, +you can define a default value as shown below, where the default value +is a `log:foo` and `log:bar` value. + +[source,xml] +---- + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + + <route> + <from uri="direct:start"/> + <to uri="{{env:SOMENAME:log:foo}}"/> + <to uri="{{sys:MyJvmPropertyName:log:bar}}"/> + </route> + </camelContext> +---- + + + +The service function is for looking up a service which is defined using +OS environment variables using the service naming idiom, to refer to a +service location using `hostname : port` + +* __NAME__**_SERVICE_HOST** +* __NAME__**_SERVICE_PORT** + +in other words the service uses `_SERVICE_HOST` and `_SERVICE_PORT` as +prefix. So if the service is named FOO, then the OS environment +variables should be set as + +[source] +---- +export $FOO_SERVICE_HOST=myserver +export $FOO_SERVICE_PORT=8888 +---- + + + +For example if the FOO service a remote HTTP service, then we can refer +to the service in the Camel endpoint uri, and use +the link:http.html[HTTP] component to make the HTTP call: + +[source,xml] +---- + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + + <route> + <from uri="direct:start"/> + <to uri="http://{{service:FOO}}/myapp"/> + </route> + </camelContext> +---- + + + +And we can use default values if the service has not been defined, for +example to call a service on localhost, maybe for unit testing etc + +[source,xml] +---- + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + + <route> + <from uri="direct:start"/> + <to uri="http://{{service:FOO:localhost:8080}}/myapp"/> + </route> + </camelContext> +---- + +[[Properties-Usingcustomfunctions]] +Using custom functions +^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.14.1* + +The link:properties.html[Properties] component allow to plugin 3rd party +functions which can be used during parsing of the property placeholders. +These functions are then able to do custom logic to resolve the +placeholders, such as looking up in databases, do custom computations, +or whatnot. The name of the function becomes the prefix used in the +placeholder. This is best illustrated in the example code below + +[source,xml] +---- + <bean id="beerFunction" class="MyBeerFunction"/> + + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + <propertyPlaceholder id="properties" location="none" ignoreMissingLocation="true"> + <propertiesFunction ref="beerFunction"/> + </propertyPlaceholder> + + <route> + <from uri="direct:start"/> + <to uri="{{beer:FOO}}"/> + <to uri="{{beer:BAR}}"/> + </route> + </camelContext> +---- + +Here we have a Camel XML route where we have defined the +`<propertyPlaceholder>` to use a custom function, which we refer to be the +bean id - eg the `beerFunction`. As the beer function uses `"beer"` as its +name, then the placeholder syntax can trigger the beer function by +starting with `beer:value`. + +The implementation of the function is only two methods as shown below: + +[source,java] +---- + public static final class MyBeerFunction implements PropertiesFunction { + + @Override + public String getName() { + return "beer"; + } + + @Override + public String apply(String remainder) { + return "mock:" + remainder.toLowerCase(); + } + } +---- + +The function must implement +the `org.apache.camel.component.properties.PropertiesFunction` +interface. The method `getName` is  the name of the function, eg beer. +And the `apply` method is where we implement the custom logic to do. As +the sample code is from an unit test, it just returns a value to refer +to a mock endpoint. + +To register a custom function from Java code is as shown below: + +[source,java] +---- + PropertiesComponent pc = context.getComponent("properties", PropertiesComponent.class); + pc.addFunction(new MyBeerFunction()); +---- + + + +[[Properties-SeeAlso]] +See Also +~~~~~~~~ + +* link:properties.html[Properties] component + +[[Properties-SeeAlso.1]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + +* link:jasypt.html[Jasypt] for using encrypted values (eg passwords) in +the properties http://git-wip-us.apache.org/repos/asf/camel/blob/6fb1216b/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index aa03636..588aa08 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -93,6 +93,7 @@ * [CDI](cdi.adoc) * [JMS](jms.adoc) * [Metrics](metrics.adoc) + * [Properties](properties.adoc) * [SJMS](sjms.adoc) * [SJMS Batch](sjms-batch.adoc)
