This interface defines the principal manager which is the clients view on
all principals known to the repository. Each principal manager is bound to
a session and is restricted by the respective access control. The principal
manager in addition provides basic search facilities.

A Principal is an object used to connect
to any kind of security mechanism. Example for this are the
login modules that use principals
to process the login procedure.
A principal can be a member of a Group. A
group is a principal itself and can therefore be a member of a group again.

Please note the following security considerations that need to be respected
when implementing the PrincipalManager: All principals returned by this
manager as well as Group.members() must respect access restrictions
that may be present for the Session this manager has been built
for. The same applies for getGroupMembership(Principal).

Field Summary

static int

SEARCH_TYPE_ALL
Filter flag indicating that all Principals should be search
irrespective whether they represent a group of Principals or not.

static int

SEARCH_TYPE_GROUP
Filter flag indicating that only Principals that represent
a group of Principals should be searched
and returned.

hasPrincipal

Checks if the principal with the given name is known to this manager
(in respect to the sessions access rights). If this method returns
true then the following expression evaluates to true
as well: PrincipalManager.getPrincipal(name).getName().equals(name)

Parameters:

principalName - the name of the principal to check

Returns:

return true if the principal with this name is known
to this manager; false otherwise.

getPrincipal

Returns the principal with the given name if is known to this manager
(with respect to the sessions access rights).
Please note that due to security reasons Group principals will only
reveal those members that are visible to the Session this
PrincipalManager has been built for.

Parameters:

principalName - the name of the principal to retrieve

Returns:

return the requested principal or null if not exists

findPrincipals

Gets the principals matching a simple filter expression applied against
the principal name.
TODO: define the filter expression.
An implementation may limit the number of principals returned.
If there are no matching principals, an empty iterator is returned.

Parameters:

simpleFilter -

Returns:

a PrincipalIterator over the Principals
matching the given filter.

findPrincipals

Gets the principals matching a simple filter expression applied against
the principal name AND the specified search
type.
TODO: define the filter expression.
An implementation may limit the number of principals returned.
If there are no matching principals, an empty iterator is returned.