FacesViews (OmniFaces 2.0-SNAPSHOT API)

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, FacesViewsViewHandlerInstaller, 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

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addMappings(ServletContext servletContext)` This will map the `FacesServlet` to extensions found during scanning in `ApplicationInitializer`.
`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`	`isFacesViewsActive(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 void`	`registerFilter(ServletContext servletContext)` This will register the `FacesViewsForwardingFilter`.
`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 void`	`setViewHander(ServletContext servletContext)` Register a view handler that transforms a view id with extension back to an extensionless one.
`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
  - registerFilter
```
public static void registerFilter(ServletContext servletContext)
```
    This will register the FacesViewsForwardingFilter.
    
    Parameters:
    
    servletContext - The involved servlet context.
  - addMappings
```
public static void addMappings(ServletContext servletContext)
```
    This will map the FacesServlet to extensions found during scanning in ApplicationInitializer. This part of the initialization is executed via ApplicationListener, because the FacesServlet has to be available.
    
    Parameters:
    
    servletContext - The involved servlet context.
  - setViewHander
```
public static void setViewHander(ServletContext servletContext)
```
    Register a view handler that transforms a view id with extension back to an extensionless one.
    
    Parameters:
    
    servletContext - The involved servlet context.
  - isFacesViewsActive
```
public static boolean isFacesViewsActive(ServletContext servletContext)
```
  - 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

Class FacesViews

Installation

PrettyFaces

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

WEB_INF_VIEWS

FACES_VIEWS_ENABLED_PARAM_NAME

FACES_VIEWS_SCAN_PATHS_PARAM_NAME

FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME

FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME

FACES_VIEWS_PATH_ACTION_PARAM_NAME

FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME

FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME

FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME

SCAN_PATHS

PUBLIC_SCAN_PATHS

SCANNED_VIEWS_EXTENSIONLESS

FACES_SERVLET_EXTENSIONS

FACES_VIEWS_RESOURCES

FACES_VIEWS_REVERSE_RESOURCES

FACES_VIEWS_RESOURCES_EXTENSIONS

FACES_VIEWS_ORIGINAL_SERVLET_PATH

Method Detail

registerFilter

addMappings

setViewHander

isFacesViewsActive

scanViewsFromRootPaths

getRootPaths

getPublicRootPaths

normalizeRootPath

isResourceInPublicPath

getExtensionAction

getPathAction

getFacesServletDispatchMethod

getViewHandlerMode

getViewHandlerMode

isFilterAfterDeclaredFilters

isScannedViewsAlwaysExtensionless

scanViews

canScanDirectory

canScanResource

scanViews

tryScanAndStoreViews

scanAndStoreViews

stripFacesViewsPrefix

getMappedPath

mapFacesServlet

getFacesServletExtensions

getFacesServletExtensions

getExtensionlessURLWithQuery

getExtensionlessURLWithQuery