org.apache.shiro.web.env

Class 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 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(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(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(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(ServletContext servletContext)
        Destroys the WebEnvironment for the given servlet context.
        Parameters:
        servletContext - the ServletContext attributed to the WebSecurityManager