javax.faces.application.ViewHandler Maven / Gradle / Ivy
Show all versions of jsf-api Show documentation
/*
* 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;
/**
*
* ViewHandler 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 Render Response and
* Restore View 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. An
* implementation
* of this class must be thread-safe.
*
* Please see {@link StateManager} for information on how the
* ViewHandler interacts the {@link StateManager}.
* Version 2 of the specification formally
* introduced the concept of View Declaration Language. 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 ViewHandler 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 ViewHandler
* provides {@link #getViewDeclarationLanguage} as a convenience method
* to access the VDL implementation given a viewId.
*
*/
public abstract class ViewHandler {
private static final Logger log = Logger.getLogger("javax.faces.application");
// ------------------------------------------------------ Manifest Constants
/**
* The key, in the session's attribute set, under which the
* response character encoding may be stored and retrieved.
*
*/
public static final String CHARACTER_ENCODING_KEY =
"javax.faces.request.charset";
/**
* Allow the web
* application to define a list
* of alternate suffixes for pages containing JSF content.
* This list is a space separated
* list of values of the form
* .<extension>. The first physical
* resource whose extension matches one of the configured extensions
* will be the suffix used to create the view ID. If this
* init parameter is not specified, the default value is taken from
* the value of the constant {@link #DEFAULT_SUFFIX}.
*/
public static final String DEFAULT_SUFFIX_PARAM_NAME =
"javax.faces.DEFAULT_SUFFIX";
/**
* The value to use for the default
* extension if the webapp is using url extension mapping.
*/
public static final String DEFAULT_SUFFIX = ".xhtml .view.xml .jsp";
/**
*
* 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.
*
*
* @since 2.0
*/
public static final String FACELETS_SKIP_COMMENTS_PARAM_NAME =
"javax.faces.FACELETS_SKIP_COMMENTS";
/**
* 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}
*
* @since 2.0
*/
public static final String FACELETS_SUFFIX_PARAM_NAME =
"javax.faces.FACELETS_SUFFIX";
/**
* The value to use for the default extension
* for Facelet based XHTML pages if the webapp is using
* url extension mapping.
*
* @since 2.0
*/
public static final String DEFAULT_FACELETS_SUFFIX = ".xhtml";
/**
* 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
* *.xhtml, or a resource prefix (starting with '/' and
* interpreted as relative to the web application root), as in
* /user/*. The latter class of entry can also take the form
* of /<filename>.<extension>* such as
* /login.jsp*. The runtime must also consider the
* facelets.VIEW_MAPPINGS param name as an alias to this
* param name for backwards compatibility with existing Facelets
* applications.
*
* @since 2.0
*/
public static final String FACELETS_VIEW_MAPPINGS_PARAM_NAME =
"javax.faces.FACELETS_VIEW_MAPPINGS";
/**
*
* 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.
*
* @since 2.0
*/
public static final String FACELETS_BUFFER_SIZE_PARAM_NAME =
"javax.faces.FACELETS_BUFFER_SIZE";
/**
* 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.
*
*
* @since 2.0
*/
public static final String FACELETS_REFRESH_PERIOD_PARAM_NAME =
"javax.faces.FACELETS_REFRESH_PERIOD";
/**
*
* 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.
*
*
*
* @since 2.0
*/
public static final String FACELETS_LIBRARIES_PARAM_NAME =
"javax.faces.FACELETS_LIBRARIES";
/**
* 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.
*
*
* @since 2.0
*/
public static final String FACELETS_DECORATORS_PARAM_NAME =
"javax.faces.FACELETS_DECORATORS";
/**
*
* 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.
*
*
* @since 2.0
*/
public static final String DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME =
"DISABLE_FACELET_JSF_VIEWHANDLER";
// ---------------------------------------------------------- Public Methods
/**
* Returns an appropriate {@link Locale} to use for this and
* subsequent requests for the current client.
*
* @param context {@link FacesContext} for the current request
*
* @throws NullPointerException if context is
* null
*/
public abstract Locale calculateLocale(FacesContext context);
/**
* Returns the correct character encoding to be used for this request.
*
* The following algorithm is employed.
*
*
*
* Examine the Content-Type request header. If it has
* a charset parameter, extract it and return that as the
* encoding.
If no charset parameter was found, check for the
* existence of a session by calling {@link ExternalContext#getSession(boolean)}
* passing false as the argument. If that method returns
* true, 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.
Otherwise, return null
*
* @since 1.2
*/
public String calculateCharacterEncoding(FacesContext context) {
ExternalContext extContext = context.getExternalContext();
Map 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;
}
/**
* Return an appropriate renderKitId for this and
* subsequent requests from the current client. It is an error for
* this method to return null.
*
* The default return value is {@link
* javax.faces.render.RenderKitFactory#HTML_BASIC_RENDER_KIT}.
*
* @param context {@link FacesContext} for the current request
*
* @throws NullPointerException if context is
* null
*/
public abstract String calculateRenderKitId(FacesContext context);
/**
* Create and
* return a new {@link UIViewRoot} instance initialized with
* information from the argument FacesContext and
* viewId. Locate
* the {@link ViewDeclarationLanguage} implementation for the VDL
* used in the view. The argument viewId must be
* converted to a physical viewId that can refer to an
* actual resource suitable for use by the
* ViewDeclarationLanguage {@link
* ViewDeclarationLanguage#createView}, which must be called by
* this method.
* @throws NullPointerException if context
* is null
*/
public abstract UIViewRoot createView(FacesContext context, String viewId);
/**
*
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.
*
* The default implementation of this method simply returns
* rawViewId unchanged.
*
* @param context the FacesContext for this request
*
* @param rawViewId the viewId to derive,
*
* @since 2.0
*/
public String deriveViewId(FacesContext context, String rawViewId) {
return rawViewId;
}
/**
* 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 deriveViewId(), this method does not require that
* a physical view be present.
*
* The default implementation of this method simply returns
* rawViewId unchanged.
*
* @param context the FacesContext for this request
*
* @param rawViewId the viewId to derive,
*
* @since 2.1
*/
public String deriveLogicalViewId(FacesContext context, String rawViewId) {
return rawViewId;
}
/**
* If
* the value returned from this
* method is used as the file argument to the
* four-argument constructor for java.net.URL (assuming
* appropriate values are used for the first three arguments), then
* a client making a request to the toExternalForm() of
* that URL will select the argument
* viewId for traversing the JSF lifecycle. Please see
* section JSF.7.6.2 for the complete specification,
* especially for details related
* to view protection using the {@link javax.faces.render.ResponseStateManager#NON_POSTBACK_VIEW_TOKEN_PARAM}
* .
*
* @param context {@link FacesContext} for this request
* @param viewId View identifier of the desired view
*
* @throws IllegalArgumentException if viewId is not
* valid for this ViewHandler, or does not start with
* "/".
* @throws NullPointerException if context or
* viewId is null.
*/
public abstract String getActionURL(FacesContext context, String viewId);
/**
* If the value returned from this
* method is used as the file argument to the
* four-argument constructor for java.net.URL (assuming
* appropriate values are used for the first three arguments), then
* a client making a request to the toExternalForm() of
* that URL will select the argument path
* 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.
*
* @param context {@link FacesContext} for the current request
* @param path Resource path to convert to a URL
*
* @throws IllegalArgumentException if viewId is not
* valid for this ViewHandler.
* @throws NullPointerException if context or
* path is null.
*/
public abstract String getResourceURL(FacesContext context, String path);
/**
* Return an unmodifiable
* Set of the protected views currently known to this
* ViewHandler instance. Compliant implementations must
* return a Set that is the concatenation of the
* contents of all the <url-pattern> elements
* within all the <protected-views> 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 Set.
*
* @since 2.2
*/
public Set getProtectedViewsUnmodifiable() {
return Collections.unmodifiableSet(Collections.EMPTY_SET);
}
/**
* Add the argument
* urlPattern to the thread safe Set 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.
*
* @param urlPattern the url-pattern to add.
*
* @since 2.2
*/
public void addProtectedView(String urlPattern) {
}
/**
* Remove the argument
* urlPattern from the thread safe Set of
* protected views for this application, if present in the
* Set. If the argument urlPattern is not
* present in the Set, 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 true if
* this Set contained the argument. The default
* implementation takes no action and returns
* false.
*
* @param urlPattern the url-pattern to remove.
*
* @since 2.2
*/
public boolean removeProtectedView(String urlPattern) {
return false;
}
/**
* Return a JSF action URL derived
* from the viewId 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 context and
* viewId.
*
* @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>parameters,
boolean includeViewParams) {
return getActionURL(context, viewId);
}
/**
* 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 context and
* viewId.
*
* @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> parameters,
boolean includeViewParams) {
return getActionURL(context, viewId);
}
/**
* Return
* the {@link ViewDeclarationLanguage} instance used for this ViewHandler
* instance.
*
*
*
* The default implementation must use {@link
* javax.faces.view.ViewDeclarationLanguageFactory#getViewDeclarationLanguage}
* to obtain the appropriate ViewDeclarationLanguage
* implementation for the argument viewId. Any
* exceptions thrown as a result of invoking that method must not be
* swallowed.
*
* The default implementation of this method returns null.
*
*
*
* @param context the FacesContext for this request.
*
* @param viewId the logical view
* id, as returned from {@link #deriveLogicalViewId} for which the
* ViewDeclarationLanguage should be returned.
* @since 2.0
*/
public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context,
String viewId) {
return null;
}
/**
*
* Initialize the view
* for the request processing lifecycle.
*
* This method must be called at the beginning of the Restore
* View Phase of the Request Processing Lifecycle. It is responsible
* for performing any per-request initialization necessary to the operation
* of the lifycecle.
*
* The default implementation must
* perform the following actions. If {@link
* ExternalContext#getRequestCharacterEncoding} returns
* null, call {@link #calculateCharacterEncoding} and
* pass the result, if non-null, into the {@link
* ExternalContext#setRequestCharacterEncoding} method. If {@link
* ExternalContext#getRequestCharacterEncoding} returns
* non-null take no action.
* @throws FacesException if a problem occurs setting the encoding,
* such as the UnsupportedEncodingException 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);
}
}
}
/**
* Perform whatever
* actions are required to render the response view to the response
* object associated with the current {@link FacesContext}.
* Otherwise, the default
* implementation must obtain a reference to the {@link
* ViewDeclarationLanguage} for the viewId of the
* argument viewToRender and call its {@link
* ViewDeclarationLanguage#renderView} method, returning the result
* and not swallowing any exceptions thrown by that method.
*
* @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 context or
* viewToRender is null
* @throws FacesException if a servlet error occurs
*/
public abstract void renderView(FacesContext context, UIViewRoot viewToRender)
throws IOException, FacesException;
/**
* Perform whatever
* actions are required to restore the view associated with the
* specified {@link FacesContext} and viewId. It may
* delegate to the restoreView of the associated {@link
* StateManager} to do the actual work of restoring the view. If
* there is no available state for the specified
* viewId, return null.
* Otherwise, the default implementation
* must obtain a reference to the {@link ViewDeclarationLanguage}
* for this viewId and call its {@link
* ViewDeclarationLanguage#restoreView} method, returning the result
* and not swallowing any exceptions thrown by that method.
* @param context {@link FacesContext} for the current request
* @param viewId the view identifier for the current request
*
* @throws NullPointerException if context
* is null
* @throws FacesException if a servlet error occurs
*/
public abstract UIViewRoot restoreView(FacesContext context, String viewId);
/**
* 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.
*
* This method must do nothing if the current
* request is an Ajax request. When responding to
* Ajax requests, the state is obtained by calling
* {@link StateManager#getViewState}
* and then written into the Ajax response during final
* encoding
* ({@link javax.faces.component.UIViewRoot#encodeEnd}.
*
*
* @param context {@link FacesContext} for the current request
*
* @throws IOException if an input/output error occurs
* @throws NullPointerException if context
* is null
*/
public abstract void writeState(FacesContext context) throws IOException;
}