| [[velocity-component]] |
| == Velocity Component |
| |
| *Available as of Camel version 1.2* |
| |
| The *velocity:* component allows you to process a message using an |
| http://velocity.apache.org/[Apache Velocity] template. This can be ideal |
| when using Templating to generate responses for |
| requests. |
| |
| Maven users will need to add the following dependency to their `pom.xml` |
| for this component: |
| |
| [source,xml] |
| ------------------------------------------------------------ |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-velocity</artifactId> |
| <version>x.x.x</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ------------------------------------------------------------ |
| |
| ### URI format |
| |
| [source,java] |
| ------------------------------- |
| velocity:templateName[?options] |
| ------------------------------- |
| |
| Where *templateName* is the classpath-local URI of the template to |
| invoke; or the complete URL of the remote template (eg: |
| file://folder/myfile.vm[file://folder/myfile.vm]). |
| |
| You can append query options to the URI in the following format, |
| `?option=value&option=value&...` |
| |
| ### Options |
| |
| |
| |
| // component options: START |
| The Velocity component supports 2 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *velocityEngine* (advanced) | To use the VelocityEngine otherwise a new engine is created | | VelocityEngine |
| | *resolveProperty Placeholders* (advanced) | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | boolean |
| |=== |
| // component options: END |
| |
| |
| |
| |
| // endpoint options: START |
| The Velocity endpoint is configured using URI syntax: |
| |
| ---- |
| velocity:resourceUri |
| ---- |
| |
| with the following path and query parameters: |
| |
| ==== Path Parameters (1 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *resourceUri* | *Required* Path to the resource. You can prefix with: classpath, file, http, ref, or bean. classpath, file and http loads the resource using these protocols (classpath is default). ref will lookup the resource in the registry. bean will call a method on a bean to be used as the resource. For bean you can specify the method name after dot, eg bean:myBean.myMethod. | | String |
| |=== |
| |
| |
| ==== Query Parameters (5 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *contentCache* (producer) | Sets whether to use resource content cache or not | false | boolean |
| | *encoding* (producer) | Character encoding of the resource content. | | String |
| | *loaderCache* (producer) | Enables / disables the velocity resource loader cache which is enabled by default | true | boolean |
| | *propertiesFile* (producer) | The URI of the properties file which is used for VelocityEngine initialization. | | String |
| | *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean |
| |=== |
| // endpoint options: END |
| // spring-boot-auto-configure options: START |
| === Spring Boot Auto-Configuration |
| |
| |
| The component supports 3 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *camel.component.velocity.enabled* | Enable velocity component | true | Boolean |
| | *camel.component.velocity.resolve-property-placeholders* | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | Boolean |
| | *camel.component.velocity.velocity-engine* | To use the VelocityEngine otherwise a new engine is created. The option is a org.apache.velocity.app.VelocityEngine type. | | String |
| |=== |
| // spring-boot-auto-configure options: END |
| |
| |
| |
| ### Message Headers |
| |
| The velocity component sets a couple headers on the message (you can't |
| set these yourself and from Camel 2.1 velocity component will not set |
| these headers which will cause some side effect on the dynamic template |
| support): |
| |
| [width="100%",cols="10%,90%",options="header",] |
| |======================================================================= |
| |Header |Description |
| |
| |`CamelVelocityResourceUri` |The *templateName* as a `String` object. |
| |
| |`CamelVelocitySupplementalContext` |*Camel 2.16:* To add additional information to the used VelocityContext. |
| The value of this header should be a `Map` with key/values that will |
| added (override any existing key with the same name). + |
| This can be used to pre setup some common key/values you want to reuse |
| in your velocity endpoints. |
| |======================================================================= |
| |
| Headers set during the Velocity evaluation are returned to the message |
| and added as headers. Then its kinda possible to return values from |
| Velocity to the Message. |
| |
| For example, to set the header value of `fruit` in the Velocity template |
| `.tm`: |
| |
| [source,java] |
| ------------------------------- |
| $in.setHeader("fruit", "Apple") |
| ------------------------------- |
| |
| The `fruit` header is now accessible from the `message.out.headers`. |
| |
| ### Velocity Context |
| |
| Camel will provide exchange information in the Velocity context (just a |
| `Map`). The `Exchange` is transfered as: |
| |
| [width="100%",cols="10%,90%",options="header",] |
| |======================================================================= |
| |key |value |
| |
| |`exchange` |The `Exchange` itself. |
| |
| |`exchange.properties` |The `Exchange` properties. |
| |
| |`headers` |The headers of the In message. |
| |
| |`camelContext` |The Camel Context instance. |
| |
| |`request` |The In message. |
| |
| |`in` |The In message. |
| |
| |`body` |The In message body. |
| |
| |`out` |The Out message (only for InOut message exchange pattern). |
| |
| |`response` |The Out message (only for InOut message exchange pattern). |
| |======================================================================= |
| |
| Since Camel-2.14, you can setup a custom Velocity Context yourself by |
| setting the message header *CamelVelocityContext *just like this |
| |
| [source,java] |
| ----------------------------------------------------------------------- |
| VelocityContext velocityContext = new VelocityContext(variableMap); |
| exchange.getIn().setHeader("CamelVelocityContext", velocityContext); |
| ----------------------------------------------------------------------- |
| |
| |
| |
| ### Hot reloading |
| |
| The Velocity template resource is, by default, hot reloadable for both |
| file and classpath resources (expanded jar). If you set |
| `contentCache=true`, Camel will only load the resource once, and thus |
| hot reloading is not possible. This scenario can be used in production, |
| when the resource never changes. |
| |
| ### Dynamic templates |
| |
| *Available as of Camel 2.1* + |
| Camel provides two headers by which you can define a different resource |
| location for a template or the template content itself. If any of these |
| headers is set then Camel uses this over the endpoint configured |
| resource. This allows you to provide a dynamic template at runtime. |
| |
| [width="100%",cols="10%,10%,80%",options="header",] |
| |======================================================================= |
| |Header |Type |Description |
| |
| |CamelVelocityResourceUri |String |*Camel 2.1:* A URI for the template resource to use instead of the |
| endpoint configured. |
| |
| |CamelVelocityTemplate |String |*Camel 2.1:* The template to use instead of the endpoint configured. |
| |======================================================================= |
| |
| ### Samples |
| |
| For example you could use something like |
| |
| [source,java] |
| ---------------------------------------- |
| from("activemq:My.Queue"). |
| to("velocity:com/acme/MyResponse.vm"); |
| ---------------------------------------- |
| |
| To use a Velocity template to formulate a response to a message for |
| InOut message exchanges (where there is a `JMSReplyTo` header). |
| |
| If you want to use InOnly and consume the message and send it to another |
| destination, you could use the following route: |
| |
| [source,java] |
| ---------------------------------------- |
| from("activemq:My.Queue"). |
| to("velocity:com/acme/MyResponse.vm"). |
| to("activemq:Another.Queue"); |
| ---------------------------------------- |
| |
| And to use the content cache, e.g. for use in production, where the |
| `.vm` template never changes: |
| |
| [source,java] |
| ---------------------------------------------------------- |
| from("activemq:My.Queue"). |
| to("velocity:com/acme/MyResponse.vm?contentCache=true"). |
| to("activemq:Another.Queue"); |
| ---------------------------------------------------------- |
| |
| And a file based resource: |
| |
| [source,java] |
| ----------------------------------------------------------------- |
| from("activemq:My.Queue"). |
| to("velocity:file://myfolder/MyResponse.vm?contentCache=true"). |
| to("activemq:Another.Queue"); |
| ----------------------------------------------------------------- |
| |
| In *Camel 2.1* it's possible to specify what template the component |
| should use dynamically via a header, so for example: |
| |
| [source,java] |
| --------------------------------------------------------------------------- |
| from("direct:in"). |
| setHeader("CamelVelocityResourceUri").constant("path/to/my/template.vm"). |
| to("velocity:dummy"); |
| --------------------------------------------------------------------------- |
| |
| In *Camel 2.1* it's possible to specify a template directly as a header |
| the component should use dynamically via a header, so for example: |
| |
| [source,java] |
| --------------------------------------------------------------------------------------------------------------- |
| from("direct:in"). |
| setHeader("CamelVelocityTemplate").constant("Hi this is a velocity template that can do templating ${body}"). |
| to("velocity:dummy"); |
| --------------------------------------------------------------------------------------------------------------- |
| |
| ### The Email Sample |
| |
| In this sample we want to use Velocity templating for an order |
| confirmation email. The email template is laid out in Velocity as: |
| |
| [source,java] |
| ---------------------------------------------- |
| Dear ${headers.lastName}, ${headers.firstName} |
| |
| Thanks for the order of ${headers.item}. |
| |
| Regards Camel Riders Bookstore |
| ${body} |
| ---------------------------------------------- |
| |
| And the java code: |
| |
| ### See Also |
| |
| * Configuring Camel |
| * Component |
| * Endpoint |
| * Getting Started |