Field Detail

• BASIC_AUTH

  public static final java.lang.String BASIC_AUTH

  String identifier for BASIC authentication.

  See Also:

  Constant Field Values

• CLIENT_CERT_AUTH

  public static final java.lang.String CLIENT_CERT_AUTH

  String identifier for CLIENT_CERT authentication.

  See Also:

  Constant Field Values

• DIGEST_AUTH

  public static final java.lang.String DIGEST_AUTH

  String identifier for DIGEST authentication.

  See Also:

  Constant Field Values

• FORM_AUTH

  public static final java.lang.String FORM_AUTH

  String identifier for FORM authentication.

  See Also:

  Constant Field Values

Constructor Detail

• ExternalContext

  public ExternalContext()

Method Detail

• addResponseCookie

  public void addResponseCookie(java.lang.String name,
                                java.lang.String value,
                                java.util.Map<java.lang.String,java.lang.Object> properties)

  Adds the cookie represented by the arguments to the response.

  Jakarta Servlet: This must be accomplished by calling the jakarta.servlet.http.HttpServletResponse method addCookie(). The Cookie argument must be constructed by passing the name and value parameters. If the properties arugument is non-null and not empty, the Cookie instance must be initialized as described below.

  Cookie handling table

  Key in "values" Map (case sensitive)	Expected type of value.	Name of setter method on Cookie instance to be set with the value from the Map.
  comment	String	setComment
  domain	String	setDomain
  maxAge	Integer	setMaxAge
  secure	Boolean	setSecure
  path	String	setPath
  httpOnly	Boolean	setHttpOnly
  any other attribute (e.g. SameSite)	String	setAttribute

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  name - To be passed as the first argument to the Cookie constructor.

  value - To be passed as the second argument to the Cookie constructor.

  properties - A Map containg key/value pairs to be passed as arguments to the setter methods as described above.

  Since:

  2.0

• dispatch

  public abstract void dispatch(java.lang.String path)
                         throws java.io.IOException

  Dispatch a request to the specified resource to create output for this response.

  Jakarta Servlet: This must be accomplished by calling the jakarta.servlet.ServletContext method getRequestDispatcher(path), and calling the forward() method on the resulting object.

  If the call to getRequestDisatcher(path) returns null, send aServletResponse SC_NOT_FOUND error code.

  Parameters:

  path - Context relative path to the specified resource, which must start with a slash ("/") character

  Throws:

  FacesException - thrown if a ServletException occurs

  java.io.IOException - if an input/output error occurs

• encodeActionURL

  public abstract java.lang.String encodeActionURL(java.lang.String url)

  Return the input URL, after performing any rewriting needed to ensure that it will correctly identify an addressable action in the current application.

  Encoding the ClientWindow

  Call ClientWindow.isClientWindowRenderModeEnabled(jakarta.faces.context.FacesContext). If the result is false take no further action and return the rewritten URL. If the result is true, call getClientWindow(). If the result is non-null, call ClientWindow.getId() and append the id to the query string of the URL, making the necessary allowances for a pre-existing query string or no query-string.

  Call ClientWindow.getQueryURLParameters(jakarta.faces.context.FacesContext). If the result is non-null, for each parameter in the map, unconditionally add that parameter to the URL.

  The name of the query string parameter is given by the value of the constant ResponseStateManager.CLIENT_WINDOW_URL_PARAM.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletResponse method encodeURL(url).

  Parameters:

  url - The input URL to be encoded

  Returns:

  the encoded URL.

  Throws:

  java.lang.NullPointerException - if url is null

• encodeNamespace

  public abstract java.lang.String encodeNamespace(java.lang.String name)

  Return the specified name, after prefixing it with a namespace that ensures that it will be unique within the context of a particular page.

  Jakarta Servlet: The input value must be returned unchanged.

  Parameters:

  name - Name to be encoded

  Returns:

  the unique name prefixed with namespace.

• encodeResourceURL

  public abstract java.lang.String encodeResourceURL(java.lang.String url)

  Return the input URL, after performing any rewriting needed to ensure that it will correctly identify an addressable resource in the current application.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletResponse method encodeURL(url).

  Parameters:

  url - The input URL to be encoded

  Returns:

  the encoded resource URL.

  Throws:

  java.lang.NullPointerException - if url is null

• encodeWebsocketURL

  public abstract java.lang.String encodeWebsocketURL(java.lang.String url)

  Return the websocket URL, after performing any rewriting needed to ensure that it will correctly identify an addressable websocket in the current application.

  Jakarta Servlet: This must ensure that the input URL is prefixed with the correct websocket scheme, domain and port and then encoded by encodeResourceURL(String).

  Parameters:

  url - The input URL to be encoded.

  Returns:

  the encoded websocket URL.

  Throws:

  java.lang.NullPointerException - if url is null.

  Since:

  2.3

• getApplicationMap

  public abstract java.util.Map<java.lang.String,java.lang.Object> getApplicationMap()

  Return a mutable Map representing the application scope attributes for the current application. The returned Map must implement the entire contract for a modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the Map must cause the corresponding changes in the set of application scope attributes. Particularly the clear(), remove(), put(), putAll(), and get() operations must take the appropriate action on the underlying data structure.

  It is valid to call this method during application startup or shutdown. If called at startup or shutdown time, this method returns a Map that is backed by the same container context instance (ServletContext or PortletContext) as the one returned by calling getApplicationMap() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the set of attributes available via the jakarta.servlet.ServletContext methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

  Returns:

  the map associated with the backed ServletContext.

• getAuthType

  public abstract java.lang.String getAuthType()

  Return the name of the authentication scheme used to authenticate the current user, if any; otherwise, return null. For standard authentication schemes, the returned value will match one of the following constants: BASIC_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH, or FORM_AUTH.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getAuthType().

  Returns:

  the authentication type.

• getFlash

  public Flash getFlash()

  Return the threadsafe Flash for this application. The default implementation will throw UnsupportedOperationException. Compliant Jakarta Faces runtimes must provide an implementation of this method.

  Returns:

  the Flash for this application.

  Since:

  2.0

• getMimeType

  public java.lang.String getMimeType(java.lang.String file)

  Returns the MIME type of the specified file or null if the MIME type is not known. The MIME type is determined by the container.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method calls through to the getMimeType() method on the same container context instance (ServletContext or PortletContext) as the one used when calling getMimeType() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method getMimeType().

  Parameters:

  file - The file for which the mime type should be obtained.

  Returns:

  the MIME type of the file.

  Since:

  2.0

• getContext

  public abstract java.lang.Object getContext()

  Return the application environment object instance for the current appication.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this returns the same container context instance (ServletContext or PortletContext) as the one returned when calling getContext() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the current application's jakarta.servlet.ServletContext instance.

  Returns:

  the object of the ServletContext.

• getContextName

  public java.lang.String getContextName()

  Return the name of the container context for this application.

  Return the result of calling getServletContextName() on the ServletContext instance for this application. It is valid to call this method during application startup or shutdown.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the name the ServletContext.

• getApplicationContextPath

  public java.lang.String getApplicationContextPath()

  Return the name of the container context for this application.

  Jakarta Servlet: Return the result of calling getContextPath() on the ServletContext instance for this application.

  It is valid to call this method during application startup or shutdown.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the context path of this application.

  Since:

  2.2

• getInitParameter

  public abstract java.lang.String getInitParameter(java.lang.String name)

  Return the value of the specified application initialization parameter (if any).

  Jakarta Servlet: This must be the result of the jakarta.servlet.ServletContext method getInitParameter(name).

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method calls through to the actual container context to return the init parameter value.

  Parameters:

  name - Name of the requested initialization parameter

  Returns:

  the value of the specified parameter.

  Throws:

  java.lang.NullPointerException - if name is null

• getInitParameterMap

  public abstract java.util.Map<java.lang.String,java.lang.String> getInitParameterMap()

  Return an immutable Map whose keys are the set of application initialization parameter names configured for this application, and whose values are the corresponding parameter values. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method returns a Map that is backed by the same container context instance (ServletContext or PortletContext) as the one returned by calling getInitParameterMap() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This result must be as if it were synthesized by calling the jakarta.servlet.ServletContext method getInitParameterNames, and putting each configured parameter name/value pair into the result.

  Returns:

  the init parameter map for this application.

• getRemoteUser

  public abstract java.lang.String getRemoteUser()

  Return the login name of the user making the current request if any; otherwise, return null.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getRemoteUser().

  Returns:

  the user name of the current request.

• getRequest

  public abstract java.lang.Object getRequest()

  Return the environment-specific object instance for the current request.

  Jakarta Servlet: This must be the current request's jakarta.servlet.http.HttpServletRequest instance.

  Returns:

  the instance of the current request.

• setRequest

  public void setRequest(java.lang.Object request)

  Set the environment-specific request to be returned by subsequent calls to getRequest(). This may be used to install a wrapper for the request.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  request - the request object to be set.

  Since:

  1.2

• getRequestScheme

  public java.lang.String getRequestScheme()

  Returns the name of the scheme used to make this request, for example, http, https, or ftp.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method getScheme().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the name of the scheme.

  Since:

  2.0

• getRequestServerName

  public java.lang.String getRequestServerName()

  Returns the host name of the server to which the request was sent.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method getServerName().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the host name of the server.

  Since:

  2.0

• getRequestServerPort

  public int getRequestServerPort()

  Returns the port number to which the request was sent.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method getServerPort().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the port number to which the request was sent.

  Since:

  2.0

• setRequestCharacterEncoding

  public void setRequestCharacterEncoding(java.lang.String encoding)
                                   throws java.io.UnsupportedEncodingException

  Overrides the name of the character encoding used in the body of this request.

  Calling this method after the request has been accessed will have no no effect, unless a Reader or Stream has been obtained from the request, in which case an IllegalStateException is thrown.

  Jakarta Servlet: This must call through to the jakarta.servlet.ServletRequest method setCharacterEncoding().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  encoding - the encoding name to be set.

  Throws:

  java.io.UnsupportedEncodingException - if this is not a valid encoding

  Since:

  1.2

• getRealPath

  public java.lang.String getRealPath(java.lang.String path)

  Returns a String containing the real path for a given virtual path.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method calls through to the getRealPath() method on the same container context instance (ServletContext or PortletContext) as the one used when calling getRealPath() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method getRealPath().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  path - The context of the requested initialization parameter

  Returns:

  the real path for the specified virtual path.

  Since:

  2.0

• getRequestContextPath

  public abstract java.lang.String getRequestContextPath()

  Return the portion of the request URI that identifies the web application context for this request.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getContextPath().

  Returns:

  the context path for this request.

• getRequestCookieMap

  public abstract java.util.Map<java.lang.String,java.lang.Object> getRequestCookieMap()

  Return an immutable Map whose keys are the set of cookie names included in the current request, and whose values (of type jakarta.servlet.http.Cookie) are the first (or only) cookie for each cookie name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getCookies(), unless null was returned, in which case this must be a zero-length array.

  Returns:

  the cookie map in the current request.

• getRequestHeaderMap

  public abstract java.util.Map<java.lang.String,java.lang.String> getRequestHeaderMap()

  Return an immutable Map whose keys are the set of request header names included in the current request, and whose values (of type String) are the first (or only) value for each header name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map. In addition, key comparisons must be performed in a case insensitive manner.

  Jakarta Servlet: This must be the set of headers available via the jakarta.servlet.http.HttpServletRequest methods getHeader() and getHeaderNames().

  Returns:

  the header map in the current request.

• getRequestHeaderValuesMap

  public abstract java.util.Map<java.lang.String,java.lang.String[]> getRequestHeaderValuesMap()

  Return an immutable Map whose keys are the set of request header names included in the current request, and whose values (of type String[]) are all of the value for each header name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map. In addition, key comparisons must be performed in a case insensitive manner.

  Jakarta Servlet: This must be the set of headers available via the jakarta.servlet.http.HttpServletRequest methods getHeaders() and getHeaderNames().

  Returns:

  the header values map in the current request.

• getRequestLocale

  public abstract java.util.Locale getRequestLocale()

  Return the preferred Locale in which the client will accept content.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method getLocale().

  Returns:

  the Locale of the current request.

• getRequestLocales

  public abstract java.util.Iterator<java.util.Locale> getRequestLocales()

  Return an Iterator over the preferred Locales specified in the request, in decreasing order of preference.

  Jakarta Servlet: This must be an Iterator over the values returned by the jakarta.servlet.ServletRequest method getLocales().

  Returns:

  the Iterator of Locales of the current request.

• getRequestMap

  public abstract java.util.Map<java.lang.String,java.lang.Object> getRequestMap()

  Return a mutable Map representing the request scope attributes for the current application. The returned Map must implement the entire contract for a modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the Map must cause the corresponding changes in the set of request scope attributes. Particularly the clear(), remove(), put(), putAll(), and get() operations must take the appropriate action on the underlying data structure.

  Jakarta Servlet: This must be the set of attributes available via the jakarta.servlet.ServletRequest methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

  Returns:

  the map including the attributes of the current request.

• getRequestParameterMap

  public abstract java.util.Map<java.lang.String,java.lang.String> getRequestParameterMap()

  Return an immutable Map whose keys are the set of request parameters names included in the current request, and whose values (of type String) are the first (or only) value for each parameter name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

  Jakarta Servlet: This must be the set of parameters available via the jakarta.servlet.ServletRequest methods getParameter() and getParameterNames().

  Returns:

  the map for the current request parameters.

• getRequestParameterNames

  public abstract java.util.Iterator<java.lang.String> getRequestParameterNames()

  Return an Iterator over the names of all request parameters included in the current request.

  Jakarta Servlet: This must be an Iterator over the values returned by the jakarta.servlet.ServletRequest method getParameterNames().

  Returns:

  the Iterator for the names of the current request parameters.

• getRequestParameterValuesMap

  public abstract java.util.Map<java.lang.String,java.lang.String[]> getRequestParameterValuesMap()

  Return an immutable Map whose keys are the set of request parameters names included in the current request, and whose values (of type String[]) are all of the values for each parameter name returned by the underlying request. The returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for java.util.Map.

  Jakarta Servlet: This must be the set of parameters available via the jakarta.servlet.ServletRequest methods getParameterValues() and getParameterNames().

  Returns:

  the map for the parameter values of the current request.

• getRequestPathInfo

  public abstract java.lang.String getRequestPathInfo()

  Return the extra path information (if any) included in the request URI; otherwise, return null.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getPathInfo().

  Returns:

  the path information of the current request.

• getRequestServletPath

  public abstract java.lang.String getRequestServletPath()

  Return the Jakarta Servlet path information (if any) included in the request URI; otherwise, return null.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getServletPath().

  Returns:

  the Jakarta Servlet path information of the current request.

• getRequestCharacterEncoding

  public java.lang.String getRequestCharacterEncoding()

  Return the character encoding currently being used to interpret this request.

  Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletRequest method getCharacterEncoding().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the character encoding currently being used.

  Since:

  1.2

• getRequestContentType

  public java.lang.String getRequestContentType()

  Return the MIME Content-Type for this request. If not available, return null.

  Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletRequest method getContentType().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the Content-Type for this request.

  Since:

  1.2

• getRequestContentLength

  public int getRequestContentLength()

  Return the result of calling getContentLenth() on the ServletRequest instance for this request.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the content length of the current request.

  Since:

  2.0

• getResponseCharacterEncoding

  public java.lang.String getResponseCharacterEncoding()

  Returns the name of the character encoding (MIME charset) used for the body sent in this response.

  Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletResponse method getCharacterEncoding().

  Portlet: if this method is called during a lifecycle phase other than RENDER_RESPONSE, this must return null. If called during RENDER_RESPONSE, return the response encoding of the portlet response.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the name of the character encoding.

  Since:

  1.2

• getResponseContentType

  public java.lang.String getResponseContentType()

  Return the MIME Content-Type for this response. If not available, return null.

  Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletResponse method getContentType().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the MIME Content-Type for this response.

  Since:

  1.2

• getResource

  public abstract java.net.URL getResource(java.lang.String path)
                                    throws java.net.MalformedURLException

  Return a URL for the application resource mapped to the specified path, if it exists; otherwise, return null.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method calls through to the getResource() method on the same container context instance (ServletContext or PortletContext) as the one used when calling getResource() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method getResource(path).

  Parameters:

  path - The path to the requested resource, which must start with a slash ("/" character

  Returns:

  the URL of the resource.

  Throws:

  java.net.MalformedURLException - if the specified path is not in the correct form

  java.lang.NullPointerException - if path is null

• getResourceAsStream

  public abstract java.io.InputStream getResourceAsStream(java.lang.String path)

  Return an InputStream for an application resource mapped to the specified path, if it exists; otherwise, return null.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method calls through to the getResourceAsStream() method on the same container context instance (ServletContext or PortletContext) as the one used when calling getResourceAsStream() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method getResourceAsStream(path).

  Parameters:

  path - The path to the requested resource, which must start with a slash ("/" character

  Returns:

  the InputStream for the application resource.

  Throws:

  java.lang.NullPointerException - if path is null

• getResourcePaths

  public abstract java.util.Set<java.lang.String> getResourcePaths(java.lang.String path)

  Return the Set of resource paths for all application resources whose resource path starts with the specified argument.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this method calls through to the getResourcePaths() method on the same container context instance (ServletContext or PortletContext) as the one used when calling getResourcePaths() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method getResourcePaths(path).

  Parameters:

  path - Partial path used to match resources, which must start with a slash ("/") character

  Returns:

  the Set of resource paths for the application resources.

  Throws:

  java.lang.NullPointerException - if path is null

• getResponse

  public abstract java.lang.Object getResponse()

  Return the environment-specific object instance for the current response.

  Jakarta Servlet: This is the current request's jakarta.servlet.http.HttpServletResponse instance.

  Returns:

  the instance of the current jakarta.servlet.http.HttpServletResponse.

• setResponse

  public void setResponse(java.lang.Object response)

  Set the environment-specific response to be returned by subsequent calls to getResponse(). This may be used to install a wrapper for the response.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  response - the response instance to be set.

  Since:

  1.2

• getResponseOutputStream

  public java.io.OutputStream getResponseOutputStream()
                                               throws java.io.IOException

  Returns an OutputStream suitable for writing binary data to the user-agent.

  Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletResponse method getOutputStream().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the OutputStream for the current response.

  Throws:

  java.io.IOException - any IO related exception.

  Since:

  2.0

• getResponseOutputWriter

  public java.io.Writer getResponseOutputWriter()
                                         throws java.io.IOException

  Returns a Writer suitable for writing character data to the user-agent.

  Jakarta Servlet: This must return the value returned by the ServletResponse.getWriter().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the Writer for the current response.

  Throws:

  java.io.IOException - any IO related exception.

  Since:

  2.0

• setResponseCharacterEncoding

  public void setResponseCharacterEncoding(java.lang.String encoding)

  Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8.

  Jakarta Servlet: This must call through to the jakarta.servlet.ServletResponse method setCharacterEncoding().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  encoding - the character encoding to be sent by the current response.

  Since:

  1.2

• setResponseContentType

  public void setResponseContentType(java.lang.String contentType)

  Sets the content type of the response being sent to the client, if the response has not been committed yet.

  Jakarta Servlet: This must call setContentType() on the underlying jakarta.servlet.ServletResponse instance.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  contentType - The content type to be set as the contentType of the response.

  Since:

  2.0

• getSession

  public abstract java.lang.Object getSession(boolean create)

  If the create parameter is true, create (if necessary) and return a session instance associated with the current request. If the create parameter is false return any existing session instance associated with the current request, or return null if there is no such session.

  Jakarta Servlet: This must return the result of calling getSession(create) on the underlying jakarta.servlet.http.HttpServletRequest instance.

  Parameters:

  create - Flag indicating whether or not a new session should be created if there is no session associated with the current request

  Returns:

  the session object of the current request.

• getSessionId

  public java.lang.String getSessionId(boolean create)

  Return the id of the current session or the empty string if no session has been created and the create parameter is false.

  Jakarta Servlet: If create is true, obtain a reference to the HttpSession for the current request (creating the session if necessary) and return its id. If create is false, obtain a reference to the current session, if one exists, and return its id. If no session exists, return the empty string.

  Parameters:

  create - Flag indicating whether or not a new session should be created if there is no session associated with the current request

  Returns:

  the session id for the current request.

  Since:

  2.2

• getSessionMaxInactiveInterval

  public int getSessionMaxInactiveInterval()

  Returns the maximum time interval, in seconds, that the Jakarta Servlet container will keep this session open between client accesses. After this interval, the Jakarta Servlet container will invalidate the session. The maximum time interval can be set with the setSessionMaxInactiveInterval(int) method.

  A return value of zero or less indicates that the session will never timeout.

  Jakarta Servlet: This must return the result of calling getMaxInactiveInterval on the underlying jakarta.servlet.http.HttpSession instance.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the session maximum inactive interval.

  Since:

  2.1

• getSessionMap

  public abstract java.util.Map<java.lang.String,java.lang.Object> getSessionMap()

  Return a mutable Map representing the session scope attributes for the current application. The returned Map must implement the entire contract for a modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the Map must cause the corresponding changes in the set of session scope attributes. Particularly the clear(), remove(), put(), and get() operations must take the appropriate action on the underlying data structure. Accessing attributes via this Map must cause the creation of a session associated with the current request, if such a session does not already exist.

  Jakarta Servlet: This must be the set of attributes available via the jakarta.servlet.http.HttpSession methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

  Returns:

  the session map for the current application.

• getUserPrincipal

  public abstract java.security.Principal getUserPrincipal()

  Return the Principal object containing the name of the current authenticated user, if any; otherwise, return null.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method getUserPrincipal().

  Returns:

  the Principal object.

• getClientWindow

  public ClientWindow getClientWindow()

  Return the ClientWindow set in a preceding call to setClientWindow(jakarta.faces.lifecycle.ClientWindow), or null if no such call has been made.

  Returns:

  the instance of the ClientWindow.

  Since:

  2.2

• invalidateSession

  public void invalidateSession()

  Invalidates this session then unbinds any objects bound to it.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpSession method invalidate().

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Since:

  2.0

• isUserInRole

  public abstract boolean isUserInRole(java.lang.String role)

  Return true if the currently authenticated user is included in the specified role. Otherwise, return false.

  Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest method isUserInRole(role).

  Parameters:

  role - Logical role name to be checked

  Returns:

  the flag indicating whether the current user is in the specified role.

  Throws:

  java.lang.NullPointerException - if role is null

• log

  public abstract void log(java.lang.String message)

  Log the specified message to the application object.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this calls the log() method on the same container context instance (ServletContext or PortletContext) as the one used during a call to log() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.ServletContext method log(String).

  Parameters:

  message - Message to be logged

  Throws:

  java.lang.NullPointerException - if message is null

• log

  public abstract void log(java.lang.String message,
                           java.lang.Throwable exception)

  Log the specified message and exception to the application object.

  It is valid to call this method during application startup or shutdown. If called during application startup or shutdown, this calls the log() method on the same container context instance (ServletContext or PortletContext) as the one used when calling log() on the ExternalContext returned by the FacesContext during an actual request.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.ServletContext method log(String,Throwable).

  Parameters:

  message - Message to be logged

  exception - Exception to be logged

  Throws:

  java.lang.NullPointerException - if message or exception is null

• redirect

  public abstract void redirect(java.lang.String url)
                         throws java.io.IOException

  Redirect a request to the specified URL, and cause the responseComplete() method to be called on the FacesContext instance for the current request.

  The implementation must determine if the request is an Ajax request by obtaining a PartialViewContext instance from the FacesContext and calling PartialViewContext.isAjaxRequest().

  Jakarta Servlet: For non Ajax requests, this must be accomplished by calling the jakarta.servlet.http.HttpServletResponse method sendRedirect().

  For Ajax requests, the implementation must:

  • Get a PartialResponseWriter instance from the FacesContext.
  • Call setResponseContentType(java.lang.String) with text/xml
  • Call setResponseCharacterEncoding(java.lang.String) with UTF-8
  • Call addResponseHeader(java.lang.String, java.lang.String) with Cache-Control, no-cache
  • Call PartialResponseWriter.startDocument()
  • Call PartialResponseWriter.redirect(java.lang.String) with the url argument.
  • Call PartialResponseWriter.endDocument()

  Parameters:

  url - Absolute URL to which the client should be redirected

  Throws:

  java.lang.IllegalArgumentException - if the specified url is relative

  java.lang.IllegalStateException - if, in a portlet environment, the current response object is a RenderResponse instead of an ActionResponse

  java.lang.IllegalStateException - if, in a Jakarta Servlet environment, the current response has already been committed

  java.io.IOException - if an input/output error occurs

• setResponseHeader

  public void setResponseHeader(java.lang.String name,
                                java.lang.String value)

  Set the response header with the given name and value.

  Jakarta Servlet:This must be performed by calling the jakarta.servlet.http.HttpServletResponse setHeader method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  name - The name of the response header.

  value - The value of the response header.

  Since:

  2.0

• addResponseHeader

  public void addResponseHeader(java.lang.String name,
                                java.lang.String value)

  Add the given name and value to the response header.

  Jakarta Servlet:This must be performed by calling the jakarta.servlet.http.HttpServletResponse addHeader method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  name - The name of the response header.

  value - The value of the response header.

  Since:

  2.0

• setResponseBufferSize

  public void setResponseBufferSize(int size)

  Set the buffer size for the current response.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse setBufferSize method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  size - the new buffer size

  Since:

  2.0

• getResponseBufferSize

  public int getResponseBufferSize()

  Return the buffer size for the current response.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse getBufferSize method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the buffer size of the response.

  Since:

  2.0

• isResponseCommitted

  public boolean isResponseCommitted()

  Check if the current response has been committed.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse isCommitted method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the flag indicating whether the current response has been committed.

  Since:

  2.0

• responseReset

  public void responseReset()

  Resets the current response.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse reset method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Since:

  2.0

• responseSendError

  public void responseSendError(int statusCode,
                                java.lang.String message)
                         throws java.io.IOException

  Sends an HTTP status code with message.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse sendError method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  statusCode - an HTTP status code

  message - an option message to detail the cause of the code

  Throws:

  java.io.IOException - any IO related exceptions.

  Since:

  2.0

• setResponseStatus

  public void setResponseStatus(int statusCode)

  Sets the HTTP status code for the response.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse setStatus method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  statusCode - an HTTP status code

  Since:

  2.0

• setSessionMaxInactiveInterval

  public void setSessionMaxInactiveInterval(int interval)

  Specifies the time, in seconds, between client requests before the Jakarta Servlet container will invalidate this session.

  An interval value of zero or less indicates that the session should never timeout.

  Jakarta Servlet: This must call setMaxInactiveInterval on the underlying jakarta.servlet.http.HttpServletRequest instance.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  interval - the value to be set.

  Since:

  2.1

• setClientWindow

  public void setClientWindow(ClientWindow window)

  Associate this instance with a ClientWindow.

  Parameters:

  window - the window with which this instance is associated.

  Since:

  2.2

• responseFlushBuffer

  public void responseFlushBuffer()
                           throws java.io.IOException

  Flushes the buffered response content to the client.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse flushBuffer method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Throws:

  java.io.IOException - any IO related exception.

  Since:

  2.0

• setResponseContentLength

  public void setResponseContentLength(int length)

  Set the content length of the response.

  Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse setContentLength method.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  length - the value to be set.

  Since:

  2.0

• encodeBookmarkableURL

  public java.lang.String encodeBookmarkableURL(java.lang.String baseUrl,
                                                java.util.Map<java.lang.String,java.util.List<java.lang.String>> parameters)

  The purpose of this method is to generate a query string from the collection of Parameter objects provided by the parameters argument and append that query string to the baseUrl. This method must be able to encode the parameters to a baseUrl that may or may not have existing query parameters. The parameter values should be encoded appropriately for the environment so that the resulting URL can be used as the target of a link (e.g., in an href attribute) in a Jakarta Faces response. It's possible for an ExternalContext implementation to override this method in any way that would make the URL bookmarkable in that environment.

  See encodeActionURL(java.lang.String) for the required specification of how to encode the ClientWindow.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Parameters:

  baseUrl - The base URL onto which the query string generated by this method will be appended. The URL may contain query parameters.

  parameters - The collection of Parameter objects, representing name=value pairs that are used to produce a query string

  Returns:

  the result of encoding.

  Since:

  2.0

• encodeRedirectURL

  public java.lang.String encodeRedirectURL(java.lang.String baseUrl,
                                            java.util.Map<java.lang.String,java.util.List<java.lang.String>> parameters)

  The purpose of this method is to generate a query string from the collection of Parameter objects provided by the parameters argument and append that query string to the baseUrl. This method must be able to encode the parameters to a baseUrl that may or may not have existing query parameters. The parameter values should be encoded appropriately for the environment so that the resulting URL can be used as the target of a redirect. It's possible for an ExternalContext implementation to override this method to accomodate the definition of redirect for that environment.

  See encodeActionURL(java.lang.String) for the required specification of how to encode the ClientWindow.

  Parameters:

  baseUrl - The base URL onto which the query string generated by this method will be appended. The URL may contain query parameters.

  parameters - The collection of Parameter objects, representing name=value pairs that are used to produce a query string

  Returns:

  the result of encoding.

  Since:

  2.0

• encodePartialActionURL

  public java.lang.String encodePartialActionURL(java.lang.String url)

  Return the input URL, after performing any rewriting needed to ensure that it can be used in a partial page submission (ajax request) to correctly identify an addressable action in the current application.

  See encodeActionURL(java.lang.String) for the required specification of how to encode the ClientWindow.

  Jakarta Servlet:Returns the same encoded URL as the encodeActionURL(String url) method.

  Portlet:Returns an encoded URL that, upon HTTP POST, will invoke the RESOURCE_PHASE of the portlet lifecycle.

  Parameters:

  url - The input URL to be encoded

  Returns:

  the encoded URL.

  Throws:

  java.lang.NullPointerException - if url is null

  Since:

  2.0

• isSecure

  public boolean isSecure()

  Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.

  Jakarta Servlet: This must return the result of calling isSecure on the underlying jakarta.servlet.http.HttpServletRequest instance.

  The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

  Returns:

  the boolean indicating whether this request is secured.

  Since:

  2.1

• release

  public abstract void release()

  Release any resources associated with this ExternalContext instance. This method is called during during destruction of the associated FacesContext.

  Since:

  4.0