A utility method for subclasses that returns the first available principal of interest to this particular realm.
The heuristic used to acquire the principal is as follows:
<ul>
<li>Attempt to get <em>this particular Realm's</em> 'primary' principal in the {@code PrincipalCollection} via a
<code>principals.{@link PrincipalCollection#fromRealm(string) fromRealm}({@link #getName() getName()})</code>
call.</li>
<li>If the previous call does not result in any principals, attempt to get the overall 'primary' principal
from the PrincipalCollection via {@link hunt.shiro.subject.PrincipalCollection#getPrimaryPrincipal()}.</li>
<li>If there are no principals from that call (or the PrincipalCollection argument was null to begin with),
return {@code null}</li>
</ul>
@param principals the PrincipalCollection holding all principals (from all realms) associated with a single Subject.
@return the 'primary' principal attributed to this particular realm, or the fallback 'master' principal if it
exists, or if not {@code null}.
A utility method for subclasses that returns the first available principal of interest to this particular realm. The heuristic used to acquire the principal is as follows: <ul> <li>Attempt to get <em>this particular Realm's</em> 'primary' principal in the {@code PrincipalCollection} via a <code>principals.{@link PrincipalCollection#fromRealm(string) fromRealm}({@link #getName() getName()})</code> call.</li> <li>If the previous call does not result in any principals, attempt to get the overall 'primary' principal from the PrincipalCollection via {@link hunt.shiro.subject.PrincipalCollection#getPrimaryPrincipal()}.</li> <li>If there are no principals from that call (or the PrincipalCollection argument was null to begin with), return {@code null}</li> </ul>
@param principals the PrincipalCollection holding all principals (from all realms) associated with a single Subject. @return the 'primary' principal attributed to this particular realm, or the fallback 'master' principal if it exists, or if not {@code null}.