Package com.orchestranetworks.service.directory

# Class DirectoryDefault

java.lang.Object
com.orchestranetworks.service.directory.Directory
com.orchestranetworks.service.directory.DirectoryDefault

public class DirectoryDefault extends Directory
The default internal directory implementation that is delivered with EBX®.

#### Extending this class

This class can be extended to authenticate users without using the default directory.

Note that this is not the recommended method and some conditions apply. The proper method is to extend `Directory`.

If overriding one of the `authenticateUserFrom...` methods to use an alternative user directory, user login must be synchronized between this other directory and the `ebx-directory` instance. This means that users login must be present in both directories.

See Also:
  - `DirectoryDefaultHelper`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `DirectoryDefault.RoleEntity`
  Represents a role entity that is, or can be, persisted in the default directory.
  `static interface`
  `DirectoryDefault.UserEntity`
  Represents a user entity that is, or can be, persisted in the default directory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `UserReference`
  `authenticateUserFromLoginPassword(String aLogin, String aPassword)`
  Authenticates a user using the login and password specified.
  `String`
  `displaySpecificRole(Role aSpecificRole, Locale aLocale)`
  Returns a label for this specific role.
  `String`
  `displayUser(UserReference aUserReference, Locale aLocale)`
  Returns a label for the specified user.
  `String`
  `displayUserWithSalutation(UserReference aUserReference, Locale aLocale)`
  Returns a label for the specified user so that it can be used in the user interface.
  `static String`
  `encryptString(String s)`
  Returns the encrypted string corresponding to the "clear" password specified.
  `static String`
  `formerEncryptString(String s)`
  Returns the encrypted string corresponding to the 'clear-text' password specified, as per releases prior to 6.0.2.
  `List<Role>`
  `getAllSpecificRoles()`
  Returns all the specific roles defined by this directory.
  `List<UserReference>`
  `getAllUserReferences()`
  Returns all the users defined by this directory.
  `static DirectoryDefault`
  `getInstance(Repository aRepository)`
  Returns the default internal directory instance that is delivered with EBX®.
  `List<Profile>`
  `getProfiles(ProfileListContext aProfileContext)`
  Returns all profiles according to the specified context.
  `String`
  `getRoleDescription(Role aRole, Locale aLocale)`
  Returns the specific role description.
  `String`
  `getRoleEmail(Role aRole)`
  Returns the email address of the specified role.
  `List<Role>`
  `getRolesForUser(UserReference userReference)`
  Returns the specific roles of the specified user.
  `URI`
  `getUserAvatarURI(UserReference aUserReference)`
  Returns the URL to the image associated with the specified user.
  `String`
  `getUserEmail(UserReference aUserReference)`
  Returns the email address of the specified user, `null` if unknown.
  `String`
  `getUserInitials(UserReference aUserReference, Locale aLocale)`
  Returns the initials defined in the user record.
  `List<UserReference>`
  `getUsersInRole(Role aRole)`
  Returns all users that belong to the specified role.
  `static String`
  `hashPassword(String login, String password)`
  Returns the SHA-512 hash of the password, and uses the login as salt.
  `boolean`
  `hasUsersInRole(Role aRole)`
  Returns `true` if one or more users have the specified role.
  `boolean`
  `isRoleStrictlyIncluded(Role aRole, Role anotherRole)`
  Returns true when aRole is included in anotherRole.
  `boolean`
  `isSpecificRoleDefined(Role aRole)`
  Returns `true` if the specific role exists in this directory.
  `boolean`
  `isUserDefined(UserReference aUserReference)`
  Returns `true` if the specified user actually exists in this directory.
  `boolean`
  `isUserInRole(UserReference aUserReference, Role aRole)`
  Returns `true` if the user has the specified role.

  ### Methods inherited from class com.orchestranetworks.service.directory.Directory

  `authenticateUserFromArray, authenticateUserFromHttpRequest, authenticateUserFromSOAPHeader, displayBuiltInRole, getBackedUpUsers, getBackingUpUsers, getUserAuthenticationURI`

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

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

- ## Method Details

  - ### getInstance

    public static DirectoryDefault getInstance(Repository aRepository)
    Returns the default internal directory instance that is delivered with EBX®. Returns `null` if a custom directory implementation is used.
    Parameters:
      `aRepository` - EBX® repository.

  - ### encryptString

    public static String encryptString(String s)
    Returns the encrypted string corresponding to the "clear" password specified. This is the default encryption function used by this directory (see `authenticateUserFromLoginPassword(String, String)`), and also by the user interface component associated with the data type `osd:password`.

    A SHA-512 algorithm is used. The value to be hash should already have been salted if needed before calling this method.

    See Also:
      - `Encryption`

  - ### hashPassword

    public static String hashPassword(String login, String password)
    Returns the SHA-512 hash of the password, and uses the login as salt.
    Since:
      6.0.2

  - ### formerEncryptString

    public static String formerEncryptString(String s)
    Returns the encrypted string corresponding to the 'clear-text' password specified, as per releases prior to 6.0.2. This was the default encryption function used by this directory, and also by the user interface component associated with the data type `osd:password` in previous versions. This method must not be used outside the purpose of checking old stored encryption. In particular, this method may not be used with a string having a length greater than 60, as there are some risks of hash collision.
    Since:
      6.0.2
    See Also:
      - `Encryption`

  - ### getAllSpecificRoles

    public List<Role> getAllSpecificRoles()
    Returns all the specific roles defined by this directory.
    Returns:
      a `List` of `Role` instances.

  - ### getAllUserReferences

    public List<UserReference> getAllUserReferences()
    Returns all the users defined by this directory.
    Returns:
      a `List` of `UserReference` instances.

  - ### getRoleDescription

    public String getRoleDescription(Role aRole, Locale aLocale)
    Returns the specific role description.

  - ### getRoleEmail

    public String getRoleEmail(Role aRole)
    Returns the email address of the specified role.
    Overrides:
      `getRoleEmail` in class `Directory`
    Since:
      5.7.0

  - ### getRolesForUser

    public List<Role> getRolesForUser(UserReference userReference)
    Returns the specific roles of the specified user.
    See Also:
      - `Role`

  - ### isUserDefined

    public boolean isUserDefined(UserReference aUserReference)
    Description copied from class: `Directory`
    Returns `true` if the specified user actually exists in this directory.
    Specified by:
      `isUserDefined` in class `Directory`
    See Also:
      - `DirectoryHandler.isProfileDefined(Profile)`

  - ### isSpecificRoleDefined

    public boolean isSpecificRoleDefined(Role aRole)
    Description copied from class: `Directory`
    Returns `true` if the specific role exists in this directory.
    Specified by:
      `isSpecificRoleDefined` in class `Directory`
    See Also:
      - `DirectoryHandler.isProfileDefined(Profile)`

  - ### authenticateUserFromLoginPassword

    public UserReference authenticateUserFromLoginPassword(String aLogin, String aPassword)
    Description copied from class: `Directory`
    Authenticates a user using the login and password specified.

    Note: For the EBX® user interface, the full authentication process is detailed in the class `UIHttpManagerComponent`. This method can also be called by a client application through `Repository.createSessionFromLoginPassword(String, String)`.

    Specified by:
      `authenticateUserFromLoginPassword` in class `Directory`
    Returns:
      the user reference corresponding to the specified login/password, or `null` if login does not exist or password is incorrect.

  - ### isUserInRole

    public boolean isUserInRole(UserReference aUserReference, Role aRole)
    Returns `true` if the user has the specified role. The method must return `false` if the user does not exist.

    Warning: If this method is to be overridden, built-in roles must not be omitted.

    Specified by:
      `isUserInRole` in class `Directory`
    See Also:
      - `Session.isUserInRole(Profile)`
      - `DirectoryHandler.isUserInRole(UserReference, Role)`

  - ### isRoleStrictlyIncluded

    public boolean isRoleStrictlyIncluded(Role aRole, Role anotherRole)
    Returns true when aRole is included in anotherRole.
    Overrides:
      `isRoleStrictlyIncluded` in class `Directory`
    See Also:
      - `DirectoryHandler.isRoleStrictlyIncluded(Role, Role)`

  - ### getUserEmail

    public String getUserEmail(UserReference aUserReference)
    Description copied from class: `Directory`
    Returns the email address of the specified user, `null` if unknown.

    The default implementation of this method always returns `null`.

    Overrides:
      `getUserEmail` in class `Directory`

  - ### getProfiles

    public List<Profile> getProfiles(ProfileListContext aProfileContext)
    Description copied from class: `Directory`
    Returns all profiles according to the specified context.

    ##### Postconditions:

    The profiles returned have some restrictions:

    - For defining permissions (see `ProfileListContext.isForDefiningPermission()`), the list must not contain the ADMINISTRATOR built-in role.
    - For owning a dataspace, snapshot, or dataset (see `ProfileListContext.isForSelectingBranchOwner()` and `ProfileListContext.isForSelectingInstanceOwner()`), the list must not contain the built-in role OWNER.
    - For workflows (see `ProfileListContext.isForWorkflow()`, the list must not contain the built-in role OWNER.
    - For defining views (see `ProfileListContext.isForDefiningViews()`, the list must not contain the built-in role OWNER.
    Specified by:
      `getProfiles` in class `Directory`
    Returns:
      an immutable list of `profiles`

  - ### getUsersInRole

    public List<UserReference> getUsersInRole(Role aRole)
    Description copied from class: `Directory`
    Returns all users that belong to the specified role.

    Default implementation throws an exception: this method must be overridden.

    Overrides:
      `getUsersInRole` in class `Directory`
    Returns:
      an immutable list of `UserReference`, each responding `true` to method `Directory.isUserInRole(UserReference, Role)`.

  - ### hasUsersInRole

    public boolean hasUsersInRole(Role aRole)
    Description copied from class: `Directory`
    Returns `true` if one or more users have the specified role.

    Default implementation is not optimized as it is equivalent to calling:

    `!getUsersInRole(aRole).isEmpty()`

    This method should be overridden in case of performance issues.

    Overrides:
      `hasUsersInRole` in class `Directory`

  - ### displaySpecificRole

    public String displaySpecificRole(Role aSpecificRole, Locale aLocale)
    Description copied from class: `Directory`
    Returns a label for this specific role.

    Any implementation of this method should handle the case where the role no longer exists in the directory (due to having been deleted). In this case, this method is expected to return a label indicating that the specified role is unknown.

    The default implementation of this method uses the name of the role.

    Overrides:
      `displaySpecificRole` in class `Directory`
    See Also:
      - `DirectoryHandler.displayProfile(Profile, Locale)`

  - ### displayUser

    public String displayUser(UserReference aUserReference, Locale aLocale)
    Description copied from class: `Directory`
    Returns a label for the specified user.

    Implementation recommendations:

    - Since the returned label is used in lists, for example for setting permissions or ownership, it is recommended for it to contain at least the `identifier` of the user.
    - Any implementation of this method should handle the case where the user no longer exists in the directory (due to having been removed from the directory). In this case, it is expected for this method to return a particular label indicating that the specified user is unknown.

    The default implementation of this method simply displays the `identifier` of the user (and mentions that it is "unknown", if the user is not defined).

    Overrides:
      `displayUser` in class `Directory`
    See Also:
      - `DirectoryHandler.displayProfile(Profile, Locale)`

  - ### displayUserWithSalutation

    public String displayUserWithSalutation(UserReference aUserReference, Locale aLocale)
    Description copied from class: `Directory`
    Returns a label for the specified user so that it can be used in the user interface. For example, it is displayed by the EBX® user interface in the user interface header.

    The default implementation of this method invokes the method `Directory.displayUser(UserReference, Locale)`.

    A custom implementation could display a salutation with first and last names, for example "Mr. Andrew Smith".

    Overrides:
      `displayUserWithSalutation` in class `Directory`

  - ### getUserAvatarURI

    public URI getUserAvatarURI(UserReference aUserReference)
    Description copied from class: `Directory`
    Returns the URL to the image associated with the specified user. If this method returns `null`, the user's initials are usually used as the user avatar.

    The image must be a square format, there is no size limitation. Accepted image formats are the formats supported by the browser.

    Default implementation returns `null`.

    Overrides:
      `getUserAvatarURI` in class `Directory`
    See Also:
      - `UIComponentWriter.addUserAvatar(UserReference)`

  - ### getUserInitials

    public String getUserInitials(UserReference aUserReference, Locale aLocale)
    Returns the initials defined in the user record.

    If not defined, returns the first letter of the first name and the last name.

    Overrides:
      `getUserInitials` in class `Directory`
    Since:
      5.7.0
    See Also:
      - `Directory.getUserAvatarURI(UserReference)`