org.apache.shiro.subject.SubjectContext Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.shiro.subject;
import org.apache.shiro.authc.AuthenticationInfo;
import org.apache.shiro.authc.AuthenticationToken;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.session.Session;
import java.io.Serializable;
import java.util.Map;
/**
* A {@code SubjectContext} is a 'bucket' of data presented to a {@link SecurityManager} which interprets
* this data to construct {@link org.apache.shiro.subject.Subject 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 {@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 subject
* instance. 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 exist
* in the {@link #getSession() session} or another attribute in the context. The {@link #resolvePrincipals()} will know
* how to resolve the principals based on heuristics. If the {@code resolve*} methods return {@code 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
* {@code resolve*} methods should be used when actually constructing the {@code Subject} instance to ensure the most
* specific/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 that
* way.
*
* @see org.apache.shiro.mgt.SecurityManager#createSubject SecurityManager.createSubject
* @see org.apache.shiro.mgt.SubjectFactory SubjectFactory
* @since 1.0
*/
public interface SubjectContext extends Map {
/**
* Returns the SecurityManager instance that should be used to back the constructed {@link Subject} instance or
* {@code null} if one has not yet been provided to this context.
*
* @return the SecurityManager instance that should be used to back the constructed {@link Subject} instance or
* {@code null} if one has not yet been provided to this context.
*/
SecurityManager getSecurityManager();
/**
* Sets the SecurityManager instance that should be used to back the constructed {@link Subject} instance
* (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
*
* @param securityManager the SecurityManager instance that should be used to back the constructed {@link Subject}
* instance.
*/
void setSecurityManager(SecurityManager securityManager);
/**
* Resolves the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
* instance (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
*
* @return the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
* instance
*/
SecurityManager resolveSecurityManager();
/**
* Returns the session id of the session that should be associated with the constructed {@link 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.
*
* @return the session id of the session that should be associated with the constructed {@link Subject} instance.
*/
Serializable getSessionId();
/**
* Sets the session id of the session that should be associated with the constructed {@link 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.
*
* @param sessionId the session id of the session that should be associated with the constructed {@link Subject}
* instance.
*/
void setSessionId(Serializable sessionId);
/**
* Returns any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
* being created.
*
* This is typically used in the case where the existing {@code Subject} instance returned by
* this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful
* authentication - you want to return most of the state of the previous {@code Subject} instance when creating the
* newly authenticated instance.
*
* @return any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
* being created.
*/
Subject getSubject();
/**
* Sets the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
* being created.
*
* This is typically used in the case where the existing {@code Subject} instance returned by
* this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful
* authentication - you want to return most of the state of the previous {@code Subject} instance when creating the
* newly authenticated instance.
*
* @param subject the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
* being created.
*/
void setSubject(Subject subject);
/**
* Returns the principals (aka identity) that the constructed {@code Subject} should reflect.
*
* @return the principals (aka identity) that the constructed {@code Subject} should reflect.
*/
PrincipalCollection getPrincipals();
PrincipalCollection resolvePrincipals();
/**
* Sets the principals (aka identity) that the constructed {@code Subject} should reflect.
*
* @param principals the principals (aka identity) that the constructed {@code Subject} should reflect.
*/
void setPrincipals(PrincipalCollection principals);
/**
* Returns the {@code Session} to use when building the {@code Subject} instance. Note that it is more
* common to specify a {@link #setSessionId sessionId} to acquire the desired session rather than having to
* construct a {@code Session} to be returned by this method.
*
* @return the {@code Session} to use when building the {@code Subject} instance.
*/
Session getSession();
/**
* Sets the {@code Session} to use when building the {@code Subject} instance. Note that it is more
* common to specify a {@link #setSessionId sessionId} to automatically resolve the desired session rather than
* constructing a {@code Session} to call this method.
*
* @param session the {@code Session} to use when building the {@code Subject} instance.
*/
void setSession(Session session);
Session resolveSession();
/**
* Returns {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}
* otherwise. Be careful setting this value to {@code true} - you should know what you are doing and have a good
* reason for ignoring Shiro's default authentication state mechanisms.
*
* @return {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}
* otherwise.
*/
boolean isAuthenticated();
/**
* Sets whether or not the constructed {@code Subject} instance should be considered as authenticated. Be careful
* when specifying {@code true} - you should know what you are doing and have a good reason for ignoring Shiro's
* default authentication state mechanisms.
*
* @param authc whether or not the constructed {@code Subject} instance should be considered as authenticated.
*/
void setAuthenticated(boolean authc);
/**
* Returns {@code true} if the constructed {@code Subject} should be allowed to create a session, {@code false}
* otherwise. Shiro's configuration defaults to {@code true} as most applications find value in Sessions.
*
* @return {@code true} if the constructed {@code Subject} should be allowed to create sessions, {@code false}
* otherwise.
* @since 1.2
*/
boolean isSessionCreationEnabled();
/**
* Sets whether or not the constructed {@code Subject} instance should be allowed to create a session,
* {@code false} otherwise.
*
* @param enabled whether or not the constructed {@code Subject} instance should be allowed to create a session,
* {@code false} otherwise.
* @since 1.2
*/
void setSessionCreationEnabled(boolean enabled);
boolean resolveAuthenticated();
AuthenticationInfo getAuthenticationInfo();
void setAuthenticationInfo(AuthenticationInfo info);
AuthenticationToken getAuthenticationToken();
void setAuthenticationToken(AuthenticationToken token);
/**
* Returns the host name or IP that should reflect the constructed {@code Subject}'s originating location.
*
* @return the host name or IP that should reflect the constructed {@code Subject}'s originating location.
*/
String getHost();
/**
* Sets the host name or IP that should reflect the constructed {@code Subject}'s originating location.
*
* @param host the host name or IP that should reflect the constructed {@code Subject}'s originating location.
*/
void setHost(String host);
String resolveHost();
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy