Servlet acting like an HTTP server connector. See
Developper FAQ #2 for details on how to
integrate a Restlet application into a servlet container.
Initially designed to deploy a single Restlet Application, this Servlet can
now deploy a complete Restlet Component. This allows you to reuse an existing
standalone Restlet Component, potentially containing several applications,
and declaring client connectors, for example for the CLAP, FILE or HTTP
protocols.
There are three separate ways to configure the deployment using this Servlet.
They are described below by order of priority:
Mode |
Description |
1 |
If a "/WEB-INF/restlet.xml" file exists and contains a valid XML
configuration as described in the documentation of the
Componentclass. It is used to instantiate and attach the described component,
contained applications and connectors. |
2 |
If the "/WEB-INF/web.xml" file contains a context parameter named
"org.restlet.component", its value must be the path of a class that inherits
from
Component. It is used to instantiate and attach the described
component, contained applications and connectors. |
3 |
If the "/WEB-INF/web.xml" file contains a context parameter named
"org.restlet.application", its value must be the path of a class that
inherits from
Application. It is used to instantiate the application
and to attach it to a default Restlet Component. |
In deployment mode 3, you can also add an optionnal "org.restlet.clients"
context parameter that contains a space separated list of client protocols
supported by the underlying component. For each one, a new client connector
is added to the Component instance.
Here is a template configuration for the ServerServlet:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>Restlet adapter</display-name>
<!-- Your component class name (Optional - For mode 2) -->
<context-param>
<param-name>org.restlet.component</param-name>
<param-value>com.mycompany.MyComponent</param-value>
</context-param>
<!-- Your application class name (Optional - For mode 3) -->
<context-param>
<param-name>org.restlet.application</param-name>
<param-value>com.mycompany.MyApplication</param-value>
</context-param>
<!-- List of supported client protocols (Optional - Only in mode 3) -->
<context-param>
<param-name>org.restlet.clients</param-name>
<param-value>HTTP HTTPS FILE</param-value>
</context-param>
<!-- Add the Servlet context path to the routes (Optional - true by default) -->
<context-param>
<param-name>org.restlet.autoWire</param-name>
<param-value>true</param-value>
</context-param>
<!-- Restlet adapter (Mandatory) -->
<servlet>
<servlet-name>ServerServlet</servlet-name>
<servlet-class>com.noelios.restlet.ext.servlet.ServerServlet</servlet-class>
</servlet>
<!-- Catch all requests (Mandatory) -->
<servlet-mapping>
<servlet-name>ServerServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Note that the enumeration of "initParameters" of your Servlet will be copied
to the "context.parameters" property of your Restlet Application. This way,
you can pass additional initialization parameters to your application, and
maybe share them with other Servlets.
An additionnal boolean parameter called "org.restlet.autoWire" allows you to
control the way your customized Component fits in the context of the wrapping
Servlet. The root cause is that both your Servlet Container and your Restlet
Component handle part of the URI routing, respectively to the right Servlet
and to the right virtual host and Restlets (most of the time Application
instances).
When a request reaches the Servlet container, it is first routed acccording
to its web.xml configuration (i.e. declared virtual hosts and webapp context
path which is generally the name of the webapp war file). Once the incoming
request reaches the ServerServlet and the wrapped Restlet Component, its URI
is, for the second time, entirely subject to a separate routing chain. It
begins with the virtual hosts, then continue to the URI pattern used when
attaching Restlets to the host. The important conclusion is that both routing
configurations must be consistent in order to work fine.
In deployment mode 3, the context path of the servlet is automatically added.
That's what we call the auto-wire feature. This is the default case, and is
equivalent to setting the value "true" for the "org.restlet.autoWire"
parameter as described above. In modes 1 or 2, if you want to manually
control the URI wiring, you can disable the auto-wiring by setting the
property to "false".