org.apache.shiro.subject
Interface SubjectContext

All Superinterfaces:

Map<String,Object>

All Known Subinterfaces:

WebSubjectContext

All Known Implementing Classes:

DefaultSubjectContext, DefaultWebSubjectContext

public interface SubjectContext
extends Map<String,Object>

A SubjectContext is a 'bucket' of data presented to a SecurityManager which interprets this data to construct Subject instances. It is essentially a Map of data with a few additional type-safe methods for easy retrieval of objects commonly used to construct Subject instances.

While this interface contains type-safe setters and getters for common data types, the map can contain anything additional that might be needed by the SecurityManager or SubjectFactory implementation to construct Subject instances.

Data Resolution

The SubjectContext interface also allows for heuristic resolution of data used to construct a subject instance. That is, if an attribute has not been explicitly provided via a setter method, the resolve* methods can use heuristics to obtain that data in another way from other attributes.

For example, if one calls getPrincipals() and no principals are returned, perhaps the principals exist in the session or another attribute in the context. The resolvePrincipals() will know how to resolve the principals based on heuristics. If the resolve* methods return null then the data could not be achieved by any heuristics and must be considered as not available in the context.

The general idea is that the normal getters can be called to see if the value was explicitly set. The resolve* methods should be used when actually constructing the Subject instance to ensure the most specific/accurate data can be used.

USAGE: Most Shiro end-users will never use a SubjectContext instance directly and instead will use a Subject.Builder (which internally uses a SubjectContext) and build Subject instances that way.

Since:

1.0

See Also:

SecurityManager.createSubject, SubjectFactory

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

AuthenticationInfo	getAuthenticationInfo()
AuthenticationToken	getAuthenticationToken()
String	getHost() Returns the host name or IP that should reflect the constructed Subject's originating location.
PrincipalCollection	getPrincipals() Returns the principals (aka identity) that the constructed Subject should reflect.
SecurityManager	getSecurityManager() Returns the SecurityManager instance that should be used to back the constructed Subject instance or null if one has not yet been provided to this context.
Session	getSession() Returns the Session to use when building the Subject instance.
Serializable	getSessionId() Returns the session id of the session that should be associated with the constructed Subject instance.
Subject	getSubject() Returns any existing Subject that may be in use at the time the new Subject instance is being created.
boolean	isAuthenticated() Returns true if the constructed Subject should be considered authenticated, false otherwise.
boolean	isSessionCreationEnabled() Returns true if the constructed Subject should be allowed to create a session, false otherwise.
boolean	resolveAuthenticated()
String	resolveHost()
PrincipalCollection	resolvePrincipals()
SecurityManager	resolveSecurityManager() Resolves the SecurityManager instance that should be used to back the constructed Subject instance (typically used to support DelegatingSubject implementations).
Session	resolveSession()
void	setAuthenticated(boolean authc) Sets whether or not the constructed Subject instance should be considered as authenticated.
void	setAuthenticationInfo(AuthenticationInfo info)
void	setAuthenticationToken(AuthenticationToken token)
void	setHost(String host) Sets the host name or IP that should reflect the constructed Subject's originating location.
void	setPrincipals(PrincipalCollection principals) Sets the principals (aka identity) that the constructed Subject should reflect.
void	setSecurityManager(SecurityManager securityManager) Sets the SecurityManager instance that should be used to back the constructed Subject instance (typically used to support DelegatingSubject implementations).
void	setSession(Session session) Sets the Session to use when building the Subject instance.
void	setSessionCreationEnabled(boolean enabled) Sets whether or not the constructed Subject instance should be allowed to create a session, false otherwise.
void	setSessionId(Serializable sessionId) Sets the session id of the session that should be associated with the constructed Subject instance.
void	setSubject(Subject subject) Sets the existing Subject that may be in use at the time the new Subject instance is being created.

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

getSecurityManager

SecurityManager getSecurityManager()

Returns the SecurityManager instance that should be used to back the constructed Subject instance or null if one has not yet been provided to this context.

Returns:

the SecurityManager instance that should be used to back the constructed Subject instance or null if one has not yet been provided to this context.

setSecurityManager

void setSecurityManager(SecurityManager securityManager)

Sets the SecurityManager instance that should be used to back the constructed Subject instance (typically used to support DelegatingSubject implementations).

Parameters:

securityManager - the SecurityManager instance that should be used to back the constructed Subject instance.

resolveSecurityManager

SecurityManager resolveSecurityManager()

Resolves the SecurityManager instance that should be used to back the constructed Subject instance (typically used to support DelegatingSubject implementations).

Returns:

the SecurityManager instance that should be used to back the constructed Subject instance

getSessionId

Serializable getSessionId()

Returns the session id of the session that should be associated with the constructed Subject instance.

The construction process is expected to resolve the session with the specified id and then construct the Subject instance based on the resolved session.

Returns:

the session id of the session that should be associated with the constructed Subject instance.

setSessionId

void setSessionId(Serializable sessionId)

Sets the session id of the session that should be associated with the constructed Subject instance.

The construction process is expected to resolve the session with the specified id and then construct the Subject instance based on the resolved session.

Parameters:

sessionId - the session id of the session that should be associated with the constructed Subject instance.

getSubject

Subject getSubject()

Returns any existing Subject that may be in use at the time the new Subject instance is being created.

This is typically used in the case where the existing Subject instance returned by this method is unauthenticated and a new Subject instance is being created to reflect a successful authentication - you want to return most of the state of the previous Subject instance when creating the newly authenticated instance.

Returns:

any existing Subject that may be in use at the time the new Subject instance is being created.

setSubject

void setSubject(Subject subject)

Sets the existing Subject that may be in use at the time the new Subject instance is being created.

This is typically used in the case where the existing Subject instance returned by this method is unauthenticated and a new Subject instance is being created to reflect a successful authentication - you want to return most of the state of the previous Subject instance when creating the newly authenticated instance.

Parameters:

subject - the existing Subject that may be in use at the time the new Subject instance is being created.

getPrincipals

PrincipalCollection getPrincipals()

Returns the principals (aka identity) that the constructed Subject should reflect.

Returns:

the principals (aka identity) that the constructed Subject should reflect.

resolvePrincipals

PrincipalCollection resolvePrincipals()

setPrincipals

void setPrincipals(PrincipalCollection principals)

Sets the principals (aka identity) that the constructed Subject should reflect.

Parameters:

principals - the principals (aka identity) that the constructed Subject should reflect.

getSession

Session getSession()

Returns the Session to use when building the Subject instance. Note that it is more common to specify a sessionId to acquire the desired session rather than having to construct a Session to be returned by this method.

Returns:

the Session to use when building the Subject instance.

setSession

void setSession(Session session)

Sets the Session to use when building the Subject instance. Note that it is more common to specify a sessionId to automatically resolve the desired session rather than constructing a Session to call this method.

Parameters:

session - the Session to use when building the Subject instance.

resolveSession

Session resolveSession()

isAuthenticated

boolean isAuthenticated()

Returns true if the constructed Subject should be considered authenticated, false otherwise. Be careful setting this value to true - you should know what you are doing and have a good reason for ignoring Shiro's default authentication state mechanisms.

Returns:

true if the constructed Subject should be considered authenticated, false otherwise.

setAuthenticated

void setAuthenticated(boolean authc)

Sets whether or not the constructed Subject instance should be considered as authenticated. Be careful when specifying true - you should know what you are doing and have a good reason for ignoring Shiro's default authentication state mechanisms.

Parameters:

authc - whether or not the constructed Subject instance should be considered as authenticated.

isSessionCreationEnabled

boolean isSessionCreationEnabled()

Returns true if the constructed Subject should be allowed to create a session, false otherwise. Shiro's configuration defaults to true as most applications find value in Sessions.

Returns:

true if the constructed Subject should be allowed to create sessions, false otherwise.

Since:

1.2

setSessionCreationEnabled

void setSessionCreationEnabled(boolean enabled)

Sets whether or not the constructed Subject instance should be allowed to create a session, false otherwise.

Parameters:

enabled - whether or not the constructed Subject instance should be allowed to create a session, false otherwise.

Since:

1.2

resolveAuthenticated

boolean resolveAuthenticated()

getAuthenticationInfo

AuthenticationInfo getAuthenticationInfo()

setAuthenticationInfo

void setAuthenticationInfo(AuthenticationInfo info)

getAuthenticationToken

AuthenticationToken getAuthenticationToken()

setAuthenticationToken

void setAuthenticationToken(AuthenticationToken token)

getHost

String getHost()

Returns the host name or IP that should reflect the constructed Subject's originating location.

Returns:

the host name or IP that should reflect the constructed Subject's originating location.

setHost

void setHost(String host)

Sets the host name or IP that should reflect the constructed Subject's originating location.

Parameters:

host - the host name or IP that should reflect the constructed Subject's originating location.

resolveHost

String resolveHost()