javax.faces.webapp

## Class FacesServlet

- java.lang.Object
- - javax.faces.webapp.FacesServlet

- All Implemented Interfaces:
    Servlet

      public final class FacesServlet
      extends Object
      implements Servlet

  FacesServlet is a servlet that manages the request processing lifecycle for web applications that are utilizing JavaServer Faces to construct the user interface.

  If the application is running in a Servlet 3.0 (and beyond) container, the runtime must provide an implementation of the `ServletContainerInitializer` interface that declares the following classes in its `HandlesTypes` annotation.

  - `ResourceDependencies`
  - `ResourceDependency`
  - javax.faces.bean.ManagedBean
  - `FacesComponent`
  - `UIComponent`
  - `Converter`
  - `FacesConverter`
  - `ListenerFor`
  - `ListenersFor`
  - `FacesBehaviorRenderer`
  - `Renderer`
  - `FacesValidator`
  - `Validator`

  This servlet must automatically be mapped if it is not explicitly mapped in `web.xml` or `web-fragment.xml` and one or more of the following conditions are true.

  - A `faces-config.xml` file is found in `WEB-INF`

  - A `faces-config.xml` file is found in the `META-INF` directory of a jar in the application's classpath.

  - A filename ending in `.faces-config.xml` is found in the `META-INF` directory of a jar in the application's classpath.

  - The `javax.faces.CONFIG_FILES` context param is declared in `web.xml` or `web-fragment.xml`.

  - The `Set` of classes passed to the `onStartup()` method of the `ServletContainerInitializer` implementation is not empty.

  If the runtime determines that the servlet must be automatically mapped, it must be mapped to the following <`url-pattern`> entries.

  - /faces
  - *.jsf
  - *.faces

  This class must be annotated with `javax.servlet.annotation.MultipartConfig`. This causes the Servlet container in which the JSF implementation is running to correctly handle multipart form data.

  Some security considerations relating to this class

  The topic of web application security is a cross-cutting concern and every aspect of the specification address it. However, as with any framework, the application developer needs to pay careful attention to security. Please consider these topics among the rest of the security concerns for the application. This is by no means a complete list of security concerns, and is no substitute for a thorough application level security review.

  Prefix mappings and the `FacesServlet`

  If the `FacesServlet` is mapped using a prefix `<url-pattern>`, such as `<url-pattern>/faces/*</url-pattern>`, something must be done to prevent access to the view source without its first being processed by the `FacesServlet`. One common approach is to apply a <security-constraint> to all facelet files and flow definition files. Please see the Deployment Descriptor chapter of the Java Servlet Specification for more information the use of <security-constraint>.

  Allowable HTTP Methods

  The JSF specification only requires the use of the GET and POST http methods. If your web application does not require any other http methods, such as PUT and DELETE, please consider restricting the allowable http methods using the <http-method> and <http-method-omission> elements. Please see the Security of the Java Servlet Specification for more information the use of these elements.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONFIG_FILES_ATTR` Context initialization parameter name for a comma delimited list of context-relative resource paths (in addition to `/WEB-INF/faces-config.xml` which is loaded automatically if it exists) containing JavaServer Faces configuration information.
    `static String` | `LIFECYCLE_ID_ATTR` Context initialization parameter name for the lifecycle identifier of the `Lifecycle` instance to be utilized.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FacesServlet()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Release all resources acquired at startup time.
    `ServletConfig` | `getServletConfig()` Return the `ServletConfig` instance for this servlet.
    `String` | `getServletInfo()` Return information about this Servlet.
    `void` | `init(ServletConfig servletConfig)` Acquire the factory instances we will require.
    `void` | `service(ServletRequest req, ServletResponse resp)` Process an incoming request, and create the corresponding response according to the following specification.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### CONFIG_FILES_ATTR

          public static final String CONFIG_FILES_ATTR

      Context initialization parameter name for a comma delimited list of context-relative resource paths (in addition to `/WEB-INF/faces-config.xml` which is loaded automatically if it exists) containing JavaServer Faces configuration information.

      See Also:
        Constant Field Values

    - #### LIFECYCLE_ID_ATTR

          public static final String LIFECYCLE_ID_ATTR

      Context initialization parameter name for the lifecycle identifier of the `Lifecycle` instance to be utilized.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FacesServlet

          public FacesServlet()

  - ### Method Detail

    - #### destroy

          public void destroy()

      Release all resources acquired at startup time.

      Specified by:
        `destroy` in interface `Servlet`

    - #### getServletConfig

          public ServletConfig getServletConfig()

      Return the `ServletConfig` instance for this servlet.

      Specified by:
        `getServletConfig` in interface `Servlet`
      Returns:
        the `ServletConfig` object that initializes this servlet
      See Also:
        `Servlet.init(javax.servlet.ServletConfig)`

    - #### getServletInfo

          public String getServletInfo()

      Return information about this Servlet.

      Specified by:
        `getServletInfo` in interface `Servlet`
      Returns:
        a `String` containing servlet information

    - #### init

          public void init(ServletConfig servletConfig)
                    throws ServletException

      Acquire the factory instances we will require.

      Specified by:
        `init` in interface `Servlet`
      Parameters:
        `servletConfig` - a `ServletConfig` object containing the servlet's configuration and initialization parameters
      Throws:
        `ServletException` - if, for any reason, the startup of this Faces application failed. This includes errors in the config file that is parsed before or during the processing of this `init()` method.
      See Also:
        `UnavailableException`, `Servlet.getServletConfig()`

    - #### service

          public void service(ServletRequest req,
                     ServletResponse resp)
                       throws IOException,
                              ServletException

      Process an incoming request, and create the corresponding response according to the following specification.

      If the `request` and `response` arguments to this method are not instances of `HttpServletRequest` and `HttpServletResponse`, respectively, the results of invoking this method are undefined.

      This method must respond to requests that contain the following strings by invoking the `sendError` method on the response argument (cast to `HttpServletResponse`), passing the code `HttpServletResponse.SC_NOT_FOUND` as the argument.

          /WEB-INF/
          /WEB-INF
          /META-INF/
          /META-INF

      If none of the cases described above in the specification for this method apply to the servicing of this request, the following action must be taken to service the request.

      Acquire a `FacesContext` instance for this request.

      Acquire the `ResourceHandler` for this request by calling `Application.getResourceHandler()`. Call `ResourceHandler.isResourceRequest(javax.faces.context.FacesContext)`. If this returns `true` call `ResourceHandler.handleResourceRequest(javax.faces.context.FacesContext)`. If this returns `false`, call `Lifecycle.attachWindow(javax.faces.context.FacesContext)` followed by `Lifecycle.execute(javax.faces.context.FacesContext)` followed by `Lifecycle.render(javax.faces.context.FacesContext)`. If a `FacesException` is thrown in either case, extract the cause from the `FacesException`. If the cause is `null` extract the message from the `FacesException`, put it inside of a new `ServletException` instance, and pass the `FacesException` instance as the root cause, then rethrow the `ServletException` instance. If the cause is an instance of `ServletException`, rethrow the cause. If the cause is an instance of `IOException`, rethrow the cause. Otherwise, create a new `ServletException` instance, passing the message from the cause, as the first argument, and the cause itself as the second argument.

      The implementation must make it so `FacesContext.release()` is called within a finally block as late as possible in the processing for the JSF related portion of this request.

      Specified by:
        `service` in interface `Servlet`
      Parameters:
        `req` - The servlet request we are processing
        `resp` - The servlet response we are creating
      Throws:
        `IOException` - if an input/output error occurs during processing
        `ServletException` - if a servlet error occurs during processing

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.