Package com.orchestranetworks.service.directory

# Class DirectoryHandler

java.lang.Object
com.orchestranetworks.service.directory.DirectoryHandler

public final class DirectoryHandler extends Object
An instance of this class wraps the current custom directory implementation, so as to add pre-processing and post-verifications to the directory method implementations.

The current directory of a repository is returned by the static method `getInstance(Repository)`.

Note: Normal use of EBX® APIs does not require accessing this class, since authentication and permissions management are transparent from the developer point of view (they are "container-managed"). However, this class may be useful when data governance has specific functional dependencies on the directory (for example, a service needs access to all defined users, or if it must display a specific profile).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `UserReference`
  `authenticateUserFromArray(Object[] args)`
  `UserReference`
  `authenticateUserFromHttpRequest(HttpServletRequest aRequest)`
  `UserReference`
  `authenticateUserFromLoginPassword(String aLogin, String aPassword)`
  `UserReference`
  `authenticateUserFromSOAPHeader(Element anHeader)`
  `String`
  `displayBuiltInRole(Role aBuiltInRole, Locale aLocale)`
  `String`
  `displayProfile(Profile aProfile, Locale aLocale)`
  Returns a label for the profile specified.
  `String`
  `displaySpecificRole(Role aSpecificRole, Locale aLocale)`
  `String`
  `displayUser(UserReference aUserReference, Locale aLocale)`
  `String`
  `displayUserWithSalutation(UserReference aUserReference, Locale aLocale)`
  `List<UserReference>`
  `getBackedUpUsers(UserReference aUserReference)`
  If the `Directory` implementation returns `null`, this method returns an empty List.
  `List<UserReference>`
  `getBackingUpUsers(UserReference aUserReference)`
  If the `Directory` implementation returns `null`, this method returns an empty List.
  `Directory`
  `getDirectoryImplementation()`
  Returns the underlying implementation of the directory.
  `static DirectoryHandler`
  `getInstance(Repository aRepository)`
  Returns the directory instance that is associated with the specified repository.
  `List<Profile>`
  `getProfiles(ProfileListContext aProfileContext)`
  `String`
  `getRoleEmail(Role aRole)`
  If not null, the email address is considered as the mailing list of all the users in this role.
  `URI`
  `getUserAuthenticationURI(Session aSession)`
  Deprecated.
  Since 6.1.3, see `Directory.getUserAuthenticationURI(Session)`.
  `String`
  `getUserEmail(UserReference aUserReference)`
  `List<UserReference>`
  `getUsersInRole(Role aRole)`
  `boolean`
  `hasUsersInRole(Role aRole)`
  `final boolean`
  `isBuiltInAdministratorDisabled()`
  Returns `true` if the built-in administrator role has been disabled.
  `boolean`
  `isProfileDefined(Profile aProfile)`
  Returns `true` if the specified profile is defined in the directory.
  `boolean`
  `isProfileIncluded(Profile aProfile, Profile anotherProfile)`
  Returns `true` when `aProfile` is equal to or included in `anotherProfile`.
  `boolean`
  `isRoleStrictlyIncluded(Role aRole, Role anotherRole)`
  Returns `true` if `aRole` is included in `anotherRole`.
  `boolean`
  `isSpecificRoleDefined(Role aSpecificRole)`
  `boolean`
  `isUserDefined(UserReference aUserReference)`
  `boolean`
  `isUserInRole(UserReference aUser, Role aRole)`
  Returns `true` if the user has the specified role.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getInstance

    public static DirectoryHandler getInstance(Repository aRepository)
    Returns the directory instance that is associated with the specified repository.

    Warning: a normal use of EBX® APIs does not require to access this class, since authentication and permissions management are transparent from the developer point of view (they are "container-managed"). However, this class may be useful when Master Data Management has specific functional dependencies on the directory (for example, a service needs all of the defined users, or it has to display a specific profile).

    See Also:
      - `getDirectoryImplementation()`

  - ### authenticateUserFromLoginPassword

    public UserReference authenticateUserFromLoginPassword(String aLogin, String aPassword) throws AuthenticationException
    Throws:
      `AuthenticationException`
    See Also:
      - `Directory.authenticateUserFromLoginPassword(String, String)`

  - ### authenticateUserFromHttpRequest

    public UserReference authenticateUserFromHttpRequest(HttpServletRequest aRequest) throws AuthenticationException
    Throws:
      `AuthenticationException`
    See Also:
      - `Directory.authenticateUserFromHttpRequest(HttpServletRequest)`

  - ### authenticateUserFromSOAPHeader

    public UserReference authenticateUserFromSOAPHeader(Element anHeader) throws AuthenticationException
    Throws:
      `AuthenticationException`
    See Also:
      - `Directory.authenticateUserFromSOAPHeader(Element)`

  - ### authenticateUserFromArray

    public UserReference authenticateUserFromArray(Object[] args)
    See Also:
      - `Directory.authenticateUserFromArray(Object[])`

  - ### isProfileDefined

    public boolean isProfileDefined(Profile aProfile)
    Returns `true` if the specified profile is defined in the directory.

    The implementation of this method does the following:

    - if the specified profile is a user reference, it calls method `isUserDefined(UserReference)`;
    - if the specified profile is a built-in role, it returns `true`;
    - if the specified profile is a specific role, it calls method `isSpecificRoleDefined(Role)`.

  - ### isUserDefined

    public boolean isUserDefined(UserReference aUserReference)
    See Also:
      - `Directory.isUserDefined(UserReference)`

  - ### isSpecificRoleDefined

    public boolean isSpecificRoleDefined(Role aSpecificRole)
    See Also:
      - `Directory.isSpecificRoleDefined(Role)`

  - ### isProfileIncluded

    public boolean isProfileIncluded(Profile aProfile, Profile anotherProfile)
    Returns `true` when `aProfile` is equal to or included in `anotherProfile`.

    The implementation of this method returns `true`:

    - If `aProfile` references a user `U`, and:
      - either `anotherProfile` references the same user,
      - or `anotherProfile` is a role and user `U` has this role (this calls method `isUserInRole(UserReference, Role)`).
    - If `aProfile` references a role `R`, and:
      - either `anotherProfile` references the same role,
      - or `anotherProfile` is a role and role `R` is, included in `anotherProfile` (this calls method `isRoleStrictlyIncluded(Role, Role)`).

    If the specified profile has been authenticated and the corresponding Session object is available, it is recommended to invoke `Session.isUserInRole(Profile)` instead of this method, for performance purposes.

    See Also:
      - `Session.isUserInRole(Profile)`

  - ### isRoleStrictlyIncluded

    public boolean isRoleStrictlyIncluded(Role aRole, Role anotherRole)
    Returns `true` if `aRole` is included in `anotherRole`.

    This method invokes `Directory.isRoleStrictlyIncluded(Role, Role)`, unless:

    - the specified `aRole` is `Profile.ADMINISTRATOR` and that role is disabled, in which case returns `false`,
    - the specified `aRole` is `Profile.EVERYONE` and that role is a specific one, in which case returns `true`.
    See Also:
      - `isBuiltInAdministratorDisabled()`

  - ### isUserInRole

    public boolean isUserInRole(UserReference aUser, Role aRole)
    Returns `true` if the user has the specified role.

    This method invokes `Directory.isUserInRole(UserReference, Role)`, unless the specified role is `built-in administrator role` and that role is disabled, in which case returns `false`.

    If the specified user has been authenticated and the corresponding Session object is available, it is recommended to invoke `Session.isUserInRole(Profile)` instead of this method, for performance purposes.

    See Also:
      - `Session.isUserInRole(Profile)`
      - `isBuiltInAdministratorDisabled()`

  - ### isBuiltInAdministratorDisabled

    public final boolean isBuiltInAdministratorDisabled()
    Returns `true` if the built-in administrator role has been disabled.
    Since:
      5.4.0
    See Also:
      - Configuring the user and roles directory

  - ### getProfiles

    public List<Profile> getProfiles(ProfileListContext aProfileContext)
    Throws:
      `RuntimeException` - If the list returned by the directory implementation has incorrect elements.
    See Also:
      - `Directory.getProfiles(ProfileListContext)`

  - ### getUsersInRole

    public List<UserReference> getUsersInRole(Role aRole)
    Throws:
      `RuntimeException` - If the list returned by the directory implementation has incorrect elements.
    See Also:
      - `Directory.getUsersInRole(Role)`

  - ### hasUsersInRole

    public boolean hasUsersInRole(Role aRole)
    Since:
      6.0.6
    See Also:
      - `Directory.hasUsersInRole(Role)`

  - ### getUserEmail

    public String getUserEmail(UserReference aUserReference)
    See Also:
      - `Directory.getUserEmail(UserReference)`

  - ### getRoleEmail

    public String getRoleEmail(Role aRole)
    If not null, the email address is considered as the mailing list of all the users in this role.
    Since:
      5.7.0
    See Also:
      - `Directory.getRoleEmail(Role)`

  - ### displayProfile

    public String displayProfile(Profile aProfile, Locale aLocale)
    Returns a label for the profile specified. This label is displayed in the EBX® user interface.

    The implementation of this method does the following:

    - if the specified profile is a user reference, it calls method `displayUser(UserReference, Locale)`;
    - if the specified profile is a built-in role, it calls method `displayBuiltInRole(Role, Locale)`;
    - if the specified profile is a specific role, it calls method `displaySpecificRole(Role, Locale)`.

  - ### displaySpecificRole

    public String displaySpecificRole(Role aSpecificRole, Locale aLocale)
    See Also:
      - `Directory.displaySpecificRole(Role, Locale)`

  - ### displayUser

    public String displayUser(UserReference aUserReference, Locale aLocale)
    See Also:
      - `Directory.displayUser(UserReference, Locale)`

  - ### displayUserWithSalutation

    public String displayUserWithSalutation(UserReference aUserReference, Locale aLocale)
    Throws:
      `IllegalArgumentException` - if user is not actually defined.
    See Also:
      - `Directory.displayUserWithSalutation(UserReference, Locale)`

  - ### getBackedUpUsers

    public List<UserReference> getBackedUpUsers(UserReference aUserReference)
    If the `Directory` implementation returns `null`, this method returns an empty List.
    Throws:
      `RuntimeException` - If the list returned by the directory implementation has incorrect elements. It also checks that a user cannot be backed up by himself.
    See Also:
      - `Directory.getBackedUpUsers(UserReference)`

  - ### getBackingUpUsers

    public List<UserReference> getBackingUpUsers(UserReference aUserReference)
    If the `Directory` implementation returns `null`, this method returns an empty List.
    Throws:
      `RuntimeException` - If the list returned by the directory implementation has incorrect elements.
    See Also:
      - `Directory.getBackingUpUsers(UserReference)`

  - ### getDirectoryImplementation

    public Directory getDirectoryImplementation()
    Returns the underlying implementation of the directory.

  - ### displayBuiltInRole

    public String displayBuiltInRole(Role aBuiltInRole, Locale aLocale)
    See Also:
      - `Directory.displayBuiltInRole(Role, Locale)`

  - ### getUserAuthenticationURI

    @Deprecated public URI getUserAuthenticationURI(Session aSession)
    Deprecated.
    Since 6.1.3, see `Directory.getUserAuthenticationURI(Session)`.
    Since:
      5.2.0
    See Also:
      - `Directory.getUserAuthenticationURI(Session)`