public final class FacesServlet extends java.lang.Object implements 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.
FacesConfig
ResourceDependencies
ResourceDependency
FacesComponent
UIComponent
Converter
FacesConverter
ListenerFor
ListenersFor
FacesBehaviorRenderer
Renderer
FacesValidator
Validator
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.
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 theFacesServlet
. 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.
Modifier and Type | Field and Description |
---|---|
static java.lang.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 java.lang.String |
DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME
The |
static java.lang.String |
LIFECYCLE_ID_ATTR
Context initialization parameter name for the lifecycle identifier of the
Lifecycle instance to be utilized. |
Constructor and Description |
---|
FacesServlet() |
Modifier and Type | Method and Description |
---|---|
void |
destroy()
Release all resources acquired at startup time.
|
ServletConfig |
getServletConfig()
Return the
ServletConfig instance for this servlet. |
java.lang.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. |
public static final java.lang.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.
public static final java.lang.String LIFECYCLE_ID_ATTR
Context initialization parameter name for the lifecycle identifier of the Lifecycle
instance to be utilized.
public static final java.lang.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.
public void init(ServletConfig servletConfig) throws ServletException
Acquire the factory instances we will require.
init
in interface Servlet
servletConfig
- a ServletConfig
object containing the servlet's configuration and initialization
parametersServletException
- 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.UnavailableException
,
Servlet.getServletConfig()
public void service(ServletRequest req, ServletResponse resp) throws java.io.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(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.
service
in interface Servlet
req
- The Jakarta Servlet request we are processingresp
- The Jakarta Servlet response we are creatingjava.io.IOException
- if an input/output error occurs during processingServletException
- if a Jakarta Servlet error occurs during processingpublic void destroy()
Release all resources acquired at startup time.
public ServletConfig getServletConfig()
Return the ServletConfig
instance for this servlet.
getServletConfig
in interface Servlet
ServletConfig
object that initializes this servletServlet.init(jakarta.servlet.ServletConfig)
public java.lang.String getServletInfo()
Return information about this Servlet.
getServletInfo
in interface Servlet
String
containing servlet information