Package 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:

  • Field Details

    • 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:

    • 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:

    • ENVIRONMENT_ATTRIBUTE_KEY

      public static final String ENVIRONMENT_ATTRIBUTE_KEY

  • Constructor Details

    • EnvironmentLoader

      public EnvironmentLoader()

  • Method Details

    • 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:

    • doLoadWebEnvironmentsFromServiceLoader

      protected Iterator<WebEnvironment> doLoadWebEnvironmentsFromServiceLoader()

    • getDefaultWebEnvironmentClass

      protected Class<? extends WebEnvironment> getDefaultWebEnvironmentClass(javax.servlet.ServletContext ctx)
      Returns the default WebEnvironment class, which is unless overridden: IniWebEnvironment.
      Parameters:
      ctx - servlet context
      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:
      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:

    • 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:

    • 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