Interface SubjectContext

All Superinterfaces:
Map<String,Object>
All Known Implementing Classes:
DefaultSubjectContext
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:

  • Method Details

    • 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()