org.apache.shiro.subject
Class Subject.Builder

java.lang.Object
  org.apache.shiro.subject.Subject.Builder

Enclosing interface:

Subject

public static class Subject.Builder
extends Object

Builder design pattern implementation for creating Subject instances in a simplified way without requiring knowledge of Shiro's construction techniques.

NOTE: This is provided for framework development support only and should typically never be used by application developers. Subject instances should generally be acquired by using SecurityUtils.getSubject()

Usage

The simplest usage of this builder is to construct an anonymous, session-less Subject instance:

 Subject subject = new Subject.Builder().buildSubject();

The default, no-arg Subject.Builder() constructor shown above will use the application's currently accessible SecurityManager via SecurityUtils.getSecurityManager(). You may also specify the exact SecurityManager instance to be used by the additional Subject.Builder(securityManager) constructor if desired.

All other methods may be called before the buildSubject() method to provide context on how to construct the Subject instance. For example, if you have a session id and want to acquire the Subject that 'owns' that session (assuming the session exists and is not expired):

 Subject subject = new Subject.Builder().sessionId(sessionId).buildSubject();

Similarly, if you want a Subject instance reflecting a certain identity:

 PrincipalCollection principals = new SimplePrincipalCollection("username", yourRealmName);
 Subject subject = new Subject.Builder().principals(principals).build();

Note* that the returned Subject instance is not automatically bound to the application (thread) for further use. That is, SecurityUtils.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 Subject for continued use if desired.

Since:

1.0

Constructor Summary

Subject.Builder()
Constructs a new Subject.Builder instance, using the SecurityManager instance available to the calling code as determined by a call to SecurityUtils.getSecurityManager() to build the Subject instance.

Subject.Builder(SecurityManager securityManager)
Constructs a new Subject.Builder instance which will use the specified SecurityManager when building the Subject instance.

Method Summary

Subject.Builder	authenticated(boolean authenticated) Ensures the Subject being built will be considered authenticated.
Subject	buildSubject() Creates and returns a new Subject instance reflecting the cumulative state acquired by the other methods in this class.
Subject.Builder	contextAttribute(String attributeKey, Object attributeValue) Allows custom attributes to be added to the underlying context Map used to construct the Subject instance.
protected SubjectContext	getSubjectContext() Returns the backing context used to build the Subject instance, available to subclasses since the context class attribute is marked as private.
Subject.Builder	host(String host) Ensures the Subject being built will reflect the specified host name or IP as its originating location.
protected SubjectContext	newSubjectContextInstance() Creates a new SubjectContext instance to be used to populate with subject contextual data that will then be sent to the SecurityManager to create a new Subject instance.
Subject.Builder	principals(PrincipalCollection principals) Ensures the Subject being built will reflect the specified principals (aka identity).
Subject.Builder	session(Session session) Ensures the Subject being built will use the specified Session instance.
Subject.Builder	sessionCreationEnabled(boolean enabled) Configures whether or not the created Subject instance can create a new Session if one does not already exist.
Subject.Builder	sessionId(Serializable sessionId) Enables building a Subject instance that owns the Session with the specified sessionId.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Subject.Builder

public Subject.Builder()

Constructs a new Subject.Builder instance, using the SecurityManager instance available to the calling code as determined by a call to SecurityUtils.getSecurityManager() to build the Subject instance.

Subject.Builder

public Subject.Builder(SecurityManager securityManager)

Constructs a new Subject.Builder instance which will use the specified SecurityManager when building the Subject instance.

Parameters:

securityManager - the SecurityManager to use when building the Subject instance.

Method Detail

newSubjectContextInstance

protected SubjectContext newSubjectContextInstance()

Creates a new SubjectContext instance to be used to populate with subject contextual data that will then be sent to the SecurityManager to create a new Subject instance.

Returns:

a new SubjectContext instance

getSubjectContext

protected SubjectContext getSubjectContext()

Returns the backing context used to build the Subject instance, available to subclasses since the context class attribute is marked as private.

Returns:

the backing context used to build the Subject instance, available to subclasses.

sessionId

public Subject.Builder sessionId(Serializable sessionId)

Enables building a Subject instance that owns the Session with the specified sessionId.

Usually when specifying a sessionId, no other 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:

 new Subject.Builder().sessionId(sessionId).buildSubject();

Although simple in concept, this method provides very powerful functionality previously absent in almost all Java environments:

The ability to reference a Subject and their server-side session across clients of different mediums such as web applications, Java applets, standalone C# clients over XML-RPC and/or SOAP, and many others. This is a huge benefit in heterogeneous enterprise applications.

To maintain session integrity across client mediums, the sessionId must 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 Cookies or when using URL rewriting. As long as the sessionId is transmitted securely, session integrity can be maintained.

Parameters:

sessionId - the id of the session that backs the desired Subject being acquired.

Returns:

this Builder instance for method chaining.

host

public Subject.Builder host(String host)

Ensures the Subject being built will reflect the specified host name or IP as its originating location.

Parameters:

host - the host name or IP address to use as the Subject's originating location.

Returns:

this Builder instance for method chaining.

session

public Subject.Builder session(Session session)

Ensures the Subject being built will use the specified Session instance. Note that it is more common to use the sessionId builder method rather than having to construct a Session instance for this method.

Parameters:

session - the session to use as the Subject's Session

Returns:

this Builder instance for method chaining.

principals

public Subject.Builder principals(PrincipalCollection principals)

Ensures the Subject being built will reflect the specified principals (aka identity).

For example, if your application's unique identifier for users is a String username, and you wanted to create a Subject instance that reflected a user whose username is 'jsmith', and you knew the Realm that could acquire jsmith's principals based on the username was named "myRealm", you might create the 'jsmith Subject instance this way:

 PrincipalCollection identity = new SimplePrincipalCollection("jsmith", "myRealm");
 Subject jsmith = new Subject.Builder().principals(identity).buildSubject();

Similarly, if your application's unique identifier for users is a long value (such as might be used as a primary key in a relational database) and you were using a JDBC Realm named, (unimaginatively) "jdbcRealm", you might create the Subject instance this way:

 long userId = //get user ID from somewhere
 PrincipalCollection userIdentity = new SimplePrincipalCollection(userId, "jdbcRealm");
 Subject user = new Subject.Builder().principals(identity).buildSubject();

Parameters:

principals - the principals to use as the Subject's identity.

Returns:

this Builder instance for method chaining.

sessionCreationEnabled

public Subject.Builder sessionCreationEnabled(boolean enabled)

Configures whether or not the created Subject instance can create a new Session if one does not already exist. If set to false, any application calls to subject.getSession() or subject.getSession(true)) will result in a SessionException.

This setting is true by default, as most applications find value in sessions.

Parameters:

enabled - whether or not the created Subject instance can create a new Session if one does not already exist.

Returns:

this Builder instance for method chaining.

Since:

1.2

authenticated

public Subject.Builder authenticated(boolean authenticated)

Ensures the Subject being built will be considered authenticated. Per the isAuthenticated() JavaDoc, 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:

authenticated - whether or not the built Subject will be considered authenticated.

Returns:

this Builder instance for method chaining.

See Also:

Subject.isAuthenticated()

contextAttribute

public Subject.Builder contextAttribute(String attributeKey,
                                        Object attributeValue)

Allows custom attributes to be added to the underlying context Map used to construct the Subject instance.

A null key throws an IllegalArgumentException. A null value effectively removes any previously stored attribute under the given key from the context map.

*NOTE*: This method is only useful when configuring Shiro with a custom SubjectFactory implementation. This method allows end-users to append additional data to the context map which the SubjectFactory implementation can use when building custom Subject instances. As such, this method is only useful when a custom SubjectFactory implementation has been configured.

Parameters:

attributeKey - the key under which the corresponding value will be stored in the context Map.

attributeValue - the value to store in the context map under the specified attributeKey.

Returns:

this Builder instance for method chaining.

Throws:

IllegalArgumentException - if the attributeKey is null.

See Also:

SubjectFactory.createSubject(SubjectContext)

buildSubject

public Subject buildSubject()

Creates and returns a new Subject instance reflecting the cumulative state acquired by the other methods in this class.

This 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 Subject instances, all reflecting the exact same state. If a new (different) Subject is to be constructed, a new Builder instance must be created.

Note that the returned Subject instance is not automatically bound to the application (thread) for further use. That is, SecurityUtils.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 Subject for continued use if desired.

Returns:

a new Subject instance reflecting the cumulative state acquired by the other methods in this class.