org.apache.shiro.web.env

Class EnvironmentLoader

java.lang.Object

org.apache.shiro.web.env.EnvironmentLoader

Direct Known Subclasses:

EnvironmentLoaderListener

public class EnvironmentLoader
extends Object

An EnvironmentLoader is responsible for loading a web application's Shiro WebEnvironment (which includes the web app's WebSecurityManager) into the ServletContext at application startup.

In Shiro 1.1 and earlier, the Shiro ServletFilter was responsible for creating the WebSecurityManager and any additional objects (security filters, etc). However, any component not filtered by the Shiro Filter (such as other context listeners) was not able to easily acquire the these objects to perform security operations.

Due to this, in Shiro 1.2 and later, this EnvironmentLoader (or more likely, the EnvironmentLoaderListener subclass) is the preferred mechanism to initialize a Shiro environment. The Shiro Filter, while still required for request filtering, will not perform this initialization at startup if the EnvironmentLoader (or listener) runs first.

Usage

This implementation will look for two servlet context context-params in web.xml: shiroEnvironmentClass and shiroConfigLocations that customize how the WebEnvironment instance will be initialized.

shiroEnvironmentClass

The shiroEnvironmentClass context-param, if it exists, allows you to specify the fully-qualified implementation class name of the WebEnvironment to instantiate. For example:

 <context-param>
     <param-name>shiroEnvironmentClass</param-name>
     <param-value>com.foo.bar.shiro.MyWebEnvironment</param-value>
 </context-param>
 

If not specified, the default value is the IniWebEnvironment class, which assumes Shiro's default INI configuration format

shiroConfigLocations

The shiroConfigLocations context-param, if it exists, allows you to specify the config location(s) (resource path(s)) that will be relayed to the instantiated WebEnvironment. For example:

 <context-param>
     <param-name>shiroConfigLocations</param-name>
     <param-value>/WEB-INF/someLocation/shiro.ini</param-value>
 </context-param>
 

The WebEnvironment implementation must implement the ResourceConfigurable interface if it is to acquire the shiroConfigLocations value.

If this context-param is not specified, the WebEnvironment instance determines default resource lookup behavior. For example, the IniWebEnvironment will check the following two locations for INI config by default (in order):

1. /WEB-INF/shiro.ini
2. classpath:shiro.ini

Web Security Enforcement

Using this loader will only initialize Shiro's environment in a web application - it will not filter web requests or perform web-specific security operations. To do this, you must ensure that you have also configured the ShiroFilter in web.xml.

Finally, it should be noted that this implementation was based on ideas in Spring 3's org.springframework.web.context.ContextLoader implementation - no need to reinvent the wheel for this common behavior.

Since:

1.2

See Also:

EnvironmentLoaderListener, ShiroFilter

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONFIG_LOCATIONS_PARAM Servlet Context config param for the resource path to use for configuring the WebEnvironment instance: shiroConfigLocations
static String	ENVIRONMENT_ATTRIBUTE_KEY
static String	ENVIRONMENT_CLASS_PARAM Servlet Context config param for specifying the WebEnvironment implementation class to use: shiroEnvironmentClass

Constructor Summary

Constructors

Constructor and Description
EnvironmentLoader()

Method Summary

Modifier and Type	Method and Description
protected WebEnvironment	createEnvironment(javax.servlet.ServletContext sc) Instantiates a WebEnvironment based on the specified ServletContext.
protected void	customizeEnvironment(WebEnvironment environment) Any additional customization of the Environment can be by overriding this method.
void	destroyEnvironment(javax.servlet.ServletContext servletContext) Destroys the WebEnvironment for the given servlet context.
protected WebEnvironment	determineWebEnvironment(javax.servlet.ServletContext servletContext) Return the WebEnvironment implementation class to use, based on the order of: A custom WebEnvironment class - specified in the servletContext ENVIRONMENT_ATTRIBUTE_KEY property ServiceLoader.load(WebEnvironment.class) - (if more then one instance is found a ConfigurationException will be thrown A call to getDefaultWebEnvironmentClass() (default: IniWebEnvironment)
protected Class<?>	determineWebEnvironmentClass(javax.servlet.ServletContext servletContext) Deprecated. This method is not longer used by Shiro, and will be removed in future versions, use determineWebEnvironment(ServletContext) or determineWebEnvironment(ServletContext)
protected void	finalizeEnvironment(WebEnvironment environment) Any additional cleanup of the Environment can be done by overriding this method.
protected Class<? extends WebEnvironment>	getDefaultWebEnvironmentClass() Returns the default WebEnvironment class, which is unless overridden: IniWebEnvironment.
WebEnvironment	initEnvironment(javax.servlet.ServletContext servletContext) Initializes Shiro's WebEnvironment instance for the specified ServletContext based on the CONFIG_LOCATIONS_PARAM value.

Methods inherited from class java.lang.Object

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

Field Detail

ENVIRONMENT_CLASS_PARAM

public static final String ENVIRONMENT_CLASS_PARAM

Servlet Context config param for specifying the WebEnvironment implementation class to use: shiroEnvironmentClass

See Also:

Constant Field Values

CONFIG_LOCATIONS_PARAM

public static final String CONFIG_LOCATIONS_PARAM

Servlet Context config param for the resource path to use for configuring the WebEnvironment instance: shiroConfigLocations

See Also:

Constant Field Values

ENVIRONMENT_ATTRIBUTE_KEY

public static final String ENVIRONMENT_ATTRIBUTE_KEY

Constructor Detail

EnvironmentLoader

public EnvironmentLoader()

Method Detail

initEnvironment

public WebEnvironment initEnvironment(javax.servlet.ServletContext servletContext)
                               throws IllegalStateException

Initializes Shiro's WebEnvironment instance for the specified ServletContext based on the CONFIG_LOCATIONS_PARAM value.

Parameters:

servletContext - current servlet context

Returns:

the new Shiro WebEnvironment instance.

Throws:

IllegalStateException - if an existing WebEnvironment has already been initialized and associated with the specified ServletContext.

determineWebEnvironmentClass

@Deprecated
protected Class<?> determineWebEnvironmentClass(javax.servlet.ServletContext servletContext)

Deprecated. This method is not longer used by Shiro, and will be removed in future versions, use determineWebEnvironment(ServletContext) or determineWebEnvironment(ServletContext)

Return the WebEnvironment implementation class to use, either the default IniWebEnvironment or a custom class if specified.

Parameters:

servletContext - current servlet context

Returns:

the WebEnvironment implementation class to use

See Also:

ENVIRONMENT_CLASS_PARAM, IniWebEnvironment, determineWebEnvironment(ServletContext), getDefaultWebEnvironmentClass()

getDefaultWebEnvironmentClass

protected Class<? extends WebEnvironment> getDefaultWebEnvironmentClass()

Returns the default WebEnvironment class, which is unless overridden: IniWebEnvironment.

Returns:

the default WebEnvironment class.

determineWebEnvironment

protected WebEnvironment determineWebEnvironment(javax.servlet.ServletContext servletContext)

Return the WebEnvironment implementation class to use, based on the order of:

• A custom WebEnvironment class - specified in the servletContext ENVIRONMENT_ATTRIBUTE_KEY property
• ServiceLoader.load(WebEnvironment.class) - (if more then one instance is found a ConfigurationException will be thrown
• A call to getDefaultWebEnvironmentClass() (default: IniWebEnvironment)

Parameters:

servletContext - current servlet context

servletContext - the servletContext to query the ENVIRONMENT_ATTRIBUTE_KEY property from

Returns:

the WebEnvironment implementation class to use

See Also:

ENVIRONMENT_CLASS_PARAM

createEnvironment

protected WebEnvironment createEnvironment(javax.servlet.ServletContext sc)

Instantiates a WebEnvironment based on the specified ServletContext.

This implementation determines a WebEnvironment implementation class to use. That class is instantiated, configured, and returned.

This allows custom WebEnvironment implementations to be specified via a ServletContext init-param if desired. If not specified, the default IniWebEnvironment implementation will be used.

Parameters:

sc - current servlet context

Returns:

the constructed Shiro WebEnvironment instance

See Also:

MutableWebEnvironment, ResourceConfigurable

customizeEnvironment

protected void customizeEnvironment(WebEnvironment environment)

Any additional customization of the Environment can be by overriding this method. For example setup shared resources, etc. By default this method does nothing.

Parameters:

environment -

destroyEnvironment

public void destroyEnvironment(javax.servlet.ServletContext servletContext)

Destroys the WebEnvironment for the given servlet context.

Parameters:

servletContext - the ServletContext attributed to the WebSecurityManager

finalizeEnvironment

protected void finalizeEnvironment(WebEnvironment environment)

Any additional cleanup of the Environment can be done by overriding this method. For example clean up shared resources, etc. By default this method does nothing.

Parameters:

environment -

Since:

1.3