org.restlet.ext.servlet

Class ServerServlet

java.lang.Object

javax.servlet.GenericServlet

javax.servlet.http.HttpServlet

org.restlet.ext.servlet.ServerServlet

All Implemented Interfaces:

Serializable, Servlet, ServletConfig

public class ServerServlet
extends HttpServlet

Servlet acting like an HTTP server connector. This Servlet can deploy multiple Restlet applications or components. 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. Please note that you can also combine the two first of them whereas the last one is a full alternative. They are described below by order of priority:

Mode	Description
1	A "/WEB-INF/restlet.xml" file exists and contains a valid XML configuration as described in the documentation of the Component class. It is used to instantiate and attach the described component, contained applications and connectors. Please note that you can combine the usage of such configuration file and method 2.
2	The "/WEB-INF/web.xml" file contains a 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. Please note that you can combine the definition of your own custom Component subclass and method 1.
3	The "/WEB-INF/web.xml" file contains a 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 an implicit Restlet Component.

In deployment mode 3, you can also add an optional "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 implicit Component instance.
Here is an example configuration to attach two separate applications:

 <?xml version="1.0" encoding="UTF-8"?>
 <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         id="WebApp_ID" version="2.5">
 
         <display-name>Restlet adapters</display-name>
 
         <servlet>
                 <servlet-name>Restlet1</servlet-name>
                 <servlet-class>org.restlet.ext.servlet.ServerServlet</servlet-class>
                 <init-param>
                         <param-name>org.restlet.application</param-name>
                         <param-value>test.MyApplication1</param-value>
                 </init-param>
         </servlet>
 
         <servlet-mapping>
                 <servlet-name>Restlet1</servlet-name>
                 <url-pattern>/1/*</url-pattern>
         </servlet-mapping>
 
         <servlet>
                 <servlet-name>Restlet2</servlet-name>
                 <servlet-class>org.restlet.ext.servlet.ServerServlet</servlet-class>
                 <init-param>
                         <param-name>org.restlet.application</param-name>
                         <param-value>test.MyApplication2</param-value>
                 </init-param>
         </servlet>
 
         <servlet-mapping>
                 <servlet-name>Restlet2</servlet-name>
                 <url-pattern>/2/*</url-pattern>
         </servlet-mapping>
 
 </web-app>
 

Now, here is a more detailed template configuration showing you more configuration options:

 <?xml version="1.0" encoding="UTF-8"?>
 <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         id="WebApp_ID" version="2.5">
 
         <display-name>Restlet adapters</display-name>
 
         <!-- Servlet to Restlet adapter declaration (Mandatory) -->
         <servlet>
                 <servlet-name>RestletAdapter</servlet-name>
                 <servlet-class>org.restlet.ext.servlet.ServerServlet</servlet-class>
 
                 <!-- Your component class name (Optional - For mode 2) -->
                 <init-param>
                         <param-name>org.restlet.component</param-name>
                         <param-value>test.MyComponent</param-value>
                 </init-param>
 
                 <!-- Your application class name (Optional - For mode 3) -->
                 <init-param>
                         <param-name>org.restlet.application</param-name>
                         <param-value>test.MyApplication</param-value>
                 </init-param>
 
                 <!-- List of supported client protocols (Optional - Only in mode 3) -->
                 <init-param>
                         <param-name>org.restlet.clients</param-name>
                         <param-value>HTTP HTTPS FILE</param-value>
                 </init-param>
 
                 <!-- Add the Servlet context path to routes (Optional) -->
                 <init-param>
                         <param-name>org.restlet.autoWire</param-name>
                         <param-value>true</param-value>
                 </init-param>
         </servlet>
 
         <!-- Mapping catching all requests on a given path (Mandatory) -->
         <servlet-mapping>
                 <servlet-name>RestletAdapter</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 additional 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 according 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 continues 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".

Also, a WAR client connector is automatically attached to the parent Restlet component. It lets you access to resources inside your WAR using the uniform interface. Here is an example of WAR URI that can be resolved by this client: "war:///WEB-INF/web.xml". In order to use it, just call the Context.getClientDispatcher() in your application.

Also, the ServletContext is copied into an "org.restlet.ext.servlet.ServletContext" attribute of the Restlet application in case you need access to it.

Finally, an "org.restlet.ext.servlet.offsetPath" attribute, containing the computed offset path used to attach applications when (and only when) the auto-wiring feature is set, is added to the component's context.

Author:

Jerome Louvel

See Also:

J2EE home page, Serialized Form

Constructor Summary

Constructors

Constructor and Description
ServerServlet() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected Application	createApplication(Context parentContext) Creates the single Application used by this Servlet.
protected ServerCall	createCall(Server server, HttpServletRequest request, HttpServletResponse response) Creates a new Servlet call wrapping a Servlet request/response couple and a Server connector.
protected Component	createComponent() Creates the single Component used by this Servlet.
protected HttpServerHelper	createServer(HttpServletRequest request) Creates the associated HTTP server handling calls.
protected Client	createWarClient(Context context, ServletConfig config) Creates a new client for the WAR protocol.
void	destroy()
Application	getApplication() Returns the application.
Component	getComponent() Returns the component.
protected String	getContextPath(HttpServletRequest request) Intercepter method need for subclasses such as XdbServerServlet.
String	getInitParameter(String name, String defaultValue) Returns the value of a given initialization parameter, first from the Servlet configuration, then from the Web Application context.
protected String	getLocalAddr(HttpServletRequest request) Intercepter method need for subclasses such as XdbServerServlet.
protected int	getLocalPort(HttpServletRequest request) Intercepter method need for subclasses such as XdbServerServlet.
HttpServerHelper	getServer(HttpServletRequest request) Returns the associated HTTP server handling calls.
void	init()
protected void	init(Application application) Initialize a application.
protected void	init(Component component) Initialize a component.
protected Class<?>	loadClass(String className) Returns a class for a given qualified class name.
void	service(HttpServletRequest request, HttpServletResponse response) Services a HTTP Servlet request as an uniform call.

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerServlet

public ServerServlet()

Constructor.

Method Detail

createApplication

protected Application createApplication(Context parentContext)

Creates the single Application used by this Servlet.

Parameters:

parentContext - The parent component context.

Returns:

The newly created Application or null if unable to create

createCall

protected ServerCall createCall(Server server,
                    HttpServletRequest request,
                    HttpServletResponse response)

Creates a new Servlet call wrapping a Servlet request/response couple and a Server connector.

Parameters:

server - The Server connector.

request - The Servlet request.

response - The Servlet response.

Returns:

The new ServletCall instance.

createComponent

protected Component createComponent()

Creates the single Component used by this Servlet.

Returns:

The newly created Component or null if unable to create.

createServer

protected HttpServerHelper createServer(HttpServletRequest request)

Creates the associated HTTP server handling calls.

Parameters:

request - The HTTP Servlet request.

Returns:

The new HTTP server handling calls.

createWarClient

protected Client createWarClient(Context context,
                     ServletConfig config)

Creates a new client for the WAR protocol.

Parameters:

context - The parent context.

config - The Servlet config.

Returns:

The new WAR client instance.

destroy

public void destroy()

Specified by:

destroy in interface Servlet

Overrides:

destroy in class GenericServlet

getApplication

public Application getApplication()

Returns the application. It creates a new one if none exists.

Returns:

The application.

getComponent

public Component getComponent()

Returns the component. It creates a new one if none exists.

Returns:

The component.

getContextPath

protected String getContextPath(HttpServletRequest request)

Intercepter method need for subclasses such as XdbServerServlet.

Parameters:

request - The Servlet request.

Returns:

The portion of the request URI that indicates the context of the request.

getInitParameter

public String getInitParameter(String name,
                      String defaultValue)

Returns the value of a given initialization parameter, first from the Servlet configuration, then from the Web Application context.

Parameters:

name - The parameter name.

defaultValue - The default to use in case the parameter is not found.

Returns:

The value of the parameter or null.

getLocalAddr

protected String getLocalAddr(HttpServletRequest request)

Intercepter method need for subclasses such as XdbServerServlet.

Parameters:

request - The Servlet request.

Returns:

The Internet Protocol (IP) address of the interface on which the request was received.

getLocalPort

protected int getLocalPort(HttpServletRequest request)

Intercepter method need for subclasses such as XdbServerServlet.

Parameters:

request - The Servlet request.

Returns:

The Internet Protocol (IP) port number of the interface on which the request was received

getServer

public HttpServerHelper getServer(HttpServletRequest request)

Returns the associated HTTP server handling calls. It creates a new one if none exists.

Parameters:

request - The HTTP Servlet request.

Returns:

The HTTP server handling calls.

init

public void init()
          throws ServletException

Overrides:

init in class GenericServlet

Throws:

ServletException

init

protected void init(Application application)

Initialize a application. Copies Servlet parameters into the component's context. Copies the ServletContext into an "org.restlet.ext.servlet.ServletContext" attribute.

Parameters:

application - The application to configure.

init

protected void init(Component component)

Initialize a component. Adds a default WAR client and copies Servlet parameters into the component's context. Copies the ServletContext into an "org.restlet.ext.servlet.ServletContext" attribute.

Parameters:

component - The component to configure.

loadClass

protected Class<?> loadClass(String className)
                      throws ClassNotFoundException

Returns a class for a given qualified class name.

Parameters:

className - The class name to lookup.

Returns:

The class object.

Throws:

ClassNotFoundException

service

public void service(HttpServletRequest request,
           HttpServletResponse response)
             throws ServletException,
                    IOException

Services a HTTP Servlet request as an uniform call.

Overrides:

service in class HttpServlet

Parameters:

request - The HTTP Servlet request.

response - The HTTP Servlet response.

Throws:

ServletException

IOException