'Run As' functionality implemented (finally!)

[Les Hazlewood <lh...@apache.org>]

I just committed the implementation for SHIRO-25: 'Run As'.  It has
been a long time coming!!!  I kept the name 'runAs' in the API as it
was the overall community favorite.

The new methods on the Subject interface:

void runAs(PrincipalCollection identity); //assumes a new identity
boolean isRunAs(); //returns true if currently operating under an
assumed identity
PrincipalCollection releaseRunAs(); //releases the currently assumed
identity and returns it. Returns null if not operating under an
assumed identity
PrincipalCollection getPreviousPrincipals(); //returns the 'pre run
as' identity, or null if not operating under an assumed identity

The JavaDoc is much better than what I wrote above.   Please check it out.

I've resolved the issue with the hopes that the new methods are
suitable to everyone.  We can certainly re-open the issue if there
needs to be something changed/fixed.

Best,

Les