Provide context object for getting the mapped roles and caller principal

[arjantijms]

In Jakarta Authorization we left the object containing the roles and caller principal open ended. This was done to allow Jakarta EE implementations at a lower level to do things beyond the specification. Things like the Policy in that case need to know the Jakarta implementation. I.e. the Policy and the Jakarta implementation are tightly coupled.

Portable Policies are rare because of this, but those that do exist typically try to obtain these details for every known Jakarta EE implementations out there, often using reflection and heuristics.

While keeping the freedom that implementations have enjoyed, we can support portable policies and essentially everyone who wants to write their own policy, by providing a context object that allows for getting the (mapped) roles and the caller principal.

Such context object can be based on various SPIs that are already being used in practice.

E.g. the one from Exousia:

public interface PrincipalMapper {
    
    default List<String> getMappedRoles(Principal[] principals, Subject subject) {
        return getMappedRoles(asList(principals), subject);
    }
    
    List<String> getMappedRoles(Iterable<Principal> principals, Subject subject);
    
    default boolean isAnyAuthenticatedUserRoleMapped() {
        return false;
    }
}

The one from Soteria:

public interface CallerDetailsResolver {

    Principal getCallerPrincipal();

    <T extends Principal> Set<T> getPrincipalsByType(Class<T> pType);

    boolean isCallerInRole(String role);

    Set<String> getAllDeclaredCallerRoles();

}