0
# Environment and Configuration
1

2
Core components for initializing and configuring Apache Shiro in web applications. These classes provide environment setup, filter configuration factories, and servlet integration for bootstrapping Shiro security in web containers.
3

4
## Capabilities
5

6
### Web Environment Management
7

8
The WebEnvironment interface and its implementations provide centralized management of Shiro components in web applications, including security managers, filter chains, and servlet context integration.
9

10
```java { .api }
11
interface WebEnvironment extends Environment {
12
    /**
13
     * Returns the FilterChainResolver used to resolve filter chains for incoming requests.
14
     *
15
     * @return the FilterChainResolver instance
16
     */
17
    FilterChainResolver getFilterChainResolver();
18
    
19
    /**
20
     * Returns the ServletContext associated with this web environment.
21
     *
22
     * @return the ServletContext instance
23
     */
24
    ServletContext getServletContext();
25
    
26
    /**
27
     * Returns the WebSecurityManager instance for this environment.
28
     *
29
     * @return the WebSecurityManager instance
30
     */
31
    WebSecurityManager getWebSecurityManager();
32
    
33
    /**
34
     * Returns the configuration for Shiro's filter, providing default implementation.
35
     *
36
     * @return the ShiroFilterConfiguration instance
37
     */
38
    default ShiroFilterConfiguration getShiroFilterConfiguration() {
39
        return new ShiroFilterConfiguration();
40
    }
41
}
42
```
43

44
```java { .api }
45
class DefaultWebEnvironment extends DefaultEnvironment implements MutableWebEnvironment {
46
    /**
47
     * Creates a new DefaultWebEnvironment instance.
48
     */
49
    public DefaultWebEnvironment();
50
    
51
    /**
52
     * Returns the ServletContext associated with this environment.
53
     *
54
     * @return the ServletContext instance
55
     */
56
    public ServletContext getServletContext();
57
    
58
    /**
59
     * Sets the ServletContext for this environment.
60
     *
61
     * @param servletContext the ServletContext to set
62
     */
63
    public void setServletContext(ServletContext servletContext);
64
    
65
    /**
66
     * Returns the WebSecurityManager for this environment.
67
     *
68
     * @return the WebSecurityManager instance
69
     */
70
    public WebSecurityManager getWebSecurityManager();
71
    
72
    /**
73
     * Sets the WebSecurityManager for this environment.
74
     *
75
     * @param webSecurityManager the WebSecurityManager to set
76
     */
77
    public void setWebSecurityManager(WebSecurityManager webSecurityManager);
78
}
79
```
80

81
```java { .api }
82
interface MutableWebEnvironment extends WebEnvironment {
83
    /**
84
     * Sets the FilterChainResolver for this environment.
85
     *
86
     * @param filterChainResolver the FilterChainResolver to set
87
     */
88
    void setFilterChainResolver(FilterChainResolver filterChainResolver);
89
    
90
    /**
91
     * Sets the ServletContext for this environment.
92
     *
93
     * @param servletContext the ServletContext to set
94
     */
95
    void setServletContext(ServletContext servletContext);
96
    
97
    /**
98
     * Sets the WebSecurityManager for this environment.
99
     *
100
     * @param webSecurityManager the WebSecurityManager to set
101
     */
102
    void setWebSecurityManager(WebSecurityManager webSecurityManager);
103
}
104
```
105

106
### Environment Initialization
107

108
Classes for bootstrapping Shiro environments in web applications through servlet context management and lifecycle handling.
109

110
```java { .api }
111
class EnvironmentLoader {
112
    /** ServletContext attribute key for storing the WebEnvironment instance */
113
    public static final String ENVIRONMENT_ATTRIBUTE_KEY = "shiroEnvironment";
114
    
115
    /** ServletContext init parameter name for specifying custom environment class */
116
    public static final String ENVIRONMENT_CLASS_PARAM = "shiroEnvironmentClass";
117
    
118
    /** ServletContext init parameter name for specifying custom configuration locations */
119
    public static final String CONFIG_LOCATIONS_PARAM = "shiroConfigLocations";
120
    
121
    /**
122
     * Initializes Shiro environment in the given ServletContext.
123
     *
124
     * @param servletContext the ServletContext to initialize
125
     * @return the created WebEnvironment instance
126
     */
127
    public WebEnvironment initEnvironment(ServletContext servletContext) throws IllegalStateException;
128
    
129
    /**
130
     * Destroys the Shiro environment in the given ServletContext.
131
     *
132
     * @param servletContext the ServletContext to clean up
133
     */
134
    public void destroyEnvironment(ServletContext servletContext);
135
    
136
    /**
137
     * Hook for customizing the WebEnvironment after creation but before use.
138
     *
139
     * @param environment the WebEnvironment to customize
140
     */
141
    protected void customizeEnvironment(WebEnvironment environment);
142
    
143
    /**
144
     * Creates a WebEnvironment instance based on ServletContext configuration.
145
     *
146
     * @param sc the ServletContext
147
     * @return the created WebEnvironment instance
148
     */
149
    protected WebEnvironment createEnvironment(ServletContext sc);
150
}
151
```
152

153
```java { .api }
154
class EnvironmentLoaderListener extends EnvironmentLoader implements ServletContextListener {
155
    /**
156
     * Initializes the Shiro environment when the web application starts.
157
     *
158
     * @param sce the ServletContextEvent
159
     */
160
    public void contextInitialized(ServletContextEvent sce);
161
    
162
    /**
163
     * Destroys the Shiro environment when the web application shuts down.
164
     *
165
     * @param sce the ServletContextEvent
166
     */
167
    public void contextDestroyed(ServletContextEvent sce);
168
}
169
```
170

171
### Resource-Based Environments
172

173
Environment implementations that load configuration from external resources like INI files or other configuration formats.
174

175
```java { .api }
176
abstract class ResourceBasedWebEnvironment extends DefaultWebEnvironment {
177
    /** Default configuration resource locations to search */
178
    public static final String DEFAULT_WEB_INI_RESOURCE_PATH = "/WEB-INF/shiro.ini";
179
    
180
    /**
181
     * Creates a new ResourceBasedWebEnvironment.
182
     */
183
    public ResourceBasedWebEnvironment();
184
    
185
    /**
186
     * Returns the configuration resource locations.
187
     *
188
     * @return array of resource location strings
189
     */
190
    public String[] getConfigLocations();
191
    
192
    /**
193
     * Sets the configuration resource locations.
194
     *
195
     * @param configLocations array of resource location strings
196
     */
197
    public void setConfigLocations(String[] configLocations);
198
    
199
    /**
200
     * Initializes the environment by loading configuration from resources.
201
     */
202
    public void init();
203
    
204
    /**
205
     * Creates objects from the loaded configuration.
206
     *
207
     * @return a Map of created objects
208
     */
209
    protected abstract Map<String, Object> getObjects();
210
}
211
```
212

213
```java { .api }
214
class IniWebEnvironment extends ResourceBasedWebEnvironment {
215
    /** Default INI configuration resource path */
216
    public static final String DEFAULT_WEB_INI_RESOURCE_PATH = "/WEB-INF/shiro.ini";
217
    
218
    /**
219
     * Creates a new IniWebEnvironment that loads configuration from INI resources.
220
     */
221
    public IniWebEnvironment();
222
    
223
    /**
224
     * Returns the loaded INI configuration.
225
     *
226
     * @return the Ini instance
227
     */
228
    public Ini getIni();
229
    
230
    /**
231
     * Sets the INI configuration.
232
     *
233
     * @param ini the Ini instance to set
234
     */
235
    public void setIni(Ini ini);
236
    
237
    /**
238
     * Creates objects from the INI configuration.
239
     *
240
     * @return a Map of created objects from the INI
241
     */
242
    protected Map<String, Object> getObjects();
243
}
244
```
245

246
### Configuration Factories
247

248
Factory classes for creating Shiro components from various configuration sources like INI files.
249

250
```java { .api }
251
class IniFilterChainResolverFactory extends IniFactorySupport<FilterChainResolver> {
252
    /**
253
     * Creates a new IniFilterChainResolverFactory.
254
     */
255
    public IniFilterChainResolverFactory();
256
    
257
    /**
258
     * Returns the FilterConfig used for filter initialization.
259
     *
260
     * @return the FilterConfig instance
261
     */
262
    public FilterConfig getFilterConfig();
263
    
264
    /**
265
     * Sets the FilterConfig for filter initialization.
266
     *
267
     * @param filterConfig the FilterConfig to set
268
     */
269
    public void setFilterConfig(FilterConfig filterConfig);
270
    
271
    /**
272
     * Returns the global filters applied to all chains.
273
     *
274
     * @return List of global filter names
275
     */
276
    public List<String> getGlobalFilters();
277
    
278
    /**
279
     * Sets the global filters applied to all chains.
280
     *
281
     * @param globalFilters List of global filter names
282
     */
283
    public void setGlobalFilters(List<String> globalFilters);
284
    
285
    /**
286
     * Creates a FilterChainResolver instance from the given INI configuration.
287
     *
288
     * @param ini the INI configuration
289
     * @return the created FilterChainResolver
290
     */
291
    protected FilterChainResolver createInstance(Ini ini);
292
    
293
    /**
294
     * Creates default filter instances for the resolver.
295
     *
296
     * @return Map of filter name to Filter instance
297
     */
298
    protected Map<String, Filter> createDefaultFilterMap();
299
}
300
```
301

302
```java { .api }
303
@Deprecated
304
class WebIniSecurityManagerFactory extends IniSecurityManagerFactory {
305
    /**
306
     * Creates a new WebIniSecurityManagerFactory using default web INI resource.
307
     */
308
    public WebIniSecurityManagerFactory();
309
    
310
    /**
311
     * Creates a new WebIniSecurityManagerFactory with the specified INI resource path.
312
     *
313
     * @param iniResourcePath the INI resource path
314
     */
315
    public WebIniSecurityManagerFactory(String iniResourcePath);
316
    
317
    /**
318
     * Creates a new WebIniSecurityManagerFactory with the given INI instance.
319
     *
320
     * @param ini the INI instance
321
     */
322
    public WebIniSecurityManagerFactory(Ini ini);
323
    
324
    /**
325
     * Creates a default SecurityManager instance suitable for web applications.
326
     *
327
     * @return DefaultWebSecurityManager instance
328
     */
329
    protected SecurityManager createDefaultInstance();
330
}
331
```
332

333
### Filter Configuration
334

335
Configuration classes for Shiro's servlet filter behavior and processing options.
336

337
```java { .api }
338
class ShiroFilterConfiguration {
339
    /** Default value for filterOncePerRequest */
340
    public static final boolean DEFAULT_FILTER_ONCE_PER_REQUEST = true;
341
    
342
    /** Default value for staticSecurityManagerEnabled */
343
    public static final boolean DEFAULT_STATIC_SECURITY_MANAGER_ENABLED = false;
344
    
345
    /**
346
     * Creates a new ShiroFilterConfiguration with default settings.
347
     */
348
    public ShiroFilterConfiguration();
349
    
350
    /**
351
     * Returns whether the filter should execute only once per request.
352
     *
353
     * @return true if filter executes once per request
354
     */
355
    public boolean isFilterOncePerRequest();
356
    
357
    /**
358
     * Sets whether the filter should execute only once per request.
359
     *
360
     * @param filterOncePerRequest true to execute once per request
361
     */
362
    public void setFilterOncePerRequest(boolean filterOncePerRequest);
363
    
364
    /**
365
     * Returns whether static SecurityManager access is enabled.
366
     *
367
     * @return true if static SecurityManager is enabled
368
     */
369
    public boolean isStaticSecurityManagerEnabled();
370
    
371
    /**
372
     * Sets whether static SecurityManager access is enabled.
373
     *
374
     * @param staticSecurityManagerEnabled true to enable static SecurityManager
375
     */
376
    public void setStaticSecurityManagerEnabled(boolean staticSecurityManagerEnabled);
377
}
378
```
379

380
## Usage Examples
381

382
### Basic Web Application Setup
383

384
```java
385
// web.xml configuration
386
/*
387
<context-param>
388
    <param-name>shiroConfigLocations</param-name>
389
    <param-value>/WEB-INF/shiro.ini</param-value>
390
</context-param>
391

392
<listener>
393
    <listener-class>
394
        org.apache.shiro.web.env.EnvironmentLoaderListener
395
    </listener-class>
396
</listener>
397
*/
398

399
// Programmatic environment setup
400
public class ShiroEnvironmentConfig {
401
    public void initializeShiro(ServletContext servletContext) {
402
        EnvironmentLoader loader = new EnvironmentLoader();
403
        WebEnvironment environment = loader.initEnvironment(servletContext);
404
        
405
        // Environment is now available in ServletContext
406
        WebEnvironment env = (WebEnvironment) servletContext.getAttribute(
407
            EnvironmentLoader.ENVIRONMENT_ATTRIBUTE_KEY);
408
    }
409
}
410
```
411

412
### Custom Environment Configuration
413

414
```java
415
public class CustomWebEnvironment extends DefaultWebEnvironment {
416
    @Override
417
    public void init() {
418
        super.init();
419
        
420
        // Custom initialization logic
421
        DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager();
422
        setWebSecurityManager(securityManager);
423
        
424
        // Custom filter chain configuration
425
        PathMatchingFilterChainResolver chainResolver = new PathMatchingFilterChainResolver();
426
        setFilterChainResolver(chainResolver);
427
    }
428
}
429

430
// Register custom environment class
431
/*
432
<context-param>
433
    <param-name>shiroEnvironmentClass</param-name>
434
    <param-value>com.example.CustomWebEnvironment</param-value>
435
</context-param>
436
*/
437
```
438

439
### INI-Based Configuration
440

441
```java
442
// shiro.ini configuration file content example:
443
/*
444
[main]
445
# Configure security manager
446
securityManager = org.apache.shiro.web.mgt.DefaultWebSecurityManager
447

448
# Configure realm
449
myRealm = com.example.MyCustomRealm
450
securityManager.realms = $myRealm
451

452
# Configure session manager
453
sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
454
securityManager.sessionManager = $sessionManager
455

456
[urls]
457
/login = authc
458
/admin/** = authc, roles[admin]
459
/user/** = authc
460
/** = anon
461
*/
462

463
public void createFromIni() {
464
    Ini ini = Ini.fromResourcePath("/WEB-INF/shiro.ini");
465
    IniWebEnvironment environment = new IniWebEnvironment();
466
    environment.setIni(ini);
467
    environment.init();
468
}
469
```