Restlet

Restlet Component

The Restlet component provides Restlet based endpoints for consuming and producing RESTful resources.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-restlet</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

restlet:restletUrl[?options]

Format of restletUrl:

protocol://hostname[:port][/resourcePattern]

Restlet promotes decoupling of protocol and application concerns. The reference implementation of Restlet Engine supports a number of protocols. However, we have tested the HTTP protocol only. The default port is port 80. We do not automatically switch default port based on the protocol yet.

You can append query options to the URI in the following format, ?option=value&option=value&...

Options

Component Options

The Restlet component can be configured with the following options. Notice these are component options and cannot be configured on the endpoint, see further below for an example.

Message Headers

Message Body

Camel will store the restlet response from the external server on the OUT body. All headers from the IN message will be copied to the OUT message, so that headers are preserved during routing.

Samples

Restlet Endpoint with Authentication

The following route starts a restlet consumer endpoint that listens for POST requests on http://localhost:8080. The processor creates a response that echoes the request body and the value of the id header.

The restletRealm setting in the URI query is used to look up a Realm Map in the registry. If this option is specified, the restlet consumer uses the information to authenticate user logins. Only authenticated requests can access the resources. In this sample, we create a Spring application context that serves as a registry. The bean ID of the Realm Map should match the restletRealmRef.

The following sample starts a direct endpoint that sends requests to the server on http://localhost:8080 (that is, our restlet consumer endpoint).

That is all we need. We are ready to send a request and try out the restlet component:

The sample client sends a request to the direct:start-auth endpoint with the following headers:

• CamelRestletLogin (used internally by Camel)
• CamelRestletPassword (used internally by Camel)
• id (application header)

The sample client gets a response like the following:

received [<order foo='1'/>] as an order id = 89531

Single restlet endpoint to service multiple methods and URI templates

It is possible to create a single route to service multiple HTTP methods using the restletMethods option. This snippet also shows how to retrieve the request method from the header:

In addition to servicing multiple methods, the next snippet shows how to create an endpoint that supports multiple URI templates using the restletUriPatterns option. The request URI is available in the header of the IN message as well. If a URI pattern has been defined in the endpoint URI (which is not the case in this sample), both the URI pattern defined in the endpoint and the restletUriPatterns option will be honored.

The restletUriPatterns=#uriTemplates option references the List<String> bean defined in the Spring XML configuration.

<util:list id="uriTemplates">
    <value>/users/{username}</value>
    <value>/atom/collection/{id}/component/{cid}</value>
</util:list>

Using Restlet API to populate response

Available as of Camel 2.8

You may want to use the org.restlet.Response API to populate the response. This gives you full access to the Restlet API and fine grained control of the response. See the route snippet below where we generate the response from an inlined Camel Processor:

Configuring max threads on component

To configure the max threads options you must do this on the component, such as:

<bean id="restlet" class="org.apache.camel.component.RestletComponent">
  <property name="maxThreads" value="100"/>
</bean>

Using the Restlet servlet within a webapp

Available as of Camel 2.8
There are three possible ways to configure a Restlet application within a servlet container and using the subclassed SpringServerServlet enables configuration within Camel by injecting the Restlet Component.

Use of the Restlet servlet within a servlet container enables routes to be configured with relative paths in URIs (removing the restrictions of hard-coded absolute URIs) and for the hosting servlet container to handle incoming requests (rather than have to spawn a separate server process on a new port).

To configure, add the following to your camel-context.xml;

<camelContext>
  <route id="RS_RestletDemo">
    <from uri="restlet:/demo/{id}" />
    <transform>
      <simple>Request type : ${header.CamelHttpMethod} and ID : ${header.id}</simple>
    </transform>
  </route> 
</camelContext>

<bean id="RestletComponent" class="org.restlet.Component" />

<bean id="RestletComponentService" class="org.apache.camel.component.restlet.RestletComponent">
  <constructor-arg index="0">
    <ref bean="RestletComponent" />
  </constructor-arg>
</bean>

And add this to your web.xml;

<!-- Restlet Servlet -->
<servlet>
  <servlet-name>RestletServlet</servlet-name>
  <servlet-class>org.restlet.ext.spring.SpringServerServlet</servlet-class>
  <init-param>
    <param-name>org.restlet.component</param-name>
    <param-value>RestletComponent</param-value>
  </init-param>
</servlet>

<servlet-mapping>
  <servlet-name>RestletServlet</servlet-name>
  <url-pattern>/rs/*</url-pattern>
</servlet-mapping>

You will then be able to access the deployed route at http://localhost:8080/mywebapp/rs/demo/1234 where;

localhost:8080 is the server and port of your servlet container
mywebapp is the name of your deployed webapp
Your browser will then show the following content;

"Request type : GET and ID : 1234"

You will need to add dependency on the Spring extension to restlet which you can do in your Maven pom.xml file:

<dependency>
  <groupId>org.restlet.jee</groupId>
  <artifactId>org.restlet.ext.spring</artifactId>
  <version>${restlet-version}</version>
</dependency>

And you would need to add dependency on the restlet maven repository as well:

<repository>  
   <id>maven-restlet</id>  
   <name>Public online Restlet repository</name>  
   <url>http://maven.restlet.org</url>  
</repository>