The Restlet component provides Restlet based endpoints for consuming and producing RESTful resources.
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&...
Name | Default Value | Description |
---|---|---|
headerFilterStrategy=#refName (2.x or
later) |
An instance of RestletHeaderFilterStrategy
|
Use the # notation (headerFilterStrategy=#refName ) to
reference a header filter strategy in the Camel Registry. The strategy will be plugged
into the restlet binding if it is HeaderFilterStrategyAware . |
restletBindingRef (1.x), |
An instance of DefaultRestletBinding
|
The bean ID of a RestletBinding object in the Camel Registry. |
restletBinding (2.x or later),
restletBinding=# refName. |
An instance of DefaultRestletBinding
|
The bean ID of a RestletBinding object in the Camel Registry. |
restletMethod
|
GET
|
On a producer endpoint, specifies the request method to use. On a consumer endpoint,
specifies that the endpoint consumes only restletMethod requests. The
string value is converted to org.restlet.data.Method by the Method.valueOf(String) method.
|
restletMethod
|
GET
|
On a producer endpoint, specifies the request method to use. On a consumer endpoint,
specifies that the endpoint consumes only restletMethod requests. The
string value is converted to org.restlet.data.Method by the Method.valueOf(String) method.
|
restletMethods (2.x or later) |
None | Consumer only 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. |
restletRealmRef (1.x), |
null
|
The bean ID of the Realm Map in the Camel Registry. |
restletUriPatterns=#refName (2.x or later) |
None | Consumer only Specify one ore more URI templates to be
serviced by a restlet consumer endpoint, using the # notation to
reference a List<String> in the Camel Registry. If a URI pattern has
been defined in the endpoint URI, both the URI pattern defined in the endpoint and the
restletUriPatterns option will be honored. |
throwExceptionOnFailure (2.6 or
later) |
true
|
Producer only Throws exception on a producer failure. |
Name | Type | Description |
---|---|---|
org.apache.camel.restlet.auth.login
|
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 Fuse Mediation Router. |
org.apache.camel.restlet.auth.password
|
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 Fuse Mediation Router. |
org.apache.camel.restlet.mediaType
|
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 set based on
the object type of the OUT message body. |
org.apache.camel.restlet.queryString
|
String
|
The query string of the request URI. It is set on the IN message by
DefaultRestletBinding when the restlet component receives a request.
|
org.apache.camel.restlet.responseCode
|
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. |
org.restlet.*
|
Attributes of a restlet message that get propagated to Fuse Mediation Router IN headers. |
Name | Type | Description |
---|---|---|
CamelContentType
|
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. In Camel 2.3 onward, 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. nbsp; Otherwise, it is defaulted to
"application/x-www-form-urlencoded'. Prior to release 2.3, it is not possible to change
the request content type default. |
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 Fuse Mediation Router. |
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 Fuse Mediation Router. |
CamelRestletRequest
|
Request
|
Camel 2.8: The org.restlet.Request object which holds all request details. |
CamelRestletResponse
|
Response
|
Camel 2.8: 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 Fuse Mediation Router IN headers. |
Fuse Mediation Router 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.
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.
from("restlet:http://localhost:9080/securedOrders?restletMethod=post&restletRealm=#realm").process(new Processor() { public void process(Exchange exchange) throws Exception { exchange.getOut().setBody( "received [" + exchange.getIn().getBody() + "] as an order id = " + exchange.getIn().getHeader("id")); } });
The restletRealm
setting (in Fuse Mediation Router
2.x, use the #
notation, that is,
restletRealm=#refName
) 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.
<util:map id="realm"> <entry key="admin" value="foo" /> <entry key="bar" value="foo" /> </util:map>
The following sample starts a direct
endpoint that sends requests to
the server on
http://localhost:8080
(that is, our restlet consumer endpoint).
// Note: restletMethod and restletRealmRef are stripped // from the query before a request is sent as they are // only processed by Camel. from("direct:start-auth").to("restlet:http://localhost:9080/securedOrders?restletMethod=post");
That is all we need. We are ready to send a request and try out the restlet component:
final String id = "89531"; Map<String, Object> headers = new HashMap<String, Object>(); headers.put(RestletConstants.RESTLET_LOGIN, "admin"); headers.put(RestletConstants.RESTLET_PASSWORD, "foo"); headers.put("id", id); String response = (String) template.requestBodyAndHeaders("direct:start-auth", "<order foo='1'/>", headers);
The sample client sends a request to the direct:start-auth
endpoint
with the following headers:
CamelRestletLogin
(used internally by Fuse Mediation Router)CamelRestletPassword
(used internally by Fuse Mediation Router)id
(application header)
Note | |
---|---|
|
The sample client gets a response like the following:
received [<order foo='1'/>] as an order id = 89531
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:
from("restlet:http://localhost:9080/users/{username}?restletMethods=post,get") .process(new Processor() { public void process(Exchange exchange) throws Exception { // echo the method exchange.getOut().setBody(exchange.getIn().getHeader(Exchange.HTTP_METHOD, String.class)); } });
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.
from("restlet:http://localhost:9080?restletMethods=post,get&restletUriPatterns=#uriTemplates") .process(new Processor() { public void process(Exchange exchange) throws Exception { // echo the method String uri = exchange.getIn().getHeader(Exchange.HTTP_URI, String.class); String out = exchange.getIn().getHeader(Exchange.HTTP_METHOD, String.class); if ("http://localhost:9080/users/homer".equals(uri)) { exchange.getOut().setBody(out + " " + exchange.getIn().getHeader("username", String.class)); } else if ("http://localhost:9080/atom/collection/foo/component/bar".equals(uri)) { exchange.getOut().setBody(out + " " + exchange.getIn().getHeader("id", String.class) + " " + exchange.getIn().getHeader("cid", String.class)); } } });
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>
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:
from("restlet:http://localhost:" + portNum + "/users/{id}/like/{beer}") .process(new Processor() { public void process(Exchange exchange) throws Exception { // the Restlet request should be available if neeeded Request request = exchange.getIn().getHeader(RestletConstants.RESTLET_REQUEST, Request.class); assertNotNull("Restlet Request", request); // use Restlet API to create the response Response response = exchange.getIn().getHeader(RestletConstants.RESTLET_RESPONSE, Response.class); assertNotNull("Restlet Response", response); response.setStatus(Status.SUCCESS_OK); response.setEntity("<response>Beer is Good</response>", MediaType.TEXT_XML); exchange.getOut().setBody(response); } });
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>