/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2012 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.
*/
package javax.faces.application;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.util.Collections;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.faces.FacesException;
import javax.faces.component.UIComponent;
import javax.faces.component.UIViewRoot;
import javax.faces.context.ExternalContext;
import javax.faces.context.FacesContext;
import javax.faces.view.ViewDeclarationLanguage;
/**
* <p><strong><span
* class="changed_modified_2_0 changed_modified_2_1 changed_modified_2_2">
* ViewHandler</span></strong> is the
* pluggablity mechanism for allowing implementations of or applications
* using the JavaServer Faces specification to provide their own
* handling of the activities in the <em>Render Response</em> and
* <em>Restore View</em> phases of the request processing lifecycle.
* This allows for implementations to support different response
* generation technologies, as well as alternative strategies for saving
* and restoring the state of each view. <span class="changed_added_2_0">An
* implementation
* of this class must be thread-safe.</span></p>
*
* <p>Please see {@link StateManager} for information on how the
* <code>ViewHandler</code> interacts the {@link StateManager}. </p>
* <p class="changed_added_2_0">Version 2 of the specification formally
* introduced the concept of <em>View Declaration Language</em>. A View
* Declaration Language (VDL) is a syntax used to declare user
* interfaces comprised of instances of JSF {@link UIComponent}s. Any
* of the responsibilities of the <code>ViewHandler</code> that
* specifically deal with the VDL sub-system are now the domain of the
* VDL implementation. These responsibilities are defined on the {@link
* ViewDeclarationLanguage} class. The <code>ViewHandler</code>
* provides {@link #getViewDeclarationLanguage} as a convenience method
* to access the VDL implementation given a <code>viewId</code>.</p>
*
*/
public abstract class ViewHandler {
private static final Logger log = Logger.getLogger("javax.faces.application");
// ------------------------------------------------------ Manifest Constants
/**
* <p>The key, in the session's attribute set, under which the
* response character encoding may be stored and retrieved.</p>
*
*/
public static final String CHARACTER_ENCODING_KEY =
"javax.faces.request.charset";
/**
* <p><span class="changed_modified_2_0">Allow</span> the web
* application to define a <span class="changed_modified_2_0">list
* of alternate suffixes</span> for pages containing JSF content.
* <span class="changed_modified_2_0">This list is a space separated
* list of values of the form
* <i><code>.<extension></code></i>. The first physical
* resource whose extension matches one of the configured extensions
* will be the suffix used to create the view ID.</span> If this
* init parameter is not specified, the default value is taken from
* the value of the constant {@link #DEFAULT_SUFFIX}.</p>
*/
public static final String DEFAULT_SUFFIX_PARAM_NAME =
"javax.faces.DEFAULT_SUFFIX";
/**
* <p class="changed_modified_2_1">The value to use for the default
* extension if the webapp is using url extension mapping.</p>
*/
public static final String DEFAULT_SUFFIX = ".xhtml .view.xml .jsp";
/**
* <p class="changed_added_2_2">
* If this param is set, and calling toLowerCase().equals("true") on a
* String representation of its value returns true, the runtime must
* ensure that any XML comments in the Facelets source page are not
* delivered to the client. The runtime must also consider the
* facelets.SKIP_COMMENTS param name as an alias to this param name for
* backwards compatibility with existing facelets tag libraries.
* </p>
*
* @since 2.0
*/
public static final String FACELETS_SKIP_COMMENTS_PARAM_NAME =
"javax.faces.FACELETS_SKIP_COMMENTS";
/**
* <p class="changed_added_2_0">Allow the web application to define an
* alternate suffix for Facelet based XHTML pages containing JSF content.
* If this init parameter is not specified, the default value is
* taken from the value of the constant {@link #DEFAULT_FACELETS_SUFFIX}</p>
*
* @since 2.0
*/
public static final String FACELETS_SUFFIX_PARAM_NAME =
"javax.faces.FACELETS_SUFFIX";
/**
* <p class="changed_added_2_0">The value to use for the default extension
* for Facelet based XHTML pages if the webapp is using
* url extension mapping.</p>
*
* @since 2.0
*/
public static final String DEFAULT_FACELETS_SUFFIX = ".xhtml";
/**
* <p class="changed_added_2_0">Allow the web application to define
* a semicolon (;) separated list of strings that is used to forcibly
* declare that certain pages in the application must be interpreted
* as using Facelets, regardless of their extension. Each entry in the
* semicolon (;) separated list of strings is either a file extension, as in
* <code>*.xhtml</code>, or a resource prefix (starting with '/' and
* interpreted as relative to the web application root), as in
* <code>/user/*</code>. The latter class of entry can also take the form
* of <code>/<filename>.<extension>*</code> such as
* <code>/login.jsp*</code>. The runtime must also consider the
* <code>facelets.VIEW_MAPPINGS</code> param name as an alias to this
* param name for backwards compatibility with existing Facelets
* applications.</p>
*
* @since 2.0
*/
public static final String FACELETS_VIEW_MAPPINGS_PARAM_NAME =
"javax.faces.FACELETS_VIEW_MAPPINGS";
/**
* <p class="changed_added_2_2">
* The buffer size to set on the response when the ResponseWriter is
* generated. By default the value is 1024. A value of -1 will not assign
* a buffer size on the response. This should be increased if you are
* using development mode in order to guarantee that the response isn't
* partially rendered when an error is generated. The runtime must also
* consider the facelets.BUFFER_SIZE param name as an alias to this param
* name for backwards compatibility with existing facelets tag libraries.</p>
*
* @since 2.0
*/
public static final String FACELETS_BUFFER_SIZE_PARAM_NAME =
"javax.faces.FACELETS_BUFFER_SIZE";
/**
* <p class="changed_added_2_2">When a page is requested, what interval in seconds should the compiler
* check for changes. If you don't want the compiler to check for changes
* once the page is compiled, then use a value of -1. Setting a low
* refresh period helps during development to be able to edit pages in a
* running application.The runtime must also consider the
* facelets.REFRESH_PERIOD param name as an alias to this param name for
* backwards compatibility with existing facelets tag libraries.
* </p>
*
* @since 2.0
*/
public static final String FACELETS_REFRESH_PERIOD_PARAM_NAME =
"javax.faces.FACELETS_REFRESH_PERIOD";
/**
* <p class="changed_added_2_2">
* If this param is set, the runtime must interpret it as a semicolon (;)
* separated list of paths, starting with "/" (without the quotes). The
* runtime must interpret each entry in the list as a path relative to
* the web application root and interpret the file found at that path as
* a facelet tag library, conforming to the facelet taglibrary schema and
* expose the tags therein according to Section "Facelet Tag Library
* mechanism". The runtime must also consider the facelets.LIBRARIES
* param name as an alias to this param name for backwards compatibility
* with existing facelets tag libraries.
* </p>
*
*
* @since 2.0
*/
public static final String FACELETS_LIBRARIES_PARAM_NAME =
"javax.faces.FACELETS_LIBRARIES";
/**
* <p class="changed_added_2_2">A semicolon (;) delimitted list of class names of type
* javax.faces.view.facelets.TagDecorator, with a no-argument
* constructor. These decorators will be loaded when the first request
* for a Facelets VDL view hits the ViewHandler for page compilation.The
* runtime must also consider the facelets.DECORATORS param name as an
* alias to this param name for backwards compatibility with existing
* facelets tag libraries.
* </p>
*
* @since 2.0
*/
public static final String FACELETS_DECORATORS_PARAM_NAME =
"javax.faces.FACELETS_DECORATORS";
/**
* <p class="changed_added_2_2">
* If this param is set, and calling toLowerCase().equals("true") on a
* String representation of its value returns true, the default
* ViewHandler must behave as specified in the latest 1.2 version of this
* specification. Any behavior specified in Section "Default
* ViewDeclarationLanguage Implementation" of the spec prose document and
* implemented in the default ViewHandler that pertains to handling
* requests for pages authored in the JavaServer Faces View Declaration
* Language must not be executed by the runtime.
* </p>
*
* @since 2.0
*/
public static final String DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME =
"DISABLE_FACELET_JSF_VIEWHANDLER";
// ---------------------------------------------------------- Public Methods
/**
* <p>Returns an appropriate {@link Locale} to use for this and
* subsequent requests for the current client.</p>
*
* @param context {@link FacesContext} for the current request
*
* @throws NullPointerException if <code>context</code> is
* <code>null</code>
*/
public abstract Locale calculateLocale(FacesContext context);
/**
* <p>Returns the correct character encoding to be used for this request.</p>
*
* <p>The following algorithm is employed.</p>
*
* <ul>
*
* <li><p>Examine the <code>Content-Type</code> request header. If it has
* a <code>charset</code> parameter, extract it and return that as the
* encoding.</p></li>
*
* <li><p>If no <code>charset</code> parameter was found, check for the
* existence of a session by calling {@link ExternalContext#getSession(boolean)}
* passing <code>false</code> as the argument. If that method returns
* <code>true</code>, get the session Map by calling
* {@link ExternalContext#getSessionMap} and look for a value under the
* key given by the value of the symbolic constant
* {@link ViewHandler#CHARACTER_ENCODING_KEY}.
* If present, return the value, converted to String.</p></li>
*
* <li><p>Otherwise, return <code>null</code></p></li>
*
* </ul>
*
* @since 1.2
*/
public String calculateCharacterEncoding(FacesContext context) {
ExternalContext extContext = context.getExternalContext();
Map<String,String> headerMap = extContext.getRequestHeaderMap();
String contentType = headerMap.get("Content-Type");
String charEnc = null;
// look for a charset in the Content-Type header first.
if (null != contentType) {
// see if this header had a charset
String charsetStr = "charset=";
int len = charsetStr.length();
int idx = contentType.indexOf(charsetStr);
// if we have a charset in this Content-Type header AND it
// has a non-zero length.
if (idx != -1 && idx + len < contentType.length()) {
charEnc = contentType.substring(idx + len);
}
}
// failing that, look in the session for a previously saved one
if (null == charEnc) {
if (null != extContext.getSession(false)) {
charEnc = (String) extContext.getSessionMap().get(CHARACTER_ENCODING_KEY);
}
}
return charEnc;
}
/**
* <p>Return an appropriate <code>renderKitId</code> for this and
* subsequent requests from the current client. It is an error for
* this method to return <code>null</code>.</p>
*
* <p>The default return value is {@link
* javax.faces.render.RenderKitFactory#HTML_BASIC_RENDER_KIT}.</p>
*
* @param context {@link FacesContext} for the current request
*
* @throws NullPointerException if <code>context</code> is
* <code>null</code>
*/
public abstract String calculateRenderKitId(FacesContext context);
/**
* <p><strong class="changed_modified_2_0">Create</strong> and
* return a new {@link UIViewRoot} instance initialized with
* information from the argument <code>FacesContext</code> and
* <code>viewId</code>. <span class="changed_modified_2_0">Locate
* the {@link ViewDeclarationLanguage} implementation for the VDL
* used in the view. The argument <code>viewId</code> must be
* converted to a physical <code>viewId</code> that can refer to an
* actual resource suitable for use by the
* <code>ViewDeclarationLanguage</code> {@link
* ViewDeclarationLanguage#createView}, which must be called by
* this method.</span>
* @throws NullPointerException if <code>context</code>
* is <code>null</code>
*/
public abstract UIViewRoot createView(FacesContext context, String viewId);
/**
* <p class="changed_added_2_0">Derive and return the viewId from
* the current request, or the argument input by following the
* algorithm defined in specification section JSF.7.6.2.</p>
*
* <p>The default implementation of this method simply returns
* rawViewId unchanged.</p>
*
* @param context the <code>FacesContext</code> for this request
*
* @param rawViewId the <code>viewId</code> to derive,
*
* @since 2.0
*/
public String deriveViewId(FacesContext context, String rawViewId) {
return rawViewId;
}
/**
* <p class="changed_added_2_1">Derive and return the viewId from
* the current request, or the argument input by following the
* algorithm defined in specification section JSF.7.6.2. Note that
* unlike <code>deriveViewId()</code>, this method does not require that
* a physical view be present.</p>
*
* <p>The default implementation of this method simply returns
* rawViewId unchanged.</p>
*
* @param context the <code>FacesContext</code> for this request
*
* @param rawViewId the <code>viewId</code> to derive,
*
* @since 2.1
*/
public String deriveLogicalViewId(FacesContext context, String rawViewId) {
return rawViewId;
}
/**
* <p class="changed_modified_2_0"><span class="changed_modified_2_2">If</span>
* the value returned from this
* method is used as the <code>file</code> argument to the
* four-argument constructor for <code>java.net.URL</code> (assuming
* appropriate values are used for the first three arguments), then
* a client making a request to the <code>toExternalForm()</code> of
* that <code>URL</code> will select the argument
* <code>viewId</code> for traversing the JSF lifecycle. Please see
* section JSF.7.6.2 for the complete specification,
* <span class="changed_added_2_2">especially for details related
* to view protection using the {@link javax.faces.render.ResponseStateManager#NON_POSTBACK_VIEW_TOKEN_PARAM}
* </span>.</p>
*
* @param context {@link FacesContext} for this request
* @param viewId View identifier of the desired view
*
* @throws IllegalArgumentException if <code>viewId</code> is not
* valid for this <code>ViewHandler</code>, or does not start with
* "/".
* @throws NullPointerException if <code>context</code> or
* <code>viewId</code> is <code>null</code>.
*/
public abstract String getActionURL(FacesContext context, String viewId);
/**
* <p class="changed_modified_2_0">If the value returned from this
* method is used as the <code>file</code> argument to the
* four-argument constructor for <code>java.net.URL</code> (assuming
* appropriate values are used for the first three arguments), then
* a client making a request to the <code>toExternalForm()</code> of
* that <code>URL</code> will select the argument <code>path</code>
* for direct rendering. If the specified path starts with a slash,
* it must be treated as context relative; otherwise, it must be
* treated as relative to the action URL of the current view.</p>
*
* @param context {@link FacesContext} for the current request
* @param path Resource path to convert to a URL
*
* @throws IllegalArgumentException if <code>viewId</code> is not
* valid for this <code>ViewHandler</code>.
* @throws NullPointerException if <code>context</code> or
* <code>path</code> is <code>null</code>.
*/
public abstract String getResourceURL(FacesContext context, String path);
/**
* <p class="changed_added_2_2">Return an unmodifiable
* <code>Set</code> of the protected views currently known to this
* <code>ViewHandler</code> instance. Compliant implementations must
* return a <code>Set</code> that is the concatenation of the
* contents of all the <code><url-pattern></code> elements
* within all the <code><protected-views></code> in all of the
* application configuration resources in the current application.
* The runtime must support calling this method at any time after
* application startup. The default implementation returns an
* unmodifiable empty <code>Set</code>.</p>
*
* @since 2.2
*/
public Set<String> getProtectedViewsUnmodifiable() {
return Collections.unmodifiableSet(Collections.EMPTY_SET);
}
/**
* <p class="changed_added_2_2">Add the argument
* <code>urlPattern</code> to the thread safe <code>Set</code> of
* protected views for this application. Compliant implementations
* make it so a subsequent call to {@link
* #getProtectedViewsUnmodifiable} contains the argument. The
* runtime must support calling this method at any time after
* application startup. The default implementation takes no
* action.</p>
*
* @param urlPattern the url-pattern to add.
*
* @since 2.2
*/
public void addProtectedView(String urlPattern) {
}
/**
* <p class="changed_added_2_2">Remove the argument
* <code>urlPattern</code> from the thread safe <code>Set</code> of
* protected views for this application, if present in the
* <code>Set</code>. If the argument <code>urlPattern</code> is not
* present in the <code>Set</code>, this method has no effect.
* Compliant implementations must make it so a subsequent call to
* {@link #getProtectedViewsUnmodifiable} does not contain the
* argument. The runtime must support calling this method at any
* time after application startup. Returns <code>true</code> if
* this <code>Set</code> contained the argument. The default
* implementation takes no action and returns
* <code>false</code>.</p>
*
* @param urlPattern the url-pattern to remove.
*
* @since 2.2
*/
public boolean removeProtectedView(String urlPattern) {
return false;
}
/**
* <p class="changed_added_2_0"> Return a JSF action URL derived
* from the <code>viewId</code> argument that is suitable to be used
* by the {@link NavigationHandler} to issue a redirect request to
* the URL using a NonFaces request. Compliant implementations
* must implement this method as specified in section JSF.7.6.2.
* The default implementation simply calls through to {@link
* #getActionURL}, passing the arguments <code>context</code> and
* <code>viewId</code>.</p>
*
* @param context The FacesContext processing this request
* @param viewId The view identifier of the target page
* @param parameters A mapping of parameter names to one or more values
* @param includeViewParams A flag indicating whether view parameters should be encoded into this URL
* @since 2.0
*/
public String getRedirectURL(FacesContext context,
String viewId,
Map<String,List<String>>parameters,
boolean includeViewParams) {
return getActionURL(context, viewId);
}
/**
* <p class="changed_added_2_0"> Return a JSF action URL derived
* from the viewId argument that is suitable to be used as the
* target of a link in a JSF response. Compiliant implementations
* must implement this method as specified in section JSF.7.6.2.
* The default implementation simply calls through to {@link
* #getActionURL}, passing the arguments <code>context</code> and
* <code>viewId</code>.</p>
*
* @param context The FacesContext processing this request
* @param viewId The view identifier of the target page
* @param parameters A mapping of parameter names to one or more values
* @param includeViewParams A flag indicating whether view parameters should be encoded into this URL
*
* @since 2.0
*/
public String getBookmarkableURL(FacesContext context,
String viewId,
Map<String,List<String>> parameters,
boolean includeViewParams) {
return getActionURL(context, viewId);
}
/**
* <p class="changed_added_2_0"><span class="changed_modified_2_1">Return</span>
* the {@link ViewDeclarationLanguage} instance used for this <code>ViewHandler</code>
* instance.</p>
*
* <div class="changed_added_2_0">
*
* <p>The default implementation must use {@link
* javax.faces.view.ViewDeclarationLanguageFactory#getViewDeclarationLanguage}
* to obtain the appropriate <code>ViewDeclarationLanguage</code>
* implementation for the argument <code>viewId</code>. Any
* exceptions thrown as a result of invoking that method must not be
* swallowed.</p>
*
* <p>The default implementation of this method returns null.</p>
*
* </div>
*
* @param context the <code>FacesContext</code> for this request.
*
* @param viewId <span class="changed_modified_2_1">the logical view
* id, as returned from {@link #deriveLogicalViewId} for which the
* <code>ViewDeclarationLanguage</code> should be returned.</span>
* @since 2.0
*/
public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context,
String viewId) {
return null;
}
/**
*
* <p><span class="changed_modified_2_0">Initialize</span> the view
* for the request processing lifecycle.</p>
*
* <p>This method must be called at the beginning of the <em>Restore
* View Phase</em> of the Request Processing Lifecycle. It is responsible
* for performing any per-request initialization necessary to the operation
* of the lifycecle.</p>
*
* <p class="changed_modified_2_0">The default implementation must
* perform the following actions. If {@link
* ExternalContext#getRequestCharacterEncoding} returns
* <code>null</code>, call {@link #calculateCharacterEncoding} and
* pass the result, if non-<code>null</code>, into the {@link
* ExternalContext#setRequestCharacterEncoding} method. If {@link
* ExternalContext#getRequestCharacterEncoding} returns
* non-<code>null</code> take no action.</p>
* @throws FacesException if a problem occurs setting the encoding,
* such as the <code>UnsupportedEncodingException</code> thrown
* by the underlying Servlet or Portlet technology when the encoding is not
* supported.
*
*/
public void initView(FacesContext context) throws FacesException {
String encoding = context.getExternalContext().getRequestCharacterEncoding();
if (null != encoding) {
return;
}
encoding = calculateCharacterEncoding(context);
if (null != encoding) {
try {
context.getExternalContext().setRequestCharacterEncoding(encoding);
} catch (UnsupportedEncodingException e) {
// PENDING(edburns): I18N
String message = "Can't set encoding to: " + encoding +
" Exception:" + e.getMessage();
if (log.isLoggable(Level.WARNING)) {
log.fine(message);
}
throw new FacesException(message, e);
}
}
}
/**
* <p><span class="changed_modified_2_0">Perform</span> whatever
* actions are required to render the response view to the response
* object associated with the current {@link FacesContext}.</p>
* <p class="changed_added_2_0">Otherwise, the default
* implementation must obtain a reference to the {@link
* ViewDeclarationLanguage} for the <code>viewId</code> of the
* argument <code>viewToRender</code> and call its {@link
* ViewDeclarationLanguage#renderView} method, returning the result
* and not swallowing any exceptions thrown by that method.</p>
*
* @param context {@link FacesContext} for the current request
* @param viewToRender the view to render
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if <code>context</code> or
* <code>viewToRender</code> is <code>null</code>
* @throws FacesException if a servlet error occurs
*/
public abstract void renderView(FacesContext context, UIViewRoot viewToRender)
throws IOException, FacesException;
/**
* <p><span class="changed_modified_2_0">Perform</span> whatever
* actions are required to restore the view associated with the
* specified {@link FacesContext} and <code>viewId</code>. It may
* delegate to the <code>restoreView</code> of the associated {@link
* StateManager} to do the actual work of restoring the view. If
* there is no available state for the specified
* <code>viewId</code>, return <code>null</code>.</p>
* <p class="changed_added_2_0">Otherwise, the default implementation
* must obtain a reference to the {@link ViewDeclarationLanguage}
* for this <code>viewId</code> and call its {@link
* ViewDeclarationLanguage#restoreView} method, returning the result
* and not swallowing any exceptions thrown by that method.</p>
* @param context {@link FacesContext} for the current request
* @param viewId the view identifier for the current request
*
* @throws NullPointerException if <code>context</code>
* is <code>null</code>
* @throws FacesException if a servlet error occurs
*/
public abstract UIViewRoot restoreView(FacesContext context, String viewId);
/**
* <p>Take any appropriate action to either immediately
* write out the current state information (by calling
* {@link StateManager#writeState}, or noting where state information
* should later be written.</p>
*
* <p class="changed_added_2_0">This method must do nothing if the current
* request is an <code>Ajax</code> request. When responding to
* <code>Ajax</code> requests, the state is obtained by calling
* {@link StateManager#getViewState}
* and then written into the <code>Ajax</code> response during final
* encoding
* ({@link javax.faces.component.UIViewRoot#encodeEnd}.
* </p>
*
* @param context {@link FacesContext} for the current request
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if <code>context</code>
* is <code>null</code>
*/
public abstract void writeState(FacesContext context) throws IOException;
}