javax.faces.context
Class ExternalContext

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

public abstract class ExternalContext

extends java.lang.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.

In the method descriptions below, paragraphs starting with Servlet: and Portlet: denote behavior that is specific to that particular environment.

Field Summary

static java.lang.String	BASIC_AUTH String identifier for BASIC authentication.
static java.lang.String	CLIENT_CERT_AUTH String identifier for CLIENT_CERT authentication.
static java.lang.String	DIGEST_AUTH String identifier for DIGEST authentication.
static java.lang.String	FORM_AUTH String identifier for FORM authentication.

Constructor Summary

ExternalContext()

Method Summary

abstract void	dispatch(java.lang.String path) Dispatch a request to the specified resource to create output for this response.
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.
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.
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.
abstract java.util.Map	getApplicationMap() Return a mutable Map representing the application scope attributes for the current application.
abstract java.lang.String	getAuthType() Return the name of the authentication scheme used to authenticate the current user, if any; otherwise, return null.
abstract java.lang.Object	getContext() Return the application environment object instance for the current appication.
abstract java.lang.String	getInitParameter(java.lang.String name) Return the value of the specified application initialization parameter (if any).
abstract java.util.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.
abstract java.lang.String	getRemoteUser() Return the login name of the user making the current request if any; otherwise, return null.
abstract java.lang.Object	getRequest() Return the environment-specific object instance for the current request.
abstract java.lang.String	getRequestContextPath() Return the portion of the request URI that identifies the web application context for this request.
abstract java.util.Map	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 java.util.Map	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 java.util.Map	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 java.util.Locale	getRequestLocale() Return the preferred Locale in which the client will accept content.
abstract java.util.Iterator	getRequestLocales() Return an Iterator over the preferred Locales specified in the request, in decreasing order of preference.
abstract java.util.Map	getRequestMap() Return a mutable Map representing the request scope attributes for the current application.
abstract java.util.Map	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 java.util.Iterator	getRequestParameterNames() Return an Iterator over the names of all request parameters included in the current request.
abstract java.util.Map	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 java.lang.String	getRequestPathInfo() Return the extra path information (if any) included in the request URI; otherwise, return null.
abstract java.lang.String	getRequestServletPath() Return the servlet path information (if any) included in the request URI; otherwise, return null.
abstract java.net.URL	getResource(java.lang.String path) Return a URL for the application resource mapped to the specified path, if it exists; otherwise, return null.
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.
abstract java.util.Set	getResourcePaths(java.lang.String path) Return the Set of resource paths for all application resources whose resource path starts with the specified argument.
abstract java.lang.Object	getResponse() Return the environment-specific object instance for the current response.
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.
abstract java.util.Map	getSessionMap() Return a mutable Map representing the session scope attributes for the current application.
abstract java.security.Principal	getUserPrincipal() Return the Principal object containing the name of the current authenticated user, if any; otherwise, return null.
abstract boolean	isUserInRole(java.lang.String role) Return true if the currently authenticated user is included in the specified role.
abstract void	log(java.lang.String message) Log the specified message to the application object.
abstract void	log(java.lang.String message, java.lang.Throwable exception) Log the specified message and exception to the application object.
abstract void	redirect(java.lang.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.

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

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.

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

Portlet: This must be accomplished by calling the javax.portlet.PortletContext method getRequestDispatcher(), and calling the include() method on the resulting object.

Parameters:

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

Throws:

FacesException - thrown if a ServletException or PortletException occurs

java.lang.IllegalArgumentException - if no request dispatcher can be created for the specified path

java.lang.IllegalStateException - if this method is called in a portlet environment, and the current request is an ActionRequest instead of a RenderRequest

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

java.lang.NullPointerException - if path is null

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.

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

Portlet: This must be the value returned by the javax.portlet.PortletResponse method encodeURL(url).

Parameters:

url - The input URL to be encoded

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.

Servlet: The input value must be returned unchanged.

Portlet: The returned value must be the input value prefixed by the value returned by the javax.portlet.RenderResponse method getNamespace().

Parameters:

name - Name to be encoded

Throws:

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

java.lang.NullPointerException - if name is null

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.

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

Portlet: This must be the value returned by the javax.portlet.PortletResponse method encodeURL(url).

Parameters:

url - The input URL to be encoded

Throws:

java.lang.NullPointerException - if url is null

getApplicationMap

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

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

Portlet: This must be the set of attributes available via the javax.portlet.PortletContext methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

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.

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

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method getAuthType().

getContext

public abstract java.lang.Object getContext()

Return the application environment object instance for the current appication.

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

Portlet: This must be the current application's javax.portlet.PortletContext instance.

getInitParameter

public abstract java.lang.String getInitParameter(java.lang.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).

Portlet: This must be the result of the javax.portlet.PortletContext method getInitParameter(name).

Parameters:

name - Name of the requested initialization parameter

Throws:

java.lang.NullPointerException - if name is null

getInitParameterMap

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

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.

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

getRemoteUser

public abstract java.lang.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().

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method getRemoteUser().

getRequest

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

Portlet: This must be the current request's javax.portlet.PortletRequest instance, which will be either an ActionRequest or a RenderRequest depending upon when this method is called.

getRequestContextPath

public abstract java.lang.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().

Portlet: This must be the value returned by the javax.portlet.PortletRequest method getContextPath().

getRequestCookieMap

public abstract java.util.Map 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.ServletRequest method getCookies(), unless null was returned, in which case this must be a zero-length array.

Portlet: The must be a zero-length array.

getRequestHeaderMap

public abstract java.util.Map 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().

Portlet: This must be the set of properties available via the javax.portlet.PortletRequest methods getProperty() and getPropertyNames(). As such, HTTP headers will only be included if they were provided by the portlet container, and additional properties provided by the portlet container may also be included.

getRequestHeaderValuesMap

public abstract java.util.Map 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().

Portlet: This must be the set of properties available via the javax.portlet.PortletRequest methods getProperties() and getPropertyNames(). As such, HTTP headers will only be included if they were provided by the portlet container, and additional properties provided by the portlet container may also be included.

getRequestLocale

public abstract java.util.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().

Portlet: This must be the value returned by the javax.portlet.PortletRequest method getLocale().

getRequestLocales

public abstract java.util.Iterator getRequestLocales()

Return an Iterator over the preferred Locales 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().

Portlet: This must be an Iterator over the values returned by the javax.portlet.PortletRequest method getLocales().

getRequestMap

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

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

Portlet: This must be the set of attributes available via the javax.portlet.PortletRequest methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute().

getRequestParameterMap

public abstract java.util.Map 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().

Portlet: This must be the set of parameters available via the javax.portlet.PortletRequest methods getParameter() and getParameterNames().

getRequestParameterNames

public abstract java.util.Iterator 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().

Portlet: This must be an Iterator over the values returned by the javax.portlet.PortletRequest method getParameterNames().

getRequestParameterValuesMap

public abstract java.util.Map 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().

Portlet: This must be the set of parameters available via the javax.portlet.PortletRequest methods getParameterValues() and getParameterNames().

getRequestPathInfo

public abstract java.lang.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().

Portlet: This must be null.

getRequestServletPath

public abstract java.lang.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().

Portlet: This must be null.

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.

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

Portlet: This must be the value returned by the javax.portlet.PortletContext method getResource(path).

Parameters:

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

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.

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

Portlet: This must be the value returned by the javax.portlet.PortletContext method getResourceAsStream(path).

Parameters:

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

Throws:

java.lang.NullPointerException - if path is null

getResourcePaths

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

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

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

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:

java.lang.NullPointerException - if path is null

getResponse

public abstract java.lang.Object getResponse()

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

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

Portlet: This is the current request's javax.portlet.PortletResponse instance, which will be either an ActionResponse or a RenderResponse depending upon when this method is called.

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.

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

em>Portlet: This must return the result of calling getPortletSession(create) on the underlying javax.portlet.PortletRequest instance.

Parameters:

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

getSessionMap

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

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

Portlet: This must be the set of attributes available via the javax.portlet.PortletSession methods getAttribute(), getAttributeNames(), removeAttribute(), and setAttribute(). All session attribute access must occur in PORTLET_SCOPE scope within the session.

getUserPrincipal

public abstract java.security.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().

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method getUserPrincipal().

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.

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

Portlet: This must be the value returned by the javax.portlet.http.PortletRequest method isUserInRole(role).

Parameters:

role - Logical role name to be checked

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.

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

Portlet: This must be performed by calling the javax.portlet.PortletContext 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.

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

Portlet: This must be performed by calling the javax.portlet.PortletContext 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.

Servlet: This must be accomplished by calling the javax.servlet.http.HttpServletResponse method sendRedirect().

Portlet: This must be accomplished by calling the javax.portlet.ActionResponse method sendRedirect().

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 servlet environment, the current response has already been committed

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