javax.faces.context.ExternalContext Maven / Gradle / Ivy
Show all versions of jsf-api Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
/*
* Licensed Material - Property of IBM
* (C) Copyright IBM Corp. 2002, 2003 - All Rights Reserved.
* US Government Users Restricted Rights - Use, duplication or disclosure
* restricted by GSA ADP Schedule Contract with IBM Corp.
*/
package javax.faces.context;
import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.io.OutputStream;
import java.io.Writer;
import java.net.MalformedURLException;
import java.net.URL;
import java.security.Principal;
import java.util.*;
import javax.faces.lifecycle.ClientWindow;
/**
* 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.
*/
public abstract class ExternalContext {
@SuppressWarnings({"UnusedDeclaration"})
private ExternalContext defaultExternalContext;
// ------------------------------------------------------ Manifest Constants
/**
* String identifier for BASIC authentication.
*/
public static final String BASIC_AUTH = "BASIC";
/**
* String identifier for CLIENT_CERT authentication.
*/
public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
/**
* String identifier for DIGEST authentication.
*/
public static final String DIGEST_AUTH = "DIGEST";
/**
* String identifier for FORM authentication.
*/
public static final String FORM_AUTH = "FORM";
// ---------------------------------------------------------- Public Methods
/**
* 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.
*
*
*
* @param name To be passed as the first argument to the
* Cookie constructor.
*
* @param value To be passed as the second argument to the
* Cookie constructor.
*
* @param 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
*/
public void addResponseCookie(String name,
String value,
Map properties) {
if (defaultExternalContext != null) {
defaultExternalContext.addResponseCookie(name, value, properties);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @param path Context relative path to the specified resource,
* which must start with a slash ("/") character
*
* @throws javax.faces.FacesException thrown if a ServletException occurs
* @throws IllegalArgumentException if no request dispatcher
* can be created for the specified path
* @throws IOException if an input/output error occurs
* @throws NullPointerException if path
* is null
*/
public abstract void dispatch(String path)
throws IOException;
/**
* 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 {@link javax.faces.lifecycle.ClientWindow}
*
*
*
* Call {@link javax.faces.lifecycle.ClientWindow#isClientWindowUrlQueryParameterEnabled(javax.faces.context.FacesContext) }.
* If the result is false take no further action and return
* the rewritten URL. If the result is true, call {@link #getClientWindow()}.
* If the result is non-null, call {@link javax.faces.lifecycle.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. The name
* of the query string parameter is given by the value of the constant
* {@link javax.faces.render.ResponseStateManager#CLIENT_WINDOW_URL_PARAM}.
*
*
*
* Servlet: This must be the value returned by the
* javax.servlet.http.HttpServletResponse method
* encodeURL(url).
*
* @param url The input URL to be encoded
*
* @throws NullPointerException if url
* is null
*/
public abstract String encodeActionURL(String url);
/**
* 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.
*
* @param name Name to be encoded
*
* @throws NullPointerException if name
* is null
*/
public abstract String encodeNamespace(String name);
/**
* 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).
*
* @param url The input URL to be encoded
*
* @throws NullPointerException if url
* is null
*/
// PENDING(craigmcc) - Currently identical to encodeActionURL()
public abstract String encodeResourceURL(String url);
/**
* 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().
*
*/
public abstract Map getApplicationMap();
/**
* 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().
*
*/
public abstract String getAuthType();
/**
* Return the threadsafe {@link Flash}
* for this application. The default implementation will throw
* UnsupportedOperationException. Compliant JSF
* runtimes must provide an implementation of this method.
*
* @since 2.0
*/
public Flash getFlash() {
if (defaultExternalContext != null) {
return defaultExternalContext.getFlash();
}
throw new UnsupportedOperationException();
}
/**
* 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().
*
*
*
* @param file The file for which the mime type should be obtained.
*
* @since 2.0
*/
public String getMimeType(String file) {
if (defaultExternalContext != null) {
return defaultExternalContext.getMimeType(file);
}
throw new UnsupportedOperationException();
}
/**
* 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.
*
*/
public abstract Object getContext();
/**
*
* 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.
*
*
*/
public String getContextName() {
if (defaultExternalContext != null) {
return defaultExternalContext.getContextName();
}
throw new UnsupportedOperationException();
}
/**
*
* 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
*/
public String getApplicationContextPath() {
if (defaultExternalContext != null) {
return defaultExternalContext.getApplicationContextPath();
}
throw new UnsupportedOperationException();
}
/**
* 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.
* @param name Name of the requested initialization parameter
*
* @throws NullPointerException if name
* is null
*/
public abstract String getInitParameter(String name);
/**
* 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.
*
*/
public abstract Map getInitParameterMap();
/**
* 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().
*
*/
public abstract String getRemoteUser();
/**
* Return the environment-specific object instance for the current
* request.
*
* Servlet: This must be the current request's
* javax.servlet.http.HttpServletRequest instance.
*
*/
public abstract Object getRequest();
/**
* Set the environment-specific request to be returned by
* subsequent calls to {@link #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
*/
public void setRequest(Object request) {
if (defaultExternalContext != null) {
defaultExternalContext.setRequest(request);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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
*/
public String getRequestScheme() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestScheme();
}
throw new UnsupportedOperationException();
}
/**
* 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
*/
public String getRequestServerName() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestServerName();
}
throw new UnsupportedOperationException();
}
/**
* 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
*/
public int getRequestServerPort() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestServerPort();
}
throw new UnsupportedOperationException();
}
/**
*
* 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 java.io.UnsupportedEncodingException if this is not a valid
* encoding
*
* @since 1.2
*
*/
public void setRequestCharacterEncoding(String encoding) throws UnsupportedEncodingException {
if (defaultExternalContext != null) {
defaultExternalContext.setRequestCharacterEncoding(encoding);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
*
*
* @param path The context of the requested initialization parameter
*
* @since 2.0
*/
public String getRealPath(String path) {
if (defaultExternalContext != null) {
return defaultExternalContext.getRealPath(path);
}
throw new UnsupportedOperationException();
}
/**
* 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().
*
*/
public abstract String getRequestContextPath();
/**
* 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.
*
*/
public abstract Map getRequestCookieMap();
/**
* 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().
*
*/
public abstract 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 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().
*
*/
public abstract Map getRequestHeaderValuesMap();
/**
* 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().
*
*/
public abstract Locale getRequestLocale();
/**
* 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().
*
*/
public abstract Iterator getRequestLocales();
/**
* 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().
*
*/
public abstract Map getRequestMap();
/**
* 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().
*
*/
public abstract Map getRequestParameterMap();
/**
* 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().
*
*/
public abstract Iterator getRequestParameterNames();
/**
* 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().
*
*/
public abstract Map getRequestParameterValuesMap();
/**
* 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().
*
*/
public abstract String getRequestPathInfo();
/**
* 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().
*
*/
public abstract String getRequestServletPath();
/**
*
* 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
*
*/
public String getRequestCharacterEncoding() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestCharacterEncoding();
}
throw new UnsupportedOperationException();
}
/**
*
* 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
*/
public String getRequestContentType() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestContentType();
}
throw new UnsupportedOperationException();
}
/**
* 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
*/
public int getRequestContentLength() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestContentLength();
}
throw new UnsupportedOperationException();
}
/**
*
* 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
*/
public String getResponseCharacterEncoding() {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseCharacterEncoding();
}
throw new UnsupportedOperationException();
}
/**
*
* 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
*/
public String getResponseContentType() {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseContentType();
}
throw new UnsupportedOperationException();
}
/**
* 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).
*
* @param 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
* @throws NullPointerException if path
* is null
*/
public abstract URL getResource(String path) throws MalformedURLException;
/**
* 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).
*
* @param path The path to the requested resource, which must
* start with a slash ("/" character
*
* @throws NullPointerException if path
* is null
*/
public abstract InputStream getResourceAsStream(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).
*
* @param path Partial path used to match resources, which must
* start with a slash ("/") character
*
* @throws NullPointerException if path
* is null
*/
public abstract Set getResourcePaths(String path);
/**
* Return the environment-specific object instance for the current
* response.
*
* Servlet: This is the current request's
* javax.servlet.http.HttpServletResponse instance.
*
*/
public abstract Object getResponse();
/**
* Set the environment-specific response to be returned by
* subsequent calls to {@link #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
*/
public void setResponse(Object response) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponse(response);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
*
*
* @since 2.0
*/
public OutputStream getResponseOutputStream() throws IOException {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseOutputStream();
}
throw new UnsupportedOperationException();
}
/**
* Returns a Writer
* suitable for writing character data to the user-agent.
*
*
*
* Servlet: This must return the value returned by the
* {@link javax.servlet.ServletResponse#getWriter}.
*
* The default implementation throws
* UnsupportedOperationException and is provided for
* the sole purpose of not breaking existing applications that
* extend this class.
*
*
*
* @since 2.0
*/
public Writer getResponseOutputWriter() throws IOException {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseOutputWriter();
}
throw new UnsupportedOperationException();
}
/**
*
* 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
*
*/
public void setResponseCharacterEncoding(String encoding) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseCharacterEncoding(encoding);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
*
*
* @param contentType The content type to be set as the contentType
* of the response.
*
* @since 2.0
*/
public void setResponseContentType(String contentType) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseContentType(contentType);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @param create Flag indicating whether or not a new session should be
* created if there is no session associated with the current request
*/
public abstract Object getSession(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.
*
*
*
* @since 2.2
*
* @param create Flag indicating whether or not a new session should be
* created if there is no session associated with the current request
*/
public String getSessionId(boolean create) {
String result = "";
if (defaultExternalContext != null) {
result = defaultExternalContext.getSessionId(create);
} else {
throw new UnsupportedOperationException();
}
return result;
}
/**
* 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
* {@link #setSessionMaxInactiveInterval} 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
*/
public int getSessionMaxInactiveInterval() {
int result = 0;
if (defaultExternalContext != null) {
result = defaultExternalContext.getSessionMaxInactiveInterval();
} else {
throw new UnsupportedOperationException();
}
return result;
}
/**
* 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().
*
*/
public abstract Map getSessionMap();
/**
* 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().
*
*/
public abstract Principal getUserPrincipal();
/**
* Return the {@link ClientWindow} set in a preceding
* call to {@link #setClientWindow}, or null if no such call has
* been made.
*
* @since 2.2
*
*/
public ClientWindow getClientWindow() {
if (defaultExternalContext != null) {
return defaultExternalContext.getClientWindow();
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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
*/
public void invalidateSession() {
if (defaultExternalContext != null) {
defaultExternalContext.invalidateSession();
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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).
*
* @param role Logical role name to be checked
*
* @throws NullPointerException if role
* is null
*/
public abstract boolean isUserInRole(String role);
/**
* 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).
*
* @param message Message to be logged
*
* @throws NullPointerException if message
* is null
*/
public abstract void log(String message);
/**
* 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).
*
* @param message Message to be logged
* @param exception Exception to be logged
*
* @throws NullPointerException if message
* or exception is null
*/
public abstract void log(String message, Throwable exception);
/**
* Redirect a request
* to the specified URL, and cause the
* responseComplete() method to be called on the
* {@link FacesContext} instance for the current request.
*
* The implementation must determine if
* the request is an Ajax request by obtaining a
* {@link PartialViewContext} instance from the {@link FacesContext} and
* calling {@link 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 {@link PartialResponseWriter} instance from the
* {@link FacesContext}.
* - Call {@link #setResponseContentType} with
text/xml
* - Call {@link #setResponseCharacterEncoding} with
UTF-8
* - Call {@link #addResponseHeader} with
Cache-Control,
* no-cache
* - Call {@link PartialResponseWriter#startDocument}
* - Call {@link PartialResponseWriter#redirect} with the
url
* argument.
* - Call {@link PartialResponseWriter#endDocument}
*
*
*
*
* @param url Absolute URL to which the client should be redirected
*
* @throws IllegalArgumentException if the specified url is relative
* @throws IllegalStateException if, in a portlet environment,
* the current response object is a RenderResponse
* instead of an ActionResponse
* @throws IllegalStateException if, in a servlet environment,
* the current response has already been committed
* @throws IOException if an input/output error occurs
*/
public abstract void redirect(String url)
throws IOException;
/**
* 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.
*
* @param name The name of the response header.
* @param value The value of the response header.
*
* @since 2.0
*/
public void setResponseHeader(String name, String value) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseHeader(name, value);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @param name The name of the response header.
* @param value The value of the response header.
*
* @since 2.0
*/
public void addResponseHeader(String name, String value) {
if (defaultExternalContext != null) {
defaultExternalContext.addResponseHeader(name, value);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @param size the new buffer size
*
* @since 2.0
*/
public void setResponseBufferSize(int size) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseBufferSize(size);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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
*/
public int getResponseBufferSize() {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseBufferSize();
}
throw new UnsupportedOperationException();
}
/**
* 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
*/
public boolean isResponseCommitted() {
if (defaultExternalContext != null) {
return defaultExternalContext.isResponseCommitted();
}
throw new UnsupportedOperationException();
}
/**
* 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
*/
public void responseReset() {
if (defaultExternalContext != null) {
defaultExternalContext.responseReset();
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @param statusCode an HTTP status code
* @param message an option message to detail the cause of the code
*
* @since 2.0
*/
public void responseSendError(int statusCode, String message) throws IOException {
if (defaultExternalContext != null) {
defaultExternalContext.responseSendError(statusCode, message);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @param statusCode an HTTP status code
*
* @since 2.0
*/
public void setResponseStatus(int statusCode) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseStatus(statusCode);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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
*/
public void setSessionMaxInactiveInterval(int interval) {
if (defaultExternalContext != null) {
defaultExternalContext.setSessionMaxInactiveInterval(interval);
} else {
throw new UnsupportedOperationException();
}
}
/**
* Associate this instance with a {@link ClientWindow}.
*
* @param window the window with which this instance is associated.
*
* @since 2.2
*/
public void setClientWindow(ClientWindow window) {
if (defaultExternalContext != null) {
defaultExternalContext.setClientWindow(window);
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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.
*
* @since 2.0
*/
public void responseFlushBuffer() throws IOException {
if (defaultExternalContext != null) {
defaultExternalContext.responseFlushBuffer();
} else {
throw new UnsupportedOperationException();
}
}
/**
* 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
*/
public void setResponseContentLength(int length) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseContentLength(length);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* 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 {@link #encodeActionURL(java.lang.String)}
* for the required specification of how to encode the {@link javax.faces.lifecycle.ClientWindow}.
*
*
*
* The default implementation throws
* UnsupportedOperationException and is provided for
* the sole purpose of not breaking existing applications that
* extend this class.
*
*
* @param baseUrl The base URL onto which the query string generated by this method will be appended. The URL may contain query parameters.
* @param parameters The collection of Parameter objects, representing name=value pairs that are used to produce a query string
* @since 2.0
*/
public String encodeBookmarkableURL(String baseUrl,
Map> parameters) {
if (defaultExternalContext != null) {
return defaultExternalContext.encodeBookmarkableURL(baseUrl,
parameters);
}
throw new UnsupportedOperationException();
}
/**
* 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 {@link #encodeActionURL(java.lang.String)}
* for the required specification of how to encode the {@link javax.faces.lifecycle.ClientWindow}.
*
*
* @param baseUrl The base URL onto which the query string generated by this method will be appended. The URL may contain query parameters.
* @param parameters The collection of Parameter objects, representing name=value pairs that are used to produce a query string
* @since 2.0
*/
public String encodeRedirectURL(String baseUrl,
Map> parameters) {
if (defaultExternalContext != null) {
return defaultExternalContext.encodeRedirectURL(baseUrl, parameters);
}
throw new UnsupportedOperationException();
}
/**
* 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 {@link #encodeActionURL(java.lang.String)}
* for the required specification of how to encode the {@link javax.faces.lifecycle.ClientWindow}.
*
*
*
*
*
*
*
Servlet:Returns the same encoded URL as the
* {@link #encodeActionURL(String url)} method.
*
* Portlet:Returns an encoded URL that, upon HTTP POST, will
* invoke the RESOURCE_PHASE of the portlet lifecycle.
*
*
*
* @param url The input URL to be encoded
*
* @throws NullPointerException if url
* is null
*
* @since 2.0
*/
public String encodePartialActionURL(String url) {
if (defaultExternalContext != null) {
return defaultExternalContext.encodePartialActionURL(url);
}
throw new UnsupportedOperationException();
}
/**
* 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
*/
public boolean isSecure() {
if (defaultExternalContext != null) {
return defaultExternalContext.isSecure();
} else {
throw new UnsupportedOperationException();
}
}
}