A {@code SubjectContext} is a 'bucket' of data presented to a {@link SecurityManager} which interpretsthis data to construct {@link org.apache.shiro.subject.Subject Subject} instances. It is essentially a Map of datawith 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 {@link SecurityManager} or{@link org.apache.shiro.mgt.SubjectFactory SubjectFactory} implementation to construct {@code Subject} instances.
Data Resolution
The {@link SubjectContext} interface also allows for heuristic resolution of data used to construct a subjectinstance. That is, if an attribute has not been explicitly provided via a setter method, the {@code resolve*}methods can use heuristics to obtain that data in another way from other attributes.
For example, if one calls {@link #getPrincipals()} and no principals are returned, perhaps the principals existin the {@link #getSession() session} or another attribute in the context. The {@link #resolvePrincipals()} will knowhow to resolve the principals based on heuristics. If the {@code resolve*} methods return {@code null} then thedata 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 {@code resolve*} methods should be used when actually constructing the {@code Subject} instance to ensure the mostspecific/accurate data can be used.
USAGE: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will use a{@link Subject.Builder} (which internally uses a {@code SubjectContext}) and build {@code Subject} instances thatway.
@author Les Hazlewood
@see org.apache.shiro.mgt.SecurityManager#createSubject SecurityManager.createSubject
@see org.apache.shiro.mgt.SubjectFactory SubjectFactory
@since 1.0