javax.faces.context

## Class ExternalContext

- java.lang.Object
- - javax.faces.context.ExternalContext

- Direct Known Subclasses:
    ExternalContextWrapper

      public abstract class ExternalContext
      extends Object

  This class allows the Faces API to be unaware of the nature of its containing application environment. In particular, this class allows JavaServer Faces based appications to run in either a Servlet or a Portlet environment.

  The documentation for this class only specifies the behavior for the Servlet implementation of `ExternalContext`. The Portlet implementation of `ExternalContext` is specified under the revision of the Portlet Bridge Specification for JavaServer Faces JSR that corresponds to this version of the JSF specification. See the Preface of the "prose document", linked from the javadocs, for a reference.

  If a reference to an `ExternalContext` is obtained during application startup or shutdown time, any method documented as "valid to call this method during application startup or shutdown" must be supported during application startup or shutdown time. The result of calling a method during application startup or shutdown time that does not have this designation is undefined.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `BASIC_AUTH` String identifier for BASIC authentication.
    `static String` | `CLIENT_CERT_AUTH` String identifier for CLIENT_CERT authentication.
    `static String` | `DIGEST_AUTH` String identifier for DIGEST authentication.
    `static String` | `FORM_AUTH` String identifier for FORM authentication.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExternalContext()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addResponseCookie(String name, String value, Map<String,Object> properties)` Adds the cookie represented by the arguments to the response.
    `void` | `addResponseHeader(String name, String value)` Add the given name and value to the response header.
    `abstract void` | `dispatch(String path)` Dispatch a request to the specified resource to create output for this response.
    `abstract String` | `encodeActionURL(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.
    `String` | `encodeBookmarkableURL(String baseUrl, Map<String,List<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.
    `abstract String` | `encodeNamespace(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.
    `String` | `encodePartialActionURL(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.
    `String` | `encodeRedirectURL(String baseUrl, Map<String,List<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.
    `abstract String` | `encodeResourceURL(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.
    `String` | `getApplicationContextPath()` Return the name of the container context for this application.
    `abstract Map<String,Object>` | `getApplicationMap()` Return a mutable `Map` representing the application scope attributes for the current application.
    `abstract String` | `getAuthType()` Return the name of the authentication scheme used to authenticate the current user, if any; otherwise, return `null`.
    `ClientWindow` | `getClientWindow()` Return the `ClientWindow` set in a preceding call to `setClientWindow(javax.faces.lifecycle.ClientWindow)`, or `null` if no such call has been made.
    `abstract Object` | `getContext()` Return the application environment object instance for the current appication.
    `String` | `getContextName()` Return the name of the container context for this application.
    `Flash` | `getFlash()` Return the threadsafe `Flash` for this application.
    `abstract String` | `getInitParameter(String name)` Return the value of the specified application initialization parameter (if any).
    `abstract Map` | `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.
    `String` | `getMimeType(String file)` Returns the MIME type of the specified file or `null` if the MIME type is not known.
    `String` | `getRealPath(String path)` Returns a String containing the real path for a given virtual path.
    `abstract String` | `getRemoteUser()` Return the login name of the user making the current request if any; otherwise, return `null`.
    `abstract Object` | `getRequest()` Return the environment-specific object instance for the current request.
    `String` | `getRequestCharacterEncoding()` Return the character encoding currently being used to interpret this request.
    `int` | `getRequestContentLength()` Return the result of calling `getContentLenth()` on the `ServletRequest` instance for this request.
    `String` | `getRequestContentType()` Return the MIME Content-Type for this request.
    `abstract String` | `getRequestContextPath()` Return the portion of the request URI that identifies the web application context for this request.
    `abstract Map<String,Object>` | `getRequestCookieMap()` Return an immutable `Map` whose keys are the set of cookie names included in the current request, and whose values (of type `javax.servlet.http.Cookie`) are the first (or only) cookie for each cookie name returned by the underlying request.
    `abstract Map<String,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.
    `abstract Map<String,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.
    `abstract Locale` | `getRequestLocale()` Return the preferred `Locale` in which the client will accept content.
    `abstract Iterator<Locale>` | `getRequestLocales()` Return an `Iterator` over the preferred `Locale`s specified in the request, in decreasing order of preference.
    `abstract Map<String,Object>` | `getRequestMap()` Return a mutable `Map` representing the request scope attributes for the current application.
    `abstract Map<String,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.
    `abstract Iterator<String>` | `getRequestParameterNames()` Return an `Iterator` over the names of all request parameters included in the current request.
    `abstract Map<String,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.
    `abstract String` | `getRequestPathInfo()` Return the extra path information (if any) included in the request URI; otherwise, return `null`.
    `String` | `getRequestScheme()` Returns the name of the scheme used to make this request, for example, http, https, or ftp.
    `String` | `getRequestServerName()` Returns the host name of the server to which the request was sent.
    `int` | `getRequestServerPort()` Returns the port number to which the request was sent.
    `abstract String` | `getRequestServletPath()` Return the servlet path information (if any) included in the request URI; otherwise, return `null`.
    `abstract URL` | `getResource(String path)` Return a `URL` for the application resource mapped to the specified path, if it exists; otherwise, return `null`.
    `abstract InputStream` | `getResourceAsStream(String path)` Return an `InputStream` for an application resource mapped to the specified path, if it exists; otherwise, return `null`.
    `abstract Set<String>` | `getResourcePaths(String path)` Return the `Set` of resource paths for all application resources whose resource path starts with the specified argument.
    `abstract Object` | `getResponse()` Return the environment-specific object instance for the current response.
    `int` | `getResponseBufferSize()` Return the buffer size for the current response.
    `String` | `getResponseCharacterEncoding()` Returns the name of the character encoding (MIME charset) used for the body sent in this response.
    `String` | `getResponseContentType()` Return the MIME Content-Type for this response.
    `OutputStream` | `getResponseOutputStream()` Returns an `OutputStream` suitable for writing binary data to the user-agent.
    `Writer` | `getResponseOutputWriter()` Returns a `Writer` suitable for writing character data to the user-agent.
    `abstract Object` | `getSession(boolean create)` If the `create` parameter is `true`, create (if necessary) and return a session instance associated with the current request.
    `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`.
    `abstract Map<String,Object>` | `getSessionMap()` Return a mutable `Map` representing the session scope attributes for the current application.
    `int` | `getSessionMaxInactiveInterval()` Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses.
    `abstract Principal` | `getUserPrincipal()` Return the `Principal` object containing the name of the current authenticated user, if any; otherwise, return `null`.
    `void` | `invalidateSession()` Invalidates this session then unbinds any objects bound to it.
    `boolean` | `isResponseCommitted()` Check if the current response has been committed.
    `boolean` | `isSecure()` Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
    `abstract boolean` | `isUserInRole(String role)` Return `true` if the currently authenticated user is included in the specified role.
    `abstract void` | `log(String message)` Log the specified message to the application object.
    `abstract void` | `log(String message, Throwable exception)` Log the specified message and exception to the application object.
    `abstract void` | `redirect(String url)` Redirect a request to the specified URL, and cause the `responseComplete()` method to be called on the `FacesContext` instance for the current request.
    `void` | `responseFlushBuffer()` Flushes the buffered response content to the client.
    `void` | `responseReset()` Resets the current response.
    `void` | `responseSendError(int statusCode, String message)` Sends an HTTP status code with message.
    `void` | `setClientWindow(ClientWindow window)` Associate this instance with a `ClientWindow`.
    `void` | `setRequest(Object request)` Set the environment-specific request to be returned by subsequent calls to `getRequest()`.
    `void` | `setRequestCharacterEncoding(String encoding)` Overrides the name of the character encoding used in the body of this request.
    `void` | `setResponse(Object response)` Set the environment-specific response to be returned by subsequent calls to `getResponse()`.
    `void` | `setResponseBufferSize(int size)` Set the buffer size for the current response.
    `void` | `setResponseCharacterEncoding(String encoding)` Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8.
    `void` | `setResponseContentLength(int length)` Set the content length of the response.
    `void` | `setResponseContentType(String contentType)` Sets the content type of the response being sent to the client, if the response has not been committed yet.
    `void` | `setResponseHeader(String name, String value)` Set the response header with the given name and value.
    `void` | `setResponseStatus(int statusCode)` Sets the HTTP status code for the response.
    `void` | `setSessionMaxInactiveInterval(int interval)` Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.

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

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

- - ### Field Detail

    - #### BASIC_AUTH

          public static final String BASIC_AUTH

      String identifier for BASIC authentication.

      See Also:
        Constant Field Values

    - #### CLIENT_CERT_AUTH

          public static final String CLIENT_CERT_AUTH

      String identifier for CLIENT_CERT authentication.

      See Also:
        Constant Field Values

    - #### DIGEST_AUTH

          public static final String DIGEST_AUTH

      String identifier for DIGEST authentication.

      See Also:
        Constant Field Values

    - #### FORM_AUTH

          public static final String FORM_AUTH

      String identifier for FORM authentication.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ExternalContext

          public ExternalContext()

  - ### Method Detail

    - #### addResponseCookie

          public void addResponseCookie(String name,
                               String value,
                               Map<String,Object> properties)

      Adds the cookie represented by the arguments to the response.

      Servlet: This must be accomplished by calling the `javax.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.

      Key in "values" `Map` | 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

      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.
      Throws:
        `IllegalArgumentException` - if the `properties Map` is not-`null` and not empty and contains any keys that are not one of the keys listed above.
      Since:
        2.0

    - #### dispatch

          public abstract void dispatch(String path)
                                 throws IOException

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

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

      If the call to `getRequestDisatcher(path)` returns `null`, send a`ServletResponse 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
        `IOException` - if an input/output error occurs

    - #### encodeActionURL

          public abstract String encodeActionURL(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(javax.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(javax.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`.

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

      Parameters:
        `url` - The input URL to be encoded
      Throws:
        `NullPointerException` - if `url` is `null`

    - #### encodeNamespace

          public abstract String encodeNamespace(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.

      Servlet: The input value must be returned unchanged.

      Parameters:
        `name` - Name to be encoded

    - #### encodeResourceURL

          public abstract String encodeResourceURL(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.

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

      Parameters:
        `url` - The input URL to be encoded
      Throws:
        `NullPointerException` - if `url` is `null`

    - #### getApplicationMap

          public abstract Map<String,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.

      For any of the `Map` methods that cause an element to be removed from the underlying data structure, the following action regarding managed-beans must be taken. If the element to be removed is a managed-bean, and it has one or more public no-argument void return methods annotated with `javax.annotation.PreDestroy`, each such method must be called before the element is removed from the underlying data structure. Elements that are not managed-beans, but do happen to have methods with that annotation must not have those methods called on removal. Any exception thrown by the `PreDestroy` annotated methods must by caught and not rethrown. The exception may be logged.

      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.

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

    - #### getAuthType

          public abstract 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`.

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

    - #### getFlash

          public Flash getFlash()

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

      Since:
        2.0

    - #### getMimeType

          public String getMimeType(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.

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

      Parameters:
        `file` - The file for which the mime type should be obtained.
      Since:
        2.0

    - #### getContext

          public abstract 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.

      Servlet: This must be the current application's `javax.servlet.ServletContext` instance.

    - #### getContextName

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

    - #### getApplicationContextPath

          public String getApplicationContextPath()

      Return the name of the container context for this application.

      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.

      Since:
        2.2

    - #### getInitParameter

          public abstract String getInitParameter(String name)

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

      Servlet: This must be the result of the `javax.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
      Throws:
        `NullPointerException` - if `name` is `null`

    - #### getInitParameterMap

          public abstract Map 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.

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

    - #### getRemoteUser

          public abstract String getRemoteUser()

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

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

    - #### getRequest

          public abstract Object getRequest()

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

      Servlet: This must be the current request's `javax.servlet.http.HttpServletRequest` instance.

    - #### setRequest

          public void setRequest(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.

      Since:
        1.2

    - #### getRequestScheme

          public String getRequestScheme()

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

      Servlet: This must be the value returned by the `javax.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.

      Since:
        2.0

    - #### getRequestServerName

          public String getRequestServerName()

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

      Servlet: This must be the value returned by the `javax.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.

      Since:
        2.0

    - #### getRequestServerPort

          public int getRequestServerPort()

      Returns the port number to which the request was sent.

      Servlet: This must be the value returned by the `javax.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.

      Since:
        2.0

    - #### setRequestCharacterEncoding

          public void setRequestCharacterEncoding(String encoding)
                                           throws 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.

      Servlet: This must call through to the `javax.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.

      Throws:
        `UnsupportedEncodingException` - if this is not a valid encoding
      Since:
        1.2

    - #### getRealPath

          public String getRealPath(String path)

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

      Servlet: This must be the value returned by the `javax.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
      Since:
        2.0

    - #### getRequestContextPath

          public abstract String getRequestContextPath()

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

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

    - #### getRequestCookieMap

          public abstract Map<String,Object> getRequestCookieMap()

      Return an immutable `Map` whose keys are the set of cookie names included in the current request, and whose values (of type `javax.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`.

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

    - #### getRequestHeaderMap

          public abstract Map<String,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.

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

    - #### getRequestHeaderValuesMap

          public abstract Map<String,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.

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

    - #### getRequestLocale

          public abstract Locale getRequestLocale()

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

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

    - #### getRequestLocales

          public abstract Iterator<Locale> getRequestLocales()

      Return an `Iterator` over the preferred `Locale`s specified in the request, in decreasing order of preference.

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

    - #### getRequestMap

          public abstract Map<String,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.

      For any of the `Map` methods that cause an element to be removed from the underlying data structure, the following action regarding managed-beans must be taken. If the element to be removed is a managed-bean, and it has one or more public no-argument void return methods annotated with `javax.annotation.PreDestroy`, each such method must be called before the element is removed from the underlying data structure. Elements that are not managed-beans, but do happen to have methods with that annotation must not have those methods called on removal. Any exception thrown by the `PreDestroy` annotated methods must by caught and not rethrown. The exception may be logged.

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

    - #### getRequestParameterMap

          public abstract Map<String,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`.

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

    - #### getRequestParameterNames

          public abstract Iterator<String> getRequestParameterNames()

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

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

    - #### getRequestParameterValuesMap

          public abstract Map<String,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`.

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

    - #### getRequestPathInfo

          public abstract String getRequestPathInfo()

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

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

    - #### getRequestServletPath

          public abstract String getRequestServletPath()

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

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

    - #### getRequestCharacterEncoding

          public String getRequestCharacterEncoding()

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

      Servlet: This must return the value returned by the `javax.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.

      Since:
        1.2

    - #### getRequestContentType

          public String getRequestContentType()

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

      Servlet: This must return the value returned by the `javax.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.

      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.

      Since:
        2.0

    - #### getResponseCharacterEncoding

          public String getResponseCharacterEncoding()

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

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

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

      Since:
        1.2

    - #### getResponseContentType

          public String getResponseContentType()

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

      Servlet: This must return the value returned by the `javax.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.

      Since:
        1.2

    - #### getResource

          public abstract URL getResource(String path)
                                   throws 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.

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

      Parameters:
        `path` - The path to the requested resource, which must start with a slash ("/" character
      Throws:
        `MalformedURLException` - if the specified path is not in the correct form
        `NullPointerException` - if `path` is `null`

    - #### getResourceAsStream

          public abstract InputStream getResourceAsStream(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.

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

      Parameters:
        `path` - The path to the requested resource, which must start with a slash ("/" character
      Throws:
        `NullPointerException` - if `path` is `null`

    - #### getResourcePaths

          public abstract Set<String> getResourcePaths(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.

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

      Parameters:
        `path` - Partial path used to match resources, which must start with a slash ("/") character
      Throws:
        `NullPointerException` - if `path` is `null`

    - #### getResponse

          public abstract Object getResponse()

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

      Servlet: This is the current request's `javax.servlet.http.HttpServletResponse` instance.

    - #### setResponse

          public void setResponse(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.

      Since:
        1.2

    - #### getResponseOutputStream

          public OutputStream getResponseOutputStream()
                                               throws IOException

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

      Servlet: This must return the value returned by the `javax.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.

      Throws:
        `IOException`
      Since:
        2.0

    - #### getResponseOutputWriter

          public Writer getResponseOutputWriter()
                                         throws IOException

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

      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.

      Throws:
        `IOException`
      Since:
        2.0

    - #### setResponseCharacterEncoding

          public void setResponseCharacterEncoding(String encoding)

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

      Servlet: This must call through to the `javax.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.

      Since:
        1.2

    - #### setResponseContentType

          public void setResponseContentType(String contentType)

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

      Servlet: This must call `setContentType()` on the underlying `javax.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 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.

      Servlet: This must return the result of calling `getSession(create)` on the underlying `javax.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

    - #### getSessionId

          public 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`.

      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
      Since:
        2.2

    - #### getSessionMaxInactiveInterval

          public int getSessionMaxInactiveInterval()

      Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses. After this interval, the 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.

      Servlet: This must return the result of calling `getMaxInactiveInterval` on the underlying `javax.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.

      Since:
        2.1

    - #### getSessionMap

          public abstract Map<String,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.

      For any of the `Map` methods that cause an element to be removed from the underlying data structure, the following action regarding managed-beans must be taken. If the element to be removed is a managed-bean, and it has one or more public no-argument void return methods annotated with `javax.annotation.PreDestroy`, each such method must be called before the element is removed from the underlying data structure. Elements that are not managed-beans, but do happen to have methods with that annotation must not have those methods called on removal. Any exception thrown by the `PreDestroy` annotated methods must by caught and not rethrown. The exception may be logged.

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

    - #### getUserPrincipal

          public abstract Principal getUserPrincipal()

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

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

    - #### getClientWindow

          public ClientWindow getClientWindow()

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

      Since:
        2.2

    - #### invalidateSession

          public void invalidateSession()

      Invalidates this session then unbinds any objects bound to it.

      Servlet: This must be the value returned by the `javax.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(String role)

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

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

      Parameters:
        `role` - Logical role name to be checked
      Throws:
        `NullPointerException` - if `role` is `null`

    - #### log

          public abstract void log(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.

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

      Parameters:
        `message` - Message to be logged
      Throws:
        `NullPointerException` - if `message` is `null`

    - #### log

          public abstract void log(String message,
                 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.

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

      Parameters:
        `message` - Message to be logged
        `exception` - Exception to be logged
      Throws:
        `NullPointerException` - if `message` or `exception` is `null`

    - #### redirect

          public abstract void redirect(String url)
                                 throws 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()`.

      Servlet: For non `Ajax` requests, this must be accomplished by calling the `javax.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:
        `IllegalArgumentException` - if the specified url is relative
        `IllegalStateException` - if, in a portlet environment, the current response object is a `RenderResponse` instead of an `ActionResponse`
        `IllegalStateException` - if, in a servlet environment, the current response has already been committed
        `IOException` - if an input/output error occurs

    - #### setResponseHeader

          public void setResponseHeader(String name,
                               String value)

      Set the response header with the given name and value.

      Servlet:This must be performed by calling the `javax.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(String name,
                               String value)

      Add the given name and value to the response header.

      Servlet:This must be performed by calling the `javax.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.

      Servlet: This must be performed by calling the `javax.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.

      Servlet: This must be performed by calling the `javax.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.

      Since:
        2.0

    - #### isResponseCommitted

          public boolean isResponseCommitted()

      Check if the current response has been committed.

      Servlet: This must be performed by calling the `javax.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.

      Since:
        2.0

    - #### responseReset

          public void responseReset()

      Resets the current response.

      Servlet: This must be performed by calling the `javax.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,
                               String message)
                                 throws IOException

      Sends an HTTP status code with message.

      Servlet: This must be performed by calling the `javax.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:
        `IOException`
      Since:
        2.0

    - #### setResponseStatus

          public void setResponseStatus(int statusCode)

      Sets the HTTP status code for the response.

      Servlet: This must be performed by calling the `javax.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 servlet container will invalidate this session.

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

      Servlet: This must call `setMaxInactiveInterval` on the underlying `javax.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.

      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 IOException

      Flushes the buffered response content to the client.

      Servlet: This must be performed by calling the `javax.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:
        `IOException`
      Since:
        2.0

    - #### setResponseContentLength

          public void setResponseContentLength(int length)

      Set the content length of the response.

      Servlet: This must be performed by calling the `javax.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.

      Since:
        2.0

    - #### encodeBookmarkableURL

          public String encodeBookmarkableURL(String baseUrl,
                                     Map<String,List<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 JSF 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
      Since:
        2.0

    - #### encodeRedirectURL

          public String encodeRedirectURL(String baseUrl,
                                 Map<String,List<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
      Since:
        2.0

    - #### encodePartialActionURL

          public String encodePartialActionURL(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`.

      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
      Throws:
        `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.

      Servlet: This must return the result of calling `isSecure` on the underlying `javax.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.

      Since:
        2.1

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