org.apache.shiro
Class SecurityUtils

java.lang.Object
  org.apache.shiro.SecurityUtils

public abstract class SecurityUtils
extends Object

Accesses the currently accessible Subject for the calling code depending on runtime environment.

Since:

0.2

Constructor Summary

SecurityUtils()

Method Summary

static SecurityManager	getSecurityManager() Returns the SecurityManager accessible to the calling code.
static Subject	getSubject() Returns the currently accessible Subject available to the calling code depending on runtime environment.
static void	setSecurityManager(SecurityManager securityManager) Sets a VM (static) singleton SecurityManager, specifically for transparent use in the getSubject() implementation.

Methods inherited from class java.lang.Object

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

Constructor Detail

SecurityUtils

public SecurityUtils()

Method Detail

getSubject

public static Subject getSubject()

Returns the currently accessible Subject available to the calling code depending on runtime environment.

This method is provided as a way of obtaining a Subject without having to resort to implementation-specific methods. It also allows the Shiro team to change the underlying implementation of this method in the future depending on requirements/updates without affecting your code that uses it.

Returns:

the currently accessible Subject accessible to the calling code.

Throws:

IllegalStateException - if no Subject instance or SecurityManager instance is available with which to obtain a Subject, which which is considered an invalid application configuration - a Subject should always be available to the caller.

setSecurityManager

public static void setSecurityManager(SecurityManager securityManager)

Sets a VM (static) singleton SecurityManager, specifically for transparent use in the getSubject() implementation.

This method call exists mainly for framework development support. Application developers should rarely, if ever, need to call this method.

The Shiro development team prefers that SecurityManager instances are non-static application singletons and not VM static singletons. Application singletons that do not use static memory require some sort of application configuration framework to maintain the application-wide SecurityManager instance for you (for example, Spring or EJB3 environments) such that the object reference does not need to be static.

In these environments, Shiro acquires Subject data based on the currently executing Thread via its own framework integration code, and this is the preferred way to use Shiro.

However in some environments, such as a standalone desktop application or Applets that do not use Spring or EJB or similar config frameworks, a VM-singleton might make more sense (although the former is still preferred). In these environments, setting the SecurityManager via this method will automatically enable the getSubject() call to function with little configuration.

For example, in these environments, this will work:

 DefaultSecurityManager securityManager = new DefaultSecurityManager();
 securityManager.setRealms( ... ); //one or more Realms
 SecurityUtils.setSecurityManager( securityManager );

And then anywhere in the application code, the following call will return the application's Subject:

 Subject currentUser = SecurityUtils.getSubject();

Parameters:

securityManager - the securityManager instance to set as a VM static singleton.

getSecurityManager

public static SecurityManager getSecurityManager()
                                          throws UnavailableSecurityManagerException

Returns the SecurityManager accessible to the calling code.

This implementation favors acquiring a thread-bound SecurityManager if it can find one. If one is not available to the executing thread, it will attempt to use the static singleton if available (see the setSecurityManager method for more on the static singleton).

If neither the thread-local or static singleton instances are available, this method throws an UnavailableSecurityManagerException to indicate an error - a SecurityManager should always be accessible to calling code in an application. If it is not, it is likely due to a Shiro configuration problem.

Returns:

the SecurityManager accessible to the calling code.

Throws:

UnavailableSecurityManagerException - if there is no SecurityManager instance available to the calling code, which typically indicates an invalid application configuration.