Package org.apache.shiro.subject

Interface SubjectContext

  • All Superinterfaces:
    <,​>
    All Known Implementing Classes:
    DefaultSubjectContext
    public interface SubjectContext
extends <,​>
    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

    • 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

         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​( 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.

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

      • getHost

         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​( 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

         resolveHost()