Repository: camel Updated Branches: refs/heads/master 21f5ea96d -> 7f9c85ebb
Added camel-freemarker docs to gitbook and modified camel-fop docs Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/7f9c85eb Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/7f9c85eb Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/7f9c85eb Branch: refs/heads/master Commit: 7f9c85ebb71441e66ca1baac424e0bbfe6faea36 Parents: 21f5ea9 Author: Andrea Cosentino <anco...@gmail.com> Authored: Fri Mar 25 10:51:29 2016 +0100 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Fri Mar 25 10:51:29 2016 +0100 ---------------------------------------------------------------------- components/camel-fop/src/main/docs/fop.adoc | 5 + .../src/main/docs/freemarker.adoc | 235 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 3 files changed, 241 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/7f9c85eb/components/camel-fop/src/main/docs/fop.adoc ---------------------------------------------------------------------- diff --git a/components/camel-fop/src/main/docs/fop.adoc b/components/camel-fop/src/main/docs/fop.adoc index 43ee192..5f6f537 100644 --- a/components/camel-fop/src/main/docs/fop.adoc +++ b/components/camel-fop/src/main/docs/fop.adoc @@ -69,6 +69,11 @@ http://svn.apache.org/repos/asf/xmlgraphics/commons/trunk/src/java/org/apache/xm Endpoint Options ^^^^^^^^^^^^^^^^ +// component options: START +The FOP component has no options. +// component options: END + + // endpoint options: START The FOP component supports 5 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/7f9c85eb/components/camel-freemarker/src/main/docs/freemarker.adoc ---------------------------------------------------------------------- diff --git a/components/camel-freemarker/src/main/docs/freemarker.adoc b/components/camel-freemarker/src/main/docs/freemarker.adoc new file mode 100644 index 0000000..f25f464 --- /dev/null +++ b/components/camel-freemarker/src/main/docs/freemarker.adoc @@ -0,0 +1,235 @@ +[[FreeMarker-FreeMarker]] +FreeMarker +~~~~~~~~~~ + +The *freemarker:* component allows for processing a message using a +http://freemarker.org/[FreeMarker] template. This can be ideal when +using link:templating.html[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-freemarker</artifactId> + <version>x.x.x</version> <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------------------------------- + +[[FreeMarker-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +--------------------------------- +freemarker: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.ftl[file://folder/myfile.ftl]). + +You can append query options to the URI in the following format, +`?option=value&option=value&...` + +[[FreeMarker-Options]] +Options +^^^^^^^ + +// component options: START +The Freemarker component supports 1 options which are listed below. + +[width="100%",cols="2s,1m,8",options="header"] +|======================================================================= +| Name | Java Type | Description +| configuration | Configuration | To use an existing freemarker.template.Configuration instance as the configuration. +|======================================================================= +// component options: END + +// endpoint options: START +The Freemarker component supports 7 endpoint options which are listed below: + +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| resourceUri | producer | | String | *Required* Path to the resource or a reference to lookup a bean in the Registry to use as the resource +| configuration | producer | | Configuration | Sets the Freemarker configuration to use +| contentCache | producer | false | boolean | Sets whether to use resource content cache or not +| encoding | producer | | String | Sets the encoding to be used for loading the template file. +| templateUpdateDelay | producer | | int | Number of seconds the loaded template resource will remain in the cache. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported). +|======================================================================= +// endpoint options: END + + +[[FreeMarker-Headers]] +Headers +^^^^^^^ + +Headers set during the FreeMarker evaluation are returned to the message +and added as headers. This provides a mechanism for the FreeMarker +component to return values to the Message. + +An example: Set the header value of `fruit` in the FreeMarker template: + +[source,java] +-------------------------------------- +${request.setHeader('fruit', 'Apple')} +-------------------------------------- + +The header, `fruit`, is now accessible from the `message.out.headers`. + +[[FreeMarker-FreeMarkerContext]] +FreeMarker Context +^^^^^^^^^^^^^^^^^^ + +Camel will provide exchange information in the FreeMarker context (just +a `Map`). The `Exchange` is transferred as: + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|key |value + +|`exchange` |The `Exchange` itself. + +|`exchange.properties` |The `Exchange` properties. + +|`headers` |The headers of the In message. + +|`camelContext` |The Camel Context. + +|`request` |The In message. + +|`body` |The In message body. + +|`response` |The Out message (only for InOut message exchange pattern). +|======================================================================= + +From Camel 2.14, you can setup your custom FreeMarker context in the +message header with the key "*CamelFreemarkerDataModel*" just like this + +[source,java] +-------------------------------------------------------------------- +Map<String, Object> variableMap = new HashMap<String, Object>(); +variableMap.put("headers", headersMap); +variableMap.put("body", "Monday"); +variableMap.put("exchange", exchange); +exchange.getIn().setHeader("CamelFreemarkerDataModel", variableMap); +-------------------------------------------------------------------- + +[[FreeMarker-Hotreloading]] +Hot reloading +^^^^^^^^^^^^^ + +The FreeMarker template resource is by default *not* hot reloadable for +both file and classpath resources (expanded jar). If you set +`contentCache=false`, then Camel will not cache the resource and hot +reloading is thus enabled. This scenario can be used in development. + +[[FreeMarker-Dynamictemplates]] +Dynamic templates +^^^^^^^^^^^^^^^^^ + +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%,10%,70%",options="header",] +|======================================================================= +|Header |Type |Description |Support Version + +|FreemarkerConstants.FREEMARKER_RESOURCE |org.springframework.core.io.Resource |The template resource | <= 2.1 + +|FreemarkerConstants.FREEMARKER_RESOURCE_URI |String |A URI for the template resource to use instead of the endpoint +configured. | >= 2.1 + +|FreemarkerConstants.FREEMARKER_TEMPLATE |String |The template to use instead of the endpoint configured. | >= 2.1 +|======================================================================= + +[[FreeMarker-Samples]] +Samples +^^^^^^^ + +For example you could use something like: + +[source,java] +------------------------------------------- +from("activemq:My.Queue"). + to("freemarker:com/acme/MyResponse.ftl"); +------------------------------------------- + +To use a FreeMarker template to formulate a response for 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: + +[source,java] +------------------------------------------- +from("activemq:My.Queue"). + to("freemarker:com/acme/MyResponse.ftl"). + to("activemq:Another.Queue"); +------------------------------------------- + +And to disable the content cache, e.g. for development usage where the +`.ftl` template should be hot reloaded: + +[source,java] +-------------------------------------------------------------- +from("activemq:My.Queue"). + to("freemarker:com/acme/MyResponse.ftl?contentCache=false"). + to("activemq:Another.Queue"); +-------------------------------------------------------------- + +And a file-based resource: + +[source,java] +--------------------------------------------------------------------- +from("activemq:My.Queue"). + to("freemarker:file://myfolder/MyResponse.ftl?contentCache=false"). + 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(FreemarkerConstants.FREEMARKER_RESOURCE_URI).constant("path/to/my/template.ftl"). + to("freemarker:dummy"); +--------------------------------------------------------------------------------------------- + +[[FreeMarker-TheEmailSample]] +The Email Sample +^^^^^^^^^^^^^^^^ + +In this sample we want to use FreeMarker templating for an order +confirmation email. The email template is laid out in FreeMarker as: + +[source,java] +---------------------------------------------- +Dear ${headers.lastName}, ${headers.firstName} + +Thanks for the order of ${headers.item}. + +Regards Camel Riders Bookstore +${body} +---------------------------------------------- + +And the java code: + +[[FreeMarker-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + http://git-wip-us.apache.org/repos/asf/camel/blob/7f9c85eb/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 67f18fe..d9e660a 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -130,6 +130,7 @@ * [Facebook](facebook.adoc) * [Flatpack](flatpack.adoc) * [FOP](fop.adoc) + * [Freemarker](freemarker.adoc) * [Ironmq](ironmq.adoc) * [JMS](jms.adoc) * [JMX](jmx.adoc)
