Constructs a new {@link Subject.Builder} instance which will use the specified {@code SecurityManager} when building the {@code Subject} instance.
Ensures the {@code Subject} being built will be considered {@link hunt.shiro.subject.Subject#isAuthenticated() authenticated}. Per the {@link hunt.shiro.subject.Subject#isAuthenticated() isAuthenticated()} JavaDoc, 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.
Creates and returns a new {@code Subject} instance reflecting the cumulative state acquired by the other methods in this class. <p/> This {@code Builder} instance will still retain the underlying state after this method is called - it will not clear it; repeated calls to this method will return multiple {@link Subject} instances, all reflecting the exact same state. If a new (different) {@code Subject} is to be constructed, a new {@code Builder} instance must be created. <p/> <b>Note</b> that the returned {@code Subject} instance is <b>not</b> automatically bound to the application (thread) for further use. That is, {@link hunt.shiro.SecurityUtils SecurityUtils}.{@link hunt.shiro.SecurityUtils#getSubject() getSubject()} will not automatically return the same instance as what is returned by the builder. It is up to the framework developer to bind the returned {@code Subject} for continued use if desired.
Allows custom attributes to be added to the underlying context {@code Map} used to construct the {@link Subject} instance. <p/> A {@code null} key{@link IllegalArgumentException}. A {@code null} value effectively removes any previously stored attribute under the given key from the context map. <p/> <b>*NOTE*:</b> This method is only useful when configuring Shiro with a custom {@link SubjectFactory} implementation. This method allows end-users to append additional data to the context map which the {@code SubjectFactory} implementation can use when building custom Subject instances. As such, this method is only useful when a custom {@code SubjectFactory} implementation has been configured.
Returns the backing context used to build the {@code Subject} instance, available to subclasses since the {@code context} class attribute is marked as {@code private}.
Ensures the {@code Subject} being built will reflect the specified host name or IP as its originating location.
Creates a new {@code SubjectContext} instance to be used to populate with subject contextual data that will then be sent to the {@code SecurityManager} to create a new {@code Subject} instance.
Ensures the {@code Subject} being built will reflect the specified principals (aka identity). <p/> For example, if your application's unique identifier for users is a {@code string} username, and you wanted to create a {@code Subject} instance that reflected a user whose username is '{@code jsmith}', and you knew the Realm that could acquire {@code jsmith}'s principals based on the username was named "{@code myRealm}", you might create the '{@code jsmith} {@code Subject} instance this way: <pre> PrincipalCollection identity = new {@link hunt.shiro.subject.SimplePrincipalCollection#SimplePrincipalCollection(Object, string) SimplePrincipalCollection}("jsmith", "myRealm"); Subject jsmith = new Subject.Builder().principals(identity).buildSubject();</pre> <p/> Similarly, if your application's unique identifier for users is a {@code long} value (such as might be used as a primary key in a relational database) and you were using a {@code JDBC} {@code Realm} named, (unimaginatively) "jdbcRealm", you might create the Subject instance this way: <pre> long userId = //get user ID from somewhere PrincipalCollection userIdentity = new {@link hunt.shiro.subject.SimplePrincipalCollection#SimplePrincipalCollection(Object, string) SimplePrincipalCollection}(<em>userId</em>, "jdbcRealm"); Subject user = new Subject.Builder().principals(identity).buildSubject();</pre>
Ensures the {@code Subject} being built will use the specified {@link Session} instance. Note that it is more common to use the {@link #sessionId sessionId} builder method rather than having to construct a {@code Session} instance for this method.
Configures whether or not the created Subject instance can create a new {@code Session} if one does not already exist. If set to {@code false}, any application calls to {@code subject.getSession()} or {@code subject.getSession(true))} will result in a SessionException. <p/> This setting is {@code true} by default, as most applications find value in sessions.
Enables building a {@link Subject Subject} instance that owns the {@link Session Session} with the specified {@code sessionId}. <p/> Usually when specifying a {@code sessionId}, no other {@code Builder} methods would be specified because everything else (principals, inet address, etc) can usually be reconstructed based on the referenced session alone. In other words, this is almost always sufficient: <pre> new Subject.Builder().sessionId(sessionId).buildSubject();</pre> <p/> <b>Although simple in concept, this method provides very powerful functionality previously absent in almost all Java environments:</b> <p/> The ability to reference a {@code Subject} and their server-side session <em>across clients of different mediums</em> such as web applications, Java applets, standalone C# clients over XML-RPC and/or SOAP, and many others. This is a <em>huge</em> benefit in heterogeneous enterprise applications. <p/> To maintain session integrity across client mediums, the {@code sessionId} <b>must</b> be transmitted to all client mediums securely (e.g. over SSL) to prevent man-in-the-middle attacks. This is nothing new - all web applications are susceptible to the same problem when transmitting {@code Cookie}s or when using URL rewriting. As long as the {@code sessionId} is transmitted securely, session integrity can be maintained.
Builder design pattern implementation for creating {@link Subject} instances in a simplified way without requiring knowledge of Shiro's construction techniques. <p/> <b>NOTE</b>: This is provided for framework development support only and should typically never be used by application developers. {@code Subject} instances should generally be acquired by using <code>SecurityUtils.{@link SecurityUtils#getSubject() getSubject()}</code> <h4>Usage</h4> The simplest usage of this builder is to construct an anonymous, session-less {@code Subject} instance: <pre> Subject subject = new Subject.{@link #Builder() Builder}().{@link #buildSubject() buildSubject()};</pre> The default, no-arg {@code Subject.Builder()} constructor shown above will use the application's currently accessible {@code SecurityManager} via <code>SecurityUtils.{@link SecurityUtils#getSecurityManager() getSecurityManager()}</code>. You may also specify the exact {@code SecurityManager} instance to be used by the additional <code>Subject.{@link #Builder(hunt.shiro.mgt.SecurityManager) Builder(securityManager)}</code> constructor if desired. <p/> All other methods may be called before the {@link #buildSubject() buildSubject()} method to provide context on how to construct the {@code Subject} instance. For example, if you have a session id and want to acquire the {@code Subject} that 'owns' that session (assuming the session exists and is not expired): <pre> Subject subject = new Subject.Builder().sessionId(sessionId).buildSubject();</pre> <p/> Similarly, if you want a {@code Subject} instance reflecting a certain identity: <pre> PrincipalCollection principals = new SimplePrincipalCollection("username", <em>yourRealmName</em>); Subject subject = new Subject.Builder().principals(principals).build();</pre> <p/> <b>Note*</b> that the returned {@code Subject} instance is <b>not</b> automatically bound to the application (thread) for further use. That is, {@link hunt.shiro.SecurityUtils SecurityUtils}.{@link hunt.shiro.SecurityUtils#getSubject() getSubject()} will not automatically return the same instance as what is returned by the builder. It is up to the framework developer to bind the built {@code Subject} for continued use if desired.