Package jakarta.faces.webapp

Class FacesServlet

java.lang.Object
jakarta.faces.webapp.FacesServlet
All Implemented Interfaces:
jakarta.servlet.Servlet
public final class FacesServlet
extends Object
implements jakarta.servlet.Servlet

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

If the application is running in a Jakarta 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.

This Jakarta Servlet 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 jakarta.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
  • *.xhtml

Note that the automatic mapping to *.xhtml can be disabled with the context param DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME.

This class must be annotated with jakarta.servlet.annotation.MultipartConfig. This causes the Jakarta Servlet container in which the Jakarta Server Faces 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 Jakarta Servlet Specification for more information the use of <security-constraint>.

Allowable HTTP Methods

The Jakarta Server Faces 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 sections of the Jakarta Servlet Specification for more information about the use of these elements.

  • Field Summary

    Fields 
    Modifier and Type Field 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 Jakarta Server Faces configuration information.
    static String DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME
    The ServletContext init parameter consulted by the runtime to tell if the automatic mapping of the FacesServlet to the extension *.xhtml should be disabled.
    static String LIFECYCLE_ID_ATTR
    Context initialization parameter name for the lifecycle identifier of the Lifecycle instance to be utilized.

  • Constructor Summary

    Constructors 
    Constructor Description
    FacesServlet()  

  • Method Summary

    Modifier and Type Method Description
    void destroy()
    Release all resources acquired at startup time.
    jakarta.servlet.ServletConfig getServletConfig()
    Return the ServletConfig instance for this servlet.
    String getServletInfo()
    Return information about this Servlet.
    void init​(jakarta.servlet.ServletConfig servletConfig)
    Acquire the factory instances we will require.
    void service​(jakarta.servlet.ServletRequest req, jakarta.servlet.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 Details

    • 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 Jakarta Server 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

    • DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME

      public static final String DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME

      The ServletContext init parameter consulted by the runtime to tell if the automatic mapping of the FacesServlet to the extension *.xhtml should be disabled. The implementation must disable this automatic mapping if and only if the value of this parameter is equal, ignoring case, to true.

      If this parameter is not specified, this automatic mapping is enabled as specified above.

      See Also:
      Constant Field Values

  • Constructor Details

  • Method Details

    • init

      public void init​(jakarta.servlet.ServletConfig servletConfig) throws jakarta.servlet.ServletException

      Acquire the factory instances we will require.

      Specified by:
      init in interface jakarta.servlet.Servlet
      Throws:
      jakarta.servlet.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.

    • service

      public void service​(jakarta.servlet.ServletRequest req, jakarta.servlet.ServletResponse resp) throws IOException, jakarta.servlet.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(jakarta.faces.context.FacesContext). If this returns true call ResourceHandler.handleResourceRequest(jakarta.faces.context.FacesContext). If this returns false, call Lifecycle.attachWindow(jakarta.faces.context.FacesContext) followed by Lifecycle.execute(jakarta.faces.context.FacesContext) followed by Lifecycle.render(jakarta.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 Jakarta Server Faces related portion of this request.

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

    • destroy

      public void destroy()

      Release all resources acquired at startup time.

      Specified by:
      destroy in interface jakarta.servlet.Servlet

    • getServletConfig

      public jakarta.servlet.ServletConfig getServletConfig()

      Return the ServletConfig instance for this servlet.

      Specified by:
      getServletConfig in interface jakarta.servlet.Servlet

    • getServletInfo

      public String getServletInfo()

      Return information about this Servlet.

      Specified by:
      getServletInfo in interface jakarta.servlet.Servlet