jam01 commented on a change in pull request #4561:
URL: https://github.com/apache/camel/pull/4561#discussion_r530543896
##########
File path: components/camel-datasonnet/src/main/docs/datasonnet-language.adoc
##########
@@ -0,0 +1,193 @@
+[[datasonnet-language]]
+= DataSonnet Language
+:docTitle: DataSonnet
+:artifactId: camel-datasonnet
+:description: To use DataSonnet scripts in Camel expressions or predicates.
+:since: 3.7
+:supportLevel: Preview
+include::{cq-version}@camel-quarkus:ROOT:partial$reference/languages/datasonnet.adoc[opts=optional]
+
+*Since Camel {since}*
+
+Camel supports https://datasonnet.com/[DataSonnet] transformations to allow an
Expression or Predicate to be used in the Java DSL or
xref:manual::xml-configuration.adoc[XML
+Configuration].
+
+To use a DataSonnet expression use the following Java code:
+[source,java]
+---------------------------------------
+... datasonnet("someDSExpression") ...
+---------------------------------------
+
+== Example
+
+Here is a simple example using a DataSonnet expression as a predicate in a
Message Filter:
+
+[source,java]
+------------------------------------------------------------------------------------------------
+// lets route if a line item is over $100
+from("queue:foo")
+ .filter(datasonnet("ds.arrays.firstWith(body.lineItems, function(item)
item > 100) != null"))
+ .to("queue:bar")
+------------------------------------------------------------------------------------------------
+
+And the Spring DSL:
+
+[source,xml]
+-----------------------------------------------------------------------------
+<route>
+ <from uri="queue:foo"/>
+ <filter>
+ <datasonnet>ds.arrays.firstWith(body.lineItems, function(item) item >
100) != null</datasonnet>
+ <to uri="queue:bar"/>
+ </filter>
+</route>
+-----------------------------------------------------------------------------
+
+Here is an example of a simple DataSonnet expression as a transformation EIP.
This example will transform an XML body with
+`lineItems` into JSON while filtering out lines that are under 100.
+
+[source,java]
+------------------------------------------------------------------------------------------------
+from("queue:foo")
+ .transform(datasonnet("ds.filter(body.lineItems, function(item) item >
100)", String.class)
+ .bodyMediaType("application/xml").outputMediaType("application/json")
+ )
+ .to("queue:bar")
+------------------------------------------------------------------------------------------------
+
+And the Spring DSL:
+
+[source,xml]
+-----------------------------------------------------------------------------
+<route>
+ <from uri="queue:foo"/>
+ <filter>
+ <datasonnet bodyMediaType="application/xml"
outputMediaType="application/json" resultTypeName="java.lang.String" >
+ ds.filter(body.lineItems, function(item) item > 100)
+ </datasonnet>
+ <to uri="queue:bar"/>
+ </filter>
+</route>
+-----------------------------------------------------------------------------
+
+== Setting result type
+
+The xref:datasonnet-language.adoc[DataSonnet] expression will return a
`com.datasonnet.document.Document` by default. The
+document preserves the content type metadata along with the contents of the
result of the transformation. In predicates,
+however, the Document will be automatically unwrapped and the boolean content
will be returned. Similarly any times you
+want the content in a specific result type like a String. To do this you have
to instruct the
+xref:datasonnet-language.adoc[DataSonnet] which result type to return.
+
+In Java DSL:
+
+[source,java]
+----
+datasonnet("body.foo", String.class)
+----
+
+In Spring DSL you use the *resultType* attribute to provide a fully
+qualified classname:
+
+[source,xml]
+----
+<datasonnet resultType="java.lang.String">body.foo</datasonnet>
+----
+
+If the expression results in an array, or an object, you can instruct the
expression to return you `List.class`
+or `Map.class`, respectively. However, you must also set the output media type
to `application/x-java-object`.
+
+NOTE: The default `Document` object is useful in situations where there are
intermediate transformation steps, and so
+retaining the content metadata through a route execution is valuable.
+
+== Specifying Media Types
+
+Traditionally the input and output media types are specified through the
+https://datasonnet.s3-us-west-2.amazonaws.com/docs-ci/primary/master/datasonnet/1.0-SNAPSHOT/headers.html[DataSonnet
Header]
+The xref:datasonnet-language.adoc[DataSonnet] expression provides convenience
options for specifying the body and output
+media types without the need for a Header, this is useful if the
transformation is a one-liner, for example.
+
+The DataSonnet expression will look for a body media type in the following
order:
+
+1. If the body is a `Document` it will use the metadata in the object
+2. If the convenience bodyMediaType method was used, it will use its value
+3. A "CamelDatasonnetBodyMediaType" exchange property
+4. A "Content-Type" message header
+5. The DataSonnet Header payload media type directive
+6. `application/x-java-object`
+
+And for output media type:
+
+1. If the convenience outputMediaType method was used, it will use its value
+2. A "CamelDatasonnetOutputMediaType" exchange property
+3. A "CamelDatasonnetOutputMediaType" message header
+4. The DataSonnet Header output media type directive
+5. `application/x-java-object`
+
+== Functions
+
+Camel adds the following DataSonnet functions that can be used to access the
+exchange:
+
+[width="100%",cols="10%,10%,10%,70%",options="header",]
+|===
+|Function |Argument |Type |Description
+
+|cml.properties |key for property |String |To lookup a property using the
+xref:ROOT:properties-component.adoc[Properties] component (property
placeholders).
+
+|cml.header |the header name |String |Will return the message header.
+
+|cml.exchangeProperty |key for property |String |Will return the exchange
property.
+|===
+
+Here's an example showing some of these functions in use:
Review comment:
changed to `.setBody(datasonnet("'hello, ' + cml.properties('toGreet')",
String.class))` let us know if that works
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
