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

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          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 or FEATURE_FILTER_FORWARD_ON_404 is not set to true 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 class is instantiated as a singleton component managed by the runtime, and injection may be performed (the artifacts that may be injected are limited to injectable providers registered when the servlet or filter is configured).

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 resource configuration related initialization parameters are present a new instance of WebAppResourceConfig is created. The initialization parameter "com.sun.jersey.config.property.classpath" MAY be set to provide one or more resource paths. Each path MUST be separated by ';'. The resource 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 WebAppResourceConfig. If the initialization parameter is not present then the following resource paths are utilized: "/WEB-INF/lib" and "/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 a root resource, provider and Application classes using Context: HttpServletRequest, HttpServletResponse, ServletContext, ServletConfig and WebConfig. 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. WebConfig may be injected to abstract servlet or filter deployment.

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

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 ignored 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

FEATURE_FILTER_FORWARD_ON_404

public static final java.lang.String FEATURE_FILTER_FORWARD_ON_404

If true and a 404 response with no entity body is returned from either the runtime or the application then the runtime forwards the request to the next filter in the filter chain. This enables another filter or the underlying servlet engine to process the request. Before the request is forwarded the response status is set to 200.

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

Application code, such as methods corresponding to sub-resource locators may be invoked when this feature is enabled.

This feature is an alternative to setting PROPERTY_WEB_PAGE_CONTENT_REGEX and requires less configuration. However, application code, such as methods corresponding to sub-resource locators, may be invoked when this feature is enabled.

The default value is false.

See Also:

Constant Field Values

ServletContainer

public ServletContainer()

ServletContainer

public ServletContainer(java.lang.Class<? extends Application> appClass)

ServletContainer

public ServletContainer(Application app)

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 WebAppResourceConfig 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 int 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.

Returns:

the status code of the response.

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 WebAppResourceConfig 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