Class BasicUserInfo

  • All Implemented Interfaces:
    IBasicUserInfoDetailNames

    public class BasicUserInfo
    extends java.lang.Object
    implements IBasicUserInfoDetailNames
    User information in the database. Depending on call, various members are not always populated.
    Author:
    Christopher Mindus
    • Field Detail

      • id

        public final long id
        The unique ID.
      • userName

        public final java.lang.String userName
        The 'user_name', never null (max 254 chars).
      • userNameLower

        public final java.lang.String userNameLower
        The 'user_name_lower', lower case using Locale.ENGLISH of 'user_name', never null (max 254 chars).
      • email

        public final java.lang.String email
        The 'email', never null (max 254 chars).
      • langCodes

        public final java.util.ArrayList<java.lang.String> langCodes
        The unpacked 'lang_codes' as language codes the user wishes to use. The value is null if there are no language codes.
      • created

        public final long created
        The 'created' time in milliseconds since the epoch.
      • refreshTime

        public final long refreshTime
        The time in milliseconds since the epoch when this instance was created and refreshed.
    • Constructor Detail

      • BasicUserInfo

        public BasicUserInfo​(java.sql.Connection conn,
                             java.lang.String userName,
                             boolean lockForUpdate)
                      throws java.sql.SQLException,
                             NotFoundException
        Constructs the UserInfo by loading the information from the database.
        Parameters:
        conn - The connection.
        userName - The user name.
        lockForUpdate - Flag indicating the user should be locked for update.
        Throws:
        java.sql.SQLException - For SQL errors.
        NotFoundException - If user is not found.
      • BasicUserInfo

        public BasicUserInfo​(java.sql.Connection conn,
                             long id)
                      throws java.sql.SQLException,
                             NotFoundException
        Constructs the UserInfo by loading the information from the database.
        Parameters:
        conn - The connection.
        id - The unique ID.
        Throws:
        java.sql.SQLException - For SQL errors.
        NotFoundException - If user is not found.
    • Method Detail

      • getUserIDs

        public static long[] getUserIDs​(java.sql.Connection conn)
                                 throws java.sql.SQLException
        Gets all the defined user ID's. With the user ID's, you can then retrieve the users using:
           long id=...;
           UserAuthentication userAuth=UserAuthentication.getInstance();
           AuthenticatedUser user=userAuth.getUser(id);
           BasicUserInfo info=user.getBasicUserInfo();
         
        Parameters:
        conn - The JDBC connection.
        Returns:
        The array of User ID's.
        Throws:
        java.sql.SQLException - For SQL errors.
      • createNewUser

        public static BasicUserInfo createNewUser​(java.lang.String userName,
                                                  java.lang.String hashPW,
                                                  boolean changePW,
                                                  java.lang.String email,
                                                  java.lang.String langCode,
                                                  boolean hasLoggedIn,
                                                  java.util.Map<java.lang.String,​java.lang.String> details,
                                                  java.lang.String... groupNames)
                                           throws java.sql.SQLException,
                                                  NotFoundException
        Creates a new user and writes the information to the database.

        Note: The length of a details value should be maximum 3000 characters. If the it exceeds, it will be truncated.

        Parameters:
        userName - The user name: unique, not empty, maximum length 254.
        hashPW - The password hash: not empty, EXTERNAL for external sign in.
        changePW - Require user to change password upon next login (set to false for EXTERNAL password hash).
        email - Email address, null for none: maximum length 254.
        langCode - The selected language code, null for none.
        hasLoggedIn - Flag for user is or has logged in (will update last_login time).
        details - Details map: keys maximum length 40, values maximum length 300. Set details to null for none.
        groupNames - The groups the user should belong to.
        Throws:
        java.sql.SQLException - For SQL errors.
        NotFoundException - If a group name is not found.
      • createNewUser

        public static BasicUserInfo createNewUser​(java.sql.Connection conn,
                                                  java.lang.String userName,
                                                  java.lang.String hashPW,
                                                  boolean changePW,
                                                  java.lang.String email,
                                                  java.lang.String langCode,
                                                  boolean hasLoggedIn,
                                                  java.util.Map<java.lang.String,​java.lang.String> details,
                                                  GroupInfo... groups)
                                           throws java.sql.SQLException,
                                                  NotFoundException
        Creates a new user and writes the information to the database.

        Note: The length of a details value should be maximum 3000 characters. If the it exceeds, it will be truncated.

        Parameters:
        userName - The user name: unique, not empty, maximum length 254.
        hashPW - The password hash: not empty, EXTERNAL for external sign in.
        changePW - Require user to change password upon next login (set to false for EXTERNAL password hash).
        email - Email address, null for none: maximum length 254.
        langCode - The selected language code, null for none.
        hasLoggedIn - Flag for user is or has logged in (will update last_login time).
        details - Details map: keys maximum length 40, values maximum length 300. Set details to null for none.
        groups - The groups the user should belong to.
        Throws:
        java.sql.SQLException - For SQL errors.
        NotFoundException - If a group name is not found.
      • equals

        public boolean equals​(java.lang.Object o)
        Checks for equality. Checks only if two user ID's are equal.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - The object to compare with.
        Returns:
        When user ID equals, false otherwise.
      • toString

        public java.lang.String toString()
        String representation of the class.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string with user and distance.
      • getPasswordHash

        public java.lang.String getPasswordHash()
        Gets the 'hash_pw', never null (max 120 chars).
      • mustChangePassword

        public boolean mustChangePassword()
        Returns if the password must be changed upon next login.
        Returns:
        Flag 'change_pw' to change the password.
      • canChangePassword

        public java.lang.String canChangePassword()
        Checks if the user is allowed to change his password.
        Returns:
        null if allowed and user can change his password, otherwise an English text for the reason of the password being fixed and that it can never be changed.
      • getLastLogin

        public long getLastLogin()
        Gets the 'last_login' time in milliseconds since the epoch, 0 for never.
      • getLastFail

        public long getLastFail()
        Gets the 'last_fail' time in milliseconds since the epoch, 0 for never.
      • getFailCount

        public int getFailCount()
        Gets the 'fail_count' value, zero for never.
      • getDisabledReason

        public java.lang.String getDisabledReason()
        Gets the 'disabled' reason string, null for user not disabled.
      • getUUID

        public java.lang.String getUUID()
        Returns the UUID for this user.
        Returns:
        The UUID of this user based of the ID, user name and email.
      • needsNewHashedPassword

        public boolean needsNewHashedPassword()
        Checks if a new password needs to be provided to the database during current successful login. As the password is available, it makes it possible to save a new hash with perhaps new algorithms. This makes it very hard to crack.
        Returns:
        true if 'failCount' is larger than 3 or 'disabledReason' is present. true is also returned if 'lastLogin' is longer than a week from current time. false is otherwise returned.
      • updateSuccessfulLogin

        public void updateSuccessfulLogin​(java.sql.Connection conn,
                                          java.lang.String newHashedPassword)
                                   throws java.sql.SQLException
        Updates the information to the database for a successful login.

        The connection must be in auto-commit "off" and have the user selected for update.

        If it is required, the password hash is updated. This is done every week or after a failure. This method will also reset the disabled status.

        Parameters:
        conn - The connection.
        newHashedPassword - A new hashed password to update the entry with, null for no change.
        Throws:
        java.sql.SQLException - For SQL errors.
      • updateSuccessfulLogin

        public void updateSuccessfulLogin​(java.sql.Connection conn,
                                          java.lang.String newHashedPassword,
                                          boolean resetChangePassword)
                                   throws java.sql.SQLException
        Updates the information to the database for a successful login.

        The connection must be in auto-commit "off" and have the user selected for update.

        If it is required, the password hash is updated. This is done every week or after a failure. This method will also reset the disabled status.

        Parameters:
        conn - The connection.
        newHashedPassword - A new hashed password to update the entry with, null for no change.
        resetChangePassword - Flag to also reset the changePW (only used when newHashedPassword is specified).
        Throws:
        java.sql.SQLException - For SQL errors.
      • updateFailedLogin

        public void updateFailedLogin​(java.sql.Connection conn,
                                      java.lang.String disabledReason)
                               throws java.sql.SQLException,
                                      NotFoundException
        Updates the information to the database for failed login.

        The connection must be in auto-commit "off" and have the user selected for update.

        Parameters:
        conn - The connection.
        disabledReason - The reason to disable the user, null for no change.
        Throws:
        java.sql.SQLException - For SQL errors.
        NotFoundException - If the user has been deleted since login.
      • changePassword

        public boolean changePassword​(java.lang.String oldPassword,
                                      java.lang.String password)
                               throws java.sql.SQLException,
                                      NotFoundException
        Changes the password for the user.
        Parameters:
        oldPassword - The old password.
        password - The new password.
        Returns:
        true for success, false if the old password does not match the database hashed password.
        Throws:
        java.lang.NullPointerException - If the one of the passwords is null.
        java.sql.SQLException - For SQL errors.
        NotFoundException - If the user has been deleted since login.
        java.lang.IllegalStateException - If the user has been disabled (user cannot change password, too many invalid logins, or administrator action). The message contains the disabled reason.
      • resetPassword

        public java.lang.String resetPassword()
                                       throws java.sql.SQLException,
                                              NotFoundException
        Resets the password for the user.
        Returns:
        The new random password.
        Throws:
        java.sql.SQLException - For SQL errors.
        NotFoundException - If the user has been deleted since login.
        java.lang.IllegalStateException - If the user has been disabled (too many invalid logins, or administrator action). The message contains the disabled reason.
      • getGroups

        public GroupInfo[] getGroups​(boolean reload)
                              throws NotFoundException,
                                     java.sql.SQLException
        Gets the groups of this user.
        Parameters:
        reload - Forces reload of the groups.
        Returns:
        The array of group informations.
        Throws:
        NotFoundException - If a group is not found.
        java.sql.SQLException - For SQL errors.
      • addGroups

        public int addGroups​(java.sql.Connection conn,
                             GroupInfo... groups)
                      throws java.sql.SQLException
        Adds the groups to the user.
        Parameters:
        conn - The connection.
        groups - The groups to add.
        Returns:
        Count of added groups (if already added before).
        Throws:
        java.sql.SQLException - For SQL errors.
      • removeGroups

        public int removeGroups​(java.sql.Connection conn,
                                GroupInfo... groups)
                         throws java.sql.SQLException
        Removes the groups from the user.
        Parameters:
        conn - The connection.
        groups - The groups to add.
        Returns:
        Count of removed groups (if not present before).
        Throws:
        java.sql.SQLException - For SQL errors.
      • getDetails

        public java.util.Map<java.lang.String,​java.lang.String> getDetails()
        Gets the cached and current user details. Details are e.g. fax number, profile picture.
        Returns:
        A new read-only copy of the details with name as key and the value for it.
      • getDetails

        public java.util.Map<java.lang.String,​java.lang.String> getDetails​(boolean reload)
                                                                          throws java.sql.SQLException
        Gets the (cached and current) user details. Details are e.g. fax number, profile picture.

        Note: If you have a JDBC connection, use getDetails(Connection, boolean) instead for efficiency.

        Parameters:
        reload - Reload flag from database.
        Returns:
        If reload is false, a cached read-only map with the details name as key and the value for it, otherwise a fresh copy of the details from the database.
        Throws:
        java.sql.SQLException - For SQL errors.
      • getDetails

        public java.util.Map<java.lang.String,​java.lang.String> getDetails​(java.sql.Connection conn,
                                                                                 boolean reload)
                                                                          throws java.sql.SQLException
        Gets the user details. Details are e.g. fax number, profile picture. If not previously loaded, the "reload" flag is ignored and the details are loaded.
        Parameters:
        conn - The connection, null for cached values only.
        reload - Reload flag, i.e. instructs a full reload of all details from the database.
        Returns:
        A cached read-only map with the details name as key and the value for it.
        Throws:
        java.sql.SQLException - For SQL errors.
      • updateUserDetails

        public void updateUserDetails​(java.util.Map<java.lang.String,​java.lang.String> detailsMap)
                               throws java.sql.SQLException
        Updates user details and stores it in the database. A detail value can be added and removed. It is added if the entry is not present previously, updated if the entry did exist and the value is non-null, removed if the value is null.

        The cached details map are maintained for the user in a map, but outside updates to the database will not reflect changes to this.

        The exceptions thrown in this method may occur during the processing of changes. The database will be rolled back, however, the cached copy might be partially updated.

        Parameters:
        detailsMap - The map with details to change, keys are the detail names and the values are the new respective detail value. If the detail value is null, the detail is deleted.

        The detail following names are ignored:

        These names are used in conjunction with the License System.

        Throws:
        java.sql.SQLException - For SQL errors.
        java.lang.NullPointerException - If detail is null.
      • setUserDetail

        public java.lang.String setUserDetail​(java.sql.Connection conn,
                                              java.lang.String detail,
                                              java.lang.String value)
                                       throws java.sql.SQLException
        Sets a detail and stores it in the database. A detail value can be added and removed.

        Details are maintained for the user in a map, but outside updates to the database will not reflect changes to this.

        Note: The length of the detail value should be maximum 3000 characters. If the it exceeds, it will be truncated.

        Parameters:
        conn - The connection.
        detail - The detail name.
        value - The value, null to delete the detail.
        Returns:
        The previous value (if all details are previously loaded), null otherwise. If the detail name should not be stored in the details (see detail) parameter, null is returned and nothing is performed.
        Throws:
        java.sql.SQLException - For SQL errors.
        java.lang.NullPointerException - If detail is null.
      • setEmailVerified

        public int setEmailVerified​(java.lang.String email)
        Marks an email to be verified. The details like DETAIL_VerifyEmail[-nn] are checked and the appropriate one is removed.
        Parameters:
        email - The mail verified.
        Returns:
        1 for successful removal of verification, 0 if already verified, -1 if email is not registered with the user, or -2 for database SQL errors (already logged).
        Throws:
        java.lang.NullPointerException - If email is null.
      • setEmailVerified

        public int setEmailVerified​(java.sql.Connection conn,
                                    java.lang.String email)
                             throws java.sql.SQLException
        Marks an email to be verified. The details like DETAIL_VerifyEmail[-nn] are checked and the appropriate one is removed.
        Parameters:
        conn - The connection.
        email - The mail verified.
        Returns:
        1 for successful removal of verification, 0 if already verified, or -1 if email is not registered with the user.
        Throws:
        java.sql.SQLException - For SQL errors.
        java.lang.NullPointerException - If email is null.
      • getMailsToVerify

        public java.util.List<java.lang.String> getMailsToVerify()
        Gets all the mails that needs verification. The current details are used, so if you need a fresh copy, update them using @{link getDetails(boolean) or preferable getDetails(Connection, boolean) if you have a database connection.
        Returns:
        The list of alphabetically sorted mails to verify.
      • sendMailsToUnverifiedMailAddresses

        public int sendMailsToUnverifiedMailAddresses​(java.util.List<java.lang.String> verifyMails,
                                                      MailSender mailSender,
                                                      java.lang.String subject,
                                                      java.lang.String fromEmail,
                                                      java.lang.String bccEmails,
                                                      java.lang.String message,
                                                      java.lang.String externalWebServerBaseURL)
                                               throws NotFoundException,
                                                      java.io.IOException,
                                                      java.lang.IllegalStateException,
                                                      MessagingException
        Helper method to send a mail to all unverified mails for this user. The mail will be sent as plain text UTF-8 encoded mail.

        The message parameter is a formatted message that should contain two tags:

        • ${url} required tag that will contain the URL that the user must open in order to verify the mail.
        • ${email} optional tag that will be replaced with the email that needs verification.
        Parameters:
        verifyMails - The mails to verify, retrieved from getMailsToVerify().
        mailSender - The mail sender, null to get the default mail sender.
        subject - Subject that can contain the tag ${mail}.
        fromEmail - From email address.
        bccEmails - BCC email(s) [comma separated for multiple], null for none.
        message - The mail message to send.
        externalWebServerBaseURL - The external base URL for the web server, e.g. "https://lic.mindus.co", use null for default. The default address is retrieved using ServerShell.getExternalWebServerBaseURL().
        Returns:
        Count of mails queued for sending.
        Throws:
        NotFoundException - If mailSender cannot not be found (and the parameter mailSender, or if the externalWebServerBaseURL is null and the method ServerShell.getExternalWebServerBaseURL() returns null.
        java.io.IOException - If the mail queue directory does not exist.
        MessagingException - For messaging errors.
        java.lang.IllegalStateException - For illegal state when creating a mail to queue, or if the server is not started.
      • transferEmailDetails

        public int transferEmailDetails​(java.util.Map<java.lang.String,​java.lang.Object> otherDetails)
        Transfers all email settings such as primary email, optional additional email(s), verified emails, etc, from the details inside this BasicUserInfo instance and another details map.
        Parameters:
        otherDetails - Other details map to update.
        Returns:
        The count of changed values (new value or removed value).