javax.faces.context
Class ExternalContext

java.lang.Object
  extended by javax.faces.context.ExternalContext

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 time, any method documented as "valid to call this method during application startup" must be supported during application startup time. The result of calling a method during application startup time that does not have this designation is undefined.


Field Summary
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
ExternalContext()
           
 
Method Summary
 void addResponseCookie(String name, String value, Map<String,Object> properties)
          

Adds the cookie represented by the arguments to the response.

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

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

abstract  Object getSession(boolean create)
          If the create parameter is true, create (if necessary) and return a session instance associated with the current request.
abstract  Map<String,Object> getSessionMap()
          Return a mutable Map representing the session scope attributes for the current application.
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.

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 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 setResponseCharacterEncoding(String encoding)
          Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8.
 void setResponseContentType(String contentType)
          

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

abstract  void setResponseHeader(String name, String value)
          

Set the response header with the given name and value.

 
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

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.

Parameters:
path - Context relative path to the specified resource, which must start with a slash ("/") character
Throws:
FacesException - thrown if a ServletException occurs
IllegalArgumentException - if no request dispatcher can be created for the specified path
IOException - if an input/output error occurs
NullPointerException - if path is null

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.

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
Throws:
NullPointerException - if name is null

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. If called at startup 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().


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. If called during application startup, 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. If called during application startup, 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.

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


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. If called during application startup, 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. If called during application startup, 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 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().


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. If called during application startup, 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. If called during application startup, 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. If called during application startup, 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

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

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.HttpServletSession 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().


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. If called during application startup, 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. If called during application startup, 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.

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

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

Parameters:
name - The name of the response header.
value - The value of the response header.

addResponseHeader

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

Parameters:
name - The name of the response header.
value - The value of the response header.


Copyright © 2002-2008 Sun Microsystems, Inc. All Rights Reserved.