public abstract class Environment
extends java.lang.Object
Managed an anonymous environment consisting of a request, a response and a context.
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.
Constructor and Description |
---|
Environment() |
Modifier and Type | Method and Description |
---|---|
void |
clearCachedLocale()
If the enviroment caches the locale, it should implement this method to clear the cached locale
value.
|
abstract void |
dispatch(java.lang.String path)
Dispatch a request to the specified resource to create output
for this response.
|
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.lang.Object |
getContext()
Return the application environment object instance for the current
appication.
|
java.lang.Object |
getContextObject()
Use this API to pass any object that can be used appropriately in the
calling context.
|
abstract java.lang.Object |
getRequest()
Return the environment-specific object instance for the current
request.
|
abstract java.lang.String |
getRequestCharacterEncoding() |
abstract java.lang.String |
getRequestContextPath()
Return the portion of the request URI that identifies the web
application context for this request.
|
abstract java.util.Locale |
getRequestLocale()
Return the preferred
Locale in which the client
will accept content. |
abstract java.util.Map |
getRequestParameterMap() |
abstract java.lang.String |
getRequestPathInfo()
Return the extra path information (if any) included in the
request URI; otherwise, return
null . |
java.lang.String |
getRequestQueryString() |
abstract java.lang.String |
getRequestServletPath()
Return the servlet path information (if any) included in the
request URI; otherwise, return
null . |
abstract java.lang.String |
getRequestURI() |
abstract java.lang.Object |
getResponse()
Return the environment-specific object instance for the current
response.
|
abstract void |
redirect(java.lang.String url)
Redirect a request to the specified URL, and cause the
responseComplete() method to be called on the
javax.faces.context.FacesContext instance for the current request. |
void |
setFacesEnvironment(boolean isFacesEnvironment)
A client may invoke this to specify whether faces is enabled
in this Environment.
|
abstract void |
setRequestCharacterEncoding(java.lang.String encoding) |
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.
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.
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.
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()
.
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
.
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
.
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)
.
url
- The input URL to be encodedjava.lang.NullPointerException
- if url
is null
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
javax.faces.context.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()
.
url
- Absolute URL to which the client should be redirectedjava.lang.IllegalArgumentException
- if the specified url is relativejava.lang.IllegalStateException
- if, in a portlet environment,
the current response object is a RenderResponse
instead of an ActionResponse
java.io.IOException
- if an input/output error occurspublic 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.
path
- Context relative path to the specified resource,
which must start with a slash ("/") characterjava.lang.IllegalArgumentException
- if no request dispatcher
can be created for the specified pathjava.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 occursjava.lang.NullPointerException
- if path
is null
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()
.
public abstract java.lang.String getRequestURI()
public final void setFacesEnvironment(boolean isFacesEnvironment)
Setting this property false for requests that are not serviced by a FacesServlet can enhance performance and squelch internal error messages that are the result of invalid access to some faces APIs.
public java.lang.String getRequestQueryString()
public abstract java.lang.String getRequestCharacterEncoding()
public abstract void setRequestCharacterEncoding(java.lang.String encoding) throws java.io.IOException
java.io.IOException
public abstract java.util.Map getRequestParameterMap()
public void clearCachedLocale()
public java.lang.Object getContextObject()