docs/components/modules/ROOT/pages/restlet-component.adoc

[[restlet-component]]
= Restlet Component (deprecated)
:page-source: components/camel-restlet/src/main/docs/restlet-component.adoc

*Available as of Camel version 2.0*

*Available as of Camel version 2.0*


The Restlet component provides http://www.restlet.org[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:

[source,xml]
------------------------------------------------------------
<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

[source,text]
----
restlet:restletUrl[?options]
----

Format of restletUrl:

[source,text]
----
protocol://hostname[:port][/resourcePattern]
----

Restlet promotes decoupling of protocol and application concerns. The
reference implementation of
http://www.noelios.com/products/restlet-engine[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&...`

NOTE: It seems Restlet is case sensitive in understanding headers. For example
to use content-type, use `Content-Type`, and for location use `Location` and
so on.

To keep up performance you can set
synchronous=true as option on the endpoint uris, Or set it on the
RestletComponent as a global option so all endpoints inherit this
option.

== Options



// component options: START
The Restlet component supports 23 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *controllerDaemon* (consumer) | Indicates if the controller thread should be a daemon (not blocking JVM exit). |  | Boolean
| *controllerSleepTimeMs* (consumer) | Time for the controller thread to sleep between each control. |  | Integer
| *headerFilterStrategy* (filter) | To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message. |  | HeaderFilterStrategy
| *inboundBufferSize* (consumer) | The size of the buffer when reading messages. |  | Integer
| *maxConnectionsPerHost* (common) | Maximum number of concurrent connections per host (IP address). |  | Integer
| *maxThreads* (consumer) | Maximum threads that will service requests. |  | Integer
| *lowThreads* (consumer) | Number of worker threads determining when the connector is considered overloaded. |  | Integer
| *maxTotalConnections* (common) | Maximum number of concurrent connections in total. |  | Integer
| *minThreads* (consumer) | Minimum threads waiting to service requests. |  | Integer
| *outboundBufferSize* (consumer) | The size of the buffer when writing messages. |  | Integer
| *persistingConnections* (consumer) | Indicates if connections should be kept alive after a call. |  | Boolean
| *pipeliningConnections* (consumer) | Indicates if pipelining connections are supported. |  | Boolean
| *threadMaxIdleTimeMs* (consumer) | Time for an idle thread to wait for an operation before being collected. |  | Integer
| *useForwardedForHeader* (consumer) | Lookup the X-Forwarded-For header supported by popular proxies and caches and uses it to populate the Request.getClientAddresses() method result. This information is only safe for intermediary components within your local network. Other addresses could easily be changed by setting a fake header and should not be trusted for serious security checks. |  | Boolean
| *reuseAddress* (consumer) | Enable/disable the SO_REUSEADDR socket option. See java.io.ServerSocket#reuseAddress property for additional details. |  | Boolean
| *maxQueued* (consumer) | Maximum number of calls that can be queued if there aren't any worker thread available to service them. If the value is '0', then no queue is used and calls are rejected if no worker thread is immediately available. If the value is '-1', then an unbounded queue is used and calls are never rejected. |  | Integer
| *disableStreamCache* (consumer) | Determines whether or not the raw input stream from Restlet is cached or not (Camel will read the stream into a in memory/overflow to file, Stream caching) cache. By default Camel will cache the Restlet input stream to support reading it multiple times to ensure Camel can retrieve all data from the stream. However you can set this option to true when you for example need to access the raw stream, such as streaming it directly to a file or other persistent store. DefaultRestletBinding will copy the request input stream into a stream cache and put it into message body if this option is false to support reading the stream multiple times. | false | boolean
| *port* (consumer) | To configure the port number for the restlet consumer routes. This allows to configure this once to reuse the same port for these consumers. |  | int
| *synchronous* (producer) | Whether to use synchronous Restlet Client for the producer. Setting this option to true can yield faster performance as it seems the Restlet synchronous Client works better. |  | Boolean
| *enabledConverters* (advanced) | A list of converters to enable as full class name or simple class name. All the converters automatically registered are enabled if empty or null |  | List
| *useGlobalSslContext Parameters* (security) | Enable usage of global SSL context parameters. | false | boolean
| *sslContextParameters* (security) | To configure security using SSLContextParameters |  | SSLContextParameters
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
|===
// component options: END




// endpoint options: START
The Restlet endpoint is configured using URI syntax:

----
restlet:protocol:host:port/uriPattern
----

with the following path and query parameters:

=== Path Parameters (4 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *protocol* | *Required* The protocol to use which is http or https |  | String
| *host* | *Required* The hostname of the restlet service |  | String
| *port* | *Required* The port number of the restlet service | 80 | int
| *uriPattern* | The resource pattern such as /customer/\{id\} |  | String
|===


=== Query Parameters (19 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *restletMethod* (common) | On a producer endpoint, specifies the request method to use. On a consumer endpoint, specifies that the endpoint consumes only restletMethod requests. | GET | Method
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *restletMethods* (consumer) | Specify one or more methods separated by commas (e.g. restletMethods=post,put) to be serviced by a restlet consumer endpoint. If both restletMethod and restletMethods options are specified, the restletMethod setting is ignored. The possible methods are: ALL,CONNECT,DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,TRACE. Multiple methods can be separated by comma. |  | String
| *disableStreamCache* (consumer) | Determines whether or not the raw input stream from Restlet is cached or not (Camel will read the stream into a in memory/overflow to file, Stream caching) cache. By default Camel will cache the Restlet input stream to support reading it multiple times to ensure Camel can retrieve all data from the stream. However you can set this option to true when you for example need to access the raw stream, such as streaming it directly to a file or other persistent store. DefaultRestletBinding will copy the request input stream into a stream cache and put it into message body if this option is false to support reading the stream multiple times. | false | boolean
| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler
| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. |  | ExchangePattern
| *connectTimeout* (producer) | The Client will give up connection if the connection is timeout, 0 for unlimited wait. | 30000 | int
| *cookieHandler* (producer) | Configure a cookie handler to maintain a HTTP session |  | CookieHandler
| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean
| *socketTimeout* (producer) | The Client socket receive timeout, 0 for unlimited wait. | 30000 | int
| *throwExceptionOnFailure* (producer) | Whether to throw exception on a producer failure. If this option is false then the http status code is set as a message header which can be checked if it has an error value. | true | boolean
| *autoCloseStream* (producer) | Whether to auto close the stream representation as response from calling a REST service using the restlet producer. If the response is streaming and the option streamRepresentation is enabled then you may want to auto close the InputStream from the streaming response to ensure the input stream is closed when the Camel Exchange is done being routed. However if you need to read the stream outside a Camel route, you may need to not auto close the stream. | false | boolean
| *streamRepresentation* (producer) | Whether to support stream representation as response from calling a REST service using the restlet producer. If the response is streaming then this option can be enabled to use an java.io.InputStream as the message body on the Camel Message body. If using this option you may want to enable the autoCloseStream option as well to ensure the input stream is closed when the Camel Exchange is done being routed. However if you need to read the stream outside a Camel route, you may need to not auto close the stream. | false | boolean
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *headerFilterStrategy* (advanced) | To use a custom HeaderFilterStrategy to filter header to and from Camel message. |  | HeaderFilterStrategy
| *restletBinding* (advanced) | To use a custom RestletBinding to bind between Restlet and Camel message. |  | RestletBinding
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
| *restletRealm* (security) | To configure the security realms of restlet as a map. |  | Map
| *sslContextParameters* (security) | To configure security using SSLContextParameters. |  | SSLContextParameters
|===
// endpoint options: END
// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-restlet-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 24 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.component.restlet.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean
| *camel.component.restlet.controller-daemon* | Indicates if the controller thread should be a daemon (not blocking JVM exit). |  | Boolean
| *camel.component.restlet.controller-sleep-time-ms* | Time for the controller thread to sleep between each control. |  | Integer
| *camel.component.restlet.disable-stream-cache* | Determines whether or not the raw input stream from Restlet is cached or not (Camel will read the stream into a in memory/overflow to file, Stream caching) cache. By default Camel will cache the Restlet input stream to support reading it multiple times to ensure Camel can retrieve all data from the stream. However you can set this option to true when you for example need to access the raw stream, such as streaming it directly to a file or other persistent store. DefaultRestletBinding will copy the request input stream into a stream cache and put it into message body if this option is false to support reading the stream multiple times. | false | Boolean
| *camel.component.restlet.enabled* | Enable restlet component | true | Boolean
| *camel.component.restlet.enabled-converters* | A list of converters to enable as full class name or simple class name. All the converters automatically registered are enabled if empty or null |  | List
| *camel.component.restlet.header-filter-strategy* | To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message. The option is a org.apache.camel.spi.HeaderFilterStrategy type. |  | String
| *camel.component.restlet.inbound-buffer-size* | The size of the buffer when reading messages. |  | Integer
| *camel.component.restlet.low-threads* | Number of worker threads determining when the connector is considered overloaded. |  | Integer
| *camel.component.restlet.max-connections-per-host* | Maximum number of concurrent connections per host (IP address). |  | Integer
| *camel.component.restlet.max-queued* | Maximum number of calls that can be queued if there aren't any worker thread available to service them. If the value is '0', then no queue is used and calls are rejected if no worker thread is immediately available. If the value is '-1', then an unbounded queue is used and calls are never rejected. |  | Integer
| *camel.component.restlet.max-threads* | Maximum threads that will service requests. |  | Integer
| *camel.component.restlet.max-total-connections* | Maximum number of concurrent connections in total. |  | Integer
| *camel.component.restlet.min-threads* | Minimum threads waiting to service requests. |  | Integer
| *camel.component.restlet.outbound-buffer-size* | The size of the buffer when writing messages. |  | Integer
| *camel.component.restlet.persisting-connections* | Indicates if connections should be kept alive after a call. |  | Boolean
| *camel.component.restlet.pipelining-connections* | Indicates if pipelining connections are supported. |  | Boolean
| *camel.component.restlet.port* | To configure the port number for the restlet consumer routes. This allows to configure this once to reuse the same port for these consumers. |  | Integer
| *camel.component.restlet.reuse-address* | Enable/disable the SO_REUSEADDR socket option. See java.io.ServerSocket#reuseAddress property for additional details. |  | Boolean
| *camel.component.restlet.ssl-context-parameters* | To configure security using SSLContextParameters. The option is a org.apache.camel.support.jsse.SSLContextParameters type. |  | String
| *camel.component.restlet.synchronous* | Whether to use synchronous Restlet Client for the producer. Setting this option to true can yield faster performance as it seems the Restlet synchronous Client works better. |  | Boolean
| *camel.component.restlet.thread-max-idle-time-ms* | Time for an idle thread to wait for an operation before being collected. |  | Integer
| *camel.component.restlet.use-forwarded-for-header* | Lookup the X-Forwarded-For header supported by popular proxies and caches and uses it to populate the Request.getClientAddresses() method result. This information is only safe for intermediary components within your local network. Other addresses could easily be changed by setting a fake header and should not be trusted for serious security checks. |  | Boolean
| *camel.component.restlet.use-global-ssl-context-parameters* | Enable usage of global SSL context parameters. | false | Boolean
|===
// spring-boot-auto-configure options: END



== Message Headers

[width="100%",cols="10%,10%,80%",options="header",]
|===
|Name |Type |Description

|`Content-Type` |`String` |Specifies the content type, which can be set on the OUT message by the
application/processor. The value is the `content-type` of the response
message. If this header is not set, the content type is based on the
object type of the OUT message body. If the
Content-Type header is specified in the Camel IN message, the value of
the header determine the content type for the Restlet request message.  
Otherwise, it is defaulted to "application/x-www-form-urlencoded'.

|`CamelAcceptContentType` |`String` |The HTTP Accept request header.

|`CamelHttpMethod` |`String` |The HTTP request method. This is set in the IN message header.

|`CamelHttpQuery` |`String` |The query string of the request URI. It is set on the IN message by
`DefaultRestletBinding` when the restlet component receives a request.

|`CamelHttpResponseCode` |`String` or `Integer` |The response code can be set on the OUT message by the
application/processor. The value is the response code of the response
message. If this header is not set, the response code is set by the
restlet runtime engine.

|`CamelHttpUri` |`String` |The HTTP request URI. This is set in the IN message header.

|`CamelRestletLogin` |`String` |Login name for basic authentication. It is set on the IN message by the
application and gets filtered before the restlet request header by
Camel.

|`CamelRestletPassword` |`String` |Password name for basic authentication. It is set on the IN message by
the application and gets filtered before the restlet request header by
Camel.

|`CamelRestletRequest` |`Request` |The `org.restlet.Request` object which holds all request
details.

|`CamelRestletResponse` |`Response` |The `org.restlet.Response` object. You can use this to
create responses using the API from Restlet. See examples below.

|`org.restlet.*` |  |Attributes of a Restlet message that get propagated to Camel IN headers.

|`cache-control` |`String` or `List<CacheDirective>` |User can set the cache-control with the String value or
the List of CacheDirective of Restlet from the camel message header.
|===

== 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)

NOTE: `org.apache.camel.restlet.auth.login` and
`org.apache.camel.restlet.auth.password` will not be propagated as
Restlet header.

The sample client gets a response like the following:

[source,text]
----
received [<order foo='1'/>] as an order id = 89531
----

=== Single restlet endpoint to service multiple methods and URI templates (deprecated)

This functionality is *deprecated* so do NOT use!

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.

[source,xml]
----
<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:

*Generating response using Restlet Response API*

=== Configuring max threads on component

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

[source,xml]
----
<bean id="restlet" class="org.apache.camel.component.restlet.RestletComponent">
  <property name="maxThreads" value="100"/>
</bean>
----

=== Using the Restlet servlet within a webapp

*Available as of Camel 2.8* +
 There are
http://www.restlet.org/documentation/2.0/jee/ext/org/restlet/ext/servlet/ServerServlet.html[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;

[source,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;

[source,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;

[source,text]
----
"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:

[source,xml]
----
<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:

[source,xml]
----
<repository>  
   <id>maven-restlet</id>  
   <name>Public online Restlet repository</name>  
   <url>https://maven.restlet.com</url>
</repository>
----