org.apache.shiro.subject
Interface PrincipalCollection

All Superinterfaces:

Iterable, Serializable

All Known Subinterfaces:

MutablePrincipalCollection, PrincipalMap

All Known Implementing Classes:

SimplePrincipalCollection, SimplePrincipalMap

public interface PrincipalCollection
extends Iterable, Serializable

A collection of all principals associated with a corresponding Subject. A principal is just a security term for an identifying attribute, such as a username or user id or social security number or anything else that can be considered an 'identifying' attribute for a Subject.

A PrincipalCollection organizes its internal principals based on the Realm where they came from when the Subject was first created. To obtain the principal(s) for a specific Realm, see the fromRealm(java.lang.String) method. You can also see which realms contributed to this collection via the getRealmNames() method.

Since:

0.9

See Also:

getPrimaryPrincipal(), fromRealm(String realmName), getRealmNames()

Method Summary

List	asList() Returns a single Subject's principals retrieved from all configured Realms as a List, or an empty List if there are not any principals.
Set	asSet() Returns a single Subject's principals retrieved from all configured Realms as a Set, or an empty Set if there are not any principals.
<T> Collection<T>	byType(Class<T> type) Returns all principals assignable from the specified type, or an empty Collection if no principals of that type are contained.
Collection	fromRealm(String realmName) Returns a single Subject's principals retrieved from the specified Realm only as a Collection, or an empty Collection if there are not any principals from that realm.
Object	getPrimaryPrincipal() Returns the primary principal used application-wide to uniquely identify the owning account/Subject.
Set<String>	getRealmNames() Returns the realm names that this collection has principals for.
boolean	isEmpty() Returns true if this collection is empty, false otherwise.
<T> T	oneByType(Class<T> type) Returns the first discovered principal assignable from the specified type, or null if there are none of the specified type.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

getPrimaryPrincipal

Object getPrimaryPrincipal()

Returns the primary principal used application-wide to uniquely identify the owning account/Subject.

The value is usually always a uniquely identifying attribute specific to the data source that retrieved the account data. Some examples:

• a UUID
• a long value such as a surrogate primary key in a relational database
• an LDAP UUID or static DN
• a String username unique across all user accounts

Multi-Realm Applications

In a single-Realm application, typically there is only ever one unique principal to retain and that is the value returned from this method. However, in a multi-Realm application, where the PrincipalCollection might retain principals across more than one realm, the value returned from this method should be the single principal that uniquely identifies the subject for the entire application.

That value is of course application specific, but most applications will typically choose one of the primary principals from one of the Realms.

Shiro's default implementations of this interface make this assumption by usually simply returning Iterable.iterator().next(), which just returns the first returned principal obtained from the first consulted/configured Realm during the authentication attempt. This means in a multi-Realm application, Realm configuraiton order matters if you want to retain this default heuristic.

If this heuristic is not sufficient, most Shiro end-users will need to implement a custom AuthenticationStrategy. An AuthenticationStrategy has exact control over the PrincipalCollection returned at the end of an authentication attempt via the AuthenticationStrategy#afterAllAttempts implementation.

Returns:

the primary principal used to uniquely identify the owning account/Subject

Since:

1.0

oneByType

<T> T oneByType(Class<T> type)

Returns the first discovered principal assignable from the specified type, or null if there are none of the specified type.

Note that this will return null if the 'owning' subject has not yet logged in.

Parameters:

type - the type of the principal that should be returned.

Returns:

a principal of the specified type or null if there isn't one of the specified type.

byType

<T> Collection<T> byType(Class<T> type)

Returns all principals assignable from the specified type, or an empty Collection if no principals of that type are contained.

Note that this will return an empty Collection if the 'owning' subject has not yet logged in.

Parameters:

type - the type of the principals that should be returned.

Returns:

a Collection of principals that are assignable from the specified type, or an empty Collection if no principals of this type are associated.

asList

List asList()

Returns a single Subject's principals retrieved from all configured Realms as a List, or an empty List if there are not any principals.

Note that this will return an empty List if the 'owning' subject has not yet logged in.

Returns:

a single Subject's principals retrieved from all configured Realms as a List.

asSet

Set asSet()

Returns a single Subject's principals retrieved from all configured Realms as a Set, or an empty Set if there are not any principals.

Note that this will return an empty Set if the 'owning' subject has not yet logged in.

Returns:

a single Subject's principals retrieved from all configured Realms as a Set.

fromRealm

Collection fromRealm(String realmName)

Returns a single Subject's principals retrieved from the specified Realm only as a Collection, or an empty Collection if there are not any principals from that realm.

Note that this will return an empty Collection if the 'owning' subject has not yet logged in.

Parameters:

realmName - the name of the Realm from which the principals were retrieved.

Returns:

the Subject's principals from the specified Realm only as a Collection or an empty Collection if there are not any principals from that realm.

getRealmNames

Set<String> getRealmNames()

Returns the realm names that this collection has principals for.

Returns:

the names of realms that this collection has one or more principals for.

isEmpty

boolean isEmpty()

Returns true if this collection is empty, false otherwise.

Returns:

true if this collection is empty, false otherwise.