You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by bu...@apache.org on 2014/08/06 15:18:55 UTC
svn commit: r918554 - in /websites/production/camel/content:
cache/main.pageCache rest-dsl.html
Author: buildbot
Date: Wed Aug 6 13:18:55 2014
New Revision: 918554
Log:
Production update by buildbot for camel
Modified:
websites/production/camel/content/cache/main.pageCache
websites/production/camel/content/rest-dsl.html
Modified: websites/production/camel/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/camel/content/rest-dsl.html
==============================================================================
--- websites/production/camel/content/rest-dsl.html (original)
+++ websites/production/camel/content/rest-dsl.html Wed Aug 6 13:18:55 2014
@@ -89,11 +89,10 @@
return new RouteBuilder() {
@Override
public void configure() throws Exception {
- rest("/say/hello")
- .get().to("direct:hello");
- rest("/say/bye")
- .get().consumes("application/json").to("direct:bye")
- .post().to("mock:update");
+ rest("/say")
+ .get("/hello").to("direct:hello")
+ .get("/bye").consumes("application/json").to("direct:bye")
+ .post("/bye").to("mock:update");
from("direct:hello")
.transform().constant("Hello World");
@@ -102,18 +101,16 @@
}
};
}]]></script>
-</div></div><p> </p><p>This defines a REST service with the following url mappings:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Uri template</th><th colspan="1" rowspan="1" class="confluenceTh">Verb</th><th colspan="1" rowspan="1" class="confluenceTh">Consumes</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">/say/hello</td><td colspan="1" rowspan="1" class="confluenceTd">get</td><td colspan="1" rowspan="1" class="confluenceTd"><em>all</em></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">/say/bye</td><td colspan="1" rowspan="1" class="confluenceTd">get</td><td colspan="1" rowspan="1" class="confluenceTd">application/json</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">/say/bye</td><td colspan="1" rowspan="1" class="confluenceTd">post</td><td colspan="1" rowspan="1" class="confluenceTd"><em>all</em></td></tr></tbody></table></div><p>Notice that in the REST service we
route directly to a Camel endpoint using the to(). This is because the Rest DSL has a short-hand for routing directly to an endpoint using to(). An alternative is to embed a Camel route directly using route() - there is such an example further below.</p><h3 id="RestDSL-RestDSLwithXML">Rest DSL with XML</h3><p>The REST DSL supports the XML DSL also using either Spring or Blueprint. The example above can be define in XML as shown below:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><p>This defines a REST service with the following url mappings:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Base Path</th><th colspan="1" rowspan="1" class="confluenceTh">Uri template</th><th colspan="1" rowspan="1" class="confluenceTh">Verb</th><th colspan="1" rowspan="1" class="confluenceTh">Consumes</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><span>/say</span></td><td colspan="1" rowspan="1" class="confluenceTd">/hello</td><td colspan="1" rowspan="1" class="confluenceTd">get</td><td colspan="1" rowspan="1" class="confluenceTd"><em>all</em></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">/say</td><td colspan="1" rowspan="1" class="confluenceTd">/bye</td><td colspan="1" rowspan="1" class="confluenceTd">get</td><td colspan="1" rowspan="1" class="confluenceTd">application/json</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">/say</td><td cols
pan="1" rowspan="1" class="confluenceTd">/bye</td><td colspan="1" rowspan="1" class="confluenceTd">post</td><td colspan="1" rowspan="1" class="confluenceTd"><em>all</em></td></tr></tbody></table></div><p>Notice that in the REST service we route directly to a Camel endpoint using the to(). This is because the Rest DSL has a short-hand for routing directly to an endpoint using to(). An alternative is to embed a Camel route directly using route() - there is such an example further below.</p><h3 id="RestDSL-RestDSLwithXML">Rest DSL with XML</h3><p>The REST DSL supports the XML DSL also using either Spring or Blueprint. The example above can be define in XML as shown below:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ <camelContext xmlns="http://camel.apache.org/schema/spring">
- <rest uri="/say/hello">
- <get>
+ <rest path="/say">
+ <get uri="/hello">
<to uri="direct:hello"/>
</get>
- </rest>
- <rest uri="/say/bye">
- <get consumes="application/json">
+ <get uri="/bye" consumes="application/json">
<to uri="direct:bye"/>
</get>
- <post>
+ <post uri="/bye">
<to uri="mock:update"/>
</post>
</rest>
@@ -130,7 +127,7 @@
</transform>
</route>
</camelContext>]]></script>
-</div></div><p> </p><h3 id="RestDSL-Usingpathprefixes">Using path prefixes</h3><p>The REST DSL allows to define path prefixes to make the DSL a bit more DRY. For example to define a customer path, we can set the prefix in rest("/customer") and then provide the past postfix in the verbs, as shown below:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><h3 id="RestDSL-Usingbasepath">Using base path</h3><p>The REST DSL allows to define base path to make the DSL a bit more DRY. For example to define a customer path, we can set the base path in rest("/customer") and then provide the uri templates in the verbs, as shown below:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ rest("/customers/")
.get("/{id}").to("direct:customerDetail")
.get("/{id}/orders").to("direct:customerOrders")
@@ -138,7 +135,7 @@
]]></script>
</div></div><p> </p><p>And using XML DSL it becomes:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ <rest uri="/customers/">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ <rest path="/customers/">
<get uri="/{id}">
<to uri="direct:customerDetail"/>
</get>
@@ -152,10 +149,22 @@
</div></div> <div class="aui-message success shadowed information-macro">
<span class="aui-icon icon-success">Icon</span>
<div class="message-content">
- <p>The REST DSL will take care of duplicate path separators when using path prefixes. In the example above the rest path prefix ends with a slash ( / ) and the verb starts with a slash ( / ). But Apache Camel will take care of this and remove the duplicated slash.</p>
+ <p>The REST DSL will take care of duplicate path separators when using base path and uri templates. In the example above the rest base path ends with a slash ( / ) and the verb starts with a slash ( / ). But Apache Camel will take care of this and remove the duplicated slash.</p>
</div>
</div>
-<h3 id="RestDSL-EmbeddingCamelroutes">Embedding Camel routes</h3><p>Each of the rest service becomes a Camel route, so in the first example we have 2 x get and 1 x post REST service, which each become a Camel route. And we have 2 regular Camel routes, meaning we have 3 + 2 = 5 routes in total. </p><p>There are two route modes with the Rest DSL</p><ul><li><span style="line-height: 1.4285715;">mini using a singular to</span></li><li><span style="line-height: 1.4285715;">embedding a Camel route using route </span></li></ul><p><span style="line-height: 1.4285715;">The first example is using the former with a singular to. And that is why we end up with 3 + 2 = 5 total routes.</span></p><p><span style="line-height: 1.4285715;">The same example could use embedded Camel routes, which is shown below:</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p>It is not required to use both base path and uri templates. You can omit the bast path and define the base path and uri template in the verbs only. The example above can be defined as:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ <rest>
+ <get uri="/customers/{id}">
+ <to uri="direct:customerDetail"/>
+ </get>
+ <get uri="/customers/{id}/orders">
+ <to uri="direct:customerOrders"/>
+ </get>
+ <post uri="/customers/neworder">
+ <to uri="direct:customerNewOrder"/>
+ </post>
+ </rest>]]></script>
+</div></div><h3 id="RestDSL-EmbeddingCamelroutes">Embedding Camel routes</h3><p>Each of the rest service becomes a Camel route, so in the first example we have 2 x get and 1 x post REST service, which each become a Camel route. And we have 2 regular Camel routes, meaning we have 3 + 2 = 5 routes in total. </p><p>There are two route modes with the Rest DSL</p><ul><li><span style="line-height: 1.4285715;">mini using a singular to</span></li><li><span style="line-height: 1.4285715;">embedding a Camel route using route </span></li></ul><p><span style="line-height: 1.4285715;">The first example is using the former with a singular to. And that is why we end up with 3 + 2 = 5 total routes.</span></p><p><span style="line-height: 1.4285715;">The same example could use embedded Camel routes, which is shown below:</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ protected RouteBuilder createRouteBuilder() throws Exception {
return new RouteBuilder() {
@Override
@@ -185,7 +194,7 @@ restConfiguration().component("rest
// use the rest DSL to define the rest services
rest("/users/")
- .post("new").type(UserPojo.class)
+ .post().type(UserPojo.class)
.to("direct:newUser");]]></script>
</div></div><p>Notice we use <code>type</code> to define the incoming type. We can optionally define an outgoing type (which can be a good idea, to make it known from the DSL and also for tooling and JMX APIs to know both the incoming and outgoing types of the REST services.). To define the outgoing type, we use <code>outType</code> as shown below:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[// configure to use restlet on localhost with the given port
@@ -194,7 +203,7 @@ restConfiguration().component("rest
// use the rest DSL to define the rest services
rest("/users/")
- .post("new").type(UserPojo.class).outType(CountryPojo.class)
+ .post().type(UserPojo.class).outType(CountryPojo.class)
.to("direct:newUser");]]></script>
</div></div><p><span style="line-height: 1.4285715;"><br clear="none"></span></p><p><span style="line-height: 1.4285715;">The </span><code style="line-height: 1.4285715;">UserPojo</code><span style="line-height: 1.4285715;"> is just a plain pojo with getter/setter as shown:</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class UserPojo {
@@ -236,7 +245,7 @@ public class UserPojo {
}
]]></script>
-</div></div><p>By having the JAXB annotations the POJO supports both json and xml bindings.</p><p> </p><h3 id="RestDSL-ConfiguringRestDSL"><span style="line-height: 1.5625;">Configuring Rest DSL</span></h3><p>The Rest DSL allows to configure the following options using a builder style</p><p> </p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Option</th><th colspan="1" rowspan="1" class="confluenceTh">Default</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">component</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">The Camel Rest component to use for the REST transport, such as restlet, spark-rest. If no component has been explicit configured, then Camel will lookup if there is a Camel component that integrates with the Rest DSL, or if a <code>org.apache.camel.sp
i.RestConsumerFactory</code> is registered in the registry. If either one is found, then that is being used.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scheme</td><td colspan="1" rowspan="1" class="confluenceTd">http</td><td colspan="1" rowspan="1" class="confluenceTd">The scheme to use for exposing the REST service. Usually http or https is supported</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">hostname</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">The hostname to use for exposing the REST service.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">port</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">The port number to use for exposing the REST service.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">restHostNameResolver</td><td colspan="1" rowspan="1" class="confluenceTd">localHostName<
/td><td colspan="1" rowspan="1" class="confluenceTd">If no hostname has been explicit configured, then this resolver is used to compute the hostname the REST service will be using. The resolver supports <code>localHostName</code> or <code>localIp</code>.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">bindingMode</td><td colspan="1" rowspan="1" class="confluenceTd">off</td><td colspan="1" rowspan="1" class="confluenceTd">Whether binding is in use. See further above for more details.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">jsonDataFormat</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Name of specific json data format to use. By default <code>json-jackson</code> will be used. <strong>Notice:</strong> Currently Jackson is what we recommend and are using for testing.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">xmlDataFormat</td><td colspan="1" rowspan="1" class="conflu
enceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Name of specific XML data format to use. By default <code>jaxb</code> will be used. <strong>Notice:</strong> Currently only <code>jaxb</code> is supported.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">componentProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Allows to configure as many additional properties. This is used to configure component specific options such as for <a shape="rect" href="restlet.html">Restlet</a> / <a shape="rect" href="spark-rest.html">Spark-Rest</a> etc.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">endpointProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd"><span>Allows to configure as many additional properties. This is used to configure endpoint specific options for <span> </span><a shape="r
ect" href="restlet.html">Restlet</a><span> / </span><a shape="rect" href="spark-rest.html">Spark-Rest</a><span> etc.</span></span></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">consumerProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd"><span>Allows to configure as many additional properties. This is used to configure consumer specific options for </span><span> </span><a shape="rect" href="restlet.html">Restlet</a><span> / </span><a shape="rect" href="spark-rest.html">Spark-Rest</a><span> etc.</span></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">dataFormatProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Allows to configure as many additional properties. This is used to configure the data format specific options. For example set property prettyPrint to true to have json outputt
ed in pretty mode.</td></tr></tbody></table></div><p> </p><p><span style="line-height: 1.4285715;">For example to configure to use the spark-rest component on port 9091, then we can do as follows</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>By having the JAXB annotations the POJO supports both json and xml bindings.</p><h3 id="RestDSL-ConfiguringRestDSL"><span style="line-height: 1.5625;">Configuring Rest DSL</span></h3><p>The Rest DSL allows to configure the following options using a builder style</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Option</th><th colspan="1" rowspan="1" class="confluenceTh">Default</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">component</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">The Camel Rest component to use for the REST transport, such as restlet, spark-rest. If no component has been explicit configured, then Camel will lookup if there is a Camel component that integrates with the Rest DSL, or if a <code>org.apache.camel.spi.RestConsumerFactory</cod
e> is registered in the registry. If either one is found, then that is being used.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scheme</td><td colspan="1" rowspan="1" class="confluenceTd">http</td><td colspan="1" rowspan="1" class="confluenceTd">The scheme to use for exposing the REST service. Usually http or https is supported</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">hostname</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">The hostname to use for exposing the REST service.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">port</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">The port number to use for exposing the REST service.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">restHostNameResolver</td><td colspan="1" rowspan="1" class="confluenceTd">localHostName</td><td colspan="1" rowspa
n="1" class="confluenceTd">If no hostname has been explicit configured, then this resolver is used to compute the hostname the REST service will be using. The resolver supports <code>localHostName</code> or <code>localIp</code>.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">bindingMode</td><td colspan="1" rowspan="1" class="confluenceTd">off</td><td colspan="1" rowspan="1" class="confluenceTd">Whether binding is in use. See further above for more details.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">jsonDataFormat</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Name of specific json data format to use. By default <code>json-jackson</code> will be used. <strong>Notice:</strong> Currently Jackson is what we recommend and are using for testing.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">xmlDataFormat</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td col
span="1" rowspan="1" class="confluenceTd">Name of specific XML data format to use. By default <code>jaxb</code> will be used. <strong>Notice:</strong> Currently only <code>jaxb</code> is supported.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">componentProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Allows to configure as many additional properties. This is used to configure component specific options such as for <a shape="rect" href="restlet.html">Restlet</a> / <a shape="rect" href="spark-rest.html">Spark-Rest</a> etc.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">endpointProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd"><span>Allows to configure as many additional properties. This is used to configure endpoint specific options for <span> </span><a shape="rect" href="restlet.html">R
estlet</a><span> / </span><a shape="rect" href="spark-rest.html">Spark-Rest</a><span> etc.</span></span></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">consumerProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd"><span>Allows to configure as many additional properties. This is used to configure consumer specific options for </span><span> </span><a shape="rect" href="restlet.html">Restlet</a><span> / </span><a shape="rect" href="spark-rest.html">Spark-Rest</a><span> etc.</span></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">dataFormatProperty</td><td colspan="1" rowspan="1" class="confluenceTd"> </td><td colspan="1" rowspan="1" class="confluenceTd">Allows to configure as many additional properties. This is used to configure the data format specific options. For example set property prettyPrint to true to have json outputted in pretty mode.</td></t
r></tbody></table></div><p> </p><p><span style="line-height: 1.4285715;">For example to configure to use the spark-rest component on port 9091, then we can do as follows</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[restConfiguration().component("spark-rest").port(9091).componentProperty("foo", "123");]]></script>
</div></div><p><span style="line-height: 1.4285715;"><br clear="none"></span></p><p><span style="line-height: 1.4285715;">And with XML DSL</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<restConfiguration component="spark-rest" port="9091"> <componentProperty key="foo" value="123"/> </restConfiguration>]]></script>