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

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

EnvironmentLoader()

Method Summary

protected WebEnvironment	createEnvironment(javax.servlet.ServletContext sc) Instantiates a WebEnvironment based on the specified ServletContext.
protected void	customizeEnvironment(WebEnvironment environment)
void	destroyEnvironment(javax.servlet.ServletContext servletContext) Destroys the WebEnvironment for the given servlet context.
protected Class<?>	determineWebEnvironmentClass(javax.servlet.ServletContext servletContext) Return the WebEnvironment implementation class to use, either the default IniWebEnvironment or a custom class if specified.
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

protected Class<?> determineWebEnvironmentClass(javax.servlet.ServletContext 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

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)

destroyEnvironment

public void destroyEnvironment(javax.servlet.ServletContext servletContext)

Destroys the WebEnvironment for the given servlet context.

Parameters:

servletContext - the ServletContext attributed to the WebSecurityManager