Article

The Camel Rest DSL

February 2, 2017
Developer Tools
Mary Cochran
Camel / Red Hat Fuse

Camel

Apache Camel is a piece of JBoss Fuse.  It is an open source integration framework with a variety of components to fit your integration needs.  Camel is a Java-based implementation of the Enterprise Integration Patterns based on a book by Gregor Hohpe and Bobby Woolf.  Camel includes components for HTTP, Files, FTP, JMS, JDBC, AWS, and much more.  While Camel can be used for many different purposes, this post will focus on the REST DSL specifically.

Rest DSL Overview

Apache Camel provides a quick and easy way to get REST endpoints up and running without a dependency on CXF by using the Rest DSL.  Red Hat support for the Rest DSL came with the release of JBoss Fuse 6.2. Before Camel 2.15, most Rest implementation was done using the CXFRS Camel component.  While the CXFRS component did its job, many found it complex and confusing.  It required more files to be maintained than the new Rest DSL and made the application dependent on CXF.  The following Camel components support the use of the Rest DSL:

  • camel-coap
  • camel-netty-http
  • camel-netty4-http
  • camel-jetty
  • camel-restlet
  • camel-servlet
  • camel-spark-rest
  • camel-undertow

Rest DSL Syntax

As with any Camel route, if using the Java DSL, the class must extend the RouteBuilder class and implement a configure() method to form the route definition. One must specify which Camel component the route should use in the restConfiguration() call.  In this configuration, the servlet component is being used.  The binding mode is set to enforce the use of json.  You can leave it as auto so that the rest endpoint can process json, xml, or something else.  Next, the endpoint can be defined.  The root URL will be defined in using syntax like rest ("/user").  Then you can specify what type of call can be made to the endpoint: GET, PUT, POST, or DELETE. What the endpoint produces and consumes may also be defined in addition to defining what type of object the endpoint is expecting to be produced or consumed.  From there, the route is defined the same as any other Camel route.

 @Override
 public void configure() throws Exception {
     restConfiguration().component("servlet").bindingMode(RestBindingMode.json);

     rest("/user")
         .get("/{id}").produces("application/json").to("direct:getUser")
         .post().consumes("application/json").type(User.class).to("direct:createUser")
         .delete("/{id}").to("direct:deleteUser");

     from("direct:getUser")
         .log("GET /user/${header.id} request received!")
         .setBody(simple("${header.id}"))
         .to("bean:usersBean?method=getUser");

     from("direct:createUser")
         .log("POST /user/ request received!")
         .to("bean:usersBean?method=createUser");

     from("direct:deleteUser")
         .log("DELETE /user/${header.id} request received!")
         .setBody(simple("${header.id}"))
         .to("bean:usersBean?method=deleteUser");
 }

Rest DSL on JBoss EAP

In order to get your Rest DSL Camel route running properly on EAP using CDI, you will need to add a servlet to the web.xml.  Please note the camel-servlet is the only supported way of using the Rest DSL with CDI on JBoss EAP at the current time.  If you want to use the Rest DSL with Spring on EAP I would suggest packing the Camel jars in your war.  If you choose to use CDI, the only edits needed are to the web.xml and then an additional annotation on your route class.

web.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

   <listener>
      <listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
   </listener>

   <!-- Camel Servlet -->
   <servlet>
      <servlet-name>CamelServlet</servlet-name>
      <servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
   </servlet>

   <!-- Camel Servlet Mapping -->
   <servlet-mapping>
      <servlet-name>CamelServlet</servlet-name>
      <url-pattern>/rest/*</url-pattern>
   </servlet-mapping>
</web-app>

route class

@ContextName("rest-dsl")
public class RestRoutes extends RouteBuilder {}

Rest DSL on JBoss Fuse Karaf

In order to get your Rest DSL route running on Karaf, you will need to have a camel-context.xml file.  Aside from this file, you will need to have proper import-packages and export-packages configured for your bundle.  This is a standard OSGi configuration.  See the JBoss Fuse documentation for more information on import and export packages.

camel-context.xml

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
 xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws" xmlns:camel="http://camel.apache.org/schema/blueprint"
 xsi:schemaLocation="
 http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
 http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/blueprint/jaxws.xsd
 http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
 ">

   <!-- The camel context which registers the route -->
   <camel:camelContext id="fusequickstart-restdsl-camel" xmlns="http://camel.apache.org/schema/blueprint">
      <!-- Package Scanning finds the Routes -->
      <packageScan>
         <package>com.redhat.consulting.fusequickstarts.karaf.rest.dsl.route</package>
      </packageScan>
   </camel:camelContext>

</blueprint>

These examples and more can found in full at https://github.com/rhtconsulting/fuse-quickstarts.

Last updated: February 23, 2024