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 javax.servlet.ServletContainerInitializer interface that declares the following classes in its javax.servlet.annotation.HandlesTypes annotation.

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
*.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 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static enum	FacesServlet.HttpMethod

Field Summary

Modifier and Type	Field and Description
private Set<FacesServlet.HttpMethod>	allHttpMethods
private boolean	allowAllMethods
private static final String	ALLOWED_HTTP_METHODS_ATTR A white space separated list of case sensitive HTTP method names that are allowed to be processed by this servlet.
private Set<FacesServlet.HttpMethod>	allowedKnownHttpMethods
private Set<String>	allowedUnknownHttpMethods
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.
private final Set<FacesServlet.HttpMethod>	defaultAllowedHttpMethods
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.
private FacesContextFactory	facesContextFactory Factory for `FacesContext` instances.
private boolean	initFacesContextReleased From GLASSFISH-15632.
private Lifecycle	lifecycle The `Lifecycle` instance to use for request processing.
public static final String	LIFECYCLE_ID_ATTR Context initialization parameter name for the lifecycle identifier of the `Lifecycle` instance to be utilized.
private static final Logger	LOGGER The `Logger` for this class.
private ServletConfig	servletConfig The `ServletConfig` instance for this servlet.

Constructor Summary

Access	Constructor and Description
public	FacesServlet()

Method Summary

Modifier and Type	Method and Description
private FacesContext	acquireFacesContext(HttpServletRequest request, HttpServletResponse response)
private FacesContextFactory	acquireFacesContextFactory()
private Lifecycle	acquireLifecycle()
public void	destroy() Implements javax.servlet.Servlet.destroy. Release all resources acquired at startup time.
private void	executeLifecyle(FacesContext context)
public ServletConfig	getServletConfig() Implements javax.servlet.Servlet.getServletConfig. Return the `ServletConfig` instance for this servlet.
public String	getServletInfo() Implements javax.servlet.Servlet.getServletInfo. Return information about this Servlet.
public void	init(ServletConfig a `ServletConfig` object containing the servlet's configuration and initialization parameters servletConfig) Implements javax.servlet.Servlet.init. Acquire the factory instances we will require.
private void	initHttpMethodValidityVerification()
private void	initHttpMethodValidityVerificationWithCatch()
public void	initializeAllowedKnownHttpMethods(List<String> allowedKnownHttpMethodsStringList)
private boolean	isHttpMethodValid(HttpServletRequest request)
private boolean	isKnownHttpMethod(String httpMethod)
private void	logIfThreadInterruped()
private void	logUnknownHttpMethod(String httpMethod)
private boolean	notProcessWebInfIfPrefixMapped(HttpServletRequest request, HttpServletResponse response)
private void	releaseFacesInitContextIfNeeded()
private void	requestEnd() DO NOT REMOVE.
private void	requestStart(String requestUri) DO NOT REMOVE.
public void	service(ServletRequest The servlet request we are processing req, ServletResponse The servlet response we are creating resp) Implements javax.servlet.Servlet.service. Process an incoming request, and create the corresponding response according to the following specification.
private void	uninitHttpMethodValidityVerification()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

allHttpMethods	back to summary
private Set<FacesServlet.HttpMethod> allHttpMethods

allowAllMethods	back to summary
private boolean allowAllMethods

ALLOWED_HTTP_METHODS_ATTR	back to summary
private static final String ALLOWED_HTTP_METHODS_ATTR A white space separated list of case sensitive HTTP method names that are allowed to be processed by this servlet. * means allow all

allowedKnownHttpMethods	back to summary
private Set<FacesServlet.HttpMethod> allowedKnownHttpMethods

allowedUnknownHttpMethods	back to summary
private Set<String> allowedUnknownHttpMethods

CONFIG_FILES_ATTR	back to summary
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.

defaultAllowedHttpMethods	back to summary
private final Set<FacesServlet.HttpMethod> defaultAllowedHttpMethods

DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME back to summary

DISABLE_FACESSERVLET_TO_XHTML_PARAM_NAME	back to summary
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.

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.

facesContextFactory	back to summary
private FacesContextFactory facesContextFactory Factory for `FacesContext` instances.

initFacesContextReleased	back to summary
private boolean initFacesContextReleased From GLASSFISH-15632. If true, the FacesContext instance left over from startup time has been released.

lifecycle	back to summary
private Lifecycle lifecycle The `Lifecycle` instance to use for request processing.

LIFECYCLE_ID_ATTR	back to summary
public static final String LIFECYCLE_ID_ATTR Context initialization parameter name for the lifecycle identifier of the `Lifecycle` instance to be utilized.

LOGGER	back to summary
private static final Logger LOGGER The `Logger` for this class.

servletConfig	back to summary
private ServletConfig servletConfig The `ServletConfig` instance for this servlet.

Constructor Detail

FacesServlet	back to summary
public FacesServlet()

Method Detail

acquireFacesContext	back to summary
private FacesContext acquireFacesContext(HttpServletRequest request, HttpServletResponse response)

acquireFacesContextFactory	back to summary
private FacesContextFactory acquireFacesContextFactory() throws UnavailableException

acquireLifecycle	back to summary
private Lifecycle acquireLifecycle() throws ServletException

destroy	back to summary
public void destroy() Implements javax.servlet.Servlet.destroy. Release all resources acquired at startup time. Annotations @Override

destroy

back to summary

public void destroy()

Implements javax.servlet.Servlet.destroy.

Release all resources acquired at startup time.

Annotations

@Override

executeLifecyle	back to summary
private void executeLifecyle(FacesContext context) throws IOException, ServletException

getServletConfig back to summary

getServletConfig	back to summary
public ServletConfig getServletConfig() Implements javax.servlet.Servlet.getServletConfig. Return the `ServletConfig` instance for this servlet. Returns:ServletConfig Doc from javax.servlet.Servlet.getServletConfig. the `ServletConfig` object that initializes this servlet Annotations @Override

public ServletConfig getServletConfig()

Implements javax.servlet.Servlet.getServletConfig.

Return the ServletConfig instance for this servlet.

Returns:ServletConfig

Doc from javax.servlet.Servlet.getServletConfig.

the ServletConfig object that initializes this servlet

Annotations

@Override

getServletInfo back to summary

getServletInfo	back to summary
public String getServletInfo() Implements javax.servlet.Servlet.getServletInfo. Return information about this Servlet. Returns:String Doc from javax.servlet.Servlet.getServletInfo. a `String` containing servlet information Annotations @Override

public String getServletInfo()

Implements javax.servlet.Servlet.getServletInfo.

Return information about this Servlet.

Returns:String

Doc from javax.servlet.Servlet.getServletInfo.

a String containing servlet information

Annotations

@Override

init back to summary

init	back to summary
public void init(ServletConfig servletConfig) throws ServletException Implements javax.servlet.Servlet.init. Acquire the factory instances we will require. Parameters servletConfig:ServletConfig Doc from javax.servlet.Servlet.init. a `ServletConfig` object containing the servlet's configuration and initialization parameters Annotations @Override Exceptions 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.

public void init(ServletConfig servletConfig) throws ServletException

Implements javax.servlet.Servlet.init.

Acquire the factory instances we will require.

Parameters

servletConfig:ServletConfig

Doc from javax.servlet.Servlet.init.

a ServletConfig object containing the servlet's configuration and initialization parameters

Annotations

@Override

Exceptions

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.

initHttpMethodValidityVerification	back to summary
private void initHttpMethodValidityVerification()

initHttpMethodValidityVerificationWithCatch	back to summary
private void initHttpMethodValidityVerificationWithCatch() throws ServletException

initializeAllowedKnownHttpMethods	back to summary
public void initializeAllowedKnownHttpMethods(List<String> allowedKnownHttpMethodsStringList)

isHttpMethodValid	back to summary
private boolean isHttpMethodValid(HttpServletRequest request)

isKnownHttpMethod	back to summary
private boolean isKnownHttpMethod(String httpMethod)

logIfThreadInterruped	back to summary
private void logIfThreadInterruped()

logUnknownHttpMethod	back to summary
private void logUnknownHttpMethod(String httpMethod)

notProcessWebInfIfPrefixMapped	back to summary
private boolean notProcessWebInfIfPrefixMapped(HttpServletRequest request, HttpServletResponse response) throws IOException

releaseFacesInitContextIfNeeded	back to summary
private void releaseFacesInitContextIfNeeded()

requestEnd	back to summary
private void requestEnd() DO NOT REMOVE. Necessary for V3 probe monitoring.

requestStart	back to summary
private void requestStart(String requestUri) DO NOT REMOVE. Necessary for V3 probe monitoring.

service back to summary

service	back to summary
public void service(ServletRequest req, ServletResponse resp) throws IOException, ServletException Implements javax.servlet.Servlet.service. 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 `javax.faces.application.Application#getResourceHandler`. Call `javax.faces.application.ResourceHandler#isResourceRequest`. If this returns `true` call `javax.faces.application.ResourceHandler#handleResourceRequest`. If this returns `false`, call `javax.faces.lifecycle.Lifecycle#attachWindow` followed by `javax.faces.lifecycle.Lifecycle#execute` followed by `javax.faces.lifecycle.Lifecycle#render`. If a `javax.faces.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 `javax.faces.context.FacesContext#release` is called within a finally block as late as possible in the processing for the JSF related portion of this request. Parameters req:ServletRequest The servlet request we are processing resp:ServletResponse The servlet response we are creating Annotations @Override Exceptions IOException: if an input/output error occurs during processing ServletException: if a servlet error occurs during processing

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

Implements javax.servlet.Servlet.service.

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 javax.faces.application.Application#getResourceHandler. Call javax.faces.application.ResourceHandler#isResourceRequest. If this returns true call javax.faces.application.ResourceHandler#handleResourceRequest. If this returns false, call javax.faces.lifecycle.Lifecycle#attachWindow followed by javax.faces.lifecycle.Lifecycle#execute followed by javax.faces.lifecycle.Lifecycle#render. If a javax.faces.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 javax.faces.context.FacesContext#release is called within a finally block as late as possible in the processing for the JSF related portion of this request.

Parameters

req:ServletRequest: The servlet request we are processing
resp:ServletResponse: The servlet response we are creating

Annotations

@Override

Exceptions

IOException:: if an input/output error occurs during processing
ServletException:: if a servlet error occurs during processing

uninitHttpMethodValidityVerification	back to summary
private void uninitHttpMethodValidityVerification()

javax.faces.webapp back to summary

private final Enum FacesServlet.HttpMethod

Class Inheritance

extends Enum<FacesServlet.HttpMethod>

java.lang.Object
java.lang.Enum
javax.faces.webapp.FacesServlet.HttpMethod

Field Summary

Modifier and Type	Field and Description
public static final FacesServlet.HttpMethod	CONNECT
public static final FacesServlet.HttpMethod	DELETE
public static final FacesServlet.HttpMethod	GET
public static final FacesServlet.HttpMethod	HEAD
private String	name Hides java.lang.Enum.name.
public static final FacesServlet.HttpMethod	OPTIONS
public static final FacesServlet.HttpMethod	POST
public static final FacesServlet.HttpMethod	PUT
public static final FacesServlet.HttpMethod	TRACE

Constructor Summary

Access	Constructor and Description
private	HttpMethod(String name)

Method Summary

Modifier and Type	Method and Description
public String	toString() Overrides java.lang.Enum.toString. Returns the name of this enum constant, as contained in the declaration.
public static FacesServlet.HttpMethod	valueOf(String name)
public static FacesServlet.HttpMethod[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal valueOf

Field Detail

CONNECT	back to summary
public static final FacesServlet.HttpMethod CONNECT

DELETE	back to summary
public static final FacesServlet.HttpMethod DELETE

GET	back to summary
public static final FacesServlet.HttpMethod GET

HEAD	back to summary
public static final FacesServlet.HttpMethod HEAD

name	back to summary
private String name Hides java.lang.Enum.name.

OPTIONS	back to summary
public static final FacesServlet.HttpMethod OPTIONS

POST	back to summary
public static final FacesServlet.HttpMethod POST

PUT	back to summary
public static final FacesServlet.HttpMethod PUT

TRACE	back to summary
public static final FacesServlet.HttpMethod TRACE

Constructor Detail

HttpMethod	back to summary
private HttpMethod(String name)

Method Detail

toString

back to summary

public String toString()

Overrides java.lang.Enum.toString.

Doc from java.lang.Enum.toString.

Returns the name of this enum constant, as contained in the declaration. This method may be overridden, though it typically isn't necessary or desirable. An enum class should override this method when a more "programmer-friendly" string form exists.

Returns:String

the name of this enum constant

Annotations

@Override

valueOf	back to summary
public static FacesServlet.HttpMethod valueOf(String name)

values	back to summary
public static FacesServlet.HttpMethod[] values()

public final Class FacesServlet

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Enum FacesServlet.HttpMethod

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail