Restlet Framework 2.2 Snapshot
Google App Engine

org.restlet.ext.servlet
Class ServerServlet

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

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
ServerServlet()
          Constructor.
 
Method Summary
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

Restlet Framework 2.2 Snapshot
Google App Engine

Copyright © 2005-2014 Restlet.