/
WebXml.java
168 lines (151 loc) · 6.92 KB
/
WebXml.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/*
* Copyright OmniFaces
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
* an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
*/
package org.omnifaces.config;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.omnifaces.cdi.config.WebXmlProducer;
/**
* <p>
* This configuration interface parses the <code>/WEB-INF/web.xml</code> and all <code>/META-INF/web-fragment</code> files
* found in the classpath and offers methods to obtain information from them which is not available by the standard
* Servlet API.
*
* <h2>Usage</h2>
* <p>
* Some examples:
* <pre>
* // 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();
* </pre>
* <pre>
* // 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();
* </pre>
* <pre>
* // Get the <form-login-page> (which is a context-relative URL to the login page of FORM based authentication).
* String formLoginPage = WebXml.instance().getFormLoginPage();
* </pre>
* <pre>
* // Get a mapping of all <security-constraint> URL patterns and associated roles.
* Map<String, Set<String>> securityConstraints = WebXml.instance().getSecurityConstraints();
* </pre>
* <pre>
* // 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");
* </pre>
* <pre>
* // Get web.xml configured session timeout (in minutes).
* int sessionTimeout = WebXml.instance().getSessionTimeout();
* </pre>
* <p>
* Since OmniFaces 3.1, you can if necessary even inject it.
* <pre>
* @Inject
* private WebXml webXml;
* </pre>
*
* @author Bauke Scholtz
* @since 1.2
* @see WebXmlSingleton
* @see WebXmlProducer
*/
public interface WebXml {
// Enum singleton -------------------------------------------------------------------------------------------------
/**
* Returns the lazily loaded enum singleton instance.
* @return The lazily loaded enum singleton instance.
* @since 3.1
*/
static WebXml instance() {
return WebXmlSingleton.INSTANCE;
}
// Actions --------------------------------------------------------------------------------------------------------
/**
* Find for the given exception the right error page location. Exception types are matched as per Servlet 3.0
* specification 10.9.2 with the exception that the given exception is already unwrapped:
* <ul>
* <li>Make a pass through all specific exception types. If a match is found in the exception class hierarchy,
* use its location. The closest match in the class hierarchy wins.
* <li>Else use the default error page location, which can be either the java.lang.Throwable or HTTP 500 or
* default one.
* </ul>
* @param exception The exception to find the error page location for.
* @return The right error page location for the given exception.
*/
String findErrorPageLocation(Throwable exception);
/**
* Returns <code>true</code> if access to the given URL is allowed for the given role. URL patterns are matched as
* per Servlet 3.0 specification 12.1:
* <ul>
* <li>Make a first pass through all URL patterns. If an exact match is found, then check the role on it.
* <li>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.
* <li>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.
* <li>Else assume it as unprotected resource and return <code>true</code>.
* </ul>
* @param url URL to be checked for access by the given role. It must start with '/' and be context-relative.
* @param role Role to be checked for access to the given URL.
* @return <code>true</code> if access to the given URL is allowed for the given role, otherwise <code>false</code>.
* @throws NullPointerException If given URL is null.
* @throws IllegalArgumentException If given URL does not start with '/'.
* @since 1.4
*/
boolean isAccessAllowed(String url, String role);
// Getters --------------------------------------------------------------------------------------------------------
/**
* Returns a list of all welcome files.
* @return A list of all welcome files.
* @since 1.4
*/
List<String> getWelcomeFiles();
/**
* Returns a mapping of all error page locations by exception type. The default location is identified by
* <code>null</code> key.
* @return A mapping of all error page locations by exception type.
*/
Map<Class<Throwable>, String> getErrorPageLocations();
/**
* Returns the location of the FORM authentication login page, or <code>null</code> if it is not defined.
* @return The location of the FORM authentication login page, or <code>null</code> if it is not defined.
*/
String getFormLoginPage();
/**
* Returns the location of the FORM authentication error page, or <code>null</code> if it is not defined.
* @return The location of the FORM authentication error page, or <code>null</code> if it is not defined.
* @since 1.8
*/
String getFormErrorPage();
/**
* Returns a mapping of all security constraint URL patterns and the associated roles in the declared order. If the
* roles is <code>null</code>, 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).
* @return A mapping of all security constraint URL patterns and the associated roles in the declared order.
* @since 1.4
*/
Map<String, Set<String>> getSecurityConstraints();
/**
* Returns the configured session timeout in minutes, or <code>-1</code> if it is not defined.
* @return The configured session timeout in minutes, or <code>-1</code> if it is not defined.
* @since 1.7
*/
int getSessionTimeout();
/**
* Returns whether the distributable flag is set in root <code>web.xml</code>.
* @return Whether the distributable flag is set in root <code>web.xml</code>.
* @since 3.9
*/
boolean isDistributable();
}