Field Detail

• refreshTime

  public final long refreshTime

  The time in milliseconds since the epoch when this instance was created and refreshed.

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 hashed password. It is based on PBKDF2 with Keyed-Hash Message Authentication Code (HMAC) with a SHA-256 hash. It can start with "EXT:" if the user has signed in using an external Sign In Provider, e.g. LinkedIn or Facebook, the remaining part of the string identifies the provider and the users identifier for that provider.

  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.

  java.lang.NullPointerException - If hashPW is null.

  java.lang.IllegalArgumentException - If hashPW is an empty string.

• 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 hashed password. It is based on PBKDF2 with Keyed-Hash Message Authentication Code (HMAC) with a SHA-256 hash. It can start with "EXTERNAL:" if the user has signed in using an external Sign In Provider, e.g. LinkedIn or Facebook, the remaining part of the string identifies the provider and the users identifier for that provider.

  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.

  java.lang.NullPointerException - If hashPW is null.

  java.lang.IllegalArgumentException - If hashPW is an empty string.

• newBasicUserInfo

  public static BasicUserInfo newBasicUserInfo​(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.

• newBasicUserInfo

  public static BasicUserInfo newBasicUserInfo​(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.

• newBasicUserInfoFromEmail

  public static BasicUserInfo newBasicUserInfoFromEmail​(java.sql.Connection conn,
                                                        java.lang.String emailAddress)
                                                 throws java.sql.SQLException,
                                                        NotFoundException

  Constructs the UserInfo by loading the information from the database.

  Parameters:

  conn - The connection.

  emailAddress - The email address to look-up.

  Throws:

  java.sql.SQLException - For SQL errors.

  NotFoundException - If user is not found.

• 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). It is based on PBKDF2 with Keyed-Hash Message Authentication Code (HMAC) with a SHA-256 hash. It can start with "EXT:" if the user has signed in using an external Sign In Provider, e.g. LinkedIn or Facebook, the remaining part of the string identifies the provider and the users identifier for that provider.

  Returns:

  A string with a hashed password, or "EXTERNAL" if the user has signed in using an external Sign In Provider, e.g. LinkedIn or Facebook.

• mustChangePassword

  public boolean mustChangePassword()

  Returns if the password must be changed upon next login.

  Specified by:

  mustChangePassword in class UserInfoBase

  Returns:

  Flag 'change_pw' to change the password.

• canChangePassword

  public java.lang.String canChangePassword()

  Checks if the user is allowed to change his password.

  Specified by:

  canChangePassword in class UserInfoBase

  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.

  Specified by:

  getLastLogin in class UserInfoBase

• getLastFail

  public long getLastFail()

  Gets the 'last_fail' time in milliseconds since the epoch, 0 for never.

  Specified by:

  getLastFail in class UserInfoBase

• getFailCount

  public int getFailCount()

  Gets the 'fail_count' value, zero for never.

  Specified by:

  getFailCount in class UserInfoBase

• getDisabledReason

  public java.lang.String getDisabledReason()

  Gets the 'disabled' reason string, null for user not disabled.

  Specified by:

  getDisabledReason in class UserInfoBase

• 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.

  Specified by:

  getDetails in class UserInfoBase

  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.

  Specified by:

  getDetails in class UserInfoBase

  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.

  Specified by:

  getDetails in class UserInfoBase

  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:

  • IBasicUserInfoDetailNames.DETAIL_UploadedProfileImage,
  • IBasicUserInfoDetailNames.DETAIL_LargeProfileImage,
  • IBasicUserInfoDetailNames.DETAIL_ThumbnailProfileImage, and
  • IBasicUserInfoDetailNames.DETAIL_DBAdministrationUserName.

  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).