WebXml (OmniFaces 2.0-SNAPSHOT API)

java.lang.Object
- java.lang.Enum<WebXml>
- - org.omnifaces.config.WebXml

All Implemented Interfaces:: Serializable, Comparable<WebXml>

public enum WebXml
extends Enum<WebXml>

This configuration enum parses the /WEB-INF/web.xml and all /META-INF/web-fragment files found in the classpath and offers methods to obtain information from them which is not available by the standard Servlet API.

Usage

Some examples:

 // Get the <welcome-file-list> (which are essentially path-relative filenames which needs to be served when a folder is requested).
 List<String> welcomeFiles = WebXml.INSTANCE.getWelcomeFiles();

 // Get a mapping of all error page locations by exception type (a key of null represents the default error page location, if any).
 Map<Class<Throwable>, String> errorPageLocations = WebXml.INSTANCE.getErrorPageLocations();

 // Get the <form-login-page> (which is a context-relative URL to the login page of FORM based authentication).
 String formLoginPage = WebXml.INSTANCE.getFormLoginPage();

 // Get a mapping of all <security-constraint> URL patterns and associated roles.
 Map<String, Set<String>> securityConstraints = WebXml.INSTANCE.getSecurityConstraints();

 // Check if access to certain (context-relative) URL is allowed for the given role based on <security-constraint>.
 boolean accessAllowed = WebXml.INSTANCE.isAccessAllowed("/admin.xhtml", "admin");

 // Get web.xml configured session timeout (in seconds).
 int sessionTimeout = WebXml.INSTANCE.getSessionTimeout();

Since:: 1.2
Author:: Bauke Scholtz

Enum Constant Summary

Enum Constants
Enum Constant and Description

INSTANCE
Returns the lazily loaded enum singleton instance.

Enum Constants
Enum Constant and Description
`INSTANCE` Returns the lazily loaded enum singleton instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`String`	`findErrorPageLocation(Throwable exception)` Find for the given exception the right error page location.
`Map<Class<Throwable>,String>`	`getErrorPageLocations()` Returns a mapping of all error page locations by exception type.
`String`	`getFormErrorPage()` Returns the location of the FORM authentication error page, or `null` if it is not defined.
`String`	`getFormLoginPage()` Returns the location of the FORM authentication login page, or `null` if it is not defined.
`Map<String,Set<String>>`	`getSecurityConstraints()` Returns a mapping of all security constraint URL patterns and the associated roles in the declared order.
`int`	`getSessionTimeout()` Returns the configured session timeout in minutes, or `-1` if it is not defined.
`List<String>`	`getWelcomeFiles()` Returns a list of all welcome files.
`WebXml`	`init(ServletContext servletContext)` Perform manual initialization with the given servlet context, if not null and not already initialized yet.
`boolean`	`isAccessAllowed(String url, String role)` Returns `true` if access to the given URL is allowed for the given role.
`static WebXml`	`valueOf(String name)` Returns the enum constant of this type with the specified name.
`static WebXml[]`	`values()` Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Enum Constant Detail
  - INSTANCE
```
public static final WebXml INSTANCE
```
    Returns the lazily loaded enum singleton instance.
    Note: if this is needed in e.g. a Filter which is called before the FacesServlet is invoked, then it won't work if the INSTANCE hasn't been referenced before. Since JSF installs a special "init" FacesContext during startup, one option for doing this initial referencing is in a ServletContextListener. The data this enum encapsulates will then be available even where there is no FacesContext available. If there's no other option, then you need to manually invoke init(ServletContext) whereby you pass the desired ServletContext.
- Method Detail
  - values
```
public static WebXml[] values()
```
    Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
```
for (WebXml c : WebXml.values())
    System.out.println(c);
```
    Returns:
    
    an array containing the constants of this enum type, in the order they are declared
  - valueOf
```
public static WebXml valueOf(String name)
```
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
    
    Parameters:
    
    name - the name of the enum constant to be returned.
    
    Returns:
    
    the enum constant with the specified name
    
    Throws:
    
    IllegalArgumentException - if this enum type has no constant with the specified name
    
    NullPointerException - if the argument is null
  - init
```
public WebXml init(ServletContext servletContext)
```
    Perform manual initialization with the given servlet context, if not null and not already initialized yet.
    
    Parameters:
    
    servletContext - The servlet context to obtain the web.xml from.
    
    Returns:
    
    The current WebXml instance, initialized and all.
  - findErrorPageLocation
```
public String findErrorPageLocation(Throwable exception)
```
    Find for the given exception the right error page location. Exception types are matched as per Servlet 3.0 specification 10.9.2:
    - Make a first pass through all specific exception types. If an exact match is found, use its location.
    - Else make a second pass through all specific exception types in the order as they are declared in web.xml. If the current exception is an instance of it, then use its location.
    - Else use the default error page location, which can be either the java.lang.Throwable or HTTP 500 or default one.
    Parameters:
    
    exception - The exception to find the error page location for.
    
    Returns:
    
    The right error page location for the given exception.
  - isAccessAllowed
```
public boolean isAccessAllowed(String url,
                               String role)
```
    Returns true if access to the given URL is allowed for the given role. URL patterns are matched as per Servlet 3.0 specification 12.1:
    - Make a first pass through all URL patterns. If an exact match is found, then check the role on it.
    - Else make a recursive pass through all prefix URL patterns, stepping down the URL one directory at a time, trying to find the longest path match. If it is found, then check the role on it.
    - Else if the last segment in the URL path contains an extension, then make a last pass through all suffix URL patterns. If a match is found, then check the role on it.
    - Else assume it as unprotected resource and return true.
    Parameters:
    
    url - URL to be checked for access by the given role. It must start with '/' and be context-relative.
    
    role - Role to be checked for access to the given URL.
    
    Returns:
    
    true if access to the given URL is allowed for the given role, otherwise false.
    
    Throws:
    
    NullPointerException - If given URL is null.
    
    IllegalArgumentException - If given URL does not start with '/'.
    
    Since:
    
    1.4
  - getWelcomeFiles
```
public List<String> getWelcomeFiles()
```
    Returns a list of all welcome files.
    
    Returns:
    
    A list of all welcome files.
    
    Since:
    
    1.4
  - getErrorPageLocations
```
public Map<Class<Throwable>,String> getErrorPageLocations()
```
    Returns a mapping of all error page locations by exception type. The default location is identified by null key.
    
    Returns:
    
    A mapping of all error page locations by exception type.
  - getFormLoginPage
```
public String getFormLoginPage()
```
    Returns the location of the FORM authentication login page, or null if it is not defined.
    
    Returns:
    
    The location of the FORM authentication login page, or null if it is not defined.
  - getFormErrorPage
```
public String getFormErrorPage()
```
    Returns the location of the FORM authentication error page, or null if it is not defined.
    
    Returns:
    
    The location of the FORM authentication error page, or null if it is not defined.
    
    Since:
    
    1.8
  - getSecurityConstraints
```
public Map<String,Set<String>> getSecurityConstraints()
```
    Returns a mapping of all security constraint URL patterns and the associated roles in the declared order. If the roles is null, then it means that no auth constraint is been set (i.e. the resource is publicly accessible). If the roles is empty, then it means that an empty auth constraint is been set (i.e. the resource is in no way accessible).
    
    Returns:
    
    A mapping of all security constraint URL patterns and the associated roles in the declared order.
    
    Since:
    
    1.4
  - getSessionTimeout
```
public int getSessionTimeout()
```
    Returns the configured session timeout in minutes, or -1 if it is not defined.
    
    Returns:
    
    The configured session timeout in minutes, or -1 if it is not defined.
    
    Since:
    
    1.7

Enum WebXml

Usage

Enum Constant Summary

Method Summary

Methods inherited from class java.lang.Enum

Methods inherited from class java.lang.Object

Enum Constant Detail

INSTANCE

Method Detail

values

valueOf

init

findErrorPageLocation

isAccessAllowed

getWelcomeFiles

getErrorPageLocations

getFormLoginPage

getFormErrorPage

getSecurityConstraints

getSessionTimeout