javax.faces.context.ExternalContext Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright 1997-2007 Sun Microsystems, Inc. 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.html
* or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt.
* Sun designates this particular file as subject to the "Classpath" exception
* as provided by Sun in the GPL Version 2 section of the License file that
* accompanied this code. If applicable, add the following below the License
* Header, with the fields enclosed by brackets [] replaced by your own
* identifying information: "Portions Copyrighted [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.
*/
/*
* $Id: ExternalContext.java,v 1.30.4.1 2007/12/17 21:14:38 rlubke Exp $
*/
/*
* 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.net.MalformedURLException;
import java.net.URL;
import java.security.Principal;
import java.util.Iterator;
import java.util.Locale;
import java.util.Set;
import java.util.Map;
/**
* 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.
*/
public abstract class ExternalContext {
// ------------------------------------------------------ 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
/**
* 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.
*
* @param path Context relative path to the specified resource,
* which must start with a slash ("/") character
*
* @throws FacesException thrown if a ServletException
* or PortletException occurs
* @throws IllegalArgumentException if no request dispatcher
* can be created for the specified path
* @throws IllegalStateException if this method is called in a portlet
* environment, and the current request is an ActionRequest
* instead of a RenderRequest
* @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.
*
*
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).
*
* @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.
*
* Portlet: The returned value must be the input value
* prefixed by the value returned by the
* javax.portlet.RenderResponse method
* getNamespace().
*
* @param name Name to be encoded
*
* @throws IllegalStateException if this method is called in a portlet
* environment, and the current response is an ActionResponse
* instead of a RenderResponse
* @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).
*
* Portlet: This must be the value returned by the
* javax.portlet.PortletResponse 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.
*
* Servlet: This must be the set of attributes available via
* the javax.servlet.ServletContext methods
* getAttribute(), getAttributeNames(),
* removeAttribute(), and setAttribute().
*
* Portlet: This must be the set of attributes available via
* the javax.portlet.PortletContext methods
* getAttribute(), getAttributeNames(),
* removeAttribute(), and setAttribute().
*/
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().
*
* Portlet: This must be the value returned by the
* javax.portlet.http.PortletRequest method
* getAuthType().
*/
public abstract String getAuthType();
/**
* 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 Object getContext();
/**
* Return the value of the specified application initialization
* parameter (if any).
*
* Servlet: This must be the result of the
* javax.servlet.ServletContext method
* getInitParameter(name).
*
* Portlet: This must be the result of the
* javax.portlet.PortletContext method
* getInitParameter(name).
*
* @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.
*
* Servlet: This result must be as if it were synthesized
* by calling the javax.servlet.ServletContext
* method getInitParameterNames, and putting
* each configured parameter name/value pair into the result.
*
* Portlet: This result must be as if it were synthesized
* by calling the javax.portlet.PortletContext
* method getInitParameterNames, and putting
* each configured parameter name/value pair into the result.
*/
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().
*
* Portlet: This must be the value returned by the
* javax.portlet.http.PortletRequest 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.
*
* 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 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) {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
impl.setRequest(request);
return;
}
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().
*
* Portlet: This must call through to the
* javax.portlet.ActionRequest 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 {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
impl.setRequestCharacterEncoding(encoding);
return;
}
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().
*
* Portlet: This must be the value returned by the
* javax.portlet.PortletRequest 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.
*
* Portlet: Ths must be an empty Map.
*/
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().
*
* Portlet: This must be the set of properties available via
* the javax.portlet.PortletRequest methods
* getProperty() and getPropertyNames().
* As such, HTTP headers will only be included if they were provided
* by the portlet container, and additional properties provided by
* the portlet container may also be included.
*/
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().
*
* Portlet: This must be the set of properties available via
* the javax.portlet.PortletRequest methods
* getProperties() and getPropertyNames().
* As such, HTTP headers will only be included if they were provided
* by the portlet container, and additional properties provided by
* the portlet container may also be included.
*/
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().
*
* Portlet: This must be the value returned by the
* javax.portlet.PortletRequest 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().
*
* Portlet: This must be an Iterator
* over the values returned by the javax.portlet.PortletRequest
* 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().
*
* Portlet: This must be the set of attributes available via
* the javax.portlet.PortletRequest 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().
*
* Portlet: This must be the set of parameters available via
* the javax.portlet.PortletRequest 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().
*
* Portlet: This must be an Iterator over the
* values returned by the javax.portlet.PortletRequest
* 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().
*
* Portlet: This must be the set of parameters available via
* the javax.portlet.PortletRequest 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().
*
* Portlet: This must be null.
*/
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().
*
* Portlet: This must be null.
*/
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().
*
* Portlet: This must return the value returned by the
* javax.portlet.ActionRequest 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() {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
return impl.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().
*
* Portlet: This must return null.
*
* 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() {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
return impl.getRequestContentType();
}
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().
*
* Portlet: This must return null.
*
* 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() {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
return impl.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().
*
* Portlet: This must return null.
*
* 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() {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
return impl.getResponseContentType();
}
throw new UnsupportedOperationException();
}
/**
* Return a URL for the application resource mapped to the
* specified path, if it exists; otherwise, return null.
*
* Servlet: This must be the value returned by the
* javax.servlet.ServletContext method
* getResource(path).
*
* Portlet: This must be the value returned by the
* javax.portlet.PortletContext method
* getResource(path).
*
* @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.
*
* Servlet: This must be the value returned by the
* javax.servlet.ServletContext method
* getResourceAsStream(path).
*
* Portlet: This must be the value returned by the
* javax.portlet.PortletContext method
* getResourceAsStream(path).
*
* @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.
*
* Servlet: This must be the value returned by the
* javax.servlet.ServletContext method
* getResourcePaths(path).
*
* Portlet: This must be the value returned by the
* javax.portlet.PortletContext 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.
*
* 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 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) {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
impl.setResponse(response);
return;
}
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().
*
* Portlet: This method must take no action.
*
* 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) {
ExternalContext impl = getDefaultExternalContext();
if (impl != null) {
impl.setResponseCharacterEncoding(encoding);
return;
}
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.
*
* em>Portlet: This must return the result of calling
* getPortletSession(create) on the underlying
* javax.portlet.PortletRequest 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 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().
*
* Portlet: This must be the set of attributes available via
* the javax.portlet.PortletSession methods
* getAttribute(), getAttributeNames(),
* removeAttribute(), and setAttribute().
* All session attribute access must occur in PORTLET_SCOPE scope
* within the session.
*/
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().
*
* Portlet: This must be the value returned by the
* javax.portlet.http.PortletRequest method
* getUserPrincipal().
*/
public abstract Principal getUserPrincipal();
/**
* Return true if the currently authenticated user is
* included in the specified role. Otherwise, return false.
*
*
* Servlet: This must be the value returned by the
* javax.servlet.http.HttpServletRequest method
* isUserInRole(role).
*
* Portlet: This must be the value returned by the
* javax.portlet.http.PortletRequest method
* isUserInRole(role).
*
* @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.
*
* Servlet: This must be performed by calling the
* javax.servlet.ServletContext method
* log(String).
*
* Portlet: This must be performed by calling the
* javax.portlet.PortletContext method
* log(String).
*
* @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.
*
* Servlet: This must be performed by calling the
* javax.servlet.ServletContext method
* log(String,Throwable).
*
* Portlet: This must be performed by calling the
* javax.portlet.PortletContext method
* log(String,Throwable).
*
* @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.
*
* 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().
*
* @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;
// --------------------------------------------------------- Private Methods
private ExternalContext getDefaultExternalContext() {
ExternalContext extCtx = null;
Map m = (Map) getRequestMap().get("com.sun.faces.util.RequestStateManager");
if (m != null) {
extCtx = (ExternalContext) m.get("com.sun.faces.ExternalContextImpl");
}
return extCtx;
}
}