com.noelios.restlet.ext.servlet
Class ServerServlet

java.lang.Object
  extended by javax.servlet.GenericServlet
      extended by javax.servlet.http.HttpServlet
          extended by com.noelios.restlet.ext.servlet.ServerServlet
All Implemented Interfaces:
java.io.Serializable, Servlet, ServletConfig
Direct Known Subclasses:
GwtShellServletWrapper, SpringServerServlet, XdbServerServlet

public class ServerServlet
extends HttpServlet

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 Component class. 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".

Author:
Jerome Louvel
See Also:
J2EE home page, Serialized Form

Constructor Summary
ServerServlet()
          Constructor.
 
Method Summary
protected  Application createApplication(Context parentContext)
          Creates the single Application used by this Servlet.
protected  HttpServerCall 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.
 java.lang.String getInitParameter(java.lang.String name, java.lang.String defaultValue)
          Returns the value of a given initialization parameter, first from the Servlet configuration, then from the Web Application context.
 HttpServerHelper getServer(HttpServletRequest request)
          Returns the associated HTTP server handling calls.
 void init()
           
protected  java.lang.Class<?> loadClass(java.lang.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 HttpServerCall 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.

getInitParameter

public java.lang.String getInitParameter(java.lang.String name,
                                         java.lang.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.

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

loadClass

protected java.lang.Class<?> loadClass(java.lang.String className)
                                throws java.lang.ClassNotFoundException
Returns a class for a given qualified class name.

Parameters:
className - The class name to lookup.
Returns:
The class object.
Throws:
java.lang.ClassNotFoundException

service

public void service(HttpServletRequest request,
                    HttpServletResponse response)
             throws ServletException,
                    java.io.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
java.io.IOException


Copyright © 2005-2008 Noelios Technologies.