com.sun.jersey.spi.container.servlet
Class ServletContainer

java.lang.Object
  extended by javax.servlet.GenericServlet
      extended by javax.servlet.http.HttpServlet
          extended by com.sun.jersey.spi.container.servlet.ServletContainer
All Implemented Interfaces:
java.io.Serializable, javax.servlet.Filter, javax.servlet.Servlet, javax.servlet.ServletConfig

public class ServletContainer
extends javax.servlet.http.HttpServlet
implements javax.servlet.Filter

A Servlet or Filter for deploying root resource classes.

If this class is declared as a filter and the initialization parameter PROPERTY_WEB_PAGE_CONTENT_REGEX is not set, then the filter must be declared at the last position in the filter chain as the filter will not forward any request to a next filter (if any) in the chain.

The following sections make reference to initialization parameters. Unless otherwise specified the initialization parameters apply to both server and filter initialization parameters.

The servlet or filter may be configured to have an initialization parameter "com.sun.jersey.config.property.resourceConfigClass" or "javax.ws.rs.Application" and whose value is a fully qualified name of a class that implements ResourceConfig or Application. If the concrete class has a constructor that takes a single parameter of the type Map then the class is instantiated with that constructor and an instance of Map that contains all the initialization parameters is passed as the parameter. Otherwise the default contructor is used to instantate the class.

If the initialization parameter "com.sun.jersey.config.property.resourceConfigClass" or "javax.ws.rs.Application" is not present and a initialization parameter "com.sun.jersey.config.property.packages" is present (see PackagesResourceConfig.PROPERTY_PACKAGES) a new instance of PackagesResourceConfig is created. The initialization parameter "com.sun.jersey.config.property.packages" MUST be set to provide one or more package names. Each package name MUST be separated by ';'. The package names are added as a property value to a Map instance using the property name (@link PackagesResourceConfig#PROPERTY_PACKAGES}. Any additional initialization parameters are then added to the Map instance. Then that Map instance is passed to the constructor of PackagesResourceConfig.

If none of the above initialization parameters are present a new instance of ClasspathResourceConfig is created. The initialization parameter "com.sun.jersey.config.property.classpath" MAY be set to provide one or more paths. Each path MUST be separated by ';'. Each path MUST be a virtual path as specified by the ServletContext.getRealPath(java.lang.String) method, and each path is transformed by that method. The transformed paths are added as a property value to a Map instance using the property name (@link ClasspathResourceConfig.PROPERTY_CLASSPATH}. Any additional initialization parameters are then added to the Map instance. Then that Map instance is passed to the constructor of ClasspathResourceConfig. If this parameter is not set then the default value is set to the following virtual paths: "/WEB-INF/lib;/WEB-INF/classes".

All initialization parameters are added as properties of the created ResourceConfig.

A new WebApplication instance will be created and configured such that the following classes may be injected onto the field of a root resource class or a parameter of a method of root resource class that is annotated with Context: HttpServletRequest, HttpServletResponse, ServletContext, and ServletConfig. If this class is used as a Servlet then the ServletConfig class may be injected. If this class is used as a Filter then the FilterConfig class may be injected.

A IoCComponentProviderFactory instance may be registered by extending this class and overriding the method initiate(ResourceConfig, WebApplication) to initiate the WebApplication with the IoCComponentProviderFactory instance.

See Also:
Serialized Form

Nested Class Summary
protected static class ServletContainer.ContextInjectableProvider<T>
          A helper class for creating an injectable provider that supports Context with a type and constant value.
 
Field Summary
static java.lang.String APPLICATION_CONFIG_CLASS
          The servlet initializaton property whose value is a fully qualified class name of a class that implements ResourceConfig or Application.
static java.lang.String JSP_TEMPLATES_BASE_PATH
          The base path in the Web Pages where JSP templates, associated with viewables of resource classes, are located.
static java.lang.String PROPERTY_WEB_PAGE_CONTENT_REGEX
          If set the regular expression used to match an incoming servlet path URI to some web page content such as static resources or JSPs to be handled by the underlying servlet engine.
static java.lang.String RESOURCE_CONFIG_CLASS
          The servlet initializaton property whose value is a fully qualified class name of a class that implements ResourceConfig or Application.
 
Constructor Summary
ServletContainer()
           
 
Method Summary
protected  void configure(javax.servlet.FilterConfig fc, ResourceConfig rc, WebApplication wa)
          Configure the ResourceConfig for a Filter.
protected  void configure(javax.servlet.ServletConfig sc, ResourceConfig rc, WebApplication wa)
          Configure the ResourceConfig for a Servlet.
protected  void configure(WebConfig wc, ResourceConfig rc, WebApplication wa)
          Configure the ResourceConfig.
protected  WebApplication create()
          Create a new instance of a WebApplication.
 void destroy()
          Destroy this Servlet or Filter.
 void doFilter(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, javax.servlet.FilterChain chain)
          Dispatches client requests to the service(java.net.URI, java.net.URI, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) method.
 void doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)
          Dispatches client requests to the doFilter(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, javax.servlet.FilterChain) method.
protected  ResourceConfig getDefaultResourceConfig(java.util.Map<java.lang.String,java.lang.Object> props, javax.servlet.ServletConfig servletConfig)
          Deprecated. methods should implement getDefaultResourceConfig(java.util.Map, com.sun.jersey.spi.container.servlet.WebConfig).
protected  ResourceConfig getDefaultResourceConfig(java.util.Map<java.lang.String,java.lang.Object> props, WebConfig wc)
          Get the default resource configuration if one is not declared in the web.xml.
 javax.servlet.ServletContext getServletContext()
          Get the servlet context for the servlet or filter, depending on how this class is registered.
 java.util.regex.Pattern getStaticContentPattern()
           
protected  WebConfig getWebConfig()
          Get the Web configuration.
 void init()
           
 void init(javax.servlet.FilterConfig filterConfig)
           
protected  void init(WebConfig webConfig)
          Initiate the Web component.
protected  void initiate(ResourceConfig rc, WebApplication wa)
          Initiate the WebApplication.
 void load()
          Load the Web application.
 void reload()
          Reload the Web application.
 void service(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Dispatches client requests to the service(java.net.URI, java.net.URI, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) method.
 void service(java.net.URI baseUri, java.net.URI requestUri, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Dispatch client requests to a resource class.
 
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, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

APPLICATION_CONFIG_CLASS

public static final java.lang.String APPLICATION_CONFIG_CLASS
The servlet initializaton property whose value is a fully qualified class name of a class that implements ResourceConfig or Application.

See Also:
Constant Field Values

RESOURCE_CONFIG_CLASS

public static final java.lang.String RESOURCE_CONFIG_CLASS
The servlet initializaton property whose value is a fully qualified class name of a class that implements ResourceConfig or Application.

See Also:
Constant Field Values

JSP_TEMPLATES_BASE_PATH

public static final java.lang.String JSP_TEMPLATES_BASE_PATH
The base path in the Web Pages where JSP templates, associated with viewables of resource classes, are located.

If this property is not set then the base path will be the root path of the Web Pages.

See Also:
Constant Field Values

PROPERTY_WEB_PAGE_CONTENT_REGEX

public static final java.lang.String PROPERTY_WEB_PAGE_CONTENT_REGEX
If set the regular expression used to match an incoming servlet path URI to some web page content such as static resources or JSPs to be handled by the underlying servlet engine.

The type of this property must be a String and the value must be a valid regular expression.

This property is only applicable when this class is used as a Filter, otherwise this property will be ingored and not processed.

If a servlet path matches this regular expression then the filter forwards the request to the next filter in the filter chain so that the underlying servlet engine can process the request otherwise Jersey will process the request.

For example if you set the value to /(image|css)/.* then you can serve up images and CSS files for your Implicit or Explicit Views while still processing your JAX-RS resources.

See Also:
Constant Field Values
Constructor Detail

ServletContainer

public ServletContainer()
Method Detail

getServletContext

public javax.servlet.ServletContext getServletContext()
Get the servlet context for the servlet or filter, depending on how this class is registered.

It is recommended that the WebConfig be utilized, see the method getWebConfig(), to obtain the servlet context and initialization parameters for a servlet or filter.

Specified by:
getServletContext in interface javax.servlet.ServletConfig
Overrides:
getServletContext in class javax.servlet.GenericServlet
Returns:
the servlet context for the servlet or filter.

init

protected void init(WebConfig webConfig)
             throws javax.servlet.ServletException
Initiate the Web component.

Parameters:
webConfig - the Web configuration.
Throws:
javax.servlet.ServletException

getWebConfig

protected WebConfig getWebConfig()
Get the Web configuration.

Returns:
the Web configuration.

create

protected WebApplication create()
Create a new instance of a WebApplication.

Returns:
the WebApplication instance.

getDefaultResourceConfig

protected ResourceConfig getDefaultResourceConfig(java.util.Map<java.lang.String,java.lang.Object> props,
                                                  WebConfig wc)
                                           throws javax.servlet.ServletException
Get the default resource configuration if one is not declared in the web.xml.

This implementaton returns an instance of ClasspathResourceConfig that scans in files and directories as declared by the ClasspathResourceConfig.PROPERTY_CLASSPATH if present, otherwise in the "WEB-INF/lib" and "WEB-INF/classes" directories.

An inheriting class may override this method to supply a different default resource configuraton implementaton.

Parameters:
props - the properties to pass to the resource configuraton.
wc - the web configuration.
Returns:
the default resource configuraton.
Throws:
javax.servlet.ServletException

configure

protected void configure(WebConfig wc,
                         ResourceConfig rc,
                         WebApplication wa)
Configure the ResourceConfig.

The ResourceConfig is configured such that the following classes may be injected onto the field of a root resource class or a parameter of a method of root resource class that is annotated with Context: HttpServletRequest, HttpServletResponse , ServletContext and WebConfig.

Any root resource class in registered in the resource configuration that is an interface is processed as follows. If the class is an interface and there exists a JNDI named object with the fully qualified class name as the JNDI name then that named object is added as a singleton root resource and the class is removed from the set of root resource classes.

An inheriting class may override this method to configure the ResourceConfig to provide alternative or additional instances that are resource or provider classes or instances, and may modify the features and properties of the ResourceConfig. For an inheriting class to extend configuration behaviour the overriding method MUST call super.configure(servletConfig, rc, wa) as the first statement of that method.

This method will be called only once at initiation. Subsequent reloads of the Web application will not result in subsequence calls to this method.

Parameters:
wc - the Web configuration
rc - the Resource configuration
wa - the Web application

initiate

protected void initiate(ResourceConfig rc,
                        WebApplication wa)
Initiate the WebApplication.

This method will be called once at initiation and for each reload of the Web application.

An inheriting class may override this method to initiate the Web application with different parameters.

Parameters:
rc - the Resource configuration
wa - the Web application

load

public void load()
Load the Web application. This will create, configure and initiate the web application.


reload

public void reload()
Reload the Web application. This will create and initiate the web application using the same ResourceConfig implementation that was used to load the Web application.

This method may be called at runtime, more than once, to reload the Web application. For example, if a ResourceConfig implementation is capable of detecting changes to resource classes (addition or removal) or providers then this method may be invoked to reload the web application for such changes to take effect.

If this method is called when there are pending requests then such requests will be processed using the previously loaded web application.


service

public void service(java.net.URI baseUri,
                    java.net.URI requestUri,
                    javax.servlet.http.HttpServletRequest request,
                    javax.servlet.http.HttpServletResponse response)
             throws javax.servlet.ServletException,
                    java.io.IOException
Dispatch client requests to a resource class.

Parameters:
baseUri - the base URI of the request.
requestUri - the URI of the request.
request - the HttpServletRequest object that contains the request the client made to the Web component.
response - the HttpServletResponse object that contains the response the Web component returns to the client.
Throws:
java.io.IOException - if an input or output error occurs while the Web component is handling the HTTP request.
javax.servlet.ServletException - if the HTTP request cannot be handled.

destroy

public void destroy()
Destroy this Servlet or Filter.

Specified by:
destroy in interface javax.servlet.Filter
Specified by:
destroy in interface javax.servlet.Servlet
Overrides:
destroy in class javax.servlet.GenericServlet

init

public void init()
          throws javax.servlet.ServletException
Overrides:
init in class javax.servlet.GenericServlet
Throws:
javax.servlet.ServletException

getDefaultResourceConfig

@Deprecated
protected ResourceConfig getDefaultResourceConfig(java.util.Map<java.lang.String,java.lang.Object> props,
                                                             javax.servlet.ServletConfig servletConfig)
                                           throws javax.servlet.ServletException
Deprecated. methods should implement getDefaultResourceConfig(java.util.Map, com.sun.jersey.spi.container.servlet.WebConfig).

Get the default resource configuration if one is not declared in the web.xml.

This implementaton returns an instance of ClasspathResourceConfig that scans in files and directories as declared by the ClasspathResourceConfig.PROPERTY_CLASSPATH if present, otherwise in the "WEB-INF/lib" and "WEB-INF/classes" directories.

An inheriting class may override this method to supply a different default resource configuraton implementaton.

Parameters:
props - the properties to pass to the resource configuraton.
servletConfig - the servlet configuration.
Returns:
the default resource configuraton.
Throws:
javax.servlet.ServletException

configure

protected void configure(javax.servlet.ServletConfig sc,
                         ResourceConfig rc,
                         WebApplication wa)
Configure the ResourceConfig for a Servlet.

The ResourceConfig is configured such that the following classes may be injected onto the field of a root resource class or a parameter of a method of root resource class that is annotated with Context: ServletConfig.

An inheriting class may override this method to configure the ResourceConfig to provide alternative or additional instances that are resource or provider classes or instances, and may modify the features and properties of the ResourceConfig. For an inheriting class to extend configuration behaviour the overriding method MUST call super.configure(servletConfig, rc, wa) as the first statement of that method.

This method will be called only once at servlet initiation. Subsequent reloads of the Web application will not result in subsequence calls to this method.

Parameters:
sc - the Servlet configuration
rc - the Resource configuration
wa - the Web application

service

public void service(javax.servlet.http.HttpServletRequest request,
                    javax.servlet.http.HttpServletResponse response)
             throws javax.servlet.ServletException,
                    java.io.IOException
Dispatches client requests to the service(java.net.URI, java.net.URI, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) method.

Overrides:
service in class javax.servlet.http.HttpServlet
Parameters:
request - the HttpServletRequest object that contains the request the client made to the servlet.
response - the HttpServletResponse object that contains the response the servlet returns to the client.
Throws:
java.io.IOException - if an input or output error occurs while the servlet is handling the HTTP request.
javax.servlet.ServletException - if the HTTP request cannot be handled.

init

public void init(javax.servlet.FilterConfig filterConfig)
          throws javax.servlet.ServletException
Specified by:
init in interface javax.servlet.Filter
Throws:
javax.servlet.ServletException

getStaticContentPattern

public java.util.regex.Pattern getStaticContentPattern()
Returns:
the Pattern compiled from a regular expression that is the property value of PROPERTY_WEB_PAGE_CONTENT_REGEX. A null value will be returned if the property is not present is or an empty String.

configure

protected void configure(javax.servlet.FilterConfig fc,
                         ResourceConfig rc,
                         WebApplication wa)
Configure the ResourceConfig for a Filter.

The ResourceConfig is configured such that the following classes may be injected onto the field of a root resource class or a parameter of a method of root resource class that is annotated with Context: FilterConfig.

An inheriting class may override this method to configure the ResourceConfig to provide alternative or additional instances that are resource or provider classes or instances, and may modify the features and properties of the ResourceConfig. For an inheriting class to extend configuration behaviour the overriding method MUST call super.configure(servletConfig, rc, wa) as the first statement of that method.

This method will be called only once at servlet initiation. Subsequent reloads of the Web application will not result in subsequence calls to this method.

Parameters:
fc - the Filter configuration
rc - the Resource configuration
wa - the Web application

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException
Dispatches client requests to the doFilter(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, javax.servlet.FilterChain) method.

Specified by:
doFilter in interface javax.servlet.Filter
Parameters:
request - the HttpServletRequest object that contains the request the client made to the servlet.
response - the HttpServletResponse object that contains the response the servlet returns to the client.
chain - the chain of filters from which the next filter can be invoked.
Throws:
java.io.IOException
javax.servlet.ServletException

doFilter

public void doFilter(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException
Dispatches client requests to the service(java.net.URI, java.net.URI, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) method.

If the servlet path matches the regular expression declared by the property PROPERTY_WEB_PAGE_CONTENT_REGEX then the request is forwarded to the next filter in the filter chain so that the underlying servlet engine can process the request otherwise Jersey will process the request.

Parameters:
request - the HttpServletRequest object that contains the request the client made to the servlet.
response - the HttpServletResponse object that contains the response the servlet returns to the client.
chain - the chain of filters from which the next filter can be invoked.
Throws:
java.io.IOException
javax.servlet.ServletException


Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved.