com.broadleafcommerce.auth.security.service.hydration

Interface UserRoleAncestryHydrationService

All Known Implementing Classes:

DefaultUserRoleAncestryHydrationService

public interface UserRoleAncestryHydrationService

A UserRole can have ancestors, starting with its direct parent defined in UserRole.parentRoleId up to the top-level ancestor.

This component enables efficient retrieval of all of a role's ancestors from the data store.

Furthermore, despite validation in UserRoleValidator against ancestry cycle formation and broken references in standard CRUD operations, there are still scenarios where these issues may come up. In AdminRolePersistenceHandler, roles are intentionally persisted without this prior validation as it's expected that any cycles or broken references created by persistence of an entity will eventually be resolved by additional persistence messages shortly afterwards (as we expect the admin user service to have already validated against this scenario).

This component accounts for these possibilities when fetching the ancestry of a role.

Author:

Samarth Dhruva (samarthd)

Method Summary

Modifier and Type	Method and Description
Collection<UserRole>	getFlattenedWithAllAncestors(Collection<UserRole> roles) A convenience method to enable fetching a flattened collection consisting of all of the given roles along with their ancestors.
Collection<UserRole>	getFlattenedWithAllAncestorsAndThrowIfAnyFailed(Collection<UserRole> roles) Same logic as documented for getFlattenedWithAllAncestors(Collection) except this method throws an exception when there's one or more UserRoleAncestryHydrationResponse not successful.
Map<String,UserRoleAncestryHydrationResponse>	getWithAllAncestors(Collection<UserRole> roles) Fetches all of the given roles' ancestors from the data store and returns a result containing them and the given roles themselves.
Map<String,Collection<UserRole>>	getWithAllAncestorsByRoleIdAndThrowIfAnyFailed(Collection<UserRole> roles) Same logic as documented for getWithAllAncestors(Collection) except this method throws an exception when there's one or more UserRoleAncestryHydrationResponse not successful, and the value of the map is a collection of the given roles along with their ancestors mapped by the given role id.

Method Detail

getWithAllAncestors

Map<String,UserRoleAncestryHydrationResponse> getWithAllAncestors(Collection<UserRole> roles)

Fetches all of the given roles' ancestors from the data store and returns a result containing them and the given roles themselves.

If a role does not have any ancestors, it will be returned by itself.

If any broken references or cycles are found in the ancestry of a role, its response will not be UserRoleAncestryHydrationResponse.successful.

Parameters:

roles - the roles whose ancestors should be fetched. These should be instances with their fields already fully populated (as they would be from the data store). Roles provided here are considered to be already-found and will re-appear in the result.

Returns:

a map from each given role's id to the hydration response for it. There is guaranteed to be an entry in this map for each given role. The response for a particular role will have it along with all of its ancestors if successful, or a description of any error that was encountered. Do note that if multiple roles share the same ancestor, each of their ancestry lists will contain the same instance of that ancestor.

getWithAllAncestorsByRoleIdAndThrowIfAnyFailed

Map<String,Collection<UserRole>> getWithAllAncestorsByRoleIdAndThrowIfAnyFailed(Collection<UserRole> roles)

Same logic as documented for getWithAllAncestors(Collection) except this method throws an exception when there's one or more UserRoleAncestryHydrationResponse not successful, and the value of the map is a collection of the given roles along with their ancestors mapped by the given role id.

Parameters:

roles - a collection of roles to get along with its ancestors

Returns:

a collection containing the given roles along with their ancestors mapped by given role id

Throws:

IllegalStateException - if there is one or more failed UserRoleAncestryHydrationResponse

getFlattenedWithAllAncestors

Collection<UserRole> getFlattenedWithAllAncestors(Collection<UserRole> roles)

A convenience method to enable fetching a flattened collection consisting of all of the given roles along with their ancestors.

This method should internally delegate to getWithAllAncestors(Collection) to perform the actual ancestor hydration. Each role whose ancestry was not successfully hydrated will be omitted from the result, and an error will be logged for it.

The result will be filtered for duplicates (can occur for example if an ancestor is shared by multiple roles) and thus each element should only appear once in the results.

Parameters:

roles - the roles whose ancestors should be fetched. These should be instances with their fields already fully populated (as they would be from the data store). Roles provided here are considered to be already-found and will re-appear in the result.

Returns:

a flattened collection consisting of all of the given roles along with their ancestors, excluding any roles for which ancestry hydration failed

getFlattenedWithAllAncestorsAndThrowIfAnyFailed

Collection<UserRole> getFlattenedWithAllAncestorsAndThrowIfAnyFailed(Collection<UserRole> roles)

Same logic as documented for getFlattenedWithAllAncestors(Collection) except this method throws an exception when there's one or more UserRoleAncestryHydrationResponse not successful.

Parameters:

roles - a collection of roles to get along with its ancestors

Returns:

a collection containing the given roles along with their ancestors

Throws:

IllegalStateException - if there is one or more failed UserRoleAncestryHydrationResponse