Returns the primary principal used application-wide to uniquely identify the owning account/Subject.
<p/>
The value is usually always a uniquely identifying attribute specific to the data source that retrieved the
account data. Some examples:
<ul>
<li>a {@link java.util.UUID UUID}</li>
<li>a {@code long} value such as a surrogate primary key in a relational database</li>
<li>an LDAP UUID or static DN</li>
<li>a string username unique across all user accounts</li>
</ul>
<h3>Multi-Realm Applications</h3>
In a single-{@code 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-{@code Realm} application, where the
{@code 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.
<p/>
That value is of course application specific, but most applications will typically choose one of the primary
principals from one of the {@code Realm}s.
<p/>
Shiro's default implementations of this interface make this
assumption by usually simply returning {@link #iterator()}.{@link java.util.Iterator#next() next()}, which just
returns the first returned principal obtained from the first consulted/configured {@code Realm} during the
authentication attempt. This means in a multi-{@code Realm} application, {@code Realm} configuration order
matters if you want to retain this default heuristic.
<p/>
If this heuristic is not sufficient, most Shiro end-users will need to implement a custom
{@link hunt.shiro.authc.pam.AuthenticationStrategy}. An {@code AuthenticationStrategy} has exact control
over the {@link PrincipalCollection} returned at the end of an authentication attempt via the
<code>AuthenticationStrategy#{@link hunt.shiro.authc.pam.AuthenticationStrategy#afterAllAttempts(hunt.shiro.authc.AuthenticationToken, hunt.shiro.authc.AuthenticationInfo) afterAllAttempts}</code>
implementation.
@return the primary principal used to uniquely identify the owning account/Subject
Returns the primary principal used application-wide to uniquely identify the owning account/Subject. <p/> The value is usually always a uniquely identifying attribute specific to the data source that retrieved the account data. Some examples: <ul> <li>a {@link java.util.UUID UUID}</li> <li>a {@code long} value such as a surrogate primary key in a relational database</li> <li>an LDAP UUID or static DN</li> <li>a string username unique across all user accounts</li> </ul> <h3>Multi-Realm Applications</h3> In a single-{@code 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-{@code Realm} application, where the {@code 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. <p/> That value is of course application specific, but most applications will typically choose one of the primary principals from one of the {@code Realm}s. <p/> Shiro's default implementations of this interface make this assumption by usually simply returning {@link #iterator()}.{@link java.util.Iterator#next() next()}, which just returns the first returned principal obtained from the first consulted/configured {@code Realm} during the authentication attempt. This means in a multi-{@code Realm} application, {@code Realm} configuration order matters if you want to retain this default heuristic. <p/> If this heuristic is not sufficient, most Shiro end-users will need to implement a custom {@link hunt.shiro.authc.pam.AuthenticationStrategy}. An {@code AuthenticationStrategy} has exact control over the {@link PrincipalCollection} returned at the end of an authentication attempt via the <code>AuthenticationStrategy#{@link hunt.shiro.authc.pam.AuthenticationStrategy#afterAllAttempts(hunt.shiro.authc.AuthenticationToken, hunt.shiro.authc.AuthenticationInfo) afterAllAttempts}</code> implementation.
@return the primary principal used to uniquely identify the owning account/Subject