org.omnifaces.facesviews

Class FacesViews

java.lang.Object

org.omnifaces.facesviews.FacesViews

public final class FacesViews
extends Object

FacesViews is a mechanism to use SEO-friendly extensionless URLs in a JSF application without the need to enlist individual Facelet source files in some configuration file.

Instead, Facelets source files can be put into either the special /WEB-INF/faces-views directory, from where they will be automatically scanned (no configuration whatsoever required) or an explicit directory can be configured to be scanned. The web app root is supported as well.

Installation

Example of configuring FacesViews to make all Facelets found in the root and its sub-directories (excluding /WEB-INF, /META-INF and /resources) available as extensionless URLs in web.xml:

 <context-param>
     <param-name>org.omnifaces.FACES_VIEWS_SCAN_PATHS</param-name>
     <param-value>/*.xhtml</param-value>
 </context-param>
 

See package documentation for additional details.

PrettyFaces

Note that there is some overlap between this feature and PrettyFaces. The difference is that FacesViews has a focus on zero- or very minimal config, where PrettyFaces has a focus on very powerful mapping mechanisms, which of course need some level of configuration. As such FacesViews will only focus on auto discovering views and mapping them to both .xhtml and to no-extension without needing to explicitly declare the FacesServlet in web.xml.

Specifically, FacesViews will thus not become a general URL rewriting tool (e.g. one that maps path segments to parameters, or that totally changes the name of the URL). For this the user is advised to look at the aforementioned PrettyFaces.

Author:

Arjan Tijms

See Also:

FacesViewsForwardingFilter, FacesViewsViewHandler, FacesViewsResolver

Field Summary

Fields

Modifier and Type	Field and Description
static String	FACES_SERVLET_EXTENSIONS The name of the application scope context parameter under which a Set that stores the extensions to which the FacesServlet is mapped.
static String	FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME The name of the init parameter (in web.xml) that determines the method used by FacesViews to invoke the FacesServlet.
static String	FACES_VIEWS_ENABLED_PARAM_NAME Web context parameter to switch auto-scanning completely off for Servlet 3.0 containers.
static String	FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME The name of the init parameter (in web.xml) that determines the action that is performed whenever a resource is requested WITH extension that's also available without an extension.
static String	FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME The name of the boolean init parameter (in web.xml) via which the user can set whether the FacesViewsForwardingFilter should match before declared filters (false) or after declared filters (true);
static String	FACES_VIEWS_ORIGINAL_SERVLET_PATH
static String	FACES_VIEWS_PATH_ACTION_PARAM_NAME The name of the init parameter (in web.xml) that determines the action that is performed whenever a resource is requested in a public path that has been used for scanning views by faces views.
static String	FACES_VIEWS_RESOURCES
static String	FACES_VIEWS_RESOURCES_EXTENSIONS
static String	FACES_VIEWS_REVERSE_RESOURCES
static String	FACES_VIEWS_SCAN_PATHS_PARAM_NAME The name of the init parameter (in web.xml) where the value holds a comma separated list of paths that are to be scanned by faces views.
static String	FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME The name of the init parameter (in web.xml) via which the user can set scanned views to be always rendered extensionless.
static String	FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME The name of the boolean init parameter (in web.xml) via which the user can set whether the FacesViewsViewHandler should strip the extension from the parent view handler's outcome or construct the URL itself and only take the query parameters (if any) from the parent.
static String	PUBLIC_SCAN_PATHS The name of the application scope context parameter under which a Set version of the public paths that are to be scanned by faces views are kept.
static String	SCAN_PATHS The name of the application scope context parameter under which a Set version of the paths that are to be scanned by faces views are kept.
static String	SCANNED_VIEWS_EXTENSIONLESS The name of the application scope context parameter under which a Boolean version of the scanned views always exensionless init parameter is kept.
static String	WEB_INF_VIEWS A special dedicated "well-known" directory where facelets implementing views can be placed.

Method Summary

Modifier and Type	Method and Description
static boolean	canScanDirectory(String rootPath, String directory)
static boolean	canScanResource(String resource, String extensionToScan)
static ExtensionAction	getExtensionAction(ServletContext servletContext)
static String	getExtensionlessURLWithQuery(HttpServletRequest request) Obtains the full request URL from the given request complete with the query string, but with the extension (if any) cut out.
static String	getExtensionlessURLWithQuery(HttpServletRequest request, String resource) Obtains the full request URL from the given request and the given resource complete with the query string, but with the extension (if any) cut out.
static FacesServletDispatchMethod	getFacesServletDispatchMethod(ServletContext servletContext)
static Set<String>	getFacesServletExtensions(FacesContext context)
static Set<String>	getFacesServletExtensions(ServletContext servletContext)
static String	getMappedPath(String path)
static PathAction	getPathAction(ServletContext servletContext)
static Set<String>	getPublicRootPaths(ServletContext servletContext)
static Set<String>	getRootPaths(ServletContext servletContext)
static ViewHandlerMode	getViewHandlerMode(FacesContext context)
static ViewHandlerMode	getViewHandlerMode(ServletContext servletContext)
static boolean	isFilterAfterDeclaredFilters(ServletContext servletContext)
static boolean	isResourceInPublicPath(ServletContext servletContext, String resource)
static boolean	isScannedViewsAlwaysExtensionless(FacesContext context)
static void	mapFacesServlet(ServletContext servletContext, Set<String> extensions) Map the Facelets Servlet to the given extensions
static String	normalizeRootPath(String rootPath)
static Map<String,String>	scanAndStoreViews(ServletContext context) Scans for faces-views resources and stores the result at the designated location "org.omnifaces.facesviews" in the ServletContext.
static Map<String,String>	scanViews(ServletContext servletContext) Scans resources (views) recursively starting with the given resource paths and returns a flat map containing all resources encountered.
static void	scanViews(ServletContext servletContext, String rootPath, Set<String> resourcePaths, Map<String,String> collectedViews, String extensionToScan, Set<String> collectedExtensions) Scans resources (views) recursively starting with the given resource paths for a specific root path, and collects those and all unique extensions encountered in a flat map respectively set.
static void	scanViewsFromRootPaths(ServletContext servletContext, Map<String,String> collectedViews, Set<String> collectedExtensions)
static String	stripFacesViewsPrefix(String resource) Strips the special 'faces-views' prefix path from the resource if any.
static void	tryScanAndStoreViews(ServletContext context) Checks if resources haven't been scanned yet, and if not does scanning and stores the result at the designated location "org.omnifaces.facesviews" in the ServletContext.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

WEB_INF_VIEWS

public static final String WEB_INF_VIEWS

A special dedicated "well-known" directory where facelets implementing views can be placed. This directory is scanned by convention so that no explicit configuration is needed.

See Also:

Constant Field Values

FACES_VIEWS_ENABLED_PARAM_NAME

public static final String FACES_VIEWS_ENABLED_PARAM_NAME

Web context parameter to switch auto-scanning completely off for Servlet 3.0 containers.

See Also:

Constant Field Values

FACES_VIEWS_SCAN_PATHS_PARAM_NAME

public static final String FACES_VIEWS_SCAN_PATHS_PARAM_NAME

The name of the init parameter (in web.xml) where the value holds a comma separated list of paths that are to be scanned by faces views.

See Also:

Constant Field Values

FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME

public static final String FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME

The name of the init parameter (in web.xml) via which the user can set scanned views to be always rendered extensionless. Without this setting (or it being set to false), it depends on whether the request URI uses an extension or not. If it doesn't, links are also rendered without one, otherwise are rendered with an extension.

See Also:

Constant Field Values

FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME

public static final String FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME

The name of the init parameter (in web.xml) that determines the action that is performed whenever a resource is requested WITH extension that's also available without an extension. See ExtensionAction

See Also:

Constant Field Values

FACES_VIEWS_PATH_ACTION_PARAM_NAME

public static final String FACES_VIEWS_PATH_ACTION_PARAM_NAME

The name of the init parameter (in web.xml) that determines the action that is performed whenever a resource is requested in a public path that has been used for scanning views by faces views. See PathAction

See Also:

Constant Field Values

FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME

public static final String FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME

The name of the init parameter (in web.xml) that determines the method used by FacesViews to invoke the FacesServlet. See FacesServletDispatchMethod.

See Also:

Constant Field Values

FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME

public static final String FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME

The name of the boolean init parameter (in web.xml) via which the user can set whether the FacesViewsForwardingFilter should match before declared filters (false) or after declared filters (true);

See Also:

Constant Field Values

FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME

public static final String FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME

The name of the boolean init parameter (in web.xml) via which the user can set whether the FacesViewsViewHandler should strip the extension from the parent view handler's outcome or construct the URL itself and only take the query parameters (if any) from the parent.

See Also:

Constant Field Values

SCAN_PATHS

public static final String SCAN_PATHS

The name of the application scope context parameter under which a Set version of the paths that are to be scanned by faces views are kept.

See Also:

Constant Field Values

PUBLIC_SCAN_PATHS

public static final String PUBLIC_SCAN_PATHS

The name of the application scope context parameter under which a Set version of the public paths that are to be scanned by faces views are kept. A public path is a path that is also directly accessible, e.g. is world readable. This excludes the special path /, which is by definition world readable but not included in this set.

See Also:

Constant Field Values

SCANNED_VIEWS_EXTENSIONLESS

public static final String SCANNED_VIEWS_EXTENSIONLESS

The name of the application scope context parameter under which a Boolean version of the scanned views always exensionless init parameter is kept.

See Also:

Constant Field Values

FACES_SERVLET_EXTENSIONS

public static final String FACES_SERVLET_EXTENSIONS

The name of the application scope context parameter under which a Set that stores the extensions to which the FacesServlet is mapped.

See Also:

Constant Field Values

FACES_VIEWS_RESOURCES

public static final String FACES_VIEWS_RESOURCES

See Also:

Constant Field Values

FACES_VIEWS_REVERSE_RESOURCES

public static final String FACES_VIEWS_REVERSE_RESOURCES

See Also:

Constant Field Values

FACES_VIEWS_RESOURCES_EXTENSIONS

public static final String FACES_VIEWS_RESOURCES_EXTENSIONS

See Also:

Constant Field Values

FACES_VIEWS_ORIGINAL_SERVLET_PATH

public static final String FACES_VIEWS_ORIGINAL_SERVLET_PATH

See Also:

Constant Field Values

Method Detail

scanViewsFromRootPaths

public static void scanViewsFromRootPaths(ServletContext servletContext,
                                          Map<String,String> collectedViews,
                                          Set<String> collectedExtensions)

getRootPaths

public static Set<String> getRootPaths(ServletContext servletContext)

getPublicRootPaths

public static Set<String> getPublicRootPaths(ServletContext servletContext)

normalizeRootPath

public static String normalizeRootPath(String rootPath)

isResourceInPublicPath

public static boolean isResourceInPublicPath(ServletContext servletContext,
                                             String resource)

getExtensionAction

public static ExtensionAction getExtensionAction(ServletContext servletContext)

getPathAction

public static PathAction getPathAction(ServletContext servletContext)

getFacesServletDispatchMethod

public static FacesServletDispatchMethod getFacesServletDispatchMethod(ServletContext servletContext)

getViewHandlerMode

public static ViewHandlerMode getViewHandlerMode(FacesContext context)

getViewHandlerMode

public static ViewHandlerMode getViewHandlerMode(ServletContext servletContext)

isFilterAfterDeclaredFilters

public static boolean isFilterAfterDeclaredFilters(ServletContext servletContext)

isScannedViewsAlwaysExtensionless

public static boolean isScannedViewsAlwaysExtensionless(FacesContext context)

scanViews

public static void scanViews(ServletContext servletContext,
                             String rootPath,
                             Set<String> resourcePaths,
                             Map<String,String> collectedViews,
                             String extensionToScan,
                             Set<String> collectedExtensions)

Scans resources (views) recursively starting with the given resource paths for a specific root path, and collects those and all unique extensions encountered in a flat map respectively set.

Parameters:

servletContext - The involved servlet context.

rootPath - one of the paths from which views are scanned. By default this is typically /WEB-INF/faces-view/

resourcePaths - collection of paths to be considered for scanning, can be either files or directories.

collectedViews - a mapping of all views encountered during scanning. Mapping will be from the simplified form to the actual location relatively to the web root. E.g key "foo", value "/WEB-INF/faces-view/foo.xhtml"

extensionToScan - a specific extension to scan for. Should start with a ., e.g. ".xhtml". If this is given, only resources with that extension will be scanned. If null, all resources will be scanned.

collectedExtensions - set in which all unique extensions will be collected. May be null, in which case no extensions will be collected

canScanDirectory

public static boolean canScanDirectory(String rootPath,
                                       String directory)

canScanResource

public static boolean canScanResource(String resource,
                                      String extensionToScan)

scanViews

public static Map<String,String> scanViews(ServletContext servletContext)

Scans resources (views) recursively starting with the given resource paths and returns a flat map containing all resources encountered.

Parameters:

servletContext - The involved servlet context.

Returns:

views

tryScanAndStoreViews

public static void tryScanAndStoreViews(ServletContext context)

Checks if resources haven't been scanned yet, and if not does scanning and stores the result at the designated location "org.omnifaces.facesviews" in the ServletContext.

Parameters:

context - The involved servlet context.

scanAndStoreViews

public static Map<String,String> scanAndStoreViews(ServletContext context)

Scans for faces-views resources and stores the result at the designated location "org.omnifaces.facesviews" in the ServletContext.

Parameters:

context - The involved servlet context.

Returns:

the view found during scanning, or the empty map if no views encountered

stripFacesViewsPrefix

public static String stripFacesViewsPrefix(String resource)

Strips the special 'faces-views' prefix path from the resource if any.

Parameters:

resource - The resource.

Returns:

the resource without the special prefix path, or as-is if it didn't start with this prefix.

getMappedPath

public static String getMappedPath(String path)

mapFacesServlet

public static void mapFacesServlet(ServletContext servletContext,
                                   Set<String> extensions)

Map the Facelets Servlet to the given extensions

Parameters:

servletContext - The involved servlet context.

extensions - collections of extensions (typically those as encountered during scanning)

getFacesServletExtensions

public static Set<String> getFacesServletExtensions(FacesContext context)

getFacesServletExtensions

public static Set<String> getFacesServletExtensions(ServletContext servletContext)

getExtensionlessURLWithQuery

public static String getExtensionlessURLWithQuery(HttpServletRequest request)

Obtains the full request URL from the given request complete with the query string, but with the extension (if any) cut out.

E.g. http://localhost/foo/bar.xhtml?kaz=1 becomes http://localhost/foo/bar?kaz=1

Parameters:

request - the request from the URL is obtained.

Returns:

request URL with query parameters but without file extension

getExtensionlessURLWithQuery

public static String getExtensionlessURLWithQuery(HttpServletRequest request,
                                                  String resource)

Obtains the full request URL from the given request and the given resource complete with the query string, but with the extension (if any) cut out.

E.g. http://localhost/foo/bar.xhtml?kaz=1 becomes http://localhost/foo/bar?kaz=1

Parameters:

request - the request from which the base URL is obtained.

resource - the resource relative to the base URL

Returns:

request URL with query parameters but without file extension